Export (0) Print
Expand All
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

WSALookupServiceBegin (Windows Sockets)

Windows Mobile 6.5
A version of this page is also available for
4/8/2010

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


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

lpqsRestrictions

[in] Pointer to the search criteria.

dwControlFlags

[in] Flag that controls the depth of the search. The following table shows a list of flags for the dwControlFlags parameter.

Flag Description

LUP_DEEP

Queries deep as opposed to just the first level.

LUP_NOCONTAINERS

Does not return any containers.

LUP_NEAREST

If possible, returns results in the order of distance. The measure of distance is provider specific.

LUP_RES_SERVICE

Indicates whether prime response is in the remote or local part of the 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 (Windows Sockets), 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 (Windows Sockets) to start retrieving the results set.

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

The following table shows a list of possible error codes.

Error code Description

WSAEINVAL

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

WSANO_DATA

The name was found in the database but no data matching the given restrictions was located.

WSANOTINITIALIZED

Ws2.dll has not been initialized. The application must first call the WSAStartup function before calling any Windows Sockets functions.

WSASERVICE_NOT_FOUND

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

WSA_NOT_ENOUGH_MEMORY

There was insufficient memory to perform the operation.

WSAEFAULT

The restriction parameters specified in lpqsRestrictions or the handle returned in lphLookup by WSALookupServiceBegin are not valid.

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 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 name space does not support containers, and LUP_CONTAINERS is specified, it should simply return WSANO_DATA.

Aa916075.note(en-us,MSDN.10).gifNote:
The built-in DNS name space provider does not accept the LUP_CONTAINERS flag. Specifying the LUP_CONTAINERS flag in a call to WSALookupServiceBegin will result in a WSANO_DATA error.

The following code sample is the preferred method of obtaining the containers within another container.

dwStatus = WSALookupServiceBegin(
      lpqsRestrictions,
      LUP_CONTAINERS,
      lphLookup);

This call is followed by the requisite number of WSALookupServiceNext (Windows Sockets) 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 (Windows Sockets) structure is used as an input parameter to WSALookupBegin to qualify the query. The following table indicates how the WSAQUERYSET (Windows Sockets) structure is used to construct a query. When a parameter is marked as (Optional), a NULL pointer can be supplied, indicating that the parameter will not be used as a search criteria.

Member Query interpretation

dwSize

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

dwOutputflags

Ignored for queries.

lpszServiceInstanceName

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

lpServiceClassId

(Required) The globally unique identifier (GUID) corresponding to the service class.

lpVersion

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

lpszComment

Ignored for queries.

dwNameSpace1

The 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

The size of the protocol constraint array, which can be zero.

lpafpProtocols

(Optional) References an array of the AFPROTOCOLS structure. Only services that use these protocols will be returned.

lpszQueryString

(Optional) Some name spaces (such as whois++) support enriched SQL-like queries that 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.

Aa916075.note(en-us,MSDN.10).gifImportant:
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.

Bluetooth clients use WSALookupServiceBegin (Windows Sockets), WSALookupServiceNext (Windows Sockets), and WSALookupServiceEnd to discover the existence of a particular service on the Bluetooth RFCOMM server. Queries can be done for local and remote addresses, although for RFCOMM a client can connect only to remote addresses.

Headerwinsock2.h
LibraryWs2.lib
Windows Embedded CEWindows CE .NET 4.0 and later
Windows MobileWindows Mobile Version 5.0 and later

Community Additions

Show:
© 2014 Microsoft