Bluetooth and WSALookupServiceBegin for Service Discovery

To discover the existence of a particular service on a Bluetooth server, clients use the WSALookupServiceBegin, WSALookupServiceNext, and WSALookupServiceEnd functions. Queries can be performed for local and remote addresses, but connections can only be established with remote addresses. Service handles discovered during this operation cannot be used to delete the service via WSASetService. Loopback is not supported by RFCOMM.

Two basic types of service discovery queries can be performed:

  • Queries for one or more services on the local device
  • Queries for one or more services on a specified peer device

The WSALookupServiceBegin function receives a WSAQUERYSET structure in its lpqsRestrictions parameter. WSALookupServiceBegin performs a client query based on the set of search restrictions that the WSAQUERYSET contains. Bluetooth clients must specify the restrictions, listed in the following table, in the WSAQUERYSET structure when using the WSALookupServiceBegin function to query for services.

WSAQUERYSET memberRestriction
dwSizeSet to sizeof(WSAQUERYSET).
lpServiceClassIdSet to the most specific Bluetooth UUID that can be used to determine the scope of the query.

For example, setting lpServiceClassId to the UUID of the L2CAP protocol results in all L2CAP services returned, essentially enumerating all SD records on the target. Setting the UUID to a specific service, however, returns only the instances of that service.

dwNameSpaceSet to NS_BTH.
dwNumberOfCsAddrsSet to 0.
lpszContextSet to the Bluetooth Device Address with which to establish an SDP connection to perform the query of services. This member must be a string that is converted by using the WSAAddressToString function.

If the local radio address is supplied, the local SDP records are searched.

Other membersAll other members of the WSAQUERYSET structure are ignored.

 

The SDP connection to the remote device does not remain active after the WSALookupServiceBegin function completes a service query; the connection is terminated before WSALookupServiceBegin returns. Applications that require the SDP connection to remain active after a service query completes should specify the service class UUID to which to connect by using the serviceClassId member of the SOCKADDR_BTH structure when issuing the Windows Sockets connect function call.

The flags, listed in the following table, are used in the dwControlFlags parameter of the WSALookupServiceBegin and WSALookupServiceNext functions to control the query results. The LUP_CONTAINERS and LUP_FLUSHCACHE flags are used by the WSALookupServiceBegin function; the rest of the flags are used in calls to the WSALookupServiceNext function.

FlagResult
LUP_CONTAINERSMust not be set.
LUP_FLUSHCACHEApplications should generally specify LUP_FLUSHCACHE. This flag instructs the system to ignore any cached information and establish an over-the-air SDP connection to the specified device to perform the SDP search. This non-cached operation may take several seconds (whereas a cached search returns quickly). Bluetooth currently does not proactively cache SDP records from nearby devices, nor does it currently aggressively cache previous queries. Therefore, applications should anticipate that queries may return no results (with an error code of WSASERVICE_NOT_FOUND) if LUP_FLUSHCACHE is not specified. The cached data that is available by using the Windows Sockets interface may be enhanced in the future.
LUP_RES_SERVICEReturn information about the local Bluetooth address. This flag has an effect only if LUP_RETURN_ADDR is also specified.
LUP_RETURN_NAMEReturn the display name of the service in the lpszServiceInstanceName member of the WSAQUERYSET structure for each call to the WSALookupServiceNext function.
LUP_RETURN_TYPEReturn the service class ID in the lpServiceClassId member of the WSAQUERYSET structure.
Note  Use of this flag is only applicable to the WSALookupServiceBegin function. This value is always zero for WSALookupServiceNext.
 
LUP_RETURN_ADDRReturn an address in the lpcsaBuffer member to be used with connect function calls. The returned address contains the port number.
LUP_RETURN_BLOBReturn the matching SD records in the lpBlob member, formatted according to the Bluetooth SDP record specification.
LUP_RETURN_ALLReturn all of the above flags' information.
LUP_RETURN_COMMENTReturn the service description in the lpszComment member of the WSAQUERYSET structure for each call to the WSALookupServiceNext function.
LUP_FLUSHPREVIOUSSkip the next available record, and return the record that follows it.

 

Advanced Service Queries

The query operations that are described in the previous section can be used to return all results from a single GUID, which should be sufficient for most applications. An advanced query enables an application to create a more specific query; it provides the capability to match UUIDs and attributes in returned information.

To perform an advanced query for services, Bluetooth clients must specify the following restrictions in the WSAQUERYSET structure that is passed into the lpqsRestrictions parameter.

WSAQUERYSET memberRestriction
dwSizeSet to sizeof(WSAQUERYSET).
lpszContextSet to the Bluetooth Device Address with which to establish an SDP connection to perform the query of services. This member must be a string that is converted by using the WSAAddressToString function.

If the local radio address is supplied, the local SDP records are searched.

lpBlob.pBlobDataPointer to a BTH_QUERY_SERVICE structure that contains all parameters that limit the results of the query.
dwNameSpaceSet to NS_BTH.
Other membersAll other members of the WSAQUERYSET structure are ignored.

 

