SIO_ADDRESS_LIST_QUERY 제어 코드

아티클
06/12/2023

설명

SIO_ADDRESS_LIST_QUERY 제어 코드는 애플리케이션이 바인딩할 수 있는 소켓 프로토콜 패밀리의 로컬 전송 주소 목록을 가져옵니다. 주소 목록은 주소 패밀리에 따라 다르며 일부 주소는 목록에서 제외됩니다.

이 작업을 수행하려면 다음 매개 변수를 사용하여 WSAIoctl 또는 WSPIoctl 함수를 호출합니다.

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.
);

매개 변수

초

소켓을 식별하는 설명자입니다.

dwIoControlCode

작업을 위한 제어 코드입니다. 이 작업에 는 SIO_ADDRESS_LIST_QUERY 사용합니다.

lpvInBuffer

입력 버퍼에 대한 포인터입니다. 이 매개 변수는 이 작업에 사용되지 않습니다.

cbInBuffer

입력 버퍼의 크기(바이트)입니다. 이 매개 변수는 이 작업에 사용되지 않습니다.

lpvOutBuffer

출력 버퍼에 대한 포인터입니다.

cbOutBuffer

출력 버퍼의 크기(바이트)입니다.

lpcbBytesReturned

출력 버퍼에 저장된 데이터의 크기(바이트)를 수신하는 변수에 대한 포인터입니다.

lpvOverlapped

WSAOVERLAPPED 구조체에 대한 포인터입니다.

소켓 이 겹치는 특성 없이 만들어진 경우 lpOverlapped 매개 변수는 무시됩니다.

가 겹치는 특성으로 열렸고 lpOverlapped 매개 변수가 NULL이 아닌 경우 작업은 겹치는(비동기) 작업으로 수행됩니다. 이 경우 lpOverlapped 매개 변수는 유효한 WSAOVERLAPPED 구조를 가리킵니다.

겹치는 작업의 경우 WSAIoctl 또는 WSPIoctl 함수는 즉시 반환되고 작업이 완료되면 적절한 완료 메서드가 신호를 보냅니다. 그렇지 않으면 작업이 완료되거나 오류가 발생할 때까지 함수가 반환되지 않습니다.

lpCompletionRoutine

형식: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

작업이 완료되었을 때 호출되는 완료 루틴에 대한 포인터입니다(겹치지 않는 소켓의 경우 무시됨).

lpThreadId

WPUQueueApc에 대한 후속 호출에서 공급자가 사용할 WSATHREADID 구조체에 대한 포인터입니다. 공급자는 WPUQueueApc 함수가 반환될 때까지 참조된 WSATHREADID 구조체(동일한 포인터가 아님)를 저장해야 합니다.

참고 이 매개 변수는 WSPIoctl 함수에 만 적용됩니다.

lpErrno

오류 코드에 대한 포인터입니다.

참고 이 매개 변수는 WSPIoctl 함수에 만 적용됩니다.

반환 값

작업이 성공적으로 완료되면 WSAIoctl 또는 WSPIoctl 함수는 0을 반환합니다.

작업이 실패하거나 보류 중인 경우 WSAIoctl 또는 WSPIoctl 함수는 SOCKET_ERROR 반환합니다. 확장된 오류 정보를 얻으려면 WSAGetLastError를 호출합니다.

오류 코드	의미
WSA_IO_PENDING	겹치는 작업이 성공적으로 시작되었으며 나중에 완료가 표시됩니다.
WSA_OPERATION_ABORTED	소켓의 닫기 또는 SIO_FLUSH IOCTL 명령 실행으로 인해 겹치는 작업이 취소되었습니다.
WSAEFAULT	lpOverlapped 또는 lpCompletionRoutine 매개 변수는 사용자 주소 공간의 유효한 부분에 완전히 포함되지 않습니다.
WSAEINPROGRESS	콜백이 진행 중일 때 함수가 호출됩니다.
WSAEINTR	차단 작업이 중단되었습니다.
WSAEINVAL	dwIoControlCode 매개 변수가 유효한 명령이 아니거나 지정된 입력 매개 변수를 사용할 수 없거나 지정된 소켓 유형에 명령을 적용할 수 없습니다. cbInBuffer 매개 변수가 NULL로 설정되지 않은 경우 이 오류가 반환됩니다.
WSAENETDOWN	네트워크 하위 시스템이 실패했습니다.
WSAENOBUFS	사용할 수 있는 버퍼 공간이 없습니다.
WSAENOPROTOOPT	소켓 옵션은 지정된 프로토콜에서 지원되지 않습니다.
WSAENOTSOCK	설명자 가 소켓이 아닙니다.
WSAEOPNOTSUPP	지정된 IOCTL 명령은 지원되지 않습니다. 이 오류는 SIO_ADDRESS_LIST_QUERY IOCTL이 전송 공급자에서 지원되지 않는 경우 반환됩니다.

설명

SIO_ADDRESS_LIST_QUERY IOCTL은 Windows 2000 이상 버전의 운영 체제에서 지원됩니다.

