LPNSPV2SETSERVICEEX 콜백 함수(ws2spi.h)

아티클
08/28/2023

NSPv2SetServiceEx 함수는 네임스페이스 NSPv2(서비스 공급자 버전 2) 공급자의 네임스페이스 내에서 instance 이름 또는 서비스 등록을 취소합니다.

구문

LPNSPV2SETSERVICEEX Lpnspv2setserviceex;

void Lpnspv2setserviceex(
  [in] HANDLE hAsyncCall,
  [in] LPGUID lpProviderId,
  [in] LPWSAQUERYSET2W lpqsRegInfo,
  [in] WSAESETSERVICEOP essOperation,
  [in] DWORD dwControlFlags,
  [in] LPVOID lpvClientSessionArg
)
{...}

매개 변수

[in] hAsyncCall

비동기 호출에 사용된 NSPv2LookupServiceBegin 에 대한 이전 호출에서 반환된 핸들입니다.

[in] lpProviderId

이름 또는 서비스가 등록된 특정 네임스페이스 공급자의 GUID에 대한 포인터입니다.

[in] lpqsRegInfo

등록 시 업데이트할 속성 정보입니다.

[in] essOperation

요청된 작업의 유형입니다.

이 매개 변수는 Winsock2.h 헤더 파일에 정의된 WSAESETSERVICEOP 열거형 형식의 값 중 하나일 수 있습니다.

값	의미
RNRSERVICE_REGISTER 0	서비스를 등록합니다. NetWare 환경 내에서 사용되는 SAP(Service Advertising Protocol) 네임스페이스의 경우 이는 주기적인 브로드캐스트를 보내는 것을 의미합니다. DNS(Domain Name System) 네임스페이스에 대한 NOP입니다. 영구 데이터 저장소의 경우 이는 주소 정보를 업데이트하는 것을 의미합니다.
RNRSERVICE_DEREGISTER 1	서비스 등록을 취소합니다. SAP 네임스페이스의 경우 주기적인 브로드캐스트 전송을 중지합니다. DNS 네임스페이스에 대한 NOP입니다. 영구 데이터 저장소의 경우 이는 주소 정보를 삭제하는 것을 의미합니다.
RNRSERVICE_DELETE 2	동적 이름 및 영구 공간에서 서비스를 삭제합니다. 여러 CSADDR_INFO 구조체(SERVICE_MULTIPLE 플래그 사용)로 표시되는 서비스의 경우 제공된 주소만 삭제되며, 이는 서비스가 등록될 때 제공된 해당 CSADDR_INFO 구조와 정확히 일치해야 합니다.

[in] dwControlFlags

요청된 작업을 제어하는 플래그 집합입니다.

이 매개 변수에 사용할 수 있는 값은 Winsock2.h 헤더 파일에 정의되어 있습니다.

값	의미
SERVICE_MULTIPLE 0x00000001	작업의 scope 제어합니다. 이 값을 설정하면 지정된 주소 집합에서만 작업이 수행됩니다. 등록 작업은 기존 주소를 무효화하지 않으며 등록 취소 작업은 지정된 주소 집합만 무효화합니다. 이 값이 없으면 서비스 주소가 그룹으로 관리됩니다. 레지스터 또는 등록 취소는 지정된 주소 집합을 추가하기 전에 모든 기존 주소를 무효화합니다.

값

의미

SERVICE_MULTIPLE

0x00000001

작업의 scope 제어합니다.

이 값을 설정하면 지정된 주소 집합에서만 작업이 수행됩니다. 등록 작업은 기존 주소를 무효화하지 않으며 등록 취소 작업은 지정된 주소 집합만 무효화합니다.

이 값이 없으면 서비스 주소가 그룹으로 관리됩니다. 레지스터 또는 등록 취소는 지정된 주소 집합을 추가하기 전에 모든 기존 주소를 무효화합니다.

[in] lpvClientSessionArg

클라이언트 세션에 대한 포인터입니다.

반환 값

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

오류 코드	의미
WSA_NOT_ENOUGH_MEMORY	이 작업을 수행하는 데 사용할 수 있는 메모리가 부족합니다.
WSAEACCES	호출 루틴에는 서비스를 설치할 수 있는 충분한 권한이 없습니다.
WSAEINVAL	이 공급자에 대해 하나 이상의 매개 변수가 잘못되었거나 누락되었습니다.
WSAEOPNOTSUPP	이 작업은 지원되지 않습니다. 네임스페이스 공급자가 이 함수를 구현하지 않으면 이 오류가 반환됩니다. 지정된 dwControlCode 가 인식할 수 없는 명령인 경우에도 이 오류가 반환될 수 있습니다.
WSASERVICE_NOT_FOUND	서비스를 알 수 없습니다. 지정된 네임스페이스에서 서비스를 찾을 수 없습니다.

설명

NSPv2SetServiceEx 함수는 Windows Vista 이상에서 사용할 수 있는 네임스페이스 서비스 공급자 버전 2(NSPv2) 아키텍처의 일부로 사용됩니다.

Windows Vista 및 Windows Server 2008에서 NSPv2SetServiceEx 함수는 NS_EMAIL 네임스페이스 공급자의 작업에만 사용할 수 있습니다.

NSPv2Startup 함수는 새 클라이언트 프로세스가 네임스페이스 공급자를 사용하기 시작할 때마다 호출됩니다. 공급자는 ppvClientSessionArg 매개 변수가 가리키는 클라이언트 세션 인수를 사용하여 이 세션에 대한 정보를 저장할 수 있습니다. 이 클라이언트 세션 인수는 lpvClientSessionArg 매개 변수의 NSPv2SetServiceEx 함수에 전달할 수 있습니다.

