Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
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 NSPLookupServiceBeginin order to retrieve the requested service information.

The provider will pass back a WSAQUERYSETstructure in the lpqsResultsbuffer. The client should continue to call this function until it returns WSA_E_NOMORE, indicating that all the WSAQUERYSEThave been returned.

Syntax 

int NSPAPI WSALookupServiceNext(
  HANDLE
 hLookup,
  DWORD 
dwControlFlags,
  LPDWORD
 lpdwBufferLength,
  LPWSAQUERYSET
 lpqsResults 
);

Parameters

hLookup

[in] Handle returned from the previous call to WSALookupServiceBegin.

dwControlFlags

[in] Flags to control the next operation. Currently only LUP_FLUSHPREVIOUS is defined as a means to cope with a result set that is too large. If an application does not supply a large enough buffer, setting LUP_FLUSHPREVIOUS instructs the provider to discard the last result set, which was too large, and move to the next set for this call.

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 lpqsResultsto retrieve the record.

lpqsResults

[out] Pointer to a block of memory that will contain one result set in a WSAQUERYSETstructure on return.

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

WSA_E_NO_MORE

There is no more data available.

In Winsock, 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. Name space providers should switch to using the WSA_E_NO_MORE error code as soon as possible to maintain compatibility with the widest possible range of applications.

WSA_E_CANCELLED

Call to NSPLookupServiceEndwas made while this call was still processing. The call has been canceled. The data in the lpqsResultsbuffer is undefined.

In Winsock, 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. Name space providers should switch to using the WSA_E_CANCELLED error code as soon as possible to maintain compatibility with the widest possible range of applications.

WSAEFAULT

The lpqsResultsbuffer was too small to contain a WSAQUERYSETset.

WSAEINVAL

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

WSA_INVALID_HANDLE

Specified lookup handle is invalid.

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

Not enough free memory available to perform this operation.

Remarks

The dwControlFlagsspecified in this function and the ones specified at the time of NSPLookupServiceBeginare treated as "restrictions" for the purpose of combination. The restrictions are combined between the ones at NSPLookupServiceBegintime and the ones at NSPLookupServiceNexttime. Therefore, the flags at NSPLookupServiceNextcan never increase the amount of data returned beyond what was requested at NSPLookupServiceBegin, although it is notan error to specify more or less flags. The flags specified at a given NSPLookupServiceNextapply only to that call.

The dwControlFlagsLUP_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 NSPLookupServiceNext, they have their defined effect regardless of the setting of the same flags at NSPLookupServiceBegin.

For example, if LUP_RETURN_VERSION is specified at NSPLookupServiceBegin, the service provider retrieves records including the version. If LUP_RETURN_VERSION is notspecified at NSPLookupServiceNext, 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 notspecified at NSPLookupServiceBeginbut is specified at NSPLookupServiceNext, the returned information does not include the private data. No error is generated.

The following table describes how the query results are represented in the WSAQUERYSETstructure.

WSAQUERYSET member name Result interpretation

dwSize

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

dwOuputFlags

RESULT_IS_ALIAS flag indicates this is an alias result.

lpszServiceInstanceName

References the string that contains the service name.

lpServiceClassId

GUID corresponding to the service class.

lpVersion

References version number of the particular service instance.

lpszComment

Optional comment string supplied by service instance.

dwNameSpace

Name space in which the service instance was found.

lpNSProviderId

Identifies the specific name-space provider that supplied this query result.

lpszContext

Specifies the context point in a hierarchical name space at which the service is located.

dwNumberOfProtocols

Undefined for results.

lpafpProtocols

Undefined for results, all needed protocol information is in the CSADDR_INFOstructures.

lpszQueryString

When dwControlFlagsincludes LUP_RETURN_QUERY_STRING, this member returns the unparsed remainder of the lpszServiceInstanceNamespecified 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 lpszServiceInstanceNameis fully parsed and LUP_RETURN_QUERY_STRING is used, this member is NULL or points to a zero-length string.

dwNumberOfCsAddrs

Indicates the number of elements in the array of CSADDR_INFOstructures.

lpcsaBuffer

Pointer to an array of CSADDR_INFOstructures, with one complete transport address contained within each element.

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