名称

bt_gethostbyname, bt_gethostbyaddr, bt_gethostent, bt_sethostent, bt_endhostent, bt_getprotobyname, bt_getprotobynumber, bt_getprotoent, bt_setprotoent, bt_endprotoent, bt_aton, bt_ntoa, bt_devaddr, bt_devname, bt_devinfo, bt_devenum, bt_devopen, bt_devclose, bt_devsend, bt_devrecv, bt_devreq, bt_devfilter, bt_devfilter_pkt_set, bt_devfilter_pkt_clr, bt_devfilter_pkt_tst, bt_devfilter_evt_set, bt_devfilter_evt_clr, bt_devfilter_evt_tst, bt_devinquiry, bdaddr_same, bdaddr_any, bdaddr_copy — Bluetooth ルーチン

ライブラリ

Bluetooth Library (libbluetooth, -lbluetooth)

書式

#include < bluetooth.h>

struct hostent *
bt_gethostbyname( const char *name);

struct hostent *
bt_gethostbyaddr( const char *addr, int len, int type);

struct hostent *
bt_gethostent( void);

void
bt_sethostent( int stayopen);

void
bt_endhostent( void);

struct protoent *
bt_getprotobyname( const char *name);

struct protoent *
bt_getprotobynumber( int proto);

struct protoent *
bt_getprotoent( void);

void
bt_setprotoent( int stayopen);

void
bt_endprotoent( void);

int
bt_aton( const char *str, bdaddr_t *ba);

const char *
bt_ntoa( const bdaddr_t *ba, char *str);

int
bt_devaddr( const char *devname, bdaddr_t *addr);

int
bt_devname( char *devname, const bdaddr_t *addr);

int
(bt_devenum_cb_t)( int s, struct bt_devinfo const *di, void *arg);

int
bt_devinfo( struct bt_devinfo *di);

int
bt_devenum( bt_devenum_cb_t *cb, void *arg);

int
bt_devopen( char const *devname);

int
bt_devclose( int s);

int
bt_devsend( int s, uint16_t opcode, void *param, size_t plen);

ssize_t
bt_devrecv( int s, void *buf, size_t size, time_t to);

int
bt_devreq( int s, struct bt_devreq *r, time_t to);

int
bt_devfilter( int s, struct bt_devfilter const *new, struct bt_devfilter *old);

void
bt_devfilter_pkt_set( struct bt_devfilter *filter, uint8_t type);

void
bt_devfilter_pkt_clt( struct bt_devfilter *filter, uint8_t type);

int
bt_devfilter_pkt_tst( struct bt_devfilter const *filter, uint8_t type);

void
bt_devfilter_evt_set( struct bt_devfilter *filter, uint8_t event);

void
bt_devfilter_evt_clt( struct bt_devfilter *filter, uint8_t event);

int
bt_devfilter_evt_tst( struct bt_devfilter const *filter, uint8_t event);

int
bt_devinquiry( char const *devname, time_t length, int num_rsp, struct bt_devinquiry **ii);

int
bdaddr_same( const bdaddr_t *a, const bdaddr_t *b);

int
bdaddr_any( const bdaddr_t *a);

int
bdaddr_copy( const bdaddr_t *dst, const bdaddr_t *src);

解説

bt_gethostent(), bt_gethostbyname() と bt_gethostbyaddr() 関数は、それぞれ名前またはアドレスによって参照される Bluetooth ホストを表現する hostent 構造体でオブジェクトへの各ポインタを返します。

bt_gethostbyname() に渡された name 引数は、 ヌル文字で終了した ホスト名を指すべきです。 bt_gethostbyaddr() に渡された addr 引数は、バイナリ形式 (すなわち、人間に解読可能な ASCII 形式の Bluetooth BD_ADDR でない) で len バイト長であるアドレスを指すべきです。 type 引数は、このアドレスのアドレスファミリを指定して、 AF_BLUETOOTH に設定されなければなりません。

返された構造体は、 /etc/bluetooth/hosts ファイル中の行から取得された情報を含んでいます。

bt_sethostent() 関数は、 /etc/bluetooth/hosts ファイルが bt_gethostbyname() または bt_gethostbyaddr() へのそれぞれの呼び出しの後にオープンした状態のままであるかどうかを制御します。 stayopen フラグが 0 でなければ、ファイルは、クローズされません。

