Funzione SetAddrInfoExA (ws2tcpip.h)

Articolo
11/20/2024

La funzione SetAddrInfoEx registra o annulla la registrazione di un nome, un nome di servizio e gli indirizzi associati a un provider di spazi dei nomi specifico.

Sintassi

INT WSAAPI SetAddrInfoExA(
  [in]            PCSTR                              pName,
  [in]            PCSTR                              pServiceName,
  [in, out]       SOCKET_ADDRESS                     *pAddresses,
  [in]            DWORD                              dwAddressCount,
  [in, optional]  LPBLOB                             lpBlob,
  [in]            DWORD                              dwFlags,
  [in]            DWORD                              dwNameSpace,
  [in, optional]  LPGUID                             lpNspId,
  [in, optional]  timeval                            *timeout,
  [in, optional]  LPOVERLAPPED                       lpOverlapped,
  [in, optional]  LPLOOKUPSERVICE_COMPLETION_ROUTINE lpCompletionRoutine,
  [out, optional] LPHANDLE                           lpNameHandle
);

Parametri

[in] pName

Puntatore a un NULLstringa con terminazione contenente un nome con cui gli indirizzi devono essere registrati o annullati la registrazione. Interpretazione di questo parametro specifico per il provider dello spazio dei nomi.

[in] pServiceName

Puntatore a un facoltativo nullstringa con terminazione contenente il nome del servizio associato al nome registrato. L'interpretazione di questo parametro è specifica per il provider dello spazio dei nomi.

[in, out] pAddresses

Puntatore a un elenco facoltativo di indirizzi da registrare con il provider dello spazio dei nomi.

[in] dwAddressCount

Numero di indirizzi passati in parametro pAddresses. Se questo parametro è zero, il parametro pName viene annullata la registrazione dal provider dello spazio dei nomi.

[in, optional] lpBlob

Puntatore facoltativo ai dati utilizzati per impostare informazioni sullo spazio dei nomi specifiche del provider associate al parametro pName oltre un elenco di indirizzi. Le informazioni che non possono essere passate nel parametro pAddresses possono essere passate nel parametro lpBlob . Il formato di queste informazioni è specifico del provider dello spazio dei nomi.

[in] dwFlags

Set di flag che controllano la modalità di registrazione dei parametri pName e pServiceName con il provider dello spazio dei nomi. L'interpretazione di queste informazioni è specifica per il provider di spazi dei nomi.

[in] dwNameSpace

Identificatore dello spazio dei nomi che determina il provider di spazi dei nomi con cui registrare queste informazioni. Il passaggio di un identificatore di spazio dei nomi specifico comporterà la registrazione di queste informazioni solo con i provider dello spazio dei nomi che supportano lo spazio dei nomi specificato. Se si specifica NS_ALL, le informazioni verranno registrate con tutti i provider di spazi dei nomi installati e attivi.

Le opzioni per il parametro dwNameSpace sono elencate nel Winsock2.h. Diversi provider di spazi dei nomi sono inclusi in Windows Vista e versioni successive. È possibile installare altri provider di spazi dei nomi, pertanto i valori possibili seguenti sono solo quelli comunemente disponibili. Molti altri sono possibili.

Valore	Significato
NS_ALL	Tutti gli spazi dei nomi installati e attivi.
NS_BTH	Spazio dei nomi Bluetooth. Questo identificatore dello spazio dei nomi è supportato in Windows Vista e versioni successive.
NS_DNS	Spazio dei nomi DNS (Domain Name System).
NS_EMAIL	Spazio dei nomi di posta elettronica. Questo identificatore dello spazio dei nomi è supportato in Windows Vista e versioni successive.
NS_NLA	Spazio dei nomi NLA (Network Location Awareness). Questo identificatore dello spazio dei nomi è supportato in Windows XP e versioni successive.
NS_PNRPNAME	Spazio dei nomi peer-to-peer per un nome peer specifico. Questo identificatore dello spazio dei nomi è supportato in Windows Vista e versioni successive.
NS_PNRPCLOUD	Spazio dei nomi peer-to-peer per una raccolta di nomi peer. Questo identificatore dello spazio dei nomi è supportato in Windows Vista e versioni successive.

[in, optional] lpNspId

Puntatore a un GUID facoltativo di un provider di spazi dei nomi specifico per registrare queste informazioni nel caso in cui più provider di spazi dei nomi siano registrati in un singolo spazio dei nomi, ad esempio NS_DNS. Il passaggio del GUID per un provider di spazi dei nomi specifico comporterà la registrazione delle informazioni solo con il provider dello spazio dei nomi specificato. È possibile chiamare la funzione WSAEnumNameSpaceProviders per recuperare il GUID per un provider di spazi dei nomi.

