Freigeben über


GetServiceA-Funktion (nspapi.h)

Die GetService-Funktion ruft Informationen zu einem Netzwerkdienst im Kontext einer Gruppe von Standardnamespaces oder einem angegebenen Namespace ab. Der Netzwerkdienst wird durch seinen Typ und Namen angegeben. Die Informationen über den Dienst werden als Satz von NS_SERVICE_INFO Datenstrukturen abgerufen.

Hinweis Die GetService-Funktion ist eine Microsoft-spezifische Erweiterung der Windows Sockets 1.1-Spezifikation. Diese Funktion ist veraltet. Zur Vereinfachung von Windows Sockets 1.1-Entwicklern ist dieses Referenzmaterial enthalten.
 
Hinweis Die unter Protokollunabhängige Namensauflösung beschriebenen Funktionen bieten entsprechende Funktionen in Windows Sockets 2.
 

Syntax

INT GetServiceA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpGuid,
  [in]           LPSTR                lpServiceName,
  [in]           DWORD                dwProperties,
  [out]          LPVOID               lpBuffer,
  [in, out]      LPDWORD              lpdwBufferSize,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo
);

Parameter

[in] dwNameSpace

Der Namespace oder eine Reihe von Standardnamespaces, die das Betriebssystem nach Informationen über den angegebenen Netzwerkdienst abfragen soll.

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

Wert Bedeutung
NS_DEFAULT
Ein Satz von Standardnamespaces. Das Betriebssystem fragt jeden Namespace innerhalb dieses Satzes ab. Der Satz von Standardnamespaces umfasst in der Regel alle Namespaces, die auf dem System installiert sind. Systemadministratoren können jedoch bestimmte Namespaces aus dem Satz ausschließen. NS_DEFAULT ist der Wert, den die meisten Anwendungen für dwNameSpace verwenden sollten.
NS_DNS
Das Domänennamensystem, das im Internet für die Hostnamenauflösung verwendet wird.
NS_NETBT
Die NetBIOS-Ebene über TCP/IP. Alle Betriebssysteme registrieren ihre Computernamen bei NetBIOS. Dieser Namespace wird verwendet, um mithilfe dieser Registrierung einen Computernamen in eine IP-Adresse aufzulösen. Beachten Sie, dass NS_NETBT auf einen WINS-Server zugreifen können, um die Auflösung auszuführen.
NS_SAP
Das NetWare Service Advertising-Protokoll. Dies kann ggf. auf die NetWare-Bindery zugreifen. NS_SAP ist ein dynamischer Namespace, der die Registrierung von Diensten ermöglicht.
NS_TCPIP_HOSTS
Sucht hostnamen und IP-Adressen in der <Datei systemroot>\system32\drivers\etc\hosts.
NS_TCPIP_LOCAL
Lokale TCP/IP-Namensauflösungsmechanismen, einschließlich Vergleichen mit dem lokalen Hostnamen und Suchen nach Hostnamen und IP-Adressen im Cache von Host-zu-IP-Adresszuordnungen.
 

Die meisten Aufrufe von GetService sollten den speziellen Wert NS_DEFAULT verwenden. Dadurch kommt ein Client aus, ohne die verfügbaren Namespaces in einem Internetwork zu kennen. Der Systemadministrator bestimmt den Namespacezugriff. Namespaces können kommen und gehen, ohne dass der Client die Änderungen beachten muss.

[in] lpGuid

Ein Zeiger auf einen global eindeutigen Bezeichner (Globally Unique Identifier, GUID), der den Typ des Netzwerkdiensts angibt. Die Headerdatei Svcguid.h enthält GUID-Diensttypen aus vielen bekannten Diensten innerhalb der DNS- und SAP-Namespaces.

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

[in] lpServiceName

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

[in] dwProperties

Ein Satz von Bitflags, die die Dienstinformationen angeben, die die Funktion abruft. Jede dieser Bitflagskonstanten entspricht außer PROP_ALL einem bestimmten Member der SERVICE_INFO Datenstruktur. Wenn das Flag festgelegt ist, fügt die Funktion Informationen in den entsprechenden Member der in *lpBuffer gespeicherten Datenstrukturen ein. Die folgenden Bitflags sind definiert.

