Funzione GetAddressByNameA (nspapi.h)

Articolo
03/15/2023

[GetAddressByName non è più disponibile per l'uso a partire da Windows Sockets 2. Usare invece le funzioni dettagliate in Risoluzione dei nomi indipendenti dal protocollo.]

La funzione GetAddressByName esegue una query su uno spazio dei nomi o 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 possono essere usate 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, che il sistema operativo deve eseguire query per le informazioni sull'indirizzo di rete.

Usare una delle costanti seguenti per specificare uno spazio dei nomi.

Valore	Significato
NS_DEFAULT	Set di spazi dei nomi predefiniti. La funzione esegue una query su ogni spazio dei nomi all'interno di questo set. Il set di spazi dei nomi predefiniti include in genere tutti gli spazi dei nomi installati nel sistema. Gli amministratori di sistema, tuttavia, possono escludere spazi dei nomi specifici dal set. Si tratta del valore che la maggior parte delle applicazioni deve usare per dwNameSpace.
NS_DNS	Domain Name System (DNS) usato in Internet per la risoluzione dei nomi host.
NS_NETBT	Livello NetBIOS su TCP/IP. Tutti i sistemi operativi registrano i nomi dei computer con NetBIOS. Questo spazio dei nomi viene usato per convertire un nome computer in un indirizzo IP che usa questa registrazione. Si noti che NS_NETBT può accedere a un server WINS per eseguire la risoluzione.
NS_SAP	Protocollo NetWare Service Advertising. In questo modo è possibile accedere al bindery NetWare, se appropriato. NS_SAP è uno spazio dei nomi dinamico che consente la registrazione dei servizi.
NS_TCPIP_HOSTS	Valore di ricerca nel <file systemroot>\system32\drivers\etc\host.
NS_TCPIP_LOCAL	Meccanismi di risoluzione dei nomi TCP/IP locali, inclusi i confronti con il nome host locale e cerca nomi host e indirizzi IP nella cache dell'host ai mapping degli indirizzi IP.

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 deve essere consapevole delle 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 automaticamente incluso 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 di 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 LocalAddr delle strutture CSADDR_INFO archiviate in *lpCsaddrBuffer.

Se dwResolution è impostato su RES_SERVICE, la funzione ignora il parametro lpServiceName .

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 gli aspetti del processo di risoluzione dei nomi del servizio. Vengono definiti i flag di bit seguenti.

Valore	Significato
RES_SERVICE	Se impostata, la funzione recupera l'indirizzo a cui deve essere associato un servizio del tipo specificato. Equivale a impostare il parametro lpServiceName su NULL. Se questo flag è deselezionato, si verifica una normale risoluzione dei nomi.
RES_FIND_MULTIPLE	Se questo flag è impostato, il sistema operativo esegue una ricerca estesa di tutti gli spazi dei nomi per il servizio. Chiede a ogni spazio dei nomi appropriato di risolvere il nome del servizio. Se questo flag è deselezionato, il sistema operativo smette di cercare gli indirizzi del servizio non appena ne viene trovato uno.
RES_SOFT_SEARCH	Questo flag è valido se lo spazio dei nomi supporta più livelli di ricerca. Se questo flag è valido e impostato, il sistema operativo esegue una ricerca semplice e rapida dello spazio dei nomi. Ciò è utile se un'applicazione deve ottenere solo indirizzi facili da trovare per il servizio. Se questo flag è valido e chiaro, il sistema operativo esegue una ricerca più estesa dello spazio dei nomi.

Valore

Significato

RES_SERVICE

Se impostata, la funzione recupera l'indirizzo a cui deve essere associato un servizio del tipo specificato. Equivale a impostare il parametro lpServiceName su NULL.

Se questo flag è deselezionato, si verifica una normale risoluzione dei nomi.

RES_FIND_MULTIPLE

Se questo flag è impostato, il sistema operativo esegue una ricerca estesa di tutti gli spazi dei nomi per il servizio. Chiede a ogni spazio dei nomi appropriato di risolvere il nome del servizio. Se questo flag è deselezionato, il sistema operativo smette di cercare gli indirizzi del servizio non appena ne viene trovato uno.

RES_SOFT_SEARCH

Questo flag è valido se lo spazio dei nomi supporta più livelli di ricerca.

Se questo flag è valido e impostato, il sistema operativo esegue una ricerca semplice e rapida dello spazio dei nomi. Ciò è utile se un'applicazione deve ottenere solo indirizzi facili da trovare per il servizio.

Se questo flag è valido e chiaro, il sistema operativo esegue una ricerca più estesa dello spazio dei nomi.

[in, optional] lpServiceAsyncInfo

Riservato per l'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. Si supponga che più strutture verranno scritte, anche se in molti casi ci sarà solo una.

[in, out] lpdwBufferLength

Puntatore a una variabile che, dopo l'input, specifica le dimensioni, in byte, del buffer a cui punta lpCsaddrBuffer.

Dopo l'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 di *lpdwBufferLength e la funzione ha esito positivo, questo è il numero di byte effettivamente archiviati nel buffer. Se questo valore è maggiore del valore di input di *lpdwBufferLength, il buffer era troppo piccolo e il valore di output di *lpdwBufferLength è la dimensione minima del buffer richiesto.

[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. C'è un doppio terminatore zero alla fine dell'elenco. Il primo nome nella matrice è il nome primario del servizio. I nomi che seguono sono alias. Un esempio di spazio dei nomi che supporta alias è DNS.

Se uno spazio dei nomi non supporta gli alias, archivia un doppio terminatore zero 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, negli elementi (caratteri) del buffer a cui punta lpAliasBuffer.

Dopo l'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 di *lpdwAliasBufferLength e la funzione ha esito positivo, questo è il numero di elementi effettivamente archiviati nel buffer. Se questo valore è maggiore del valore di input di *lpdwAliasBufferLength, il buffer era troppo piccolo e il valore di output di *lpdwAliasBufferLength è la dimensione minima necessaria 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 sull'errore estese, chiamare GetLastError, che restituisce il valore di errore esteso seguente.

Codice di errore	Significato
ERROR_INSUFFICIENT_BUFFER	Il buffer a cui punta lpCsaddrBuffer era troppo piccolo per ricevere tutte le strutture CSADDR_INFO pertinenti. Chiamare la funzione con un buffer pari almeno al valore restituito in *lpdwBufferLength.

Commenti

Questa funzione è una versione più potente della funzione gethostbyname . La funzione GetAddressByName funziona con più servizi dei nomi.

Nota La funzione gethostbyname è stata deprecata dall'introduzione della funzione getaddrinfo . Gli sviluppatori che creano applicazioni Windows Sockets 2 sono invitati a usare la funzione getaddrinfo anziché gethostbyname.

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 predefinito o un suffisso che il provider di servizi 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	nspapi.h
Libreria	Mswsock.lib
DLL	Mswsock.dll