NAME

obexapp —

simple OBEX application

SYNOPSIS

obexapp -c [-fh] -a BD_ADDR [-A BD_ADDR] -C channel [-m MTU]

obexapp -c [-fh] -a BD_ADDR [-A BD_ADDR] -C channel [-m MTU] [-r path] -n command parameters

obexapp -s [-dDSRh] [-A BD_ADDR] [-C channel] [-m MTU] [-r path] [-u user]

DESCRIPTION

The obexapp is a simple OBEX application. In can operate in three modes:

interactive client mode;
non-interactive client mode;
server mode.

In the interactive client mode obexapp opens RFCOMM connection to the specified BD_ADDR and channel and starts interactive OBEX session.

In the non-interactive client mode obexapp opens RFCOMM connection to the specified BD_ADDR and channel and performs specified OBEX command with the specified parameters. Only one OBEX command can be performed at a time.

The following OBEX commands are supported in the non-interactive client mode:

get remote-file [local-file]: Get remote-file from the remote OBEX server as save it as local-file. If the local-file parameter was omitted then it is constructed from the remote-file. The path component of the constructed local file name will be set to the current directory unless -r option was specified.
getdefault local-file: Get the default vCard object from the remote OBEX server and save it as local-file.
put local-file [remote-file]: Put one local-file to the remote OBEX server as remote-file. If the remote-file parameter was omitted the it is constructed from the local-file. The path component of the constructed remote file name will be removed.

In the server mode obexapp listens for incomming connections, on the specified BD_ADDR and channel when given, from remote clients. If no channel is given, the first unused RFCOMM channel will be allocated. Once new connection is accepted obexapp forks and start new OBEX server for the client. Note: if -D option was specified then OBEX server will not listen and fork. In this case it is assumed that stdin/stdout was already connected to the client.

When operating in server mode, the “Class of Device” setting of the Bluetooth controller should be changed to indicate that “Object Transfer” is supported, as some devices filter the inquiry results by device class.

The options are as follows:

-A BD_ADDR: Specify which local Bluetooth device should be used. This option can be used when the host has multiple Bluetooth devices connected at the same time. If not specified, BDADDR_ANY will be used.
-a BD_ADDR: In the client mode this required option specifies the remote BD_ADDR of the OBEX server.
-C channel: In both client and server modes this option specifies RFCOMM channel to connect to or listen on. In the server mode RFCOMM channel should be number between 1 and 30. In the client mode RFCOMM channel could be either number between 1 and 30 or service name. Supported service names are: IrMC for IrMC Sync service, FTRN for OBEX File Transfer service and OPUSH for OBEX Push service. If service name was specified instead of numeric RFCOMM channel then obexapp utility will try to obtain RFCOMM channel for the service via Service Discovery Protocol.
-c: Act as OBEX client. This is the default mode.
-D: Use direct IO on stdin/stdout instead of listening on a L2CAP socket (server mode only, and will not create any SDP service records).
-d: Do not detach from the controlling terminal, i.e. run in foreground (server mode only).
-f: Connect to Folder Browsing Service on the remote OBEX server (client mode only). By default client does not specify any service in OBEX connect request.
-h: Display usage message and exit.
-l priority: Set least severe log priority. In other words, log any message that has more severe or equal priority than given priority. Priority should be specified by its name. Supported priority names are: alert, crit, debug, emerg, err, error, info, none, notice, panic, warn and warning. Default log priority is error.
-m MTU: Set OBEX MTU. Defaults to the maximum supported value.
-n: Work in the non-interactive client mode.
-R: Virtualize root folder for each client device in server mode. Will automatically turn on secure mode, i.e. -S option. Please read section below for a complete description.
-r path: Specify root folder. Default root folder in the server mode is /var/spool/obex unless -u option was specified. The -u option will set default root folder to the user's home directory. Current directory is the default root folder in the non-interactive client mode.
-S: Run OBEX server in secure mode. This only works if server was started as root. In secure mode server will chroot to the root folder.
-s: Act as OBEX server.
-u user: Specifies the user the server should run as after it initializes. The value specified may be either a username or a numeric user id. This only works if server was started as root.

VIRTUAL ROOT FOLDERS

When accepting connections in server mode, obexapp will attempt to find an entry that would act as a virtual root folder for the connecting device. Virtual root folders must reside under default root folder which is set with -r option. The rules are as follows:

obexapp will try to resolve connecting device's BD_ADDR using bt_gethostbyaddr(3) call and check for an entry that matches resolved name (if any);
obexapp will check for an entry that matches connecting device's BD_ADDR;
obexapp will check for an entry, named “default”;

If none of the above matches, then the connection to the client is terminated. Otherwise, obexapp will try to change default root folder the the found entry.

If -u option was specified, the obexapp will try to change to the specified user. Otherwise obexapp will try change to the user, that owns the found entry. That is, if the found entry is a symlink, the obexapp will try change to the user, that owns symlink and not to the user, that owns the entry symlink points to.

This allows the same system to intelligently distinguish different client devices as belonging to different users. An administrator can set up the subdirectories for known devices under /var/spool/obex (or wherever, see -r option) for each user, or even as symlinks to each user's home directory (or a subdirectory thereof).

LOCALE SUPPORT

The obexapp utility uses iconv(3) library to convert characters between the local encoding and the UTF-16BE and UTF-8 encodings. In order to properly initialize iconv(3) library the LANG or LC_CTYPE environment variable must be set. The local character encoding also must be supported by the iconv(3) library. The “ASCII”, “C”, “POSIX” and “US-ASCII” locales are aliased to “en_US.US-ASCII” locale.

