3.3. HCI API

3.3.1. Function set

The HCI API function set divided into two subsets: system (Affix specific) function set and HC (Bluetooth device specific) function set. All an Affix function names have low-case style and all a HC function names have mixed-case style and are starting from HCI_ or __HCI_. The HC functions are implemented according to the Bluetooth System Specification [BTSPEC].

The Affix system function set is presented in Table 3-7.

• zero (0) if no error occurred;

• -1 in a case of system error, and errno is set appropriately. (like any Linux system call does);

• above zero (>0) in a case of HCI error (see Bluetooth Specification for values).

General HC function format is: int HCI_Xxxx(int hd, param, param, ...);

The rest of parameters of HC functions depend on actual function and is defined according to Bluetooth Specification. Its description can be carefully read from there.

The following table presents only partial set of HC functions implemented in the Affix. A complete set can be found in hci_cmds.h.

3.3.2. Data structures

Data structures related to the HCI interface are defined in hci_types.h header.

• struct sockaddr_affix.

  struct sockaddr_affix {
         sa_family_t   family;
         BD_ADDR       bda;
         uint16_t      port;
         BD_ADDR       local;  /* local Bluetooth adapter to connect to */
  };

• INQUIRY_ITEM

  typedef struct {
         BD_ADDR   bda;
         __u8      PS_Repetition_Mode;
         __u8      PS_Period_Mode;
         __u8      PS_Mode;
         __u32     Class_of_Device:24;
         __u16     Clock_Offset;
  }__PACK__ INQUIRY_ITEM;

• struct hci_dev_attr.

  /* flags mask */
  
  #define HCI_FLAGS_RUNNING       0x00000001
  #define HCI_FLAGS_UP            0x00000002
  
  #define HCI_FLAGS_ROLE          0x000000F0
  #define HCI_ROLE_ALLOW_SWITCH   0x00000000
  #define HCI_ROLE_DENY_SWITCH    0x00000010
  #define HCI_ROLE_REMAIN_SLAVE   0x00000000
  #define HCI_ROLE_BECOME_MASTER  0x00000020
  
  #define HCI_FLAGS_SECURITY      0x0000FF00
  #define HCI_SECURITY_OPEN       0x00000100
  #define HCI_SECURITY_SERVICE    0x00000200
  #define HCI_SECURITY_LINK       0x00000400
  /* levels */
  #define HCI_SECURITY_AUTH       0x00001000
  #define HCI_SECURITY_ENCRYPT    0x00002000
  #define HCI_SECURITY_AUTHOR     0x00004000
  
  struct hci_dev_attr {
          int       hd;
          char      name[IFNAMSIZ];
          BD_ADDR   bda;
          int       flags;
  };

• struct hci_msg_hdr.

  #define MGR_STATE_CHANGE  0x01
  
  struct hci_msg_hdr {
          int   opcode;
          int   length;
  };

• struct hci_state_change.

  /* hci device events */
  #define HCIDEV_UP           0x0001
  #define HCIDEV_DOWN         0x0002
  #define HCIDEV_CHANGE       0x0004
  #define HCIDEV_REGISTER     0x0005
  #define HCIDEV_UNREGISTER   0x0006
  #define HCIDEV_ATTACH       0x0100
  #define HCIDEV_DETACH       0x0200
  
  struct hci_state_change {
          struct hci_msg_hdr  hdr;
          int                 hd;
          int                 event;
  };

3.3.3. Sample code

Here is an example of the HCI API usage.

int main(int argc, char *argv[])
{
    int   devs[16], num, i, err;

    num = hci_get_devs(devs);
    if (num < 0) {
        printf("unable to get device list\n");
        return -1;
    }

    if (num == 0) {
        printf("No Bluetooth Adapters found\n");
        return 0;
    }

    for (i = 0; i < num; i++) {
         fd = _hci_open_id(devs[i]);
         if (fd < 0) {
             printf("Unable to open Bluetooth device: %d\n\n", devs[i]);
             return -1;
         }
 
         err = hci_get_attr(fd, &da);
         if (err < 0) {
             printf("Unable to get attribute for: %d\n", devs[i]);
             return -1;
         }

         printf("%s\t%s\n", da.name, bda2str(&da.bda));

         if (!(da.state & HCI_STATE_UP)) {
             printf("\tDevice is down");
             continue;
         }

         err = HCI_WriteScanEnable(fd, 0x02);
         if (err) {
             printf("unable to set scan mode\n");
             return -1;
         }

}

Next example illustrates how to discover surrounding devices.

int main(int argc, char *argv[])
{
   int    fd, i, argind = 1;
   __u32  length;
   int    err;
   INQUIRY_ITEM devs[20];
   char   *devnames[20];
   char   namebuf[248];
   __u8   num;

   if (argv[argind]) {
          sscanf(argv[argind], "%x", &length);
   } else 
          length = 8;

   fd = hci_open("bt0");
   if (fd < 0) {
        printf("Unable to open device %s: %s\n", btdev, sys_errlist[errno]);
        return -1;
   }

   printf("Searching %d sec ...\n", length);
   err = HCI_Inquiry(fd, length, 20, devs, &num);
   print_hci_error(err);
   if (num == 0) {
       printf("done.\nNo devices found.\n");
       return 0;
   }
   printf("Searching done. Resolving names ...\n");
   for (i = 0; i < num; i++) {
        err = HCI_RemoteNameRequest(fd, &devs[i], namebuf);
        if (!err)
              devnames[i] = strdup(namebuf);
        else 
              devnames[i] = NULL;
    }
    printf("done.\n");
    for (i = 0; i < num; i++) {
         printf("%d, bda: %s, name: %s\n", i, bda2str(&devs[i].bda), devnames[i]);
         if (devnames[i])
             free(devnames[i]);
    }
   return 0;
}