WSANSPIoctl 함수(winsock2.h)

아티클
03/13/2024

Windows Sockets WSANSPIoctl 함수를 사용하면 개발자가 등록된 네임스페이스에 대한 I/O 컨트롤 호출을 수행할 수 있습니다.

구문

INT WSAAPI WSANSPIoctl(
  [in]      HANDLE          hLookup,
  [in]      DWORD           dwControlCode,
  [in]      LPVOID          lpvInBuffer,
  [in, out] DWORD           cbInBuffer,
  [out]     LPVOID          lpvOutBuffer,
  [in]      DWORD           cbOutBuffer,
  [out]     LPDWORD         lpcbBytesReturned,
  [in]      LPWSACOMPLETION lpCompletion
);

매개 변수

[in] hLookup

WSALookupServiceBegin 함수에 대한 이전 호출에서 반환된 조회 핸들입니다.

[in] dwControlCode

수행할 작업의 제어 코드입니다.

dwControlCode 매개 변수에 사용할 수 있는 값은 네임스페이스 공급자에 의해 결정됩니다.

다음 값은 네트워크 위치 인식(NS_NLA) 네임스페이스 공급자를 비롯한 여러 Microsoft 네임스페이스 공급자에서 지원됩니다. 이 IOCTL은 Winsock2.h 헤더 파일에 정의되어 있습니다.

값	의미
SIO_NSP_NOTIFY_CHANGE	이 작업은 hLookup 매개 변수를 사용하여 이전 호출과 함께 반환된 결과가 여전히 유효한지 확인합니다. 이러한 이전 호출에는 hLookup 매개 변수를 검색하기 위한 WSALookupServiceBegin 함수에 대한 초기 호출이 포함됩니다. 이러한 이전 호출에는 hLookup 매개 변수를 사용하여 WSALookupServiceNext 함수에 대한 호출이 포함될 수도 있습니다.

값

의미

SIO_NSP_NOTIFY_CHANGE

이 작업은 hLookup 매개 변수를 사용하여 이전 호출과 함께 반환된 결과가 여전히 유효한지 확인합니다. 이러한 이전 호출에는 hLookup 매개 변수를 검색하기 위한 WSALookupServiceBegin 함수에 대한 초기 호출이 포함됩니다. 이러한 이전 호출에는 hLookup 매개 변수를 사용하여 WSALookupServiceNext 함수에 대한 호출이 포함될 수도 있습니다.

[in] lpvInBuffer

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

[in, out] cbInBuffer

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

[out] lpvOutBuffer

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

[in] cbOutBuffer

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

[out] lpcbBytesReturned

반환된 바이트 수에 대한 포인터입니다.

[in] lpCompletion

비동기 처리에 사용되는 WSACOMPLETION 구조체에 대한 포인터입니다. lpCompletion을 NULL로 설정하여 강제 차단(동기) 실행을 적용합니다.

반환 값

Success는 NO_ERROR 반환합니다. 실패는 SOCKET_ERROR 반환하고 WSAGetLastError 함수를 호출하여 특정 오류 코드를 검색할 수 있습니다. 다음 표에서는 오류 코드에 대해 설명합니다.

오류 코드	Description
WSA_INVALID_HANDLE	hLookup 매개 변수가 WSALookupServiceBegin에서 반환된 유효한 쿼리 핸들이 아닙니다.
WSA_IO_PENDING	겹치는 작업이 성공적으로 시작되었으며 나중에 완료가 표시됩니다.
WSAEFAULT	lpvInBuffer, cbInBuffer, lpvOutBuffer, cbOutBuffer 또는 lpCompletion 인수는 사용자 주소 공간의 유효한 부분에 완전히 포함되지 않습니다. 또는 cbInBuffer 또는 cbOutBuffer 인수가 너무 작고 인수가 필요한 할당 크기를 반영하도록 수정됩니다.
WSAEINVAL	제공된 매개 변수는 허용되지 않거나 지정된 작업에 적합하지 않은 경우 작업이 여러 네임스페이스의 결과를 부적절하게 반환합니다.
WSAENETDOWN	네트워크 하위 시스템이 실패했습니다.
WSAEOPNOTSUPP	이 작업은 지원되지 않습니다. 네임스페이스 공급자가 이 함수를 구현하지 않으면 이 오류가 반환됩니다. 지정된 dwControlCode 가 인식할 수 없는 명령인 경우에도 이 오류가 반환될 수 있습니다.
WSAEWOULDBLOCK	소켓이 겹치는 I/O(비동기 처리)를 사용하지 않고 있지만 lpCompletion 매개 변수는 NULL이 아닙니다. 이 오류는 lpCompletion 매개 변수가 NULL (설문 조사)이면 쿼리 집합이 유효한 상태로 유지됨을 나타내는 SIO_NSP_NOTIFY_CHANGE IOCTL에 대한 특별 알림으로 사용됩니다.

