LPNSPV2LOOKUPSERVICEBEGIN 콜백 함수(ws2spi.h)

아티클
08/28/2023

NSPv2LookupServiceBegin 함수는 WSAQUERYSET2 구조에 포함된 정보로 제한되는 네임스페이스 버전 2 서비스 공급자의 클라이언트 쿼리를 시작합니다.

구문

LPNSPV2LOOKUPSERVICEBEGIN Lpnspv2lookupservicebegin;

INT Lpnspv2lookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSET2W lpqsRestrictions,
  [in]  DWORD dwControlFlags,
  [out] LPVOID lpvClientSessionArg,
  [out] LPHANDLE lphLookup
)
{...}

매개 변수

[in] lpProviderId

쿼리할 네임스페이스 서비스 공급자의 식별자에 대한 포인터입니다.

[in] lpqsRestrictions

검색 조건에 대한 포인터입니다. 설명 부분을 참조하세요.

[in] dwControlFlags

검색에 영향을 주는 플래그 집합입니다. 이 매개 변수는 Winsock2.h 헤더 파일에 정의된 다음 값의 조합일 수 있습니다.

값	의미
LUP_DEEP 0x0001	첫 번째 수준이 아닌 공급자의 계층 구조를 쿼리합니다.
LUP_CONTAINERS 0x0002	컨테이너만 반환합니다.
LUP_NOCONTAINERS 0x0004	컨테이너를 반환하지 않습니다.
LUP_NEAREST 0x0008	가능하면 는 거리 순서로 결과를 반환합니다. 거리 측정값은 공급자별입니다.
LUP_RETURN_NAME 0x0010	이름을 lpszServiceInstanceName으로 검색합니다.
LUP_RETURN_TYPE 0x0020	형식을 lpServiceClassId로 검색합니다.
LUP_RETURN_VERSION 0x0040	버전을 lpVersion으로 검색합니다.
LUP_RETURN_COMMENT 0x0080	주석을 lpszComment로 검색합니다.
LUP_RETURN_ADDR 0x0100	주소를 lpcsaBuffer로 검색합니다.
LUP_RETURN_BLOB 0x0200	개인 데이터를 lpBlob으로 검색합니다.
LUP_RETURN_ALIASES 0x0400	사용 가능한 모든 별칭 정보는 NSPv2LookupServiceNextEx에 대한 연속 호출에서 반환되며 반환되는 각 별칭에는 RESULT_IS_ALIAS 플래그가 설정됩니다.
LUP_RETURN_QUERY_STRING 0x0800	쿼리 문자열을 lpszQueryString으로 검색합니다.
LUP_RETURN_ALL 0x0ff0	이름, 형식, 버전, 주석, 주소, Blob, 별칭 및 쿼리 문자열을 포함한 정보를 검색합니다.
LUP_FLUSHCACHE 0x1000	공급자가 정보를 캐시한 경우 캐시를 무시하고 네임스페이스 자체를 쿼리합니다.
LUP_FLUSHPREVIOUS 0x2000	NSPv2LookupServiceNextEx에서 dwControlFlags 매개 변수의 값으로 사용됩니다. 이 플래그를 설정하면 공급자가 제공된 버퍼에 비해 너무 큰 마지막 결과 집합을 삭제하고 다음 결과 집합으로 이동하도록 지시합니다.
LUP_NON_AUTHORITATIVE 0x4000	네임스페이스 공급자가 이름에 대해 신뢰할 수 없는 결과를 포함해야 했음을 나타냅니다.
LUP_RES_RESERVICE 0x8000	소수 응답이 CSADDR_INFO 구조의 원격 또는 로컬 부분에 있는지 여부를 나타냅니다. 다른 부분은 두 경우 모두 사용할 수 있어야 합니다. 이 옵션은 서비스 instance 요청에만 적용됩니다.
LUP_SECURE 0x8000	네임스페이스 공급자가 보안 쿼리를 사용해야 임을 나타냅니다. 이 옵션은 이름 쿼리 요청에만 적용됩니다.
LUP_RETURN_PREFERRED_NAMES 0x10000	네임스페이스 공급자가 기본 설정 이름만 반환해야 했음을 나타냅니다.
LUP_ADDRCONFIG 0x100000	네임스페이스 공급자가 주소 구성을 반환해야 했음을 나타냅니다.
LUP_DUAL_ADDR 0x200000	네임스페이스 공급자가 이중 주소를 반환해야 했음을 나타냅니다. 이 옵션은 이중 모드 소켓(IPv6 및 IPv4 매핑된 주소)에만 적용됩니다.
LUP_DISABLE_IDN_ENCODING 0x800000	네임스페이스 공급자가 자동 International Domain Names 인코딩을 사용하지 않도록 설정해야 함을 나타냅니다. 이 값은 Windows 8 및 Windows Server 2012 지원됩니다.

