3.3. HCI API

3.3.1. Function Set

The HCI API function set divided into two subsets: system (Affix specific) function set and HCI (Bluetooth device specific) function set. All Affix function names have low-case style and all a HCI function names have mixed-case style and are starting from HCI_ or __HCI_. The HCI 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 HCI function format is: int HCI_Xxxx(int hd, param, param, ...);

The rest of parameters of HCI 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 HCI 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. See definition in chapter Section 3.2.1.

• 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_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
  
  /* Security mode flags */
  #define HCI_FLAGS_SECURITY      0x0000FF00
  #define HCI_SECURITY_OPEN       0x00000100
  #define HCI_SECURITY_SERVICE    0x00000200
  #define HCI_SECURITY_LINK       0x00000400
  #define HCI_SECURITY_PAIRABLE   0x00000800
  
  /* Security levels */
  #define HCI_SECURITY_AUTH       0x00001000
  #define HCI_SECURITY_ENCRYPT    0x00002000
  #define HCI_SECURITY_AUTHOR     0x00004000
  #define HCI_SECURITY_OUT_AUTH   0x00100000
  #define HCI_SECURITY_OUT_ENCRYPT 0x00200000
  #define HCI_SECURITY_OUT_AUTHOR 0x00400000
  #define HCI_SECURITY_CL         0x00800000 /* connection less traffic */
  
  struct hci_dev_attr {
      int     devnum;
      char    name[IFNAMSIZ];
      BD_ADDR bda;
      int     flags;
      int     pkt_type;
      struct hcidev_stats stats;
  };

• 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     devnum;
      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;
}