[in, optional] timeout

Parametro facoltativo che indica il tempo, espresso in millisecondi, per attendere una risposta dal provider dello spazio dei nomi prima di interrompere la chiamata. Questo parametro è attualmente riservato e deve essere impostato su NULL perché non è supportata un'opzione di timeout .

[in, optional] lpOverlapped

Puntatore facoltativo a una struttura sovrapposta utilizzata per l'operazione asincrona. Questo parametro è attualmente riservato e deve essere impostato su NULL perché le operazioni asincrone non sono supportate.

[in, optional] lpCompletionRoutine

Puntatore facoltativo a una funzione da richiamare al completamento corretto per le operazioni asincrone. Questo parametro è attualmente riservato e deve essere impostato su NULL perché le operazioni asincrone non sono supportate.

[out, optional] lpNameHandle

Puntatore facoltativo usato solo per le operazioni asincrone. Questo parametro è attualmente riservato e deve essere impostato su NULL perché le operazioni asincrone non sono supportate.

Valore restituito

In caso di esito positivo, SetAddrInfoEx restituisce NO_ERROR (0). L'errore restituisce un codice di errore windows Sockets diverso da zero, come indicato nella codici di errore di Windows Sockets.

Codice di errore	Significato
WSANOTINITIALISED	Prima di usare questa funzione, è necessario eseguire una WSAStartup chiamata.
WSATRY_AGAIN	Si è verificato un errore temporaneo nella risoluzione dei nomi.
WSAEINVAL	È stato specificato un parametro non valido. Questo errore viene restituito se uno dei parametri riservati non è NULL.
WSAENOBUFS	Spazio del buffer insufficiente disponibile.
WSANO_RECOVERY	Si è verificato un errore irreversibile nella risoluzione dei nomi.
WSA_NOT_ENOUGH_MEMORY	Si è verificato un errore di allocazione della memoria.

Osservazioni

La funzione SetAddrInfoEx fornisce un metodo indipendente dal protocollo per registrare o annullare la registrazione di un nome e uno o più indirizzi con un provider di spazi dei nomi. Il provider dello spazio dei nomi NS_EMAIL in Windows Vista e versioni successive supporta la registrazione e la registrazione degli indirizzi. I provider di spazi dei nomi predefiniti NS_DNS, NS_PNRPNAME e NS_PNRPNAME non supportano attualmente la registrazione dei nomi.

Se la funzione SetAddrInfoEx viene chiamata con NS_ALL impostato come parametro dwNameSpace e il parametro lpNspId parametro non specificato, SetAddrInfoEx tenterà di registrare o annullare la registrazione del nome e degli indirizzi associati a tutti gli spazi dei nomi installati e attivi. La funzione SetAddrInfoEx restituirà esito positivo se uno dei provider dello spazio dei nomi ha registrato o annullato la registrazione del nome, ma non vi sarà alcuna indicazione del provider dello spazio dei nomi riuscito o di quale provider di spazi dei nomi ha avuto esito negativo.

Quando si definisce UNICODE o _UNICODE, SetAddrInfoEx viene definito per SetAddrInfoExW, la versione Unicode di questa funzione. I parametri stringa vengono definiti per il tipo di dati PWSTR.

Quando UNICODE o _UNICODE non è definito, setAddrInfoEx viene definito per SetAddrInfoExA, la versione ANSI di questa funzione. I parametri stringa sono del tipo di dati PCSTR.

Le informazioni registrate con un provider di spazi dei nomi possono essere restituite chiamando le funzioni diGetAddrInfoEx , getaddrinfoo funzioni di GetAddrInfoW. La funzione GetAddrInfoEx è una versione avanzata del getaddrinfo e funzioni getAddrInfoW.

In Windows Vista e versioni successive, quando SetAddrInfoEx viene chiamato da un servizio, se l'operazione è il risultato di un processo utente che chiama il servizio, il servizio deve rappresentare l'utente. Ciò consente di applicare correttamente i raggruppamenti di sicurezza e routing.

windows 8.1 e windows Server 2012 R2: la funzione SetAddrInfoExW è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Nota

L'intestazione ws2tcpip.h definisce SetAddrInfoEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	ws2tcpip.h
libreria	Ws2_32.lib
dll	Ws2_32.dll