Wert Bedeutung
PROP_COMMENT
Wenn dieses Flag festgelegt ist, speichert die Funktion Daten im lpComment-Member der in *lpBuffer gespeicherten Datenstrukturen.
PROP_LOCALE
Wenn dieses Flag festgelegt ist, speichert die Funktion Daten im lpLocale-Member der in *lpBuffer gespeicherten Datenstrukturen.
PROP_DISPLAY_HINT
Wenn dieses Flag festgelegt ist, speichert die Funktion Daten im dwDisplayHint-Member der in *lpBuffer gespeicherten Datenstrukturen.
PROP_VERSION
Wenn dieses Flag festgelegt ist, speichert die Funktion Daten im dwVersion-Member der in *lpBuffer gespeicherten Datenstrukturen.
PROP_START_TIME
Wenn dieses Flag festgelegt ist, speichert die Funktion Daten im dwTime-Member der in *lpBuffer gespeicherten Datenstrukturen.
PROP_MACHINE
Wenn dieses Flag festgelegt ist, speichert die Funktion Daten im lpMachineName-Member der in *lpBuffer gespeicherten Datenstrukturen.
PROP_ADDRESSES
Wenn dieses Flag festgelegt ist, speichert die Funktion Daten im lpServiceAddress-Member der in *lpBuffer gespeicherten Datenstrukturen.
PROP_SD
Wenn dieses Flag festgelegt ist, speichert die Funktion Daten im ServiceSpecificInfo-Member der in *lpBuffer gespeicherten Datenstrukturen.
PROP_ALL
Wenn dieses Flag festgelegt ist, speichert die Funktion Daten in allen Membern der Datenstrukturen, die in *lpBuffer gespeichert sind.

[out] lpBuffer

Ein Zeiger auf einen Puffer zum Empfangen eines Arrays von NS_SERVICE_INFO Strukturen und zugeordneten Dienstinformationen. Jede NS_SERVICE_INFO-Struktur enthält Dienstinformationen im Kontext eines bestimmten Namespaces. Wenn dwNameSpace NS_DEFAULT ist, speichert die Funktion mehr als eine Struktur im Puffer. Andernfalls wird nur eine Struktur gespeichert.

Jede NS_SERVICE_INFO-Struktur enthält eine SERVICE_INFO-Struktur . Die Member dieser SERVICE_INFO Strukturen enthalten gültige Daten basierend auf den Bitflags, die im dwProperties-Parameter festgelegt sind. Wenn das entsprechende Bitflag eines Members in dwProperties nicht festgelegt ist, ist der Wert des Members undefiniert.

Die Funktion speichert die NS_SERVICE_INFO Strukturen in einem aufeinander folgenden Array, beginnend am Anfang des Puffers. Die Zeiger in der enthaltenen SERVICE_INFO-Strukturen verweisen auf Informationen, die im Puffer zwischen dem Ende der NS_SERVICE_INFO Strukturen und dem Ende des Puffers gespeichert sind.

[in, out] lpdwBufferSize

Ein Zeiger auf eine Variable, die bei der Eingabe die Größe des Puffers in Bytes enthält, auf den lpBuffer verweist. Bei der Ausgabe enthält diese Variable die Anzahl von Bytes, die zum Speichern der angeforderten Informationen erforderlich sind. Wenn dieser Ausgabewert größer als der Eingabewert ist, ist die Funktion aufgrund einer unzureichenden Puffergröße fehlgeschlagen.

[in, optional] lpServiceAsyncInfo

Für die zukünftige Verwendung reserviert. Muss auf NULL festgelegt werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Anzahl der NS_SERVICE_INFO Strukturen, die in *lpBuffer gespeichert sind. Null gibt an, dass keine Strukturen gespeichert wurden.

Wenn die Funktion fehlschlägt, ist der Rückgabewert SOCKET_ERROR ( – 1). Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf, wodurch einer der folgenden erweiterten Fehlerwerte zurückgegeben wird.

Fehlercode Bedeutung
ERROR_INSUFFICIENT_BUFFER
Der Puffer, auf den lpBuffer verweist, ist zu klein, um alle angeforderten Informationen zu empfangen. Rufen Sie die Funktion mit einem Puffer auf, der mindestens so groß ist wie der in *lpdwBufferSize zurückgegebene Wert.
ERROR_SERVICE_NOT_FOUND
Der angegebene Dienst wurde nicht gefunden, oder der angegebene Namespace wird nicht verwendet. Der Rückgabewert der Funktion ist in diesem Fall null.

Hinweise

Hinweis

Der nspapi.h-Header definiert GetService 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

NS_SERVICE_INFO

SERVICE_INFO

SetService

Winsock-Funktionen

Winsock-Referenz