bt_spp_open

Create a Serial Port Profile (SPP) connection to a service on a remote Bluetooth device (server) - an extended version of bt_spp_open.

Synopsis:

#include <btapi/btspp.h>

int bt_spp_open_ex(char *addr, char *service_name, char *service_uuid, int service_port, bool nonblock, void(*callback)(long, int), long param)

Since:

BlackBerry 10.3.0

Arguments:

addr: The remote Bluetooth device (server) address. The address is in the following format: 2:2:2:2:2:2, where each digit indicates the number of hexadecimal digits. For example: 00:11:22:33:AA:BB.

service_name: The name of the service that might appear in the service's Service Discovery Protocol (SDP) record. The maximal length is 50, including the terminating '\0' character. If this argument is set to an empty string or NULL, it will be excluded from the querying criteria of the remote side SDP database.

service_uuid: The Universally Unique Identifier (UUID) of the service to connect to. This parameter must be the service ID defined by the developer, not the Service Class ID assigned by the Bluetooth organization. For example, the SPP profile has a 4-digit Service Class ID of 0x1101. A developer can create multiple services for this service class, and must define a unique service ID for each of the services. This function searches for the intended service using the input UUID when the input matches a supported service ID format. If this argument is set to NULL, it will be considered as being set to UUID 00001101-0000-1000-8000-00805f9b34fb, which is reserved by the Bluetooth organization as the Service Class ID for the SPP service.

service_port: The RFCOMM channel ID that is needed to create an SPP link to the server. Any registered service on a server has this number. Normally a client-side system retrieves it for the user by querying the server's SDP database using the service UUID, the service name, or generic SPP features, or some combination of the three. However, there are situations when the user wants to connect to a known RFCOMM channel ID. In that case a non-zero service_port must be passed in. If it is left as zero, the search in the remote SDP database is done by a combination of service_name, service_uuid and generic SPP features.

nonblock: A flag that specifies whether to open a mount point of the connection in non-blocking mode. A value of true means opening the connection in non-blocking mode.

callback: A pointer to a valid callback function that provides the mount point file descriptor if you are using the function in asynchronous mode. For the synchronous mode, pass in a NULL value. The mount point file descriptor is provided when the connection to the SPP server is established. In case of a failure, the file descriptor returns with a value of -1 and errno is set with the reason.

param: The user's parameter as the first argument of the returned callback.

Library:

libbtapi (For the qcc command, use the -l btapi option to link against this library)

Description:

The function allows a user to create a connection to the SPP service on a remote device that can be found in the SDP by a combination of the following parameters: service name, service UUID, and RFCOMM channel ID. The combination may use any or all of the three parameters. If you don't want to use service_name or service_uuid for the retrieval of an SDP record, pass in NULL for either or both parameters; if you don't want to use service_port, pass in zero.

For an SDP record to be found, all non-zero parameters must match. There are two exceptions:

If all three parameters are zero, the SDP database is searched by generic SPP features.
If service_port is a non-zero value and an SDP record is not found, this function still tries to connect to the service by the RFCOMM channel ID. It does so because sometimes the SPP service is registered with a known RFCOMM channel ID but is not registered in the SDP. Note, however, that this function makes no attempt to connect by the RFCOMM channel ID if service_port is non-zero, an SDP record with that value exists, but no match is found for a non-zero service_name or service_uuid.

You can open the connection in non-blocking or blocking mode. After you successfully call this function, and when your application is finished with the file descriptor that is returned from this function, call bt_spp_close() to clean up resources.

Returns:

In the synchronous mode, this function returns the mount point file descriptor if a connection has been successfully created, -1 with the errno set otherwise. In the asynchronous mode, it returns 0 if a connection procedure has been successfully launched, -1 with the errno set otherwise. The errno can be set to one of the following values when -1 is returned. If the errno is set to any other value, a system error has occurred.