NSPv2SetServiceEx 함수는 NSPv2 공급자의 요구 사항에 따라 선택 사항입니다. NSPv2SetServiceEx 함수가 구현되지 않은 경우 NSPv2 함수 포인터는 항상 NO_ERROR 반환하는 스텁 함수일 수 있습니다.

다음 표에서는 essOperation 및 dwControlFlags 매개 변수에 대한 값의 가능한 조합을 나열합니다.

essOperation	dwControlFlags	서비스가 이미 있음	서비스가 없습니다.
RNRSERVICE_REGISTER	없음	개체를 덮어씁니다. 지정된 주소만 사용합니다. 개체가 REGISTERED입니다.	새 개체를 만듭니다. 지정된 주소만 사용합니다. 개체가 REGISTERED입니다.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	업데이트 개체입니다. 기존 집합에 새 주소를 추가합니다. 개체가 REGISTERED입니다.	새 개체를 만듭니다. 지정된 모든 주소를 사용합니다. 개체가 REGISTERED입니다.
RNRSERVICE_DEREGISTER	없음	모든 주소를 제거하지만 네임스페이스에서 개체를 제거하지는 않습니다. 개체가 DEREGISTERED입니다.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	업데이트 개체입니다. 지정된 주소만 제거합니다. 주소가 없는 경우에만 개체를 DEREGISTERED로 표시합니다. 네임스페이스에서 제거하지 않습니다.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	없음	네임스페이스에서 개체를 제거합니다.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	지정된 주소만 제거합니다. 주소가 남아 있지 않은 경우에만 네임스페이스에서 개체를 제거합니다.	WSASERVICE_NOT_FOUND

dwControlFlags 매개 변수가 SERVICE_MULTIPLE 설정되면 애플리케이션에서 해당 주소를 독립적으로 관리할 수 있습니다. 이는 애플리케이션이 해당 프로토콜을 개별적으로 관리해야 하거나 서비스가 둘 이상의 컴퓨터에 상주할 때 유용합니다. 예를 들어 서비스에서 둘 이상의 프로토콜을 사용하는 경우 하나의 수신 대기 소켓이 중단되지만 다른 소켓은 계속 작동합니다. 이 예제에서 서비스는 다른 주소에 영향을 주지 않고 중단된 주소를 등록 취소할 수 있습니다.

SERVICE_MULTIPLE 사용하는 경우 애플리케이션에서 이전 주소가 개체에 남아 있게 해서는 안 됩니다. RNRSERVICE_DEREGISTER 요청을 실행 하지 않고 애플리케이션이 중단되는 경우에 발생할 수 있습니다. 서비스가 등록되면 해당 주소를 저장해야 합니다. 다음 호출에서 서비스는 새 주소를 등록하기 전에 이러한 이전 주소를 명시적으로 등록 취소해야 합니다.

NSPv2SetServiceEx 함수가 구현되지 않은 경우 WSAEOPNOTSUPP를 반환하는 스텁 함수에서 해당 함수에 대한 호출을 가로채야 합니다. NSPV2_ROUTINE 구조체에서 구현되지 않은 NSPv2SetServiceEx 함수에 대한 NSPv2 함수 포인터는 스텁 함수를 가리킵니다.

서비스 속성

다음 표에서는 WSAQUERYSET2 멤버 이름을 나열하고 서비스 속성 데이터를 나타내는 방법을 설명합니다. 선택 사항으로 레이블이 지정되고 NSPv2 공급자의 요구 사항에 종속된 멤버는 네임스페이스 공급자에서 사용하지 않을 때 **NULL** 포인터로 제공될 수 있습니다.

WSAQUERYSET2 멤버 이름	서비스 속성 설명
dwSize	sizeof(WSAQUERYSET2)로 설정합니다. 이는 버전 관리 메커니즘입니다.
lpszServiceInstanceName	서비스 instance 이름을 포함하는 문자열입니다.
lpVersion	서비스 instance 버전 번호입니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpszComment	주석 문자열입니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
dwNameSpace	네임스페이스 식별자입니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpNSProviderId	공급자 식별자입니다. 네임스페이스 공급자 식별자도 lpProviderId 매개 변수에 전달됩니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpszContext	계층 구조 네임스페이스에서 쿼리의 시작점입니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
dwNumberOfProtocols	프로토콜 제약 조건 배열의 항목 수 크기(바이트)입니다. 이 멤버는 0일 수 있습니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpafpProtocols	AFPROTOCOLS 구조체의 배열입니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpszQueryString	일부 네임스페이스(예: whois++)는 간단한 텍스트 문자열에 포함된 풍부한 SQL과 유사한 쿼리를 지원합니다. 이 매개 변수는 해당 문자열을 지정하는 데 사용됩니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
dwNumberOfCsAddrs	lpcsaBuffer에서 참조하는 CSADDR_INFO 구조체 배열의 요소 수입니다.
lpcsaBuffer	서비스에서 수신 대기하는 주소 또는 주소를 포함하는 CSADDR_INFO 구조체 배열에 대한 포인터입니다.
dwOutputFlags	이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpBlob	공급자별 엔터티에 대한 포인터입니다. 이 멤버는 NS_EMAIL 네임스페이스에 필요합니다. 이 멤버는 다른 NSPv2 서비스 공급자에 대한 요구 사항에 따라 선택 사항입니다.

**참고** CSADDR_INFO 구조체의 **iProtocol** 멤버가 와일드카드 값을 나타내는 **IPROTOCOL_ANY** 매니페스트 상수를 포함할 수 있습니다. 네임스페이스 공급자는 지정된 주소 패밀리 및 소켓 유형에 허용되는 값을 대체해야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	ws2spi.h