SIO_ADDRESS_LIST_QUERY-Steuerelementcode

BESCHREIBUNG

Der SIO _ ADDRESS LIST _ QUERY-Steuerungscode _ erhält eine Liste der lokalen Transportadressen der Protokollfamilie des Sockets, an die die Anwendung gebunden werden kann. Die Liste der Adressen variiert je nach Adressfamilie, und einige Adressen werden aus der Liste ausgeschlossen.

Um diesen Vorgang durchzuführen, rufen Sie die WSAIoctl- oder WSPIoctl-Funktion mit den folgenden Parametern auf.

int WSAIoctl(
  (socket) s,            // descriptor identifying a socket
  SIO_ADDRESS_LIST_QUERY,            // dwIoControlCode
  NULL,                              // lpvInBuffer
  0,                                 // cbInBuffer
  (LPVOID) lpvOutBuffer,          // output buffer
  (DWORD) cbOutBuffer,            // size of output buffer  
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);
int WSPIoctl(
  (socket) s,            // descriptor identifying a socket
  SIO_ADDRESS_LIST_QUERY,            // dwIoControlCode
  NULL,                              // lpvInBuffer
  0,                                 // cbInBuffer
  (LPVOID) lpvOutBuffer,          // output buffer
  (DWORD) cbOutBuffer,            // size of output buffer  
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Parameter

s

Ein Deskriptor, der einen Socket identifiziert.

dwIoControlCode

Der Steuerungscode für den Vorgang. Verwenden Sie SIO _ ADDRESS LIST _ _ QUERY für diesen Vorgang.

lpvInBuffer

Ein Zeiger auf den Eingabepuffer. Dieser Parameter wird für diesen Vorgang nicht verwendet.

cbInBuffer

Die Größe des Eingabepuffers in Bytes. Dieser Parameter wird für diesen Vorgang nicht verwendet.

lpvOutBuffer

Ein Zeiger auf den Ausgabepuffer.

cbOutBuffer

Die Größe des Ausgabepuffers in Bytes.

lpcbBytesReturned

Ein Zeiger auf eine Variable, die die Größe der im Ausgabepuffer gespeicherten Daten in Bytes empfängt.

lpvOverlapped

Ein Zeiger auf eine WSAOVERLAPPED-Struktur.

Wenn Sockets ohne das überlappende Attribut erstellt wurden, wird der lpOverlapped-Parameter ignoriert.

Wenn s mit dem überlappenden Attribut geöffnet wurde und der lpOverlapped-Parameter nicht NULL ist, wird der Vorgang als überlappende (asynchrone) Operation ausgeführt. In diesem Fall muss der lpOverlapped-Parameter auf eine gültige WSAOVERLAPPED-Struktur verweisen.

Bei überlappenden Vorgängen wird die WSAIoctl- oder WSPIoctl-Funktion sofort zurückgegeben, und die entsprechende Abschlussmethode wird signalisiert, wenn der Vorgang abgeschlossen wurde. Andernfalls gibt die Funktion erst dann zurück, wenn der Vorgang abgeschlossen wurde oder ein Fehler auftritt.

lpCompletionRoutine

Typ: _ In_opt _ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Ein Zeiger auf die Abschlussroutine, die aufgerufen wird, wenn der Vorgang abgeschlossen wurde (bei nicht überlappenden Sockets ignoriert).

lpThreadId

Ein Zeiger auf eine WSATHREADID-Struktur, die vom Anbieter in einem nachfolgenden Aufruf von WPUQueueApc verwendet werden soll. Der Anbieter sollte die referenzierte WSATHREADID-Struktur (nicht den Zeiger auf dieselbe) speichern, bis die WPUQueueApc-Funktion zurückgegeben wurde.

Hinweis: Dieser Parameter gilt nur für die WSPIoctl-Funktion.

lpErrno

Ein Zeiger auf den Fehlercode.

Hinweis: Dieser Parameter gilt nur für die WSPIoctl-Funktion.

Rückgabewert

Wenn der Vorgang erfolgreich abgeschlossen wurde, gibt die WSAIoctl- oder WSPIoctl-Funktion 0 (null) zurück.

Wenn der Vorgang fehlschlägt oder aussteht, gibt die WSAIoctl- oder WSPIoctl-Funktion SOCKET ERROR _ zurück. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie WSAGetLastError auf.

Fehlercode Bedeutung
AUSSTEHENDE _ _ WSA-E/A Ein überlappende Vorgang wurde erfolgreich initiiert, und der Abschluss wird zu einem späteren Zeitpunkt angezeigt.
_WSA-VORGANG _ ABGEBROCHEN Ein überlappende Vorgang wurde aufgrund des Schließens des Sockets oder der Ausführung des IOCTL-Befehls SIO _ FLUSH abgebrochen.
WSAEFAULT Der lpOverlapped- oder lpCompletionRoutine-Parameter ist nicht vollständig in einem gültigen Teil des Benutzeradrenraums enthalten.
WSAEINPROGRESS Die Funktion wird aufgerufen, wenn ein Rückruf in Bearbeitung ist.
WSAEINTR Ein blockierende Vorgang wurde unterbrochen.
WSAEINVAL Der dwIoControlCode-Parameter ist kein gültiger Befehl, oder ein angegebener Eingabeparameter ist nicht akzeptabel, oder der Befehl gilt nicht für den angegebenen Sockettyp. Dieser Fehler wird zurückgegeben, wenn der cbInBuffer-Parameter nicht auf NULL festgelegt ist.
WSAENETDOWN Fehler beim Netzwerksubsystem.
WSAENOBUFS Kein Pufferspeicherplatz verfügbar.
WSAENOPROTOOPT Die Socketoption wird für das angegebene Protokoll nicht unterstützt.
WSAENOTSOCK Der Deskriptor s ist kein Socket.
WSAEOPNOTSUPP Der angegebene IOCTL-Befehl wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn die SIO _ ADDRESS LIST _ _ QUERY IOCTL vom Transportanbieter nicht unterstützt wird.

Hinweise

Die SIO _ ADDRESS LIST _ _ QUERY IOCTL wird unter Windows 2000 und höher des Betriebssystems unterstützt.

Der SIO _ ADDRESS LIST _ QUERY-Steuerungscode _ erhält eine Liste der lokalen Transportadressen der Protokollfamilie des Sockets, an die die Anwendung gebunden werden kann. Die Liste der Adressen variiert je nach Adressfamilie.

Für die AF _ INET6-Adressfamilie werden alle Adressen zurückgegeben, mit Ausnahme der folgenden:

  • Jede IP-Adresse, bei der der Status der Erkennung doppelter Adressen (Duplicate Address Detection, DAD) nicht IpDadStatePreferred ist.
  • Jede IP-Adresse mit einer Bereichsebene, die niedriger als ScopeLevelSubnet auf einer Schnittstelle ist, bei der der Schnittstellentyp IF _ TYPE SOFTWARE _ _ LOOPBACK ist. Dies bedeutet, dass link-local (fe80:*) und Loopbackadressen (::1) für Schnittstellen des IF _ TYPE SOFTWARE _ _ LOOPBACK-Typs ausgeschlossen werden, aber nicht, wenn sich diese Adressen auf einer Schnittstelle mit einem anderen Typ befinden.

Für die AF _ INET-Adressfamilie werden alle Adressen zurückgegeben, mit Ausnahme der folgenden:

  • Jede IP-Adresse, bei der der Status der Erkennung doppelter Adressen (Duplicate Address Detection, DAD) nicht IpDadStatePreferred ist.
  • Jede IP-Adresse auf einer Schnittstelle, deren Schnittstellentyp IF _ TYPE SOFTWARE _ _ LOOPBACK und link local ist. Dies bedeutet, dass lokale Linkadressen (169.254. ) und Loopbackadressen (127.) an Schnittstellen des IF TYPE SOFTWARE _ _ _ LOOPBACK-Typs ausgeschlossen werden, aber nicht, wenn sich diese Adressen auf einer Schnittstelle mit einem anderen Typ befinden.

Weitere Informationen zum DAD-Zustand finden Sie in der Dokumentation zum IP-Hilfs hilfs für die IP _ DAD _ STATE-Enumeration und die _ _ UNICAST _ ADDRESS-Struktur des IP-Adapters und in der MIB-Dokumentation zur MIB _ UNICASTIPADDRESS-ZEILENstruktur. _ Weitere Informationen zum Schnittstellentyp finden Sie in der DOKUMENTATION des IP-Hilfsers zur _ IP-Adapter-ADDRESSES-Struktur _ und der GetAdaptersAddresses-Funktion sowie in der MIB-Dokumentation zur MIB_IF_ROW2 Struktur. Weitere Informationen zur Bereichsebene finden Sie in der DOKUMENTATION des IP-Hilfsers zur IP_ADAPTER_ADDRESSES-Struktur und der SCOPE _ LEVEL-Enumeration.

Die Liste, die im Ausgabepuffer zurückgegeben wird, auf den der lpvOutBuffer-Parameter zeigt, hat die Form einer SOCKET ADDRESS _ _ LIST-Struktur.

Wenn der im lpvOutBuffer-Parameter angegebene Ausgabepuffer nicht groß genug ist, um die Adressliste zu enthalten, wird SOCKET _ ERROR als Ergebnis dieser IOCTL zurückgegeben, und WSAGetLastError gibt WSAEFAULT zurück. Die erforderliche Größe für den Ausgabepuffer in Bytes wird in diesem Fall im lpcbBytesReturned-Parameter zurückgegeben. Beachten Sie, dass der WSAEFAULT-Fehlercode auch zurückgegeben wird, wenn der Parameter lpvInBuffer, lpvOutBuffer oder lpcbBytesReturned nicht vollständig in einem gültigen Teil des Benutzeradressenbereichs enthalten ist.

Die ABFRAGE-IOCTL der SIO-ADRESSLISTE _ _ _ wird normalerweise synchron mit dem Parameter lpvOverlapped aufgerufen, der auf NULL festgelegt ist, da die Liste der Adressen sofort zurückgegeben wird.

Hinweis: In Windows Plug-n-Play-Umgebungen können Adressen dynamisch hinzugefügt und entfernt werden. Daher können Sich Anwendungen nicht darauf verlassen, dass die von SIO _ ADDRESS LIST _ _ QUERY zurückgegebenen Informationen persistent sind. Anwendungen können sich für Adressänderungsbenachrichtigungen über die SIO _ ADDRESS LIST _ _ CHANGE IOCTL registrieren, die Benachrichtigungen über überlappende E/A- oder FD ADDRESS LIST _ _ _ CHANGE-Ereignisse bietet. Die folgende Aktionssequenz kann verwendet werden, um zu gewährleisten, dass die Anwendung immer über aktuelle Adresslisteninformationen verfügt:

  • Ausgabe der IOCTL-ÄNDERUNG _ _ DER _ SIO-ADRESSLISTE
  • Ausgabe der IOCTL-ABFRAGE DER _ _ _ SIO-ADRESSLISTE
  • Wenn der IOCTL-Aufruf von SIO _ ADDRESS LIST _ _ CHANGE die Anwendung über eine Änderung der Adressliste benachrichtigt (entweder durch überlappende E/A oder durch Signalisierung des Ereignisses FD _ ADDRESS LIST _ _ CHANGE), sollte die gesamte Sequenz von Aktionen wiederholt werden.

Im Microsoft Windows Software Development Kit (SDK), das für Windows Vista und höher veröffentlicht wurde, hat sich die Organisation der Headerdateien geändert, und der ABFRAGE-Steuerungscode der SIO-ADRESSLISTE _ _ _ wird in der Ws2def.h-Headerdatei definiert. Beachten Sie, dass die Headerdatei Ws2def.h automatisch in Winsock2.h enthalten ist und niemals direkt verwendet werden sollte.

Siehe auch

GetAdaptersAddresses

IP_ADAPTER_ADDRESSES

IP_ADAPTER_UNICAST_ADDRESS

IP_DAD_STATE

MIB_IF_ROW2

MIB_UNICASTIPADDRESS_ROW

SCOPE_LEVEL

SOCKET_ADDRESS_LIST

Socket

WSAGetLastError

WSAGetOverlappedResult

WSAIoctl

WSAOVERLAPPED

WSASocketA

WSASocketW