bt_endhostent() 関数は、 /etc/bluetooth/hosts ファイルをクローズします。

bt_getprotoent(), bt_getprotobyname() と bt_getprotobynumber() 関数は、それぞれ名前または数によって参照される Bluetooth Protocol Service Multiplexor を表現する protoent 構造体でオブジェクトへの各ポインタを返します。

bt_getprotobyname() に渡された name 引数は、 ヌル文字で終了した Bluetooth Protocol Service Multiplexor 名を指すべきです。 bt_getprotobynumber() に渡された proto 引数は、望ましい Bluetooth Protocol Service Multiplexor の数値を持つべきです。

返された構造体は、 /etc/bluetooth/protocols ファイル中の行から取得された情報を含んでいます。

bt_setprotoent() 関数は、 /etc/bluetooth/protocols ファイルが bt_getprotobyname() または bt_getprotobynumber() へのそれぞれの呼び出しの後にオープンした状態のままであるかどうかを制御します。 stayopen フラグが 0 でなければ、ファイルは、クローズされません。

bt_endprotoent() 関数は、 /etc/bluetooth/protocols ファイルをクローズします。

bt_aton() ルーチンは、アドレスを提供された構造体に置いて、 Bluetooth アドレスとして指定された文字列を解釈します。それは、文字列の解釈が成功したなら 1 を返し、文字列が無効であるなら 0 を返します。

ルーチン bt_ntoa() は、Bluetooth アドレスを取り、アドレスを表す ASCII 文字列を提供されたバッファに置きます。バッファに十分な空間があるということを確実にすることは呼び出し側次第です。バッファが全く提供されなかったなら、内部の静的なバッファを使用します。

bt_devaddr() 関数は、ローカルシステムの Bluetooth デバイスのアドレスまたはデバイス名として指定された devname 文字列を解釈し、もしあれば提供された bdaddr にデバイスアドレスを置きます。この関数は、文字列の解釈が成功すれば、1 を、または文字列がローカルデバイスに何もマッチしなければ、0 を返します。 bt_devname() 関数は、Bluetooth デバイスアドレスを取り、もしあれば、そのアドレスに関連するローカルデバイス名を提供されたバッファにコピーします。呼び出し側は、提供されたバッファが少なくとも HCI_DEVNAME_SIZE 文字のサイズであることを保証しなければなりません。関数は、デバイスが見つけられたとき、1 を、そうでなければ、 0 を返します。

bt_devinfo() 関数は、与えられた Bluetooth デバイスに関する情報で提供された bt_devinfo 構造体に満たします。呼び出し側は、渡された bt_devinfo 構造体の devname フィールドに Bluetooth デバイス名が渡されると期待します。この関数は、成功すれば、0、そうでなければ、-1 を返します。 bt_devinfo 構造体は、次の通りに定義されます:

struct bt_devinfo 
{ 
        char            devname[HCI_DEVNAME_SIZE]; 
 
        uint32_t        state; 
 
        bdaddr_t        bdaddr; 
        uint16_t        _reserved0; 
 
        uint8_t         features[HCI_DEVFEATURES_SIZE]; 
 
        /* バッファ情報 */ 
        uint16_t        _reserved1; 
        uint16_t        cmd_free; 
        uint16_t        sco_size; 
        uint16_t        sco_pkts; 
        uint16_t        sco_free; 
        uint16_t        acl_size; 
        uint16_t        acl_pkts; 
        uint16_t        acl_free; 
 
        /* 状態 */ 
        uint32_t        cmd_sent; 
        uint32_t        evnt_recv; 
        uint32_t        acl_recv; 
        uint32_t        acl_sent; 
        uint32_t        sco_recv; 
        uint32_t        sco_sent; 
        uint32_t        bytes_recv; 
        uint32_t        bytes_sent; 
 
        /* その他/特有 */ 
        uint16_t        link_policy_info; 
        uint16_t        packet_type_info; 
        uint16_t        role_switch_info; 
        uint16_t        debug; 
 
        uint8_t         _padding[20]; 
};

bt_devenum() 関数は、システムの現在の Bluetooth デバイスを列挙します。見つけられたあらゆるデバイスに関して、この関数は、 bt_devenum_cb_t タイプであるべき提供された cb コールバック関数を呼び出します。コールバック関数には、 HCI ソケット s、完全に満たされた bt_devinfo 構造体 di と bt_devenum() に提供された arg 引数が渡されます。コールバック関数は、0 以上である値を返すことによって、列挙を止めることができます。個の関数は、列挙が成功したデバイスの数を返し、エラーが起こったなら、-1 を返します。

