GetAddressByNameA-Funktion (nspapi.h)

Artikel
08/25/2023

[GetAddressByName ist ab Windows Sockets 2 nicht mehr verfügbar. Verwenden Sie stattdessen die Funktionen, die unter Protokollunabhängige Namensauflösung beschrieben sind.]

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 Bindungsfunktion verwenden kann.

Syntax

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

Parameter

[in] dwNameSpace

Der Namespace oder die 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 in diesem Satz ab. Der Satz von Standardnamespaces umfasst 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 Domain Name System (DNS), das im Internet für die Hostnamenauflösung verwendet wird.
NS_NETBT	Die 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 können, um die Auflösung auszuführen.
NS_SAP	Das NetWare Service Advertising Protocol. Dies kann ggf. auf die NetWare-Binderie zugreifen. NS_SAP ist ein dynamischer Namespace, der die Registrierung von Diensten ermöglicht.
NS_TCPIP_HOSTS	Suchwert in der <Datei systemroot>\system32\drivers\etc\hosts.
NS_TCPIP_LOCAL	Lokale TCP/IP-Namensauflösungsmechanismen, einschließlich Vergleiche mit dem lokalen Hostnamen und Suchen nach Hostnamen und IP-Adressen im Cache von Host-zu-IP-Adresszuordnungen.

Die meisten Aufrufe von GetAddressByName sollten den speziellen Wert NS_DEFAULT verwenden. Dadurch kann ein Client ohne Kenntnis davon auskommen, 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 Globally Unique Identifier (GUID), der den Typ des Netzwerkdiensts angibt. Die Headerdatei Svcguid.h enthält Definitionen mehrerer GUID-Diensttypen und Makros für die Arbeit mit ihnen.

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

[in, optional] lpServiceName

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

Das Festlegen von lpServiceName auf NULL entspricht dem Festlegen von dwResolution auf RES_SERVICE. Die Funktion arbeitet im zweiten Modus und bezieht die lokale Adresse, an die ein Dienst des angegebenen Typs gebunden werden soll. Die Funktion speichert die lokale Adresse im LocalAddr-Member der CSADDR_INFO Strukturen, die in *lpCsaddrBuffer gespeichert sind.

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

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. Dadurch kann der Aufrufer den Suchbereich einschränken.

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

[in] dwResolution

Eine Reihe von Bitflags, die Aspekte des Dienstnamenauflösungsprozesses angeben. Die folgenden Bitflags 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 Flag klar ist, tritt die normale Namensauflösung auf.
RES_FIND_MULTIPLE	Wenn dieses Flag festgelegt ist, führt das Betriebssystem eine umfangreiche Suche nach allen Namespaces für den Dienst durch. Er fordert jeden geeigneten Namespace auf, den Dienstnamen aufzulösen. Wenn dieses Flag eindeutig ist, hört das Betriebssystem auf, nach Dienstadressen zu suchen, sobald eine gefunden wird.
RES_SOFT_SEARCH	Dieses Flag ist gültig, wenn der Namespace mehrere Suchebenen unterstützt. Wenn dieses Flag gültig und festgelegt ist, führt das Betriebssystem eine einfache und schnelle Suche nach dem Namespace durch. Dies ist nützlich, wenn eine Anwendung nur leicht auffindbare Adressen für den Dienst abrufen muss. Wenn dieses Flag gültig und eindeutig ist, führt das Betriebssystem eine ausführlichere Suche nach dem 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 Flag klar ist, tritt die normale Namensauflösung auf.

RES_FIND_MULTIPLE

Wenn dieses Flag festgelegt ist, führt das Betriebssystem eine umfangreiche Suche nach allen Namespaces für den Dienst durch. Er fordert jeden geeigneten Namespace auf, den Dienstnamen aufzulösen. Wenn dieses Flag eindeutig ist, hört das Betriebssystem auf, nach Dienstadressen zu suchen, sobald eine gefunden wird.

RES_SOFT_SEARCH

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

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

Wenn dieses Flag gültig und eindeutig ist, führt das Betriebssystem eine ausführlichere Suche nach dem Namespace durch.

[in, optional] lpServiceAsyncInfo

Reserviert für zukünftige Verwendung; 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 beim Lösungsversuch gefundenen Informationen ab. Sie sollten davon ausgehen, dass mehrere Strukturen geschrieben werden, obwohl es in vielen Fällen nur eine geben wird.

[in, out] lpdwBufferLength

Ein Zeiger auf eine Variable, die bei der Eingabe die Größe des Puffers in Bytes angibt, auf den von lpCsaddrBuffer verwiesen wird.

Bei der Ausgabe enthält diese Variable die Gesamtzahl der Bytes, die zum Speichern des Arrays von CSADDR_INFO Strukturen erforderlich sind. Wenn dieser Wert kleiner oder gleich dem Eingabewert von *lpdwBufferLength ist und die Funktion erfolgreich ist, ist dies die Anzahl der tatsächlich im Puffer gespeicherten Bytes. Wenn dieser Wert größer als der Eingabewert von *lpdwBufferLength ist, 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 null beendeten Namen in dem Puffer, auf den lpAliasBuffer verweist. Am Ende der Liste befindet sich ein doppelter 00-Endator. 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 keine Aliase unterstützt, speichert er einen doppelten Nullabschluss im Puffer.

Dieser Parameter ist optional und kann auf NULL festgelegt werden.

[in, out] lpdwAliasBufferLength

Ein Zeiger auf eine Variable, die bei der Eingabe die Größe des Puffers in Elementen (Zeichen) angibt, auf den lpAliasBuffer verweist.

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

Wenn lpAliasBufferNULL ist, ist lpdwAliasBufferLength bedeutungslos und kann auch NULL sein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Anzahl CSADDR_INFO Datenstrukturen, die in den Puffer geschrieben werden, auf den lpCsaddrBuffer verweist.

Wenn die Funktion fehlschlägt, ist der Rückgabewert SOCKET_ERROR( –1). Um erweiterte Fehlerinformationen abzurufen, rufen Sie GetLastError auf, wodurch der folgende erweiterte Fehlerwert zurückgegeben wird.

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

Hinweise

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

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

Mit der GetAddressByName-Funktion kann ein Client eine Windows Sockets-Adresse für einen Netzwerkdienst abrufen. Der Client gibt den relevanten Dienst anhand seines Diensttyps und Dienstnamens 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 "millikan.nt.microsoft.com" erfolgreich 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 sie durch den Namen angegeben werden. Ein Administrator oder Namespace: Das Setupprogramm kann auch die Reihenfolge von Namespacesuchen steuern.

Hinweis

Der nspapi.h-Header definiert GetAddressByName als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch 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
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	nspapi.h
Bibliothek	Mswsock.lib
DLL	Mswsock.dll

Weitere Informationen