설명

WSANSPIoctl 함수는 쿼리 핸들과 연결된 운영 매개 변수를 네임스페이스 공급자에 설정하거나 검색하는 데 사용됩니다. hLookup 매개 변수는 WSALookupServiceBegin 함수에서 이전에 반환한 네임스페이스 공급자 쿼리에 대한 핸들입니다(소켓 핸들 아님).

네임스페이스 공급자에게 전송된 모든 IOCTL은 네임스페이스의 구현에 따라 무기한 차단할 수 있습니다. 애플리케이션이 WSANSPIoctl 함수 호출에서 차단을 허용할 수 없는 경우 겹치는 I/O를 사용해야 하며 lpCompletion 매개 변수는 WSACOMPLETION 구조를 가리킵니다. WSANSPIoctl 함수가 비블로킹을 호출하고 즉시 반환하도록 하려면 WSACOMPLETION 구조체의 Type 멤버를 NSP_NOTIFY_IMMEDIATELY 설정합니다.

lpCompletion이 NULL이면 WSANSPIoctl 함수가 차단 호출로 실행됩니다. 네임스페이스 공급자는 즉시 반환되어야 하며 차단해서는 안 됩니다. 그러나 각 네임스페이스는 이 동작을 적용해야 합니다.

다음 IOCTL 코드는 여러 Microsoft 이름 공간 공급자에서 지원됩니다.

SIO_NSP_NOTIFY_CHANGE

이 IOCTL을 지원하는 Microsoft 네임스페이스 공급자에는 다음이 포함됩니다.

NS_NLA - NLA(네트워크 위치 인식) 네임스페이스 공급자입니다.
NS_PNRPNAME - PNRP(피어 이름 확인 프로토콜) 네임스페이스 공급자입니다.
NS_PNRPCLOUD - PNRP(피어 이름 확인 프로토콜) 클라우드 네임스페이스 공급자입니다.

이 IOCTL을 지원하는 다른 타사 네임스페이스 공급자도 설치할 수 있습니다.

lpCompletion 매개 변수가 NULL이면 이 IOCTL은 특수 동작을 구현합니다. lpCompletion 매개 변수가 이 IOCTL에 대해 NULL이면 이 작업은 설문 조사이며 즉시 반환됩니다. 쿼리 집합이 유효한 상태로 유지되면 쿼리 집합이 유효한 상태로 유지된다는 알림으로 WSAEWOULDBLOCK 이 반환됩니다. 쿼리 집합이 변경되고 잘못된 경우 쿼리 집합의 무효화에 대한 폴링 성공을 나타내는 NO_ERROR 반환됩니다.

lpCompletion 매개 변수가 NULL이 아니고 WSACOMPLETION 구조를 가리키는 경우 겹치는 작업이 성공적으로 시작되고 나중에 완료가 표시되면 WSANSPIoctl 함수는 WSA_IO_PENDING 반환합니다. WSACOMPLETION 구조에 지정된 메서드는 쿼리 집합이 여전히 유효한 경우 애플리케이션에 알리는 데 사용됩니다.

모든 이름 확인 프로토콜이 이 기능을 지원할 수 있는 것은 아니므로 WSAEOPNOTSUPP로 이 함수 호출이 실패할 수 있습니다. 여러 공급자의 데이터가 포함된 쿼리는 이 IOCTL을 호출할 수 없으며 WSAEINVAL을 반환합니다.