OBEX FORMATS

Device Information

telecom/devinfo.txt: Information about hardware version, software version, serial number, etc. Information about supported character sets. Supported operations: GET.
telecom/rtc.txt: The Real Time Clock Object contains the current date and time of the device. Supported operations: GET/PUT.

Phone Book

telecom/pb.vcf: Level 2 access (Access entire phonebook database). Supported operations: GET/PUT.
telecom/pb/luid/.vcf: Add new entry. Supported operations: PUT.
telecom/pb/0.vcf: Own business card. Supported operations: GET/PUT.
telecom/pb/###.vcf: Level 3 static index access. Supported operations: GET/PUT.
telecom/pb/luid/*.vcf: Level 4 unique index access. Supported operations: GET/PUT.
telecom/pb/info.log: Supported properties and memory info. Supported operations: GET.
telecom/pb/luid/###.log: Change log. Supported operations: GET.
telecom/pb/luid/cc.log: Change counter. Supported operations: GET.

Calendar

telecom/cal.vcs: Level 2 access. Supported operations: GET/PUT.
telecom/cal/luid/.vcs: Add new entry. Supported operations: PUT.
telecom/cal/###.vcs: Level 3 static index access. Supported operations: GET/PUT.
telecom/cal/luid/*.vcs: Level 4 unique index access. Supported operations: GET/PUT.
telecom/cal/info.log: Supported properties and memory info. Supported operations: GET.
telecom/cal/luid/###.log: Change log. Supported operations: GET.
telecom/cal/luid/cc.log: Change counter. Supported operations: GET.

EXAMPLES

Usage

obexapp -c -a 00:01:02:03:04:05 -C 1: Will start obexapp in the client mode and try to connect to the OBEX server at 00:01:02:03:04:05 address and channel 1. Once connected the obexapp will start interactive OBEX session.
obexapp -s -C 1: Will start obexapp in the server mode. The OBEX server will listen on ANY address and RFCOMM channel 1.
ln -s /home/wallaby /var/spool/obex/00:01:02:03:04:05
chown -h wallaby /var/spool/obex/00:01:02:03:04:05: Whenever the device with BD_ADDR of 00:01:02:03:04:05 connects, obexapp running in server mode will switch to user ID wallaby and use their home directory as the top-level for the connection.

Level 1 Information Access

The first level involves the basic ability to put an object (such as a vCard) from one device to another. At this level, a device at least has the ability to push an object from one device to another, which is useful at a minimal level. The receiving device knows from the name of the object, which database to store it in.

obex> put
put: local file> new.vcf
put: remote file> new.vcf
Success, response: OK, Success (0x20)
obex>

Level 2 Information Access

The second level requires the ability to read and write all entries in one device from the other device. For example, a device could obtain all of the vCards stored in another devices phone book. With this level of support, mobile device databases such as the phone book, message and calendar, can be backed-up and updated using a host device.

obex> get
get: remote file> telecom/pb.vcf
get: local file> pb.vcf
Success, response: OK, Success (0x20)
obex>

Level 3 Information Access

The third level requires the ability to index the objects on the target device, such that a hierarchy of objects can be formed. With this capability, a device may more efficiently update the database objects on the mobile device.

obex> get
get: remote file> telecom/pb/0.vcf
get: local file> 0.vcf
Success, response: OK, Success (0x20)
obex>

Note: I am still somewhat confused about Level 3 information access. I only managed to get telecom/pb/0.vcf (own business card) via Level 3 information acesss out of my Sony Ericsson T68i cell phone.

Level 4 Information Access

The fourth level requires that the two devices be fully able to synchronize their objects one with another. At this level of support, two devices support database modification logging and other features that provide tremendous power to synchronize the databases in very intelligent ways.

To get change counter for the phone book

obex> get
get: remote file> telecom/pb/luid/cc.log
get: local file> cc.log
Success, response: OK, Success (0x20)
obex>

Now cc.log file has the number of changes in the phone book

% cat cc.log
48
%

Using the change counter the application can now request the phone book change log

obex> get
get: remote file> telecom/pb/luid/0.log
get: local file> 0.log
Success, response: OK, Success (0x20)
obex>

Now 0.log file has information about the changes in the phone book

% cat 0.log
SN:350329711209352
DID:4390
Total-Records:28
Maximum-Records:510
M:2::000002000000
M:6::000001000000
M:8::000006000000
M:11::000008000000
M:15::000007000000
M:17::000000000000
etc.
%

From this log the applicaion can learn that record with LUID (Local Unique IDentifier) 000002000000 has been modified and change counter associated with this is 2. To get the record

obex> get
get: remote file> telecom/pb/luid/000002000000.vcf
get: local file> 000002000000.vcf
Success, response: OK, Success (0x20)
obex>

And finally

% cat 000002000000.vcf
BEGIN:VCARD
VERSION:2.1
N:Doe;John
TEL;WORK:15558001234
END:VCARD
%

DIAGNOSTICS

The obexapp utility exits 0 on success, and >0 if an error occurs.

CAVEAT

In server mode obexapp will try to register OBEX Object Push service with the local SDP daemon. This means that obexapp requires root privileges to start in server mode. Use -u option to set user name the server should run as after it initializes.

AUTHORS

Maksim Yevmenkin ⟨m_evmenkin@yahoo.com⟩