NSPLookupServiceBegin

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. Since this operation can not be canceled, it should be implemented to execute quickly. While it is acceptable to initiate a network query, this function should not require a response in order to return successfully.

int NSPLookupServiceBegin (
  LPGUID lpProviderId,                         
  LPWSAQUERYSETW lpqsRestrictions,             
  LPWSASERVICECLASSINFOW lpServiceClassInfo,   
  DWORD dwControlFlags,                        
  LPHANDLE lphLookup                           
);
 

Parameters

lpProviderId

[in] Contains the specific provider ID that should be used for the query.

lpqsRestrictions

[in] Contains the search criteria. See below for more information.

lpServiceClassInfo

[in] A WSASERVICECLASSINFOW structure which contains all of the schema information for the service.

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_FLUSHPREVIOUS	Used as a value for the dwControlFlags argument in NSPLookupServiceNext. Setting this flag instructs the provider to discard the last result set, which was too large for the supplied buffer, and move on to the next result set.
LUP_NEAREST	If possible, return results in the order of distance. The measure of distance is provider specific.
LUP_RES_RESERVICE	This indicates whether prime response is in the remote or local part of CSADDR_INFO structure. The other part needs to ber"usable" in either case.
LUP_RETURN_ALIASES	Any available alias information is to be returned in successive calls to NSPLookupServiceNext, and each alias returned will have the RESULT_IS_ALIAS flag set.
LUP_RETURN_NAME	Retrieve the name as lpszServiceInstanceName.
LUP_RETURN_TYPE	Retrieve the type as lpServiceClassId.
LUP_RETURN_WSAVERSION	Retrieve the version as lpVersion.
LUP_RETURN_COMMENT	Retrieve the comment as lpszComment.
LUP_RETURN_ADDR	Retrieve the addresses as lpcsaBuffer.
LUP_RETURN_BLOB	Retrieve the private data as lpBlob.
LUP_RETURN_ALL	Retrieve all of the information.

lphLookup

[out] Handle to be used in subsequent calls to NSPLookupServiceNext in order to retrieve 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 can all be of some well-known type, or of a set of well-known types, and therefore a query restriction could 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 = NSPLookupServiceBegin(
    lpqsRestrictions,
    LUP_CONTAINERS,
    lphLookup);
 

followed by the requisite number of NSPLookupServiceNext 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 NSPLookupServiceBegin use the containers returned from a previous call.

Forming Queries

As mentioned above, a WSAQUERYSET structure is used as an input parameter to NSPLookupServiceBegin 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 can be supplied, indicating that the field will not be used as a search criteria. See section Query-Related Data Structures for additional information.

Return Values

The function should return NO_ERROR (zero) if the routine succeeds. It should return SOCKET_ERROR (-1) if the routine fails and it must set the appropriate error code using SetLastError.

Error Codes

QuickInfo

  Windows NT: Yes
  Windows: Yes
  Windows CE: Unsupported.
  Header: Declared in ws2spi.h.