The NSPLookupServiceNext function is called after obtaining a Handle from a previous call to NSPLookupServiceBegin in order to retrieve the requested service information.
The provider will pass back a WSAQUERYSET structure in the lpqsResults buffer. The client should continue to call this function until it returns WSA_E_NOMORE, indicating that all of the WSAQUERYSET have been returned.
int NSPAPI WSALookupServiceNext (
HANDLE hLookup,
DWORD dwControlFlags,
LPDWORD lpdwBufferLength,
LPWSAQUERYSET lpqsResults
);
The dwControlFlags specified in this function and the ones specified at the time of NSPLookupServiceBegin are treated as "restrictions" for the purpose of combination. The restrictions are combined between the ones at NSPLookupServiceBegin timeand the ones at NSPLookupServiceNext time.Therefore the flags at NSPLookupServiceNext can never increase the amount of data returned beyond what was requested at NSPLookupServiceBegin, although it is NOT an error to specify more or fewer flags.The flags specified at a given NSPLookupServiceNext 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 are 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 NOT specified 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 NOT specified at NSPLookupServiceBegin but 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 WSAQUERYSET structure. Refer to section Query-Related Data Structures for additional information.
WSAQUERYSET Field 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. |
lpszServiceInstanceName | Referenced string contains service name. |
lpServiceClassId | The 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_INFO structures. |
lpszQueryString | When dwControlFlags includes LUP_RETURN_QUERY_STRING, this field 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 field is NULL or points to a zero-length string. |
dwNumberOfCsAddrs | Indicates the number of elements in the array of CSADDR_INFO structures. |
lpcsaBuffer | A pointer to an array of CSADDR_INFO structures, with one complete transport address contained within each element. |
lpBlob | (Optional) This is a pointer to a provider-specific entity. |
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.
WSA_E_NO_MORE | There is no more data available. In Windows Sockets 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.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 | A call to NSPLookupServiceEnd was made while this call was still processing. The call has been canceled. The data in the lpqsResults buffer is undefined. In Windows Sockets 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.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 lpqsResults buffer was too small to contain a WSAQUERYSET set. |
WSAEINVAL | One or more parameters were invalid or missing for this provider. |
WSA_INVALID_HANDLE | The 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. |
Windows NT: Yes
Windows: Yes
Windows CE: Unsupported.
Header: Declared in ws2spi.h.