GetAddressByNameW-Funktion (nspapi.h)

Artikel
11/20/2024

[GetAddressByName- ist nicht mehr für die Verwendung ab Windows Sockets 2 verfügbar. Verwenden Sie stattdessen die in Protocol-Independent Namensauflösungbeschriebenen Funktionen.]

Die GetAddressByName-Funktion fragt einen Namespace oder eine Reihe von Standardnamespaces ab, um Netzwerkadresseninformationen für einen angegebenen Netzwerkdienst abzurufen. Dieser Prozess wird als Dienstnamenauflösung bezeichnet. Ein Netzwerkdienst kann die Funktion auch verwenden, um lokale Adressinformationen abzurufen, die er mit der Bindung Funktion verwenden kann.

Syntax

INT GetAddressByNameW(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpServiceType,
  [in, optional] LPWSTR               lpServiceName,
  [in, optional] LPINT                lpiProtocols,
  [in]           DWORD                dwResolution,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
  [out]          LPVOID               lpCsaddrBuffer,
  [in, out]      LPDWORD              lpdwBufferLength,
  [in, out]      LPWSTR               lpAliasBuffer,
  [in, out]      LPDWORD              lpdwAliasBufferLength
);

Parameter

[in] dwNameSpace

Der Namespace oder der Satz von Standardnamespaces, den das Betriebssystem nach Netzwerkadresseninformationen abfragen soll.

Verwenden Sie eine der folgenden Konstanten, um einen Namespace anzugeben.

Wert	Bedeutung
NS_DEFAULT	Eine Reihe von Standardnamespaces. Die Funktion fragt jeden Namespace innerhalb dieses Satzes ab. Der Satz von Standardnamespaces enthält in der Regel alle namespaces, die auf dem System installiert sind. Systemadministratoren können jedoch bestimmte Namespaces aus der Gruppe ausschließen. Dies ist der Wert, den die meisten Anwendungen für dwNameSpace-verwenden sollten.
NS_DNS	Das im Internet verwendete DNS (Domain Name System) für die Auflösung von Hostnamen.
NS_NETBT	NetBIOS über TCP/IP-Ebene. Alle Betriebssysteme registrieren ihre Computernamen bei NetBIOS. Dieser Namespace wird verwendet, um einen Computernamen in eine IP-Adresse zu konvertieren, die diese Registrierung verwendet. Beachten Sie, dass NS_NETBT auf einen WINS-Server zugreifen kann, um die Auflösung auszuführen.
NS_SAP	Das NetWare Service Advertising-Protokoll. Dies kann bei Bedarf auf die NetWare-Sammelmappe zugreifen. NS_SAP ist ein dynamischer Namespace, der die Registrierung von Diensten zulässt.
NS_TCPIP_HOSTS	Nachschlagewert in der Datei <systemroot>\system32\drivers\etc\hosts.
NS_TCPIP_LOCAL	Lokale TCP/IP-Namensauflösungsmechanismen, einschließlich Vergleiche mit dem lokalen Hostnamen und nach Hostnamen und IP-Adressen im Cache des Hosts zu IP-Adresszuordnungen.

Die meisten Aufrufe von GetAddressByName sollten den speziellen Wert NS_DEFAULT verwenden. Auf diese Weise kann ein Client ohne Wissen wissen, welche Namespaces in einem Internetwork verfügbar sind. Der Systemadministrator bestimmt den Namespacezugriff. Namespaces können kommen und gehen, ohne dass der Client die Änderungen beachten muss.

[in] lpServiceType

Ein Zeiger auf einen global eindeutigen Bezeichner (GUID), der den Typ des Netzwerkdiensts angibt. Die Headerdatei "Svcguid.h" enthält Definitionen mehrerer GUID-Diensttypen und Makros zum Arbeiten mit ihnen.

Die Headerdatei "Svcguid.h" wird nicht automatisch von der Winsock2.h-Headerdatei eingeschlossen.

[in, optional] lpServiceName

Ein Zeiger auf eine mit Null beendete Zeichenfolge, die den Dienstnamen eindeutig darstellt. Beispiel: "MY SNA SERVER".

Das Festlegen lpServiceName- auf NULL- entspricht dem Festlegen dwResolution- auf RES_SERVICE. Die Funktion wird im zweiten Modus ausgeführt und erhält die lokale Adresse, an die ein Dienst des angegebenen Typs gebunden werden soll. Die Funktion speichert die lokale Adresse innerhalb des LocalAddr Member der in *lpCsaddrBuffergespeicherten CSADDR_INFO Strukturen.

Wenn dwResolution- auf RES_SERVICE festgelegt ist, ignoriert die Funktion den parameter lpServiceName.

