BthNsLookupServiceNext
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
This function retrieves the results of an SDP search.
Note
To preserve Win32 compatibility, consider using the Winsock equivalent of this function. This function is equivalent to WSALookupServiceNext.
Syntax
INT BthNsLookupServiceNext(
HANDLE hLookup,
DWORD dwFlags,
LPDWORD lpdwBufferLength,
LPWSAQUERYSET pResults
);
Parameters
- hLookup
[in] Handle obtained from BthNsLookupServiceBegin.
dwFlags
[in] Control flags for the next operation. The following table shows the flags that are supported for a device inquiry.Flag Description LUP_RETURN_NAME
Performs a name inquiry and sets the results in the pResults lpszServiceInstanceName element.
LUP_RETURN_ADDR
Returns the address of the enumerated remote device in pResults->lpcsaBuffer->RemoteAddr.lpSockaddr.
LUP_RETURN_BLOB
Returns a BthInquiryResult structure in pResults->lpBlob->pBlobData.
BTHNS_LUP_RESET_ITERATOR
Causes the list enumeration to be reset. No data is returned during this call.
The next call to this function retrieves information on the first device in the enumeration list.
BTHNS_LUP_NO_ADVANCE
If this flag is not set, the next item in the list is enumerated on the next call to this function.
If this flag is set, the next call to this function returns information on the same remote device.
- lpdwBufferLength
[in, out] On input, the number of bytes contained in the buffer that pResults points to. On output, this parameter contains the minimum number of bytes the pResults parameter uses to retrieve the record, providing the function fails and the error is BthNsEFAULT.
- pResults
[out] Points to a block of memory where the result set is stored as a WSAQUERYSET structure on return.
Return Value
If the operation was successful, the return value is zero. Otherwise, the value SOCKET_ERROR is returned. The specific error number can be retrieved by calling the WSAGetLastError function.
Remarks
The data returned when the LUP_RETURN_ADDR and LUP_RETURN_BLOB flags are set is determined during the initial inquiry in BthNsLookupServiceBegin and can be retrieved quickly by the BthNsLookupServiceNext function, because it is stored in memory.
BthNsLookupServiceBegin does not perform name inquiries because they take considerably more time than simple device discovery. Name inquiry is only done on a given device when the LUP_RETURN_NAME flag is set when the device is enumerated.
Reset the enumeration iteration list by setting the BTHNS_LUP_RESET_ITERATOR flag. If you want to enumerate the same item multiple times with different flags, you can do so by setting the BTHNS_LUP_NO_ADVANCE flag.
An application can walk through the list of devices once, with repeated calls to BthNsLookupServiceNext.
The application determines the remote addresses, resets the iteration list, and queries for a subset of device names by calling this function with the LUP_RETURN_NAME flag set.
This can be used to display a list of queried devices in a user interface. The addresses can be displayed while the application queries for the device names in the background. Each time a new name is determined, the display can be updated. An example of this scenario is demonstrated in the Phone Management Sample.
Service Searching
Results from a service search are returned in the lpBlob element of lpqsResults in raw format binary form. Unlike some service providers for other protocols, the entire results are returned in the lpBlob all at once, instead of requiring enumeration for multiple service records.
Because the raw SDP format is difficult to parse and requires knowledge of the SDP specification, a COM interface is provided to transform the octal data into a tree that can be easily manipulated.
Querying for Devices
After calling this function, each device that was matched in the call to BthNsLookupServiceBegin is enumerated one at a time. After the last device in the list is enumerated, the next call to this function returns SOCKET_ERROR and the last error is set to WSA_E_NO_MORE, unless dwFlags is set to BTHNS_LUP_RESET_ITERATOR.
Requirements
| Header | bt_api.h |
| Library | Btdrt.lib |
| Windows Embedded CE | Windows CE .NET 4.0 and later |
See Also
Reference
Bluetooth OS Functions
BthInquiryResult
WSAQUERYSET (Bluetooth)
BthNsLookupServiceBegin
BthNsLookupServiceEnd