SIO_ADDRESS_LIST_QUERY-Steuerelementcode

Artikel
06/13/2023

BESCHREIBUNG

Der SIO_ADDRESS_LIST_QUERY-Steuerelementcode ruft eine Liste der lokalen Transportadressen der Protokollfamilie des Sockets ab, an die die Anwendung gebunden werden kann. Die Liste der Adressen variiert je nach Adressfamilie, und einige Adressen werden aus der Liste ausgeschlossen.

Rufen Sie zum Ausführen dieses Vorgangs die Funktion WSAIoctl oder WSPIoctl 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 Steuerelementcode für den Vorgang. Verwenden Sie für diesen Vorgang SIO_ADDRESS_LIST_QUERY .

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 Socket s ohne das überlappende Attribut erstellt wurde, 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 überlappender (asynchroner) Vorgang 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 Vervollständigungsmethode wird nach Abschluss des Vorgangs signalisiert. Andernfalls wird die Funktion erst zurückgegeben, wenn der Vorgang abgeschlossen wurde oder ein Fehler auftritt.

lpCompletionRoutine

Typ: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Ein Zeiger auf die Vervollständigungsroutine, 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 WSATHREADID-Struktur (nicht den Zeiger auf dieselbe) speichern, bis die WPUQueueApc-Funktion zurückgegeben wird.

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 null zurück.

Wenn der Vorgang fehlschlägt oder aussteht, gibt die WSAIoctl - oder WSPIoctl-FunktionSOCKET_ERROR zurück. Rufen Sie WSAGetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Fehlercode	Bedeutung
WSA_IO_PENDING	Ein überlappender Vorgang wurde erfolgreich eingeleitet, und der Abschluss wird zu einem späteren Zeitpunkt angezeigt.
WSA_OPERATION_ABORTED	Ein überlappender Vorgang wurde aufgrund des Schließens des Sockets oder der Ausführung des SIO_FLUSH IOCTL-Befehls abgebrochen.
WSAEFAULT	Der parameter lpOverlapped oder lpCompletionRoutine ist nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten.
WSAEINPROGRESS	Die Funktion wird aufgerufen, wenn ein Rückruf ausgeführt wird.
WSAEINTR	Ein Blockierungsvorgang 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	Beim Netzwerksubsystem ist ein Fehler aufgetreten.
WSAENOBUFS	Kein Pufferspeicher 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.

Bemerkungen

Die SIO_ADDRESS_LIST_QUERY IOCTL wird unter Windows 2000 und höheren Versionen des Betriebssystems unterstützt.

Für die AF_INET6 Adressfamilie werden alle Adressen mit Ausnahme der folgenden zurückgegeben:

Jede IP-Adresse, bei der der DAD-Zustand (Duplicate Address Detection) nicht IpDadStatePreferred ist.
Jede IP-Adresse mit einer niedrigeren Bereichsebene als ScopeLevelSubnet auf einer Schnittstelle, bei der der Schnittstellentyp IF_TYPE_SOFTWARE_LOOPBACK ist. Dies bedeutet, dass Link-lokale (fe80:*) und Loopbackadressen (:::1) auf Schnittstellen IF_TYPE_SOFTWARE_LOOPBACK Typs ausgeschlossen sind, aber nicht, wenn sich diese Adressen auf einer Schnittstelle mit einem anderen Typ befinden.

Für die AF_INET Adressfamilie werden alle Adressen mit Ausnahme der folgenden zurückgegeben:

Jede IP-Adresse, bei der der DAD-Zustand (Duplicate Address Detection) nicht IpDadStatePreferred ist.
Jede IP-Adresse auf einer Schnittstelle, bei der der Schnittstellentyp IF_TYPE_SOFTWARE_LOOPBACK und die Verbindung lokal ist. Dies bedeutet, dass link-local (169.254.) und Loopbackadressen (127.) auf Schnittstellen IF_TYPE_SOFTWARE_LOOPBACK Typs ausgeschlossen sind, aber nicht, wenn sich diese Adressen auf einer Schnittstelle mit einem anderen Typ befinden.

Weitere Informationen zum DAD-Zustand finden Sie in der IP-Hilfsprogrammdokumentation zur IP_DAD_STATE-Enumeration und IP_ADAPTER_UNICAST_ADDRESS-Struktur sowie in der MIB-Dokumentation zur MIB_UNICASTIPADDRESS_ROW-Struktur . Weitere Informationen zum Schnittstellentyp finden Sie in der IP-Hilfsprogrammdokumentation zur IP_ADAPTER_ADDRESSES-Struktur und der GetAdaptersAddresses-Funktion sowie in der MIB-Dokumentation zu MIB_IF_ROW2 Struktur. Weitere Informationen zur Bereichsebene finden Sie in der IP-Hilfsprogrammdokumentation zur IP_ADAPTER_ADDRESSES-Struktur und der SCOPE_LEVEL-Enumeration .

Die im Ausgabepuffer zurückgegebene Liste, auf die der lpvOutBuffer-Parameter verweist, ist in 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 in Bytes für den Ausgabepuffer wird in diesem Fall im parameter lpcbBytesReturned 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 Benutzeradressraums enthalten ist.

Die SIO_ADDRESS_LIST_QUERY IOCTL wird normalerweise synchron aufgerufen, wobei der lpvOverlapped-Parameter 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 entweder über überlappende E/A oder FD_ADDRESS_LIST_CHANGE Ereignis bereitstellt. Die folgende Abfolge von Aktionen kann verwendet werden, um sicherzustellen, dass die Anwendung immer über aktuelle Adresslisteninformationen verfügt:

SIO_ADDRESS_LIST_CHANGE IOCTL ausstellen
SIO_ADDRESS_LIST_QUERY IOCTL ausstellen
Wenn der SIO_ADDRESS_LIST_CHANGE IOCTL-Aufruf die Anwendung einer Adresslistenänderung benachrichtigt (entweder durch überlappende E/A oder durch Signalisierung FD_ADDRESS_LIST_CHANGE Ereignisses), sollte die gesamte Abfolge von Aktionen wiederholt werden.

Im Microsoft Windows Software Development Kit (SDK), das für Windows Vista und höher veröffentlicht wurde, wurde die organization von Headerdateien geändert, und der SIO_ADDRESS_LIST_QUERY-Steuerelementcode ist in der Ws2def.h-Headerdatei definiert. Beachten Sie, dass die Ws2def.h-Headerdatei automatisch in Winsock2.h enthalten ist und nie direkt verwendet werden sollte.