Wenn dwNameSpace- auf NS_DNS festgelegt ist, ist *lpServiceName der Name des Hosts.

[in, optional] lpiProtocols

Ein Zeiger auf ein null-beendetes Array von Protokollbezeichnern. Die Funktion schränkt einen Namensauflösungsversuch auf Namespaceanbieter ein, die diese Protokolle anbieten. Auf diese Weise kann der Aufrufer den Umfang der Suche einschränken.

Wenn lpiProtocols auf NULL-festgelegt ist, ruft die Funktion Informationen zu allen verfügbaren Protokollen ab.

[in] dwResolution

Eine Reihe von Bitkennzeichnungen, die Aspekte des Prozesses zur Auflösung von Dienstnamen angeben. Die folgenden Bitkennzeichnungen werden definiert.

Wert	Bedeutung
RES_SERVICE	Wenn festgelegt, ruft die Funktion die Adresse ab, an die ein Dienst des angegebenen Typs gebunden werden soll. Dies entspricht dem Festlegen des lpServiceName--Parameters auf NULL-. Wenn dieses Kennzeichen klar ist, tritt die normale Namensauflösung auf.
RES_FIND_MULTIPLE	Wenn dieses Flag festgelegt ist, führt das Betriebssystem eine umfangreiche Suche aller Namespaces für den Dienst durch. Er fordert jeden geeigneten Namespace auf, den Dienstnamen aufzulösen. Wenn dieses Kennzeichen eindeutig ist, sucht das Betriebssystem nicht mehr nach Dienstadressen, sobald eine gefunden wird.
RES_SOFT_SEARCH	Dieses Kennzeichen ist gültig, wenn der Namespace mehrere Suchebenen unterstützt. Wenn dieses Kennzeichen gültig und festgelegt ist, führt das Betriebssystem eine einfache und schnelle Suche des Namespace durch. Dies ist nützlich, wenn eine Anwendung nur leicht zu findende Adressen für den Dienst abrufen muss. Wenn dieses Kennzeichen gültig und eindeutig ist, führt das Betriebssystem eine umfangreichere Suche des Namespace durch.

Wert

Bedeutung

RES_SERVICE

Wenn festgelegt, ruft die Funktion die Adresse ab, an die ein Dienst des angegebenen Typs gebunden werden soll. Dies entspricht dem Festlegen des lpServiceName--Parameters auf NULL-.

Wenn dieses Kennzeichen klar ist, tritt die normale Namensauflösung auf.

RES_FIND_MULTIPLE

Wenn dieses Flag festgelegt ist, führt das Betriebssystem eine umfangreiche Suche aller Namespaces für den Dienst durch. Er fordert jeden geeigneten Namespace auf, den Dienstnamen aufzulösen. Wenn dieses Kennzeichen eindeutig ist, sucht das Betriebssystem nicht mehr nach Dienstadressen, sobald eine gefunden wird.

RES_SOFT_SEARCH

Dieses Kennzeichen ist gültig, wenn der Namespace mehrere Suchebenen unterstützt.

Wenn dieses Kennzeichen gültig und festgelegt ist, führt das Betriebssystem eine einfache und schnelle Suche des Namespace durch. Dies ist nützlich, wenn eine Anwendung nur leicht zu findende Adressen für den Dienst abrufen muss.

Wenn dieses Kennzeichen gültig und eindeutig ist, führt das Betriebssystem eine umfangreichere Suche des Namespace durch.

[in, optional] lpServiceAsyncInfo

Reserviert für die zukünftige Nutzung; muss auf NULL-festgelegt werden.

[out] lpCsaddrBuffer

Ein Zeiger auf einen Puffer, um eine oder mehrere CSADDR_INFO Datenstrukturen zu empfangen. Die Anzahl der in den Puffer geschriebenen Strukturen hängt von der Menge der Informationen ab, die im Lösungsversuch gefunden wurden. Sie sollten davon ausgehen, dass mehrere Strukturen geschrieben werden, obwohl in vielen Fällen nur eine vorhanden sein wird.

[in, out] lpdwBufferLength

Ein Zeiger auf eine Variable, die bei eingabe die Größe des Puffers in Bytes angibt, auf den lpCsaddrBufferverweist.

Bei der Ausgabe enthält diese Variable die Gesamtanzahl der Bytes, die zum Speichern des Arrays von CSADDR_INFO Strukturen erforderlich sind. Wenn dieser Wert kleiner oder gleich dem Eingabewert von *lpdwBufferLengthist und die Funktion erfolgreich ist, ist dies die Anzahl der Bytes, die tatsächlich im Puffer gespeichert sind. Wenn dieser Wert größer als der Eingabewert von *lpdwBufferLengthist, war der Puffer zu klein, und der Ausgabewert von *lpdwBufferLength ist die minimale erforderliche Puffergröße.

