WSALookupServiceBeginA 함수(winsock2.h)

아티클
11/20/2024

WSALookupServiceBegin 함수는 WSAQUERYSET 구조에 포함된 정보로 제한되는 클라이언트 쿼리를 시작합니다. WSALookupServiceBeginWSALookupServiceNext 대한 후속 호출에서 실제 결과를 가져오는 데 사용해야 하는 핸들만 반환합니다.

통사론

INT WSAAPI WSALookupServiceBeginA(
  [in]  LPWSAQUERYSETA lpqsRestrictions,
  [in]  DWORD          dwControlFlags,
  [out] LPHANDLE       lphLookup
);

매개 변수

[in] lpqsRestrictions

검색 조건에 대한 포인터입니다. 자세한 내용은 비고를 참조하세요.

[in] dwControlFlags

검색의 깊이를 제어하는 플래그 집합입니다.

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	사용 가능한 별칭 정보는 WSALookupServiceNext연속 호출에서 반환되며 반환되는 각 별칭에는 RESULT_IS_ALIAS 플래그가 설정됩니다.
LUP_RETURN_QUERY_STRING 0x0800	요청에 사용되는 쿼리 문자열을 검색합니다.
LUP_RETURN_ALL 0x0FF0	모든 LUP_RETURN_* 값을 검색하는 플래그 집합입니다.
LUP_FLUSHPREVIOUS 0x1000	WSALookupServiceNextdwControlFlags 매개 변수의 값으로 사용됩니다. 이 플래그를 설정하면 공급자가 지정된 버퍼에 비해 너무 큰 마지막 결과 집합을 삭제하고 다음 결과 집합으로 이동하도록 지시합니다.
LUP_FLUSHCACHE 0x2000	공급자가 정보를 캐싱한 경우 캐시를 무시하고 네임스페이스 자체를 쿼리합니다.
LUP_RES_SERVICE 0x8000	이는 주요 응답이 CSADDR_INFO 구조의 원격 또는 로컬 부분에 있는지 여부를 나타냅니다. 다른 부분은 두 경우 모두 사용할 수 있어야 합니다.

[out] lphLookup

결과 집합 검색을 시작하기 위해 WSALookupServiceNext 호출할 때 사용할 핸들입니다.

반환 값

작업이 성공한 경우 반환 값은 0입니다. 그렇지 않으면 SOCKET_ERROR 값이 반환되고 WSAGetLastError호출하여 특정 오류 번호를 검색할 수 있습니다.

오류 코드	의미
WSA_NOT_ENOUGH_MEMORY	작업을 수행할 메모리가 부족했습니다.
WSAEINVAL	하나 이상의 매개 변수가 누락되었거나 이 공급자에 대해 잘못되었습니다.
WSANO_DATA	이름이 데이터베이스에 있지만 지정된 제한 사항과 일치하는 데이터가 없습니다.
WSANOTINITIALISED	WS2_32.DLL 초기화되지 않았습니다. 애플리케이션은 먼저 Windows 소켓 함수를 호출하기 전에 WSAStartup 호출해야 합니다.
WSASERVICE_NOT_FOUND	이러한 서비스는 알려져 있지 않습니다. 지정된 이름 공간에서 서비스를 찾을 수 없습니다. 원격 Bluetooth 디바이스를 찾을 수 없는 경우 Bluetooth 서비스 검색 요청에 대해 이 오류가 반환됩니다.

발언

lpqsRestrictions 매개 변수는 WSAQUERYSET 구조체가 포함된 버퍼를 가리킵니다. 최소한 WSAQUERYSETdwSize 멤버는 WSALookupServiceBegin 함수를 호출하기 전에 버퍼의 길이로 설정해야 합니다. 애플리케이션은 WSAQUERYSET다른 멤버를 지정하여 쿼리를 제한할 수 있습니다.

대부분의 경우 특정 전송 프로토콜에만 관심이 있는 애플리케이션은 dwNameSpace 멤버에서 네임스페이스를 지정하는 대신 dwNumberOfProtocols 및 lpafpProtocolsWSAQUERYSET 멤버를 사용하여 주소 패밀리 및 프로토콜별로 쿼리를 제한해야 합니다.

지원되는 네트워크 전송 프로토콜에 대한 정보는 EnumProtocols, WSAEnumProtocols, WSCEnumProtocols또는 WSCEnumProtocols32 함수를 사용하여 수 있습니다.

쿼리를 단일 네임스페이스로 제한할 수도 있습니다. 예를 들어 DNS의 결과만 원하는 쿼리(로컬 호스트 파일 및 기타 명명 서비스의 결과가 아님)는 dwNameSpace 멤버를 NS_DNS 설정합니다. 예를 들어 bluetooth 디바이스 검색은 dwNameSpace 멤버를 NS_BTH 설정합니다.

애플리케이션은 lpNSProviderId 멤버에서 공급자의 GUID에 대한 포인터를 지정하여 쿼리를 특정 네임스페이스 공급자로 제한할 수도 있습니다.

로컬 컴퓨터의 네임스페이스 공급자에 대한 정보는 WSAEnumNameSpaceProviders, WSAEnumNameSpaceProvidersEx, WSCEnumNameSpaceProviders32또는 WSCEnumNameSpaceProvidersEx32 함수를 사용하여 검색할 수 있습니다.

호출에서 LUP_CONTAINERS 지정한 경우 다른 제한 값을 피해야 합니다. 지정된 경우 이름 서비스 공급자가 컨테이너에 대해 이 제한을 지원할 수 있는지 여부를 결정해야 합니다. 오류가 반환될 수 없는 경우 오류를 반환해야 합니다.

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

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

dwStatus = WSALookupServiceBegin(
      lpqsRestrictions,
      LUP_CONTAINERS,
      lphLookup);

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

위에서 설명한 것처럼 WSAQUERYSET 구조체는 쿼리를 한정하기 위해 WSALookupBegin 입력 매개 변수로 사용됩니다. 다음 표에서는 WSAQUERYSET 사용하여 쿼리를 생성하는 방법을 나타냅니다. 매개 변수가 (선택 사항)으로 표시되면 NULL 포인터를 지정할 수 있습니다. 이는 매개 변수가 검색 조건으로 사용되지 않음을 나타냅니다. 자세한 내용은 Query-Related 데이터 구조 섹션을 참조하세요.

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

중요 대부분의 경우 특정 전송 프로토콜에만 관심이 있는 애플리케이션은 네임스페이스가 아닌 주소 패밀리 및 프로토콜별로 쿼리를 제한해야 합니다. 이렇게 하면 TCP/IP 서비스를 찾아야 하는 애플리케이션(예: 로컬 호스트 파일, DNS 및 NIS)과 같은 사용 가능한 모든 네임스페이스에서 쿼리를 처리할 수 있습니다.

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

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

메모

winsock2.h 헤더는 WSALookupServiceBegin을 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입대한 규칙을 참조하세요.

요구 사항

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