bt_devopen() 関数は、与えられた devname で Bluetooth デバイスをオープンし、接続されてバインドされた HCI ソケットハンドルを返します。関数は、エラーが起こったなら、-1 を返します。

bt_devclose() は、以前に bt_devopen(3) で取得されて渡された HCI ソケットハンドル s をクローズします。

bt_devsend() 関数は、以前に bt_devopen(3) で所得されて提供されたソケット s に与えられた opcode がある Bluetooth の HCI コマンドを送信します。 opcode パラメータは、ホストのバイト順序であることが期待されます。 param と plen パラメータは、コマンドパラメータを指定します。 bt_devsend() 関数は、提供されたソケット s の HCI フィルタを変更しません。関数は、成功すれば、0 を返し、エラーが起こるなら、-1 を返します。

bt_devrecv() 関数は、以前に bt_devopen(3) で所得されたソケット s から 1 つの Bluetooth HCI パケットを受信します。パケットは、サイズ size の提供されたバッファ buf に置かれます。 to パラメータは、秒単位の受信タイムアウトを指定します。 to パラメータに負の数を渡すことによって、無限のタイムアウトを指定することができます。 bt_devrecv() 関数は、提供されたソケット s の HCI フィルタを変更しません。関数は、受信された合計バイト数を返すか、またはエラーが起こるなら、-1 を返します。

bt_devreq() 関数で、以前に bt_devopen(3) で所得されたソケット s への Bluetooth HCI 要求を作成します。関数は、指定されたコマンドを送信し、指定されたイベントを待つか、または to 秒のタイムアウトが起こるのを待ちます。 bt_devreq 構造体は、次のように定義されます。

struct bt_devreq 
{ 
        uint16_t        opcode; 
        uint8_t         event; 
        void            *cparam; 
        size_t          clen; 
        void            *rparam; 
        size_t          rlen; 
};

opcode フィールドは、コマンドを指定して、ホストのバイト順序であることが期待されます。 cparam と clen フィールドは、それぞれコマンドパラメータのデータとコマンドパラメータのデータサイズを指定します。 event フィールドは、関数が待つべき Bluetooth HCI イベント ID を指定します、そうでなければ、それは、0 に設定されるべきです。 HCI Command Complete と Command Status イベントは、デフォルトで有効にされています。 rparam と rlen パラメータは、それぞれ返されるパラメータが置かれるべきバッファとバッファサイズを指定します。 bt_devreq() 関数は、提供された HCI ソケット s でフィルタを一時的に変更します。関数は、成功すれば、0 を返し、エラーが起こるなら、-1 を返します。

bt_devfilter() は、以前に bt_devopen(3) で所得されたソケット s に関連しているローカルの HCI フィルタを制御します。パケットタイプでフィルタリングを行うことができます。すなわち、 ACL, SCO または HCI コマンドとイベントパケット、さらに HCI イベント ID でも行うことができます。 (提供されているなら) new フィルタを適用する前に、関数は、ソケット s から現在のフィルタを取得し、(提供されているなら) old パラメータにそれを置くことを試みます。関数は、成功すれば、0 を返し、エラーが起こるなら、-1 を返します。

HCI フィルタ filter を変更して、テストするために bt_devfilter_pkt_set(), bt_devfilter_pkt_clr() と bt_devfilter_pkt_tst() 関数を使用することができます。 type パラメータは、 HCI パケットタイプを指定します。

HCI イベントフィルタ filter を変更して、テストするために bt_devfilter_evt_set(), bt_devfilter_evt_clr() と bt_devfilter_evt_tst() 関数を使用することができます。 event パラメータは、 HCI イベント ID を指定します。