[in, out] lpAliasBuffer

Ein Zeiger auf einen Puffer zum Empfangen von Aliasinformationen für den Netzwerkdienst.

Wenn ein Namespace Aliase unterstützt, speichert die Funktion ein Array von Zeichenfolgen mit nullen beendeten Namen in dem Puffer, auf den durch lpAliasBufferverwiesen wird. Am Ende der Liste befindet sich ein doppelter Null-Terminator. Der Vorname im Array ist der primäre Name des Diensts. Folgende Namen sind Aliase. Ein Beispiel für einen Namespace, der Aliase unterstützt, ist DNS.

Wenn ein Namespace aliase nicht unterstützt, speichert er einen doppelten Null-Terminator im Puffer.

Dieser Parameter ist optional und kann auf NULL-festgelegt werden.

[in, out] lpdwAliasBufferLength

Ein Zeiger auf eine Variable, die bei eingabe die Größe des Puffers in Elementen (Zeichen) angibt, auf die durch lpAliasBufferverwiesen wird.

Bei der Ausgabe enthält diese Variable die Gesamtanzahl der Elemente (Zeichen), die zum Speichern des Arrays von Namenszeichenfolgen erforderlich sind. Wenn dieser Wert kleiner oder gleich dem Eingabewert von *lpdwAliasBufferLengthist und die Funktion erfolgreich ist, ist dies die Anzahl der Elemente, die tatsächlich im Puffer gespeichert sind. Wenn dieser Wert größer als der Eingabewert von *lpdwAliasBufferLengthist, war der Puffer zu klein, und der Ausgabewert von *lpdwAliasBufferLength ist die minimale erforderliche Puffergröße.

Wenn lpAliasBufferNULList, ist lpdwAliasBufferLength bedeutungslos und kann auch NULL-sein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Anzahl der CSADDR_INFO Datenstrukturen, die in den Puffer geschrieben wurden, auf lpCsaddrBufferverweist.

Wenn die Funktion fehlschlägt, ist der Rückgabewert SOCKET_ERROR( –1). Rufen Sie zum Abrufen erweiterter Fehlerinformationen GetLastErrorauf, der den folgenden erweiterten Fehlerwert zurückgibt.

Fehlercode	Bedeutung
ERROR_INSUFFICIENT_BUFFER	Der Puffer, auf den lpCsaddrBuffer verweist, war zu klein, um alle relevanten CSADDR_INFO Strukturen zu erhalten. Rufen Sie die Funktion mit einem Puffer mindestens so groß auf, wie der in *lpdwBufferLengthzurückgegebene Wert.

Bemerkungen

Diese Funktion ist eine leistungsfähigere Version der gethostbyname-Funktion. Die GetAddressByName--Funktion funktioniert mit mehreren Namendiensten.

Hinweis Die funktion gethostbyname wurde durch die Einführung der getaddrinfo-Funktion veraltet. Entwickler, die Windows Sockets 2-Anwendungen erstellen, werden dringend aufgefordert, die getaddrinfo-Funktion anstelle gethostbynamezu verwenden.

Mit der GetAddressByName--Funktion kann ein Client eine Windows Sockets-Adresse für einen Netzwerkdienst abrufen. Der Client gibt den zugehörigen Diensttyp und Dienstnamen an.

Viele Namendienste unterstützen ein Standardpräfix oder Suffix, das der Namensdienstanbieter beim Auflösen von Dienstnamen berücksichtigt. Wenn beispielsweise im DNS-Namespace eine Domäne mit dem Namen "nt.microsoft.com" und "ftp millikan" als Eingabe bereitgestellt wird, kann die DNS-Software "millikan" nicht auflösen, aber erfolgreich "millikan.nt.microsoft.com" auflösen.

Beachten Sie, dass die GetAddressByName-funktion auf zwei Arten nach einer Dienstadresse suchen kann: innerhalb eines bestimmten Namespaces oder innerhalb einer Reihe von Standardnamespaces. Mithilfe eines Standardnamespaces kann ein Administrator angeben, dass bestimmte Namespaces nur nach Dienstadressen durchsucht werden, wenn er durch den Namen angegeben wird. Ein Administrator oder Namespace – Das Setupprogramm kann auch die Sortierung von Namespacesuchen steuern.

Anmerkung

Der nspapi.h-Header definiert GetAddressByName als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	nspapi.h
Library	Mswsock.lib
DLL-	Mswsock.dll

Siehe auch

Freigeben über