Share via

WSALookupServiceNext (Bluetooth) (Compact 2013)

  • Article

3/26/2014

This function retrieves the results of an SDP search.

Syntax

INT WSALookupServiceNext(
  HANDLE hLookup,
  DWORD dwFlags,
  LPDWORD lpdwBufferLength,
  LPWSAQUERYSET pResults
);

Parameters

  • hLookup
    [in] Handle obtained from WSALookupServiceBegin.

  • 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 member.

    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 (Bluetooth) structure on return.

Return Value

Returns zero on success; otherwise SOCKET_ERROR. The specific error code can be retrieved by calling WSAGetLastError.

Remarks

Note

This function is actually a Winsock function. However, the information that is presented in it is specific to Bluetooth.

The data returned when the LUP_RETURN_ADDR and LUP_RETURN_BLOB flags are set is determined during the initial inquiry in WSALookupServiceBegin (Bluetooth) and can be retrieved quickly by the WSALookupServiceNext function, because it is stored in memory. WSALookupServiceBegin 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 WSALookupServiceNext. 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.

Service Searching

Results from a service search are returned in the lpBlob member of pResultsin 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 WSALookupServiceBegin (Bluetooth) 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

winsock2.h

Library

Ws2.lib

See Also

Reference

Bluetooth API Miscellaneous Functions
BthInquiryResult
WSAQUERYSET (Bluetooth)
WSALookupServiceBegin (Bluetooth)
WSALookupServiceEnd (Bluetooth)

Other Resources

WSAGetLastError