bt_devinquiry() 関数は、Bluetooth 問い合せを実行します。 devname パラメータは、どのローカル Bluetooth デバイスが問い合せを実行するべきであるかを指定します。指定されないなら、すなわち、 NULL であるなら、最初に利用可能なデバイスが使用されます。 length パラメータは、秒単位で問い合せの合計の長さを指定します。指定されないなら、すなわち、0 であるなら、デフォルト値が使用されます。 num_rsp パラメータは、問い合せが停止する前に、受信することができる応答の数を指定します。指定されないなら、すなわち、0 であるなら、デフォルト値が使用されます。 ii パラメータは、問い合せの結果をどこに置くかを指定します。成功すれば、関数は、問い合せ結果の合計数を返し、すべての問い合せ結果を格納するためのバッファを calloc(3) を使用して割り付け、ポインタを ii パラメータ中の割り付けられたバッファへ返します。 free(3) 呼び出しを使用してバッファを処分するための関数の呼び出しは、呼び出し側に委ねられています。関数は、エラーが起こるなら、-1 を返します。 bt_devinquiry 構造体は、次のように定義されます。

struct bt_devinquiry { 
        bdaddr_t        bdaddr; 
        uint8_t         pscan_rep_mode; 
        uint8_t         pscan_period_mode; 
        uint8_t         dev_class[3]; 
        uint16_t        clock_offset; 
        int8_t          rssi; 
        uint8_t         data[240]; 
};

bdaddr_same(), bdaddr_any() と bdaddr_copy() は、便利で簡便な Bluetooth アドレスユーティリティ関数です。 bdaddr_same() 関数は、2 つの提供された BD_ADDR が同じであるかどうかテストします。 bdaddr_any() 関数は、提供された BD_ADDR が ANY BD_ADDR であかどうかテストします。 bdaddr_copy() 関数は、提供された src BD_ADDR を提供された dst BD_ADDR にコピーします。

関連ファイル

/etc/bluetooth/hosts

/etc/bluetooth/protocols

使用例

特定の BD_ADDR に関連しているホスト名を印刷 (表示) します:

const char *bdstr = "00:01:02:03:04:05"; 
bdaddr_t bd; 
struct hostent *hp; 
 
if (!bt_aton(bdstr, &bd)) 
 errx(1, "can't parse BD_ADDR %s", bdstr); 
 
if ((hp = bt_gethostbyaddr((const char *)&bd, 
    sizeof(bd), AF_BLUETOOTH)) == NULL) 
 errx(1, "no name associated with %s", bdstr); 
 
printf("name associated with %s is %s\n", bdstr, hp->h_name);

診断

bt_gethostent(), bt_gethostbyname() と bt_gethostbyaddr() から返されるエラー状態は、 NULL ポインタが返されることで示されます。そして、外部の整数 h_errno は、これが一時的な失敗かそれとも無効か、または、未知のホストであるかを確かめるためにチェックされます。ルーチン herror(3) は、失敗について説明するエラーメッセージを印刷 (表示) するために使用することができます。引数 string が NULL でないなら、それが印刷 (表示) され、コロンと空白が後に続きます。エラーメッセージは、後続する改行を付けて印刷 (表示) されます。

変数 h_errno は、次の値を持つことができます:

HOST_NOT_FOUND

そのようなホストは、知られていません。

NO_RECOVERY

何らかの予期されないサーバの失敗に遭遇しました。これは、回復不可能なエラーです。

bt_getprotoent(), bt_getprotobyname() と bt_getprotobynumber() は、EOF かエラーのときに NULL を返します。

関連項目

gethostbyaddr(3), gethostbyname(3), getprotobyname(3), getprotobynumber(3), herror(3), inet_aton(3), inet_ntoa(3), ng_hci(4)

警告

bt_gethostent() 関数は、必要なら、ファイルをオープンして /etc/bluetooth/hosts の次の行を読み込みます。

bt_sethostent() 関数は、 /etc/bluetooth/hosts ファイルをオープンして、および/または、巻き戻します。

bt_getprotoent() 関数は、必要なら、ファイルをオープンして /etc/bluetooth/protocols の次の行を読み込みます。

bt_setprotoent() 関数は、 /etc/bluetooth/protocols ファイルをオープンして、および/または、巻き戻します。

bt_devenum() 関数は、 HCI_DEVMAX まで Bluetooth デバイスを列挙します。列挙の間、 bt_devenum() 関数は、同じ HCI ソケットを使用します。この関数は、コールバック機能に渡されたソケットが、列挙されている Bluetooth デバイスにバインドされ、接続されることを保証します。

作者

Maksim Yevmenkin <m_evmenkin@yahoo.com>

バグ

これらの関数のいくつかは、静的なデータ記憶域を使用します。データが今後の使用に必要であるなら、その後の呼び出しでそれが上書きされる前にそれは、コピーされるべきです。