BthNsLookupServiceNext (Windows Embedded CE 6.0)

1/6/2010

This function retrieves the results of an SDP search.

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

See Also

Reference

Bluetooth OS Functions
BthInquiryResult
WSAQUERYSET (Bluetooth)
BthNsLookupServiceBegin
BthNsLookupServiceEnd

Concepts

Phone Management Sample

Other Resources

WSAGetLastError
Bluetooth Application Development