SIO_ADDRESS_LIST_QUERY 제어 코드는 애플리케이션이 바인딩할 수 있는 소켓 프로토콜 패밀리의 로컬 전송 주소 목록을 가져옵니다. 주소 목록은 주소 패밀리에 따라 다릅니다.

AF_INET6 주소 패밀리의 경우 다음을 제외한 모든 주소가 반환됩니다.

DAD(중복 주소 검색) 상태가 IpDadStateP가 참조되지 않는 모든 IP 주소입니다.
인터페이스 형식이 IF_TYPE_SOFTWARE_LOOPBACK 인터페이스의 ScopeLevelSubnet보다 낮은 scope 수준의 모든 IP 주소입니다. 즉, IF_TYPE_SOFTWARE_LOOPBACK 형식의 인터페이스에서 링크 로컬(fe80:*) 및 루프백(::1) 주소는 제외되지만 이러한 주소가 다른 형식의 인터페이스에 있는 경우에는 제외되지 않습니다.

AF_INET 주소 패밀리의 경우 다음을 제외한 모든 주소가 반환됩니다.

DAD(중복 주소 검색) 상태가 IpDadStateP가 참조되지 않는 모든 IP 주소입니다.
인터페이스 형식이 IF_TYPE_SOFTWARE_LOOPBACK 링크가 로컬인 인터페이스의 모든 IP 주소입니다. 즉, IF_TYPE_SOFTWARE_LOOPBACK 형식의 인터페이스에서 링크 로컬(169.254.) 및 루프백(127.) 주소는 제외되지만 이러한 주소가 다른 형식의 인터페이스에 있는 경우에는 제외되지 않습니다.

DAD 상태에 대한 자세한 내용은 IP_DAD_STATE 열거형 및 IP_ADAPTER_UNICAST_ADDRESS 구조에 대한 IP 도우미 설명서와 MIB_UNICASTIPADDRESS_ROW구조에 대한 MIB 설명서를 참조하세요. 인터페이스 유형에 대한 자세한 내용은 IP_ADAPTER_ADDRESSES 구조체에 대한 IP 도우미 설명서 및 GetAdaptersAddresses 함수 및 MIB_IF_ROW2 구조에 대한 MIB 설명서를 참조하세요. scope 수준에 대한 자세한 내용은 IP_ADAPTER_ADDRESSES 구조 및 SCOPE_LEVEL열거형에 대한 IP 도우미 설명서를 참조하세요.

lpvOutBuffer 매개 변수가 가리키는 출력 버퍼에 반환된 목록은 SOCKET_ADDRESS_LIST 구조체 형식입니다.

lpvOutBuffer 매개 변수에 지정된 출력 버퍼가 주소 목록을 포함할 만큼 크지 않으면 이 IOCTL의 결과로 SOCKET_ERROR 반환되고 WSAGetLastError는 WSAEFAULT를 반환합니다. 출력 버퍼에 필요한 크기(바이트)는 이 경우 lpcbBytesReturned 매개 변수에 반환됩니다. lpvInBuffer, lpvOutBuffer 또는 lpcbBytesReturned 매개 변수가 사용자 주소 공간의 유효한 부분에 완전히 포함되지 않은 경우에도 WSAEFAULT 오류 코드가 반환됩니다.

주소 목록이 즉시 반환되므로 SIO_ADDRESS_LIST_QUERY IOCTL은 일반적으로 lpvOverlapped 매개 변수가 NULL로 설정된 상태에서 동기적으로 호출됩니다.

참고 Windows 플러그 앤 플레이 환경에서 주소를 동적으로 추가하고 제거할 수 있습니다. 따라서 애플리케이션은 SIO_ADDRESS_LIST_QUERY 반환된 정보를 영구적으로 사용할 수 없습니다. 애플리케이션은 겹치는 I/O 또는 FD_ADDRESS_LIST_CHANGE 이벤트를 통해 알림을 제공하는 SIO_ADDRESS_LIST_CHANGE IOCTL을 통해 주소 변경 알림을 등록할 수 있습니다. 애플리케이션에 항상 현재 주소 목록 정보가 있음을 보장하기 위해 다음 작업 시퀀스를 사용할 수 있습니다.

SIO_ADDRESS_LIST_CHANGE IOCTL 발급
SIO_ADDRESS_LIST_QUERY IOCTL 발급
SIO_ADDRESS_LIST_CHANGE IOCTL 호출이 주소 목록 변경의 적용을 알릴 때마다(겹치는 I/O를 통해 또는 FD_ADDRESS_LIST_CHANGE 이벤트 신호를 통해) 전체 작업 시퀀스를 반복해야 합니다.

Windows Vista 이상용으로 릴리스된 Microsoft Windows SDK(소프트웨어 개발 키트)에서 헤더 파일의 organization 변경되었으며 SIO_ADDRESS_LIST_QUERY 제어 코드가 Ws2def.h 헤더 파일에 정의되어 있습니다. Ws2def.h 헤더 파일은 Winsock2.h에 자동으로 포함되며 직접 사용하면 안 됩니다.