Compartilhar via

NSPLookupServiceBegin

  • Artigo

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This 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. Because this operation cannot 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.

Syntax

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

Parameters

  • lpProviderId
    [in] Contains the specific provider identifier that should be used for the query.
  • lpqsRestrictions
    [in] Contains the search criteria. For more information, see below.
  • lpServiceClassInfo
    [in] Structure that contains all the schema information for the service.

  • dwControlFlags
    [in] Controls the depth of the search. The following table shows the possible values.

    Value Description

    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 parameter 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

    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 NSPLookupServiceNext, 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_WSAVERSION

    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 the information.
  • lphLookup
    [out] Handle to be used in subsequent calls to NSPLookupServiceNext in order to retrieve the results set.

Return Value

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.

The following table shows the possible error codes.

Error value Description

WSAEINVAL

One or more parameters were invalid for this provider or missing.

WSANO_DATA

Name was found in the database but it does not have the correct associated data being resolved for.

WSASERVICE_NOT_FOUND

No such service is known. The service cannot be found in the specified name space.

WSA_NOT_ENOUGH_MEMORY

Not enough free memory available to perform this operation.

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 following code sample shows the preferred method of obtaining the containers within another container,

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 previously mentioned, 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 member is marked as (Optional) a NULL pointer can be supplied, indicating that the parameter will not be used as a search criteria.

WSAQUERYSET member name Query interpretation

dwSize

Will be set to sizeof(WSAQUERYSET). This is a versioning mechanism.

dwOuputFlags

Ignored for queries.

lpszServiceInstanceName

(Optional) Referenced string contains service name. The semantics for wildcarding within the string are not defined, but can be supported by certain name-space providers.

lpServiceClassId

(Required) GUID corresponding to the service class.

lpVersion

(Optional) References the desired version number and provides version comparison semantics (that is, the version must either match exactly or must be not less than the value supplied).

lpszComment

Ignored for queries.

dwNameSpace

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. This can be zero.

lpafpProtocols

(Optional) References an array of AFPROTOCOLS structure. Only services that utilize these protocols will be returned. It is legal for the value AF_UNSPEC to appear as a protocol family value, signifying a wildcard. Name space providers may supply information on any service that uses the corresponding protocol, regardless of address family.

lpszQueryString

(Optional) Specifies a simple string that is an enriched SQL-like query. Some name spaces (such as whois++) support these queries.

dwNumberOfCsAddrs

Ignored for queries.

lpcsaBuffer

Ignored for queries.

lpBlob

(Optional) Pointer to a provider-specific entity.

Requirements

Header ws2spi.h
Library Ws2.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

AFPROTOCOLS
WSAQUERYSET (Windows Sockets)
WSASERVICECLASSINFO
NSPLookupServiceNext