[out] lpvClientSessionArg

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

[out] lphLookup

결과 집합을 검색하기 위해 NSPv2LookupServiceNextEx에 대한 후속 호출에 사용할 핸들에 대한 포인터입니다.

반환 값

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

오류 코드	의미
WSAEINVAL	이 공급자에 대해 하나 이상의 매개 변수가 잘못되었거나 누락되었습니다.
WSANO_DATA	이름이 데이터베이스에서 발견되었지만 확인된 올바른 연결된 데이터가 없습니다.
WSASERVICE_NOT_FOUND	서비스를 알 수 없습니다. 지정된 네임스페이스에서 서비스를 찾을 수 없습니다.
WSA_NOT_ENOUGH_MEMORY	이 작업을 수행하는 데 사용할 수 있는 메모리가 부족합니다.

설명

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

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

NSPv2LookupServiceBegin 함수는 NSPv2LookupServiceNextEx에 대한 후속 호출에서 실제 결과를 가져오는 데 사용해야 하는 핸들만 반환합니다. 이 작업은 취소할 수 없으므로 신속하게 실행되도록 구현해야 합니다. 네트워크 쿼리를 시작하는 것은 허용되지만 이 함수는 성공적으로 반환하기 위해 응답이 필요하지 않아야 합니다.

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

호출에서 LUP_CONTAINERS 지정한 경우 다른 모든 제한 값을 사용하지 않도록 합니다. 제공된 경우 이름 서비스 공급자는 컨테이너에 대한 이 제한을 지원할 수 있는지 여부를 결정해야 합니다. 그렇지 않은 경우 오류를 반환해야 합니다.

일부 이름 서비스 공급자에는 컨테이너를 찾는 다른 수단이 있을 수 있습니다. 예를 들어 컨테이너는 모두 잘 알려진 형식이거나 잘 알려진 형식 집합일 수 있으므로 찾기 위해 쿼리 제한을 만들 수 있습니다. 이름 서비스 공급자가 컨테이너를 찾기 위한 다른 의미에 관계없이 LUP_CONTAINERS 및 LUP_NOCONTAINERS 우선합니다. 따라서 컨테이너를 포함하는 쿼리 제한이 지정된 경우 LUP_NOCONTAINERS 지정하면 컨테이너 항목이 반환되지 않습니다. 마찬가지로 쿼리 제한에 관계없이 LUP_CONTAINERS 지정되면 컨테이너만 반환되어야 합니다. 네임스페이스가 컨테이너를 지원하지 않고 LUP_CONTAINERS 지정된 경우 WSANO_DATA 반환해야 합니다.

다른 컨테이너 내에서 컨테이너를 가져오는 기본 방법은 호출입니다.

dwStatus = NSPv2LookupServiceBegin(
    lpProviderId,
    lpqsRestrictions,
    LUP_CONTAINERS,
    lpClientSession,
    lphLookup);

NSPv2LookupServiceNextEx 호출의 필수 번호가 뒤따릅니다. 그러면 시작 컨텍스트 내에 포함된 모든 컨테이너가 반환됩니다. 즉, 심층 쿼리가 아닙니다. 이를 통해 계층 구조를 탐색하여 선택한 컨테이너의 콘텐츠를 열거하여 주소 공간 구조를 매핑할 수 있습니다. NSPv2LookupServiceBegin의 후속 사용은 이전 호출에서 반환된 컨테이너를 사용합니다.

쿼리 형성

WSAQUERYSET2 구조는 쿼리를 한정하기 위해 NSPv2LookupServiceBegin에 대한 입력 매개 변수로 사용됩니다. 다음 표에서는 **WSAQUERYSET2** 멤버 이름을 나열하고 **WSAQUERYSET2**를 사용하여 쿼리를 생성하는 방법을 설명합니다. NSPv2 공급자의 요구 사항에 따라 선택 사항으로 레이블이 지정된 멤버는 네임스페이스 공급자가 검색 조건으로 사용하지 않을 때 **NULL** 포인터로 제공할 수 있습니다. 자세한 내용은 쿼리 관련 데이터 구조를 참조하세요.

