LPNSPIOCTL 콜백 함수(ws2spi.h)

아티클
08/28/2023

NSPIoctl 함수는 IOCTL을 네임스페이스 서비스 공급자로 보냅니다.

구문

LPNSPIOCTL Lpnspioctl;

INT Lpnspioctl(
  [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]      LPWSATHREADID lpThreadId
)
{...}

매개 변수

[in] hLookup

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

[in] dwControlCode

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

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

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

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

값

의미

SIO_NSP_NOTIFY_CHANGE

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

[in] lpvInBuffer

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

[in, out] cbInBuffer

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

[out] lpvOutBuffer

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

[in] cbOutBuffer

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

[out] lpcbBytesReturned

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

[in] lpCompletion

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

[in] lpThreadId

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

반환 값

오류가 발생하지 않고 작업이 즉시 완료된 경우 NSPIoctl 함수는 NO_ERROR (0)을 반환해야 합니다. 이 경우 완료 루틴(지정된 경우)이 이미 큐에 대기 중입니다.

루틴이 실패하고 WSASetLastError를 사용하여 적절한 오류 코드를 설정해야 하는 경우 NSPIoctl 함수는 SOCKET_ERROR(즉, 1)를 반환해야 합니다.

오류 코드 WSA_IO_PENDING 겹치는 작업이 성공적으로 시작되었으며 나중에 완료가 표시됨을 나타냅니다. 다른 오류 코드는 겹치는 작업이 시작되지 않았으며 완료 표시가 발생하지 않음을 나타냅니다.

오류 코드	Description
WSA_INVALID_HANDLE	hLookup 매개 변수가 NSPLookupServiceBegin에서 반환된 유효한 쿼리 핸들이 아니었습니다.
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에 대한 특별 알림으로 사용되어 쿼리 집합이 유효한 상태로 유지됨을 나타냅니다.

설명

NSPIoctl 함수는 쿼리 핸들과 연결된 운영 매개 변수를 설정하거나 검색하기 위해 I/O 제어 코드를 네임스페이스 공급자로 보내는 데 사용됩니다. hLookup 매개 변수는 NSPLookupServiceBegin 함수(소켓 핸들 아님)에서 이전에 반환한 네임스페이스 공급자 쿼리에 대한 핸들입니다.

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

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

다음 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 구조를 가리키는 경우 NSPIoctl 함수는 겹치는 작업이 성공적으로 시작되고 나중에 완료가 표시될 경우 WSA_IO_PENDING 반환합니다. WSACOMPLETION 구조에 지정된 메서드는 쿼리 집합이 여전히 유효한 경우 애플리케이션에 알리는 데 사용됩니다.

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

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

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

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

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

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

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

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

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

요구 사항


지원되는 최소 클라이언트	Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	ws2spi.h