# Developer Information

## KBluetoothD

This section describes how to utilize kbluetoothd for your own application or access it from scripts to retrieve cached device names or similar.

### The name cache

The name cache tracks all name requests that and saves the results. With it, other applications and kbluetoothd itself can retrieve the name of another bluetoothd device from its unique bluetoothd device address, even if the device is not in range currently. This is mostly used to make the user interface more pleasant, because bluetooth addresses like 00:60:AB:13:83:3D are a bit hard to remember.

It will possibly be obsoleted as soon as BlueZ comes with it's own persistant name cache.

You can access the name cache via dcop. To look up an address in the name cache from the command line, type `dcop kbluetoothd DeviceNameCache getCachedDeviceName <address>`. To find out which device was last using a given name, you can do `dcop kbluetoothd DeviceNameCache resolveCachedDeviceName <name>`. This command is case-insensitive. Also be aware that several devices might be configured to use the same name.

### The meta server

If you want to implement a server application for a new bluetooth protocol, you can easily integrate it with kbluetoothd, so your server gets started automatically.

You have to supply a XML-file describing the SDP-record and an corresponding desktop file. kbluetoothd will then automatically set up a SDP-record, assign an rfcomm-channel and start listening on the selected channel. When someone connects to your service, kbluetoothd will start it and pass a socket for the already accepted connection to it. The number of the handle is passed as a command line argument.

The kdebluetooth package contains `kbtserialchat`, which is (besides its use for debugging and maybe even chats..) meant as a rather simple sample program for how to integrate an application into the kdebluetooth framework. Since kbtserialchat is a client and a server at the same time, you won't need to consider all command line arguments like kbtserialchat does, especially not sdp-urls.

The format of the SDP-XML-files should be rather self-descriptive, if you know how SDP-records are structured. One important point is how the parameter for the selected rfcomm-channels finds its way into the SDP-record for the server. Since the channel is selected by kbluetoothd automatically, you can't hardcode it into the SDP registration file. Instead you use <uint valref='rfcommchannel' size='8'/> as a placeholder. The rfcomm channels which are tried are defined in the corresponding desktop-file. `X-KDE-KBLUETOOTHD-port` is the first channels that is tried and `X-KDE-KBLUETOOTHD-autoPortRange` gives the number of following channels which are tried in ascending order if a channel is in use by another service already.

kbluetoothd only supports rfcomm at the moment, but when there is need for it, we will also provide support for l2cap or similar.

### The Device Discovery Service

kbluetoothd can actively search for other devices and execute commands as soon as a device was detected or disappeared. You can configure this service in kbluetoothd's control center module under the "Device Discovery"-tab.

The list of active discovery jobs as shown in the control center module is just a list of executables found in the directory `$HOME/.kde/share/apps/kbluetoothd/discovery_jobs/`. You can also add new script to the global template directory in `$PREFIX/share/apps/kdebluetooth/job-templates/`. The scripts in this directory which end on ".template" will be displayed when the user clicks "Add new job..." and will simply be copied to the active job directory in the user's home directory.

The included scripts are split in two to make it easier to update them without having to reinstall the scripts. The ".template"-part contains just the user-modifiable settings which are copied to the home directory. This script then calls the ".real"-part which stays in the template directory.

To start writing your own discovery job, click "Add new job..." and select Custom_Job. This will copy the `Custom_Job.template` to your job directory. Now click "Configure..." to change the script. This script lists all the possible command line options and environment variables which you have access to.

Be aware that when you edit this custom script, all changes are gone if you remove it from the list of active jobs. If you want to distribute it, we recommend that you also split it into a template-part for the settings and a real-part which does the actual work.

To be able to upload, download or delete files from within such a discovery job, you can use kioclient.

If you wrote some cool script for the device discovery service that might be useful for others, we will be happy to include it in the distribution :)=