WSAAsyncGetServByPort-Funktion (winsock.h)
Die WSAAsyncGetServByPort-Funktion ruft asynchron Dienstinformationen ab, die einem Port und Protokoll entsprechen.
Syntax
HANDLE WSAAsyncGetServByPort(
[in] HWND hWnd,
[in] u_int wMsg,
[in] int port,
[in] const char *proto,
[out] char *buf,
[in] int buflen
);
Parameter
[in] hWnd
Handle des Fensters, das nach Abschluss der asynchronen Anforderung eine Nachricht erhalten soll.
[in] wMsg
Nachricht, die empfangen werden soll, wenn die asynchrone Anforderung abgeschlossen ist.
[in] port
Port für den Dienst in Netzwerkbytereihenfolge.
[in] proto
Zeiger auf einen Protokollnamen. Dies kann NULL sein. In diesem Fall sucht WSAAsyncGetServByPort nach dem ersten Diensteintrag, für den s_port mit dem angegebenen Port übereinstimmen. Andernfalls entspricht WSAAsyncGetServByPort sowohl port als auch proto.
[out] buf
Zeiger auf den Datenbereich, um die Serventdaten zu empfangen. Der Datenbereich muss größer als die Größe einer Serventstruktur sein, da der Datenbereich von Windows Sockets verwendet wird, um eine Serventstruktur und alle Daten zu enthalten, auf die von Membern der Servent-Struktur verwiesen wird. Ein Puffer von MAXGETHOSTSTRUCT-Bytes wird empfohlen.
[in] buflen
Größe des Datenbereichs für den buf-Parameter in Bytes.
Rückgabewert
Der Rückgabewert gibt an, ob der asynchrone Vorgang erfolgreich initiiert wurde. Dies impliziert nicht erfolg- oder misserfolgt den Vorgang selbst.
Wenn kein Fehler auftritt, gibt WSAAsyncGetServByPort einen Wert vom Typ HANDLE zurück, der das asynchrone Aufgabenhandle für die Anforderung ist (nicht zu verwechseln mit einem Windows HTASK). Dieser Wert kann auf zwei Arten verwendet werden. Es kann verwendet werden, um den Vorgang mit WSACancelAsyncRequest abzubrechen, oder es kann verwendet werden, um asynchrone Vorgänge und Abschlussmeldungen abzugleichen, indem der wParam-Nachrichtenparameter untersucht wird.
Wenn der asynchrone Vorgang nicht initiiert werden konnte, gibt WSAAsyncGetServByPort einen Nullwert zurück, und eine bestimmte Fehlernummer kann durch Aufrufen von WSAGetLastError abgerufen werden.
Die folgenden Fehlercodes können festgelegt werden, wenn ein Anwendungsfenster eine Meldung empfängt. Wie oben beschrieben, können sie mithilfe des WSAGETASYNCERROR-Makros aus dem lParam in der Antwortnachricht extrahiert werden.
| Fehlercode | Bedeutung |
|---|---|
| Fehler beim Netzwerksubsystem. | |
| Es ist nicht genügend Pufferspeicher verfügbar. | |
| Der Proto - oder buf-Parameter befindet sich nicht in einem gültigen Teil des Prozessadressraums. | |
| Autorisierender Antwortport nicht gefunden. | |
| Nicht autoritativer Port nicht gefunden, oder Serverfehler. | |
| Nicht behebbare Fehler: Auf die Dienstdatenbank kann nicht zugegriffen werden. | |
| Gültiger Name, kein Datensatz des angeforderten Typs. |
Die folgenden Fehler können zum Zeitpunkt des Funktionsaufrufs auftreten und zeigen an, dass der asynchrone Vorgang nicht initiiert werden konnte.
| Fehlercode | Bedeutung |
|---|---|
| WSANOTINITIALISED | Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen. |
| WSAENETDOWN | Fehler beim Netzwerksubsystem. |
| WSAEINPROGRESS | Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet noch eine Rückruffunktion. |
| WSAEWOULDBLOCK | Der asynchrone Vorgang kann derzeit aufgrund von Ressourcen- oder anderen Einschränkungen innerhalb der Windows Sockets-Implementierung nicht geplant werden. |
Hinweise
Die WSAAsyncGetServByPort-Funktion ist eine asynchrone Version von getservbyport und wird verwendet, um Dienstinformationen abzurufen, die einer Portnummer entsprechen. Windows Sockets initiiert den Vorgang und kehrt sofort an den Aufrufer zurück. Dabei wird ein undurchsichtiges, asynchrones Aufgabenhandle zurückgegeben, mit dem die Anwendung den Vorgang identifizieren kann. Wenn der Vorgang abgeschlossen ist, werden die Ergebnisse (falls vorhanden) in den vom Aufrufer bereitgestellten Puffer kopiert, und eine Meldung wird an das Anwendungsfenster gesendet.
Wenn der asynchrone Vorgang abgeschlossen ist, empfängt das durch den hWnd-Parameter angegebene Anwendungsfenster eine Meldung im wMsg-Parameter . Der wParam-Parameter enthält das asynchrone Aufgabenhandle, das vom ursprünglichen Funktionsaufruf zurückgegeben wird. Die hohen 16 Bits von lParam enthalten einen beliebigen Fehlercode. Der Fehlercode kann ein beliebiger Fehler sein, wie in Winsock2.h definiert. Der Fehlercode 0 (null) gibt an, dass der asynchrone Vorgang erfolgreich abgeschlossen wurde.
Nach erfolgreichem Abschluss enthält der für den ursprünglichen Funktionsaufruf angegebene Puffer eine Servent-Struktur . Um auf die Member dieser Struktur zuzugreifen, sollte die ursprüngliche Pufferadresse in einen Servent-Strukturzeiger umgewandelt und nach Bedarf darauf zugegriffen werden.
Wenn der Fehlercode WSAENOBUFS lautet, war die Größe des Puffers, der von buflen im ursprünglichen Aufruf angegeben wurde, zu klein, um alle resultierenden Informationen zu enthalten. In diesem Fall enthalten die niedrigen 16 Bits von lParam die Größe des Puffers, der zum Bereitstellen aller erforderlichen Informationen erforderlich ist. Wenn die Anwendung entscheidet, dass die Teildaten unzureichend sind, kann sie den WSAAsyncGetServByPort-Funktionsaufruf mit einem Puffer erneut ausführen, der groß genug ist, um alle gewünschten Informationen zu empfangen (d. h. nicht kleiner als die niedrigen 16 Bits von lParam).
Der für diese Funktion angegebene Puffer wird von Windows Sockets verwendet, um eine Serventstruktur zusammen mit dem Inhalt von Datenbereichen zu erstellen, auf die von Membern derselben Serventstruktur verwiesen wird. Um den WSAENOBUFS-Fehler zu vermeiden, sollte die Anwendung einen Puffer von mindestens MAXGETHOSTSTRUCT-Bytes (wie in Winsock2.h definiert) bereitstellen.
Der Fehlercode und die Pufferlänge sollten aus lParam mithilfe der Makros WSAGETASYNCERROR und WSAGETASYNCBUFLEN extrahiert werden, die in Winsock2.h wie folgt definiert sind:
#include <windows.h>
#define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam)
#define WSAGETASYNCERROR(lParam) HIWORD(lParam)
Die Verwendung dieser Makros maximiert die Portabilität des Quellcodes für die Anwendung.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winsock.h (Winsock2.h einschließen) |
| Bibliothek | Ws2_32.lib |
| DLL | Ws2_32.dll |