WSAQUERYSET2 멤버 이름	쿼리 해석
dwSize	sizeof(WSAQUERYSET2)로 설정됩니다. 이는 버전 관리 메커니즘입니다.
lpszServiceInstanceName	서비스 이름을 포함하는 문자열입니다. 문자열 내의 와일드카드에 대한 의미 체계는 정의되지 않지만 특정 네임스페이스 공급자에서 지원될 수 있습니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpVersion	버전 비교 의미 체계를 제공하는 원하는 버전 번호(즉, 버전이 정확히 일치해야 하거나 버전이 제공된 값보다 작지 않아야 합니다). 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpszComment	이 멤버는 쿼리에 대해 무시됩니다.
dwNameSpace	검색을 제한할 단일 네임스페이스의 식별자이거나 모든 네임스페이스를 포함하도록 NS_ALL입니다.
lpNSProviderId	쿼리를 이 공급자로만 제한하는 특정 네임스페이스 공급자의 GUID입니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpszContext	계층 구조 네임스페이스에서 쿼리의 시작점입니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
dwNumberOfProtocols	프로토콜 제약 조건 배열의 항목 수 크기(바이트)입니다. 이 멤버는 0일 수 있습니다.
lpafpProtocols	AFPROTOCOLS 구조체의 배열입니다. 이러한 프로토콜을 사용하는 서비스만 반환됩니다. AF_UNSPEC 값이 프로토콜 패밀리 값으로 표시되어 와일드카드를 나타내는 것이 허용됩니다. 네임스페이스 공급자는 주소 패밀리에 관계없이 해당 프로토콜을 사용하는 모든 서비스에 대한 정보를 제공할 수 있습니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpszQueryString	일부 네임스페이스(예: whois++)는 간단한 텍스트 문자열에 포함된 풍부한 SQL과 유사한 쿼리를 지원합니다. 이 매개 변수는 해당 문자열을 지정하는 데 사용됩니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
dwNumberOfCsAddrs	이 멤버는 쿼리에 대해 무시됩니다.
lpcsaBuffer	이 멤버는 쿼리에 대해 무시됩니다.
dwOutputFlags	이 멤버는 쿼리에 대해 무시됩니다.
lpBlob	공급자별 엔터티에 대한 포인터입니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.

요구 사항

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

추가 정보

AFPROTOCOLS

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceEnd

NSPv2LookupServiceNextEx

WSAQUERYSET2 멤버 이름	쿼리 해석
dwSize	sizeof(WSAQUERYSET2)로 설정됩니다. 이는 버전 관리 메커니즘입니다.
lpszServiceInstanceName	서비스 이름을 포함하는 문자열입니다. 문자열 내의 와일드카드에 대한 의미 체계는 정의되지 않지만 특정 네임스페이스 공급자에서 지원될 수 있습니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpVersion	버전 비교 의미 체계를 제공하는 원하는 버전 번호(즉, 버전이 정확히 일치해야 하거나 버전이 제공된 값보다 작지 않아야 합니다). 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpszComment	이 멤버는 쿼리에 대해 무시됩니다.
dwNameSpace	검색을 제한할 단일 네임스페이스의 식별자이거나 모든 네임스페이스를 포함하도록 NS_ALL입니다.
lpNSProviderId	쿼리를 이 공급자로만 제한하는 특정 네임스페이스 공급자의 GUID입니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpszContext	계층 구조 네임스페이스에서 쿼리의 시작점입니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
dwNumberOfProtocols	프로토콜 제약 조건 배열의 항목 수 크기(바이트)입니다. 이 멤버는 0일 수 있습니다.
lpafpProtocols	AFPROTOCOLS 구조체의 배열입니다. 이러한 프로토콜을 사용하는 서비스만 반환됩니다. AF_UNSPEC 값이 프로토콜 패밀리 값으로 표시되어 와일드카드를 나타내는 것이 허용됩니다. 네임스페이스 공급자는 주소 패밀리에 관계없이 해당 프로토콜을 사용하는 모든 서비스에 대한 정보를 제공할 수 있습니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
lpszQueryString	일부 네임스페이스(예: whois++)는 간단한 텍스트 문자열에 포함된 풍부한 SQL과 유사한 쿼리를 지원합니다. 이 매개 변수는 해당 문자열을 지정하는 데 사용됩니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.
dwNumberOfCsAddrs	이 멤버는 쿼리에 대해 무시됩니다.
lpcsaBuffer	이 멤버는 쿼리에 대해 무시됩니다.
dwOutputFlags	이 멤버는 쿼리에 대해 무시됩니다.
lpBlob	공급자별 엔터티에 대한 포인터입니다. 이 멤버는 NSPv2 서비스 공급자의 요구 사항에 따라 선택 사항입니다.

다음을 통해 공유