LPNSPLOOKUPSERVICEBEGIN 콜백 함수(ws2spi.h)

  • 아티클

NSPLookupServiceBegin 함수는 WSAQUERYSET 구조에 포함된 정보로 제한되는 이름 서비스 공급자의 클라이언트 쿼리를 시작합니다.

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

구문

LPNSPLOOKUPSERVICEBEGIN Lpnsplookupservicebegin;

INT Lpnsplookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSETW lpqsRestrictions,
  [in]  LPWSASERVICECLASSINFOW lpServiceClassInfo,
  [in]  DWORD dwControlFlags,
  [out] LPHANDLE lphLookup
)
{...}

매개 변수

[in] lpProviderId

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

[in] lpqsRestrictions

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

[in] lpServiceClassInfo

서비스에 대한 스키마 정보를 포함하는 WSASERVICECLASSINFO 구조체에 대한 포인터입니다.

[in] dwControlFlags

검색의 깊이를 제어하는 값입니다.

값 의미
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
 사용 가능한 모든 별칭 정보는 NSPLookupServiceNext에 대한 연속 호출에서 반환되며 반환되는 각 별칭에는 **RESULT_IS_ALIAS** 플래그가 설정됩니다.
LUP_RETURN_QUERY_STRING
0x0800
 쿼리 문자열을 **lpszQueryString**으로 검색합니다.
LUP_RETURN_ALL
0x0ff0
 이름, 형식, 버전, 주석, 주소, Blob, 별칭 및 쿼리 문자열을 포함한 정보를 검색합니다.
LUP_FLUSHCACHE
0x1000
 공급자가 정보를 캐시한 경우 캐시를 무시하고 네임스페이스 자체를 쿼리합니다.
LUP_FLUSHPREVIOUS
0x2000
 NSPLookupServiceNext에서 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 매핑된 주소)에만 적용됩니다.

[out] lphLookup

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

반환 값

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

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

설명

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

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

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

dwStatus = NSPLookupServiceBegin(
    lpqsRestrictions,
    LUP_CONTAINERS,
    lphLookup);

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

쿼리 형성

언급했듯이 WSAQUERYSET 구조체는 NSPLookupServiceBegin 에 대한 입력 매개 변수로 사용되어 쿼리를 한정합니다. 다음 표에서는 WSAQUERYSET 멤버 이름을 나열하고 WSAQUERYSET 을 사용하여 쿼리를 생성하는 방법을 설명합니다. 멤버가 (선택 사항)으로 표시되면 매개 변수가 검색 조건으로 사용되지 않음을 나타내는 null 포인터를 제공할 수 있습니다. 자세한 내용은 쿼리 관련 데이터 구조를 참조하세요.

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

요구 사항

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

참고 항목

AFPROTOCOLS

NSPLookupServiceEnd

NSPLookupServiceNext

NSP_ROUTINE

WSAQUERYSET

WSASERVICECLASSINFO

WSASetLastError