WSALookupServiceBegin 11QSQSH

The Windows Sockets WSALookupServiceBegin function initiates a client query that is constrained by the information contained within a WSAQUERYSET structure. WSALookupServiceBegin only returns a handle, which should be used by subsequent calls to WSALookupServiceNext to get the actual results.

INT WSALookupServiceBegin (

LPWSAQUERYSET lpqsRestrictions,
DWORD dwControlFlags,
LPHANDLE lphLookup
);

Parameters

lpqsRestrictions

[in] Contains the search criteria. See below for details.

dwControlFlags

[in] Controls the depth of the search.

LUP_DEEP	Query deep as opposed to just the first level.
LUP_CONTAINERS	Return containers only
LUP_NOCONTAINERS	Do not return any containers
LUP_FLUSHCACHE	If the provider has been caching information, ignore the cache and go query the name space itself.
LUP_NEAREST	If possible, return results in the order of distance. The measure of distance is provider specific.
LUP_RES_SERVICE	This indicates whether prime response is in the remote or local part of CSADDR_INFO structure. The other part needs to be "usable" in either case.
LUP_RETURN_ALIAS	Any available alias information is to be returned in successive calls to WSALookupServiceNextVQ2H7O, and each alias returned will have the RESULT_IS_ALIAS flag set.
LUP_RETURN_NAME	Retrieve the name
LUP_RETURN_TYPE	Retrieve the type
LUP_RETURN_VERSION	Retrieve the version
LUP_RETURN_COMMENT	Retrieve the comment
LUP_RETURN_ADDR	Retrieve the addresses
LUP_RETURN_BLOB	Retrieve the private data
LUP_RETURN_ALL	Retrieve all of the information

lphLookup

[out] Handle to be used when calling WSALookupServiceNext in order to start retrieving the results set.

Remarks

If LUP_CONTAINERS is specified in a call, all other restriction values should be avoided. If any are supplied, it is up to the name service provider to decide if it can support this restriction over the containers. If it cannot, it should return an error.

Some name service providers may have other means of finding containers. For example, containers might all be of some well-known type, or of a set of well-known types, and therefore a query restriction may be created for finding them. No matter what other means the name service provider has for locating containers, LUP_CONTAINERS and LUP_NOCONTAINERS take precedence. Hence, if a query restriction is given that includes containers, specifying LUP_NOCONTAINERS will prevent the container items from being returned. Similarly, no matter the query restriction, if LUP_CONTAINERS is given, only containers should be returned. If a name space does not support containers, and LUP_CONTAINERS is specified, it should simply return WSANO_DATA.

The preferred method of obtaining the containers within another container, is the call:

dwStatus = WSALookupServiceBegin(

lpqsRestrictions,

LUP_CONTAINERS,

lphLookup);

followed by the requisite number of WSALookupServiceNext calls. This will return all containers contained immediately within the starting context; that is, it is not a deep query. With this, one can map the address space structure by walking the hierarchy, perhaps enumerating the content of selected containers. Subsequent uses of WSALookupServiceBegin use the containers returned from a previous call.

Forming Queries

As mentioned above, a WSAQUERYSET structure is used as an input parameter to WSALookupBegin in order to qualify the query. The following table indicates how the WSAQUERYSET is used to construct a query. When a field is marked as (Optional) a NULL pointer may be supplied, indicating that the field will not be used as a search criteria. See section Query-Related Data Structures.ZE7J4 for additional information.

WSAQUERYSET Field Name	Query Interpretation
dwSize	Must be set to sizeof(WSAQUERYSET). This is a versioning mechanism.
dwOutputflags	Ignored for queries.
lpszServiceInstanceName	(Optional) Referenced string contains service name. The semantics for wildcarding within the string are not defined, but may be supported by certain name space providers.
lpServiceClassId	(Required) The GUID corresponding to the service class.
lpVersion	(Optional) References desired version number and provides version comparison semantics (that is, version must match exactly, or version must be not less than the value supplied).
lpszComment	Ignored for queries.
dwNameSpace1	Identifier of a single name space in which to constrain the search, or NS_ALL to include all name spaces.
lpNSProviderId	(Optional) References the GUID of a specific name space provider, and limits the query to this provider only.
lpszContext	(Optional) Specifies the starting point of the query in a hierarchical name space.
dwNumberOfProtocols	Size of the protocol constraint array, may be zero.
lpafpProtocols	(Optional) References an array of AFPROTOCOLS structure. Only services that utilize these protocols will be returned.
lpszQueryString	(Optional) Some namespaces (such as whois++) support enriched SQL like queries which are contained in a simple text string. This parameter is used to specify that string.
dwNumberOfCsAddrs	Ignored for queries.
lpcsaBuffer	Ignored for queries.
lpBlob	(Optional) This is a pointer to a provider-specific entity.
1 See the Important note below

Important In most instances, applications interested in only a particular transport protocol should constrain their query by address family and protocol rather than by name space. This would allow an application that needs to locate a TCP/IP service, for example, to have its query processed by all available name spaces such as the local hosts file, DNS, and NIS.

Return Values

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSANO_DATA	The name was found in the database but no data matching the given restrictions was located.
WSANOTINITIALIZED	The Windows Sockets 2 DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
WSASERVICE_NOT_FOUND	No such service is known. The service cannot be found in the specified name space.