Funzione GetAddressByNameA (nspapi.h)
[GetAddressByName non è più disponibile per l'uso a partire da Windows Sockets 2. Usare invece le funzioni dettagliate in Protocol-Independent Risoluzione dei nomi.]
La funzione GetAddressByName esegue una query su uno spazio dei nomi o su un set di spazi dei nomi predefiniti per recuperare le informazioni sull'indirizzo di rete per un servizio di rete specificato. Questo processo è noto come risoluzione dei nomi del servizio. Un servizio di rete può anche usare la funzione per ottenere informazioni sull'indirizzo locale che può essere usato con la funzione di associazione
Sintassi
INT GetAddressByNameA(
[in] DWORD dwNameSpace,
[in] LPGUID lpServiceType,
[in, optional] LPSTR lpServiceName,
[in, optional] LPINT lpiProtocols,
[in] DWORD dwResolution,
[in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
[out] LPVOID lpCsaddrBuffer,
[in, out] LPDWORD lpdwBufferLength,
[in, out] LPSTR lpAliasBuffer,
[in, out] LPDWORD lpdwAliasBufferLength
);
Parametri
[in] dwNameSpace
Spazio dei nomi o set di spazi dei nomi predefiniti su cui il sistema operativo deve eseguire una query per ottenere informazioni sull'indirizzo di rete.
Utilizzare una delle costanti seguenti per specificare uno spazio dei nomi.
La maggior parte delle chiamate a GetAddressByName deve usare il valore speciale NS_DEFAULT. Ciò consente a un client di ottenere con nessuna conoscenza degli spazi dei nomi disponibili in un internetwork. L'amministratore di sistema determina l'accesso allo spazio dei nomi. Gli spazi dei nomi possono venire e andare senza che il client sia in grado di conoscere le modifiche.
[in] lpServiceType
Puntatore a un identificatore univoco globale (GUID) che specifica il tipo del servizio di rete. Il file di intestazione Svcguid.h include definizioni di diversi tipi di servizio GUID e macro per usarli.
Il file di intestazione Svcguid.h non viene incluso automaticamente dal file di intestazione Winsock2.h.
[in, optional] lpServiceName
Puntatore a una stringa con terminazione zero che rappresenta in modo univoco il nome del servizio. Ad esempio, "MY SNA SERVER".
L'impostazione di lpServiceName su NULL equivale all'impostazione dwResolution su RES_SERVICE. La funzione opera nella seconda modalità, ottenendo l'indirizzo locale a cui deve essere associato un servizio del tipo specificato. La funzione archivia l'indirizzo locale all'interno del membro
Se
Se dwNameSpace è impostato su NS_DNS, *lpServiceName è il nome dell'host.
[in, optional] lpiProtocols
Puntatore a una matrice con terminazione zero di identificatori di protocollo. La funzione limita un tentativo di risoluzione dei nomi ai provider di spazi dei nomi che offrono questi protocolli. In questo modo il chiamante limita l'ambito della ricerca.
Se lpiProtocols è impostato su NULL, la funzione recupera informazioni su tutti i protocolli disponibili.
[in] dwResolution
Set di flag di bit che specificano aspetti del processo di risoluzione dei nomi del servizio. Vengono definiti i flag di bit seguenti.
[in, optional] lpServiceAsyncInfo
Riservato per uso futuro; deve essere impostato su NULL.
[out] lpCsaddrBuffer
Puntatore a un buffer per ricevere una o più strutture di dati CSADDR_INFO. Il numero di strutture scritte nel buffer dipende dalla quantità di informazioni trovate nel tentativo di risoluzione. È consigliabile presupporre che verranno scritte più strutture, anche se in molti casi ne sarà presente una sola.
[in, out] lpdwBufferLength
Puntatore a una variabile che, in caso di input, specifica le dimensioni, in byte, del buffer a cui punta lpCsaddrBuffer.
In caso di output, questa variabile contiene il numero totale di byte necessari per archiviare la matrice di strutture CSADDR_INFO. Se questo valore è minore o uguale al valore di input *lpdwBufferLengthe la funzione ha esito positivo, questo è il numero di byte effettivamente archiviati nel buffer. Se questo valore è maggiore del valore di input *lpdwBufferLength, il buffer era troppo piccolo e il valore di output di *lpdwBufferLength è la dimensione minima richiesta del buffer.
[in, out] lpAliasBuffer
Puntatore a un buffer per ricevere informazioni sull'alias per il servizio di rete.
Se uno spazio dei nomi supporta gli alias, la funzione archivia una matrice di stringhe di nomi con terminazione zero nel buffer a cui punta lpAliasBuffer. Alla fine dell'elenco è presente un carattere di terminazione zero doppio. Il nome nella matrice è il nome primario del servizio. I nomi che seguono sono alias. Un esempio di spazio dei nomi che supporta gli alias è DNS.
Se uno spazio dei nomi non supporta gli alias, archivia un carattere di terminazione zero doppio nel buffer.
Questo parametro è facoltativo e può essere impostato su NULL.
[in, out] lpdwAliasBufferLength
Puntatore a una variabile che, dopo l'input, specifica le dimensioni, in elementi (caratteri) del buffer a cui punta lpAliasBuffer.
In caso di output, questa variabile contiene il numero totale di elementi (caratteri) necessari per archiviare la matrice di stringhe dei nomi. Se questo valore è minore o uguale al valore di input *lpdwAliasBufferLengthe la funzione ha esito positivo, questo è il numero di elementi effettivamente archiviati nel buffer. Se questo valore è maggiore del valore di input *lpdwAliasBufferLength, il buffer era troppo piccolo e il valore di output di *lpdwAliasBufferLength è la dimensione minima richiesta del buffer.
Se lpAliasBuffer è NULL, lpdwAliasBufferLength è senza significato e può anche essere NULL.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è il numero di strutture di dati CSADDR_INFO scritte nel buffer a cui punta lpCsaddrBuffer.
Se la funzione ha esito negativo, il valore restituito è SOCKET_ERROR( -1). Per ottenere informazioni estese sull'errore, chiamare GetLastError, che restituisce il valore di errore esteso seguente.
Codice di errore | Significato |
---|---|
|
Il buffer a cui punta lpCsaddrBuffer era troppo piccolo per ricevere tutte le strutture CSADDR_INFO pertinenti. Chiamare la funzione con un buffer almeno pari al valore restituito in *lpdwBufferLength. |
Osservazioni
Questa funzione è una versione più potente della funzione gethostbyname. La funzione GetAddressByName
La funzione GetAddressByName consente a un client di ottenere un indirizzo Windows Sockets per un servizio di rete. Il client specifica il servizio di interesse in base al tipo di servizio e al nome del servizio.
Molti servizi dei nomi supportano un prefisso o un suffisso predefinito che il provider del servizio dei nomi considera durante la risoluzione dei nomi dei servizi. Ad esempio, nello spazio dei nomi DNS, se un dominio è denominato "nt.microsoft.com" e "ftp millikan" viene fornito come input, il software DNS non riesce a risolvere "millikan", ma risolve correttamente "millikan.nt.microsoft.com".
Si noti che la funzione GetAddressByName può cercare un indirizzo del servizio in due modi: all'interno di uno spazio dei nomi specifico o all'interno di un set di spazi dei nomi predefiniti. Usando uno spazio dei nomi predefinito, un amministratore può specificare che determinati spazi dei nomi verranno cercati solo se specificati in base al nome. Un amministratore o uno spazio dei nomi: il programma di installazione può anche controllare l'ordinamento delle ricerche nello spazio dei nomi.
Nota
L'intestazione nspapi.h definisce GetAddressByName 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 2000 Professional [solo app desktop] |
server minimo supportato | Windows 2000 Server [solo app desktop] |
piattaforma di destinazione | Finestre |
intestazione |
nspapi.h |
libreria |
Mswsock.lib |
dll | Mswsock.dll |