bt_spp_open_server_ex()

Open a Serial Port Profile (SPP) server - an extended version of bt_spp_open_server.

Synopsis:

#include <btapi/btspp.h>
 
int bt_spp_open_server_ex(char *service_name, char *service_uuid, int service_port, bool nonblock, void(*callback)(long, int), long param)

Since:

BlackBerry 10.3.0

Arguments:

service_name

The name of the service to appear in the service's Service Discovery Protocol (SDP) record. The maximal length is 50 including the terminating NULL character. If this argument is empty or set to NULL, the default service name that appears in the SDP record is "SPP Service".

service_uuid

The Universally Unique Identifier (UUID) of the service to register. Note that this is 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. The service ID must be in the following format: 8-4-4-4-12, where each digit indicates the number of hexadecimal digits. For example, a valid service ID can be: 00001101-1111-2222-3333-444444444444. UUID 00001101-0000-1000-8000-00805f9b34fb is reserved by the Bluetooth organization as the Service Class ID for SPP. We do not recommend that you use it on the server side as the service ID for a newly defined service, as it cannot guarantee the uniqueness of the 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 by a known service UUID. 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 and service_uuid.

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.

param

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

callback

A pointer to a valid callback function that provides the mount point file descriptor. The mount point file descriptor is available when the SPP server has accepted incoming connections. In case of a failure, the file descriptor returns with a value of -1 and errno is set with the reason.

Library:

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

Description:

This function registers a service record and starts a thread to listen for incoming connections. When an incoming connection is accepted, a callback gets called with a valid mount point file descriptor as the argument. If the connection is not accepted, the callback returns an invalid file descriptor (-1).

You cannot register two services with the same service UUID even if other parameters (service names and RFCOMM channel IDs) are different. You also cannot register two servers with the same RFCOMM channel ID (service_port).

Before you attempt to call this function again using the same service UUID or the RFCOMM channel, you must call bt_spp_close_server(). If you do not call bt_spp_close_server(), subsequent attempts to open an SPP server will fail.

Returns:

0 if the operation is successful, -1 otherwise. If your call to this functions is successful, even if the callback returns a file descriptor of -1, ensure that you call bt_spp_close_server() when you no longer need this connection. When -1 is returned, the errno can be set to one of the following values:
  • EINVAL: Invalid arguments were specified.
  • EPERM: The bt_spp_init() function has not been called or has failed.
  • ENONMEM: There is insufficient memory to allocate to complete the function.
  • ESRVRFAULT: The operation was aborted by the user.
  • EBADMSG: There was an error parsing the incoming message.
  • EMLINK: A service with the same either service_uuid or service_port has already been registered.
  • ENODATA: A failure occurred because an error occurred on the stack.

Last modified: 2014-05-14



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus