The 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.

Syntax

INT WSALookupServiceBegin(
  __in   LPWSAQUERYSET lpqsRestrictions,
  __in   DWORD dwControlFlags,
  __out  LPHANDLE lphLookup
);

Parameters

lpqsRestrictions [in]

Pointer to the search criteria. See the following for details.

dwControlFlags [in]

Flag that controls the depth of the search.

Flag	Meaning
LUP_DEEP	Queries deep as opposed to just the first level.
LUP_CONTAINERS	Returns containers only.
LUP_NOCONTAINERS	Does not return any containers.
LUP_FLUSHCACHE	If the provider has been caching information, ignores the cache, and queries the namespace itself.
LUP_FLUSHPREVIOUS	Used as a value for the dwControlFlags parameter in WSALookupServiceNext. Setting this flag instructs the provider to discard the last result set, which was too large for the specified buffer, and move on to the next result set.
LUP_NEAREST	If possible, returns 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_ALIASES	Any available alias information is to be returned in successive calls to WSALookupServiceNext, and each alias returned will have the RESULT_IS_ALIAS flag set.
LUP_RETURN_NAME	Retrieves the name as lpszServiceInstanceName.
LUP_RETURN_TYPE	Retrieves the type as lpServiceClassId.
LUP_RETURN_VERSION	Retrieves the version as lpVersion.
LUP_RETURN_COMMENT	Retrieves the comment as lpszComment.
LUP_RETURN_ADDR	Retrieves the addresses as lpcsaBuffer.
LUP_RETURN_BLOB	Retrieves the private data as lpBlob.
LUP_RETURN_ALL	Retrieves all of the information.

 

lphLookup [out]

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

Return Value

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

Remarks

If LUP_CONTAINERS is specified in a call, all other restriction values should be avoided. If any are specified, 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 can 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 can 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 namespace 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);

This call is 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.

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 parameter is marked as (Optional) a NULL pointer can be specified, indicating that the parameter will not be used as a search criteria. See section Query-Related Data Structures for additional information.

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

Requirements

See Also

Bluetooth and WSALookupServiceBegin

Winsock Reference

Winsock Functions

WSALookupServiceEnd

WSALookupServiceNext

Send comments about this topic to Microsoft

Build date: 11/12/2009