lpvInBuffer, cbInBuffer, lpvOutBuffer 및 cbOutBuffer 매개 변수는 현재 Microsoft 네임스페이스 공급자에서 무시됩니다.

단일 스레드 애플리케이션의 경우 WSANSPIoctl 함수를 사용하는 일반적인 방법은 다음과 같습니다. 모든 WSALookupServiceNext 함수 호출 후 dwControlCode 매개 변수가 완료 루틴 없이 SIO_NSP_NOTIFY_CHANGE(lpCompletion 매개 변수가 NULL로 설정됨)로 설정된 WSANSPIoctl 함수를 호출하여 쿼리 데이터가 여전히 유효한지 확인합니다. 데이터가 잘못되면 WSALookupServiceEnd 함수를 호출하여 쿼리 핸들을 닫습니다. WSALookupServiceBegin 함수를 호출하여 새 쿼리 핸들을 검색하고 쿼리를 다시 시작합니다.

다중 스레드 애플리케이션의 경우 WSANSPIoctl 함수를 사용하는 일반적인 방법은 다음과 같습니다. WSALookupServiceBegin 함수를 처음 호출한 후 dwControlCode 매개 변수가 완료 루틴으로 SIO_NSP_NOTIFY_CHANGE 설정하여 WSANSPIoctl 함수를 호출합니다. 애플리케이션은 완료 루틴에 지정된 알림 메커니즘을 사용하여 데이터가 더 이상 유효하지 않을 때 알림을 받습니다. 한 가지 일반적인 메커니즘은 완료 루틴에 지정된 이벤트를 사용하는 것입니다. 데이터가 잘못되면 WSALookupServiceEnd 함수를 호출하여 쿼리 핸들을 닫습니다. WSALookupServiceBegin 및 WSANSPIoctl 함수를 호출하여 새 쿼리 핸들을 검색하고 쿼리를 다시 시작합니다.

일부 프로토콜은 정보를 로컬로 캐시하고 일정 시간 후에 무효화할 수 있습니다. 이 경우 로컬 캐시가 무효화되었음을 나타내기 위해 알림이 발행될 수 있습니다.

변경 내용이 자주 변경되지 않는 이름 확인 프로토콜의 경우 네임스페이스 공급자가 변경 알림이 요청되고 발급된 쿼리에 적용되지 않을 수 있는 전역 변경 이벤트를 나타낼 수 있습니다.

즉각적인 폴링 작업은 알림 개체가 필요하지 않으므로 일반적으로 훨씬 저렴합니다. 대부분의 경우 간단한 부울 변수 검사 구현됩니다. 그러나 비동기 알림은 네임스페이스 공급자 서비스의 구현에 따라 전용 작업자 스레드 및/또는 프로세스 간 통신 채널을 생성해야 할 수 있으며 변경 이벤트 신호와 관련된 알림 개체와 관련된 처리 오버헤드가 발생할 수 있습니다.

비동기 알림 요청을 취소하려면 영향을 받는 쿼리 핸들에서 WSALookupServiceEnd 함수 호출을 사용하여 원래 쿼리를 종료합니다. LUP_NOTIFY_HWND 대한 비동기 알림을 취소해도 메시지가 게시되지는 않습니다. 그러나 겹치는 작업이 완료되고 오류 WSA_OPERATION_ABORTED 알림이 전달됩니다.

참고 지정된 스레드에서 시작된 모든 I/O는 해당 스레드가 종료될 때 취소됩니다. 겹치는 소켓의 경우 작업이 완료되기 전에 스레드가 닫히면 보류 중인 비동기 작업이 실패할 수 있습니다. 자세한 내용은 ExitThread 를 참조하세요.

Windows Phone 8: 이 함수는 Windows Phone 8 이상에서 Windows Phone 스토어 앱에서 지원됩니다.

Windows 8.1 및 Windows Server 2012 R2: 이 함수는 Windows 8.1, Windows Server 2012 R2 이상에서 Windows 스토어 앱에서 지원됩니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 8.1, Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	winsock2.h