Condividi tramite


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.

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 determinati spazi dei nomi dal set. Questo è il 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
NetBIOS sul livello 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\hosts.
NS_TCPIP_LOCAL
Meccanismi di risoluzione dei nomi TCP/IP locali, inclusi i confronti con il nome host locale e cerca i nomi host e gli indirizzi IP nella cache dei mapping degli indirizzi IP dell'host.
 

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 LocalAddr delle strutture di 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 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 è chiaro, si verifica una normale risoluzione dei nomi.

RES_FIND_MULTIPLE
Se questo flag è impostato, il sistema operativo esegue una ricerca completa 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 è chiaro, 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 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
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 almeno pari al valore restituito in *lpdwBufferLength.

Osservazioni

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 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 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

Vedere anche

CSADDR_INFO

Funzioni Winsock

di riferimento winsock

getaddrinfo

gethostbyname