The following flags are passed in the dwControlFlags parameter of WSALookupServiceBegin to control the results of an advanced query.

FlagResult
LUP_CONTAINERSMust not be set.
LUP_FLUSHCACHEApplications should generally specify LUP_FLUSHCACHE. This flag instructs the system to ignore any cached information and establish an over-the-air SDP connection to the specified device to perform the SDP search. This non-cached operation may take several seconds (whereas a cached search returns quickly). Bluetooth does not proactively cache SDP records from nearby devices, nor does it aggressively cache previous queries. Therefore applications should expect that queries may frequently return no results (WSASERVICE_NOT_FOUND) if LUP_FLUSHCACHE is not specified. The cached data that is available by using the Windows Sockets interface may be enhanced in the future.
LUP_RES_SERVICEReturn information for the local Bluetooth Address. Setting this flag has an effect only if LUP_RETURN_ADDRR is also specified.
LUP_RETURN_NAMEReturn the display name of the service. This flag is ignored for SDP_SERVICE_SEARCH_REQUEST.
LUP_RETURN_TYPEReturn the service class ID. This flag is ignored for SDP_SERVICE_SEARCH_REQUEST.
LUP_RETURN_ADDRReturn an address in the lpcsaBuffer member to be used with connect function calls. The returned address contains the port number. This flag is ignored for SDP_SERVICE_SEARCH_REQUEST.
LUP_RETURN_BLOBReturn the matching SD records in a format that conforms to the Bluetooth SDP record specification. For SDP_SERVICE_SEARCH_REQUEST, the result in lpBlob for the subsequent call to WSALookupServiceNext is an array of Bluetooth SDP handles. For SDP_SERVICE_ATTRIBUTE_REQUEST and SDP_SERVICE_SEARCH_ATTRIBUTE_REQUEST, the result for each subsequent call to WSALookupServiceNext is a binary Bluetooth SDP record whose attributes are restricted to those specified by the pRange member of the query. This flag is required for SDP_SERVICE_SEARCH_REQUEST.
LUP_RETURN_COMMENTReturn the service description in the lpszComment member of the WSAQUERYSET structure for each call to the WSALookupServiceNext function.
LUP_FLUSHPREVIOUSSkip the next available record, and return the record that follows it.

 

On input, lpBlob->pBlobData points to a BTH_QUERY_SERVICE structure that contains the values listed in the following table.

Note  The initial search request must be able to fit into one L2CAP packet. The response, however, may be broken into many L2CAP packets.
 
MemberValue
typeType of search to perform. This value can be one of SDP_SERVICE_SEARCH_REQUEST, SDP_SERVICE_ATTRIBUTE_REQUEST, or SDP_SERVICE_SEARCH_ATTRIBUTE_REQUEST. Each search type is associated with an underlying search mechanism that is defined by the Bluetooth SDP specification. Each return results in the form described by the WSAQUERYSET structure that is defined earlier in this (Advanced Service Queries) section.
serviceHandleUsed for attribute searches. This value specifies the service handle with which to query the attributes in the pRange member.
uuidsUsed for service and serviceAttribute searches. This value specifies the UUIDs that a record must contain to match the search. If less than MAX_UUIDS_IN_QUERY UUIDs are to be queried, this value sets the SdpQueryUuid element that immediately follows the last valid UUID to all zeros.
numRangeUsed for attribute and serviceAttribute searches. This value specifies the number of elements in pRange.
pRangeUsed for attribute and serviceAttribute searches. This value specifies the attribute values to retrieve for any matching records.

 

After each successful call to the WSALookupServiceNext function, lpBlob->pBlobData points to a block of data that contains the values listed in the following table.

ValueDescription
SDP_SERVICE_SEARCH_REQUESTAn array of SDP record handles that is identical to the ServiceRecordHandleList defined by Bluetooth 1.1 SDP 4.5.2. The number of SDP handles that is returned is calculated by (lpBlob->cbSize)/sizeof(ULONG). All results are returned in a single call to the WSALookupServiceNext function.
SDP_SERVICE_ATTRIBUTE_REQUEST or SDP_SERVICE_SEARCH_ATTRIBUTE_REQUESTA binary Bluetooth SDP record. For SDP_SERVICE_ATTRIBUTE_REQUEST, all results are returned in a single call to the WSALookupServiceNext function.

 

Note  If the lpBlob member is not specified during input for a service query, a service and attribute search is performed for the service specified in the lpServiceClassId member on attributes from 0 through 0xFFFF.
 

Related topics

Bluetooth and WSAQUERYSET for Service Inquiry
Discovering Bluetooth Devices and Services
Bluetooth and WSALookupServiceNext
Bluetooth and WSALookupServiceBegin for Device Inquiry
BTH_QUERY_SERVICE
connect
SOCKADDR_BTH
WSAAddressToString
WSALookupServiceBegin
WSALookupServiceEnd
WSALookupServiceNext
WSAQUERYSET
Windows Sockets

 

 

Community Additions

ADD
Show: