GetServiceA-Funktion (nspapi.h)
Die GetService--Funktion ruft Informationen zu einem Netzwerkdienst im Kontext einer Reihe von Standardnamespaces oder einem angegebenen Namespace ab. Der Netzwerkdienst wird durch den Typ und den Namen angegeben. Die Informationen zum Dienst werden als Eine Reihe von NS_SERVICE_INFO Datenstrukturen abgerufen.
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, den das Betriebssystem nach Informationen zum angegebenen Netzwerkdienst abfragen soll.
Verwenden Sie eine der folgenden Konstanten, um einen Namespace anzugeben.
Die meisten Aufrufe von GetService- sollten den speziellen Wert NS_DEFAULT verwenden. Auf diese Weise kann ein Client zugreifen, ohne verfügbare 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 (GUID), der den Typ des Netzwerkdiensts angibt. Die Svcguid.h Headerdatei enthält GUID-Diensttypen aus vielen bekannten Diensten innerhalb der DNS- und SAP-Namespaces.
Die Svcguid.h Headerdatei wird nicht automatisch von der Winsock2.h Headerdatei eingeschlossen.
[in] lpServiceName
Ein Zeiger auf eine mit Null beendete Zeichenfolge, die den Dienstnamen eindeutig darstellt. Beispiel: "MY SNA SERVER".
[in] dwProperties
Eine Reihe von Bitkennzeichnungen, die die Dienstinformationen angeben, die von der Funktion abgerufen werden. Jede dieser Bitkennzeichnungskonstanten, außer PROP_ALL, entspricht einem bestimmten Element der SERVICE_INFO Datenstruktur. Wenn die Kennzeichnung festgelegt ist, fügt die Funktion Informationen in das entsprechende Element der datenstrukturen ein, die in *lpBuffergespeichert sind. Die folgenden Bitkennzeichnungen werden definiert.
[out] lpBuffer
Ein Zeiger auf einen Puffer, um ein Array von NS_SERVICE_INFO Strukturen und zugehörigen Dienstinformationen zu empfangen. Jede NS_SERVICE_INFO Struktur enthält Dienstinformationen im Kontext eines bestimmten Namespaces. Wenn dwNameSpace- NS_DEFAULT ist, speichert die Funktion mehrere Strukturen 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 Bitkennzeichnungen, die im dwProperties Parameter festgelegt sind. Wenn das entsprechende Bit-Flag eines Elements in dwPropertiesnicht festgelegt ist, ist der Wert des Elements nicht definiert.
Die Funktion speichert die NS_SERVICE_INFO Strukturen in einem aufeinander folgenden Array, beginnend am Anfang des Puffers. Die Zeiger in den 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 die durch lpBufferverwiesen wird. Bei der Ausgabe enthält diese Variable die Anzahl der Bytes, die zum Speichern der angeforderten Informationen erforderlich sind. Wenn dieser Ausgabewert größer als der Eingabewert ist, ist die Funktion aufgrund unzureichender Puffergröße fehlgeschlagen.
[in, optional] lpServiceAsyncInfo
Reserviert für die zukünftige Verwendung. Muss auf NULL-festgelegt sein.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Anzahl der in *lpBuffergespeicherten NS_SERVICE_INFO Strukturen. Null gibt an, dass keine Strukturen gespeichert wurden.
Wenn die Funktion fehlschlägt, ist der Rückgabewert SOCKET_ERROR ( – 1). Rufen Sie zum Abrufen erweiterter Fehlerinformationen GetLastErrorauf, der einen der folgenden erweiterten Fehlerwerte zurückgibt.
| Fehlercode | Bedeutung |
|---|---|
|
Der Puffer, auf den lpBuffer verweist ist zu klein, um alle angeforderten Informationen zu erhalten. Rufen Sie die Funktion mit einem Puffer mindestens so groß auf, wie der in *lpdwBufferSizezurückgegebene Wert. |
|
Der angegebene Dienst wurde nicht gefunden, oder der angegebene Namespace wird nicht verwendet. Der Rückgabewert der Funktion ist in diesem Fall null. |
Bemerkungen
Anmerkung
Der nspapi.h-Header definiert GetService 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 |