WSALookupServiceNext (Windows Sockets)
A version of this page is also available for
4/8/2010
This function is called after obtaining a handle from a previous call to the WSALookupServiceBegin (Windows Sockets) function to retrieve the requested service information.
The provider will pass back a WSAQUERYSET (Windows Sockets) structure in the lpqsResults buffer. The client should continue to call this function until it returns WSA_E_NOMORE, indicating that all of WSAQUERYSET (Windows Sockets) has been returned.
Syntax
INT WSALookupServiceNext(
HANDLE hLookup,
DWORD dwControlFlags,
LPDWORD lpdwBufferLength,
LPWSAQUERYSET lpqsResults
);
Parameters
- hLookup
[in] Handle returned from the previous call to WSALookupServiceBegin (Windows Sockets).
- dwControlFlags
[in] Flags to control the next operation. The Windows Embedded CE provider does not support this flag and will ignore it (silently).
- lpdwBufferLength
[in, out] On input, the number of bytes contained in the buffer pointed to by lpqsResults. On output, if the function fails and the error is WSAEFAULT, then it contains the minimum number of bytes to pass for the lpqsResults parameter to retrieve the record.
- lpqsResults
[out] Pointer to a block of memory, which will contain one result set in a WSAQUERYSET (Windows Sockets) structure on return.
Return Value
If the operation was successful, the return value is zero. If an error occurs, the value SOCKET_ERROR is returned, and a specific error number can be retrieved by calling WSAGetLastError. The following table shows a list of possible error codes.
| Error code | Description |
|---|---|
WSA_E_NO_MORE |
There is no more data available. In Winsock 2.2 conflicting error codes are defined for WSAENOMORE (10102) and WSA_E_NO_MORE (10110). The error code WSAENOMORE will be removed in a future version and only WSA_E_NO_MORE will remain. For Winsock 2.2, however, applications should check for both WSAENOMORE and WSA_E_NO_MORE for the widest possible compatibility with name space providers that use either one. |
WSA_E_CANCELLED |
A call to the WSALookupServiceEnd (Windows Sockets) function was made while this call was still processing. The call has been canceled. The data in the lpqsResults buffer is undefined. In Winsock 2.2 , conflicting error codes are defined for WSAECANCELLED (10103) and WSA_E_CANCELLED (10111). The error code WSAECANCELLED will be removed in a future version and only WSA_E_CANCELLED will remain. For Winsock 2.2 , however, applications should check for both WSAECANCELLED and WSA_E_CANCELLED for the widest possible compatibility with name space providers that use either one. |
WSAEFAULT |
The lpqsResults buffer was too small to contain a WSAQUERYSET set. |
WSAEINVAL |
One or more required parameters were invalid or missing. |
WSA_INVALID_HANDLE |
The specified Lookup handle is invalid. |
WSANOTINITIALIZED |
Ws2.dll has not been initialized. The application must first call the WSAStartup function before calling any Windows Sockets functions. |
WSANO_DATA |
The name was found in the database, but no data matching the given restrictions was located. |
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. |
Remarks
The dwControlFlags parameter specified in this function and the ones specified at the time of WSALookupServiceBegin (Windows Sockets) are treated as restrictions for the purpose of combination. The restrictions are combined between the ones at WSALookupServiceBegin time and the ones at WSALookupServiceNext time. Therefore, the flags at WSALookupServiceNext can never increase the amount of data returned beyond what was requested at WSALookupServiceBegin, although it is not an error to specify more or fewer flags. The flags specified at a given WSALookupServiceNext apply only to that call.
The dwControlFlags LUP_FLUSHPREVIOUS and LUP_RES_SERVICE are exceptions to the combined restrictions rule because they are behavior flags instead of restriction flags. If either of these flags is used in WSALookupServiceNext, it will have its defined effect regardless of the setting of the same flags at WSALookupServiceBegin.
For example, if LUP_RETURN_VERSION is specified at WSALookupServiceBegin, the service provider retrieves records including the version. If LUP_RETURN_VERSION is not specified at WSALookupServiceNext, the returned information does not include the version, even though it was available. No error is generated.
Also, for example, if LUP_RETURN_BLOB is not specified at WSALookupServiceBegin but is specified at WSALookupServiceNext, the returned information does not include the private data. No error is generated.
Query Results
The following table describes how the query results are represented in the WSAQUERYSET (Windows Sockets) structure.
| WSAQUERYSET member name | Result interpretation |
|---|---|
dwSize |
Will be set to sizeof(WSAQUERYSET). This is used as a versioning mechanism. |
dwOuputFlags |
The RESULT_IS_ALIAS flag indicates this is an alias result. |
'l'->LpszServiceInstanceName |
The referenced string contains the service name. |
'l'->LpServiceClassId |
The GUID corresponding to the service class. |
'l'->LpVersion |
References the version number of the particular service instance. |
'l'->LpszComment |
An optional comment string supplied by the service instance. |
'd'->DwNameSpace |
The name space in which the service instance was found. |
'l'->LpNSProviderId |
Identifies the specific name space provider that supplied this query result. |
'l'->LpszContext |
Specifies the context point in a hierarchical name space at which the service is located. |
'd'->DwNumberOfProtocols |
Undefined for results. |
lpafpProtocols |
Undefined for results. All needed protocol information is in the CSADDR_INFO structures. |
'l'->LpszQueryString |
When dwControlFlags includes LUP_RETURN_QUERY_STRING, this parameter returns the unparsed remainder of the lpszServiceInstanceName specified in the original query. For example, in a name space that identifies services by hierarchical names that specify a host name and a file path within that host, the address returned might be the host address and the unparsed remainder might be the file path. If the lpszServiceInstanceName is fully parsed and LUP_RETURN_QUERY_STRING is used, this parameter is NULL or points to a zero-length string. |
'd'->DwNumberOfCsAddrs |
Indicates the number of elements in the array of CSADDR_INFO structures. |
'l'->LpcsaBuffer |
A pointer to an array of CSADDR_INFO structures, with one complete transport address contained within each element. |
'l'->LpBlob |
(Optional) This is a pointer to a provider-specific entity. |
Notes for Bluetooth
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.
Requirements
| Header | winsock2.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
WSALookupServiceBegin (Windows Sockets)
WSALookupServiceEnd (Windows Sockets)
WSAGetLastError
WSAStartup