diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 5 | ||||
| -rw-r--r-- | doc/adapter-api.txt | 284 | ||||
| -rw-r--r-- | doc/agent-api.txt | 91 | ||||
| -rw-r--r-- | doc/audio-api.txt | 136 | ||||
| -rw-r--r-- | doc/device-api.txt | 133 | ||||
| -rw-r--r-- | doc/input-api.txt | 36 | ||||
| -rw-r--r-- | doc/manager-api.txt | 56 | ||||
| -rw-r--r-- | doc/network-api.txt | 38 | ||||
| -rw-r--r-- | doc/serial-api.txt | 37 |
9 files changed, 816 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 00000000..5505391e --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,5 @@ + +EXTRA_DIST = manager-api.txt adapter-api.txt device-api.txt agent-api.txt \ + serial-api.txt network-api.txt input-api.txt audio-api.txt + +MAINTAINERCLEANFILES = Makefile.in diff --git a/doc/adapter-api.txt b/doc/adapter-api.txt new file mode 100644 index 00000000..a05bf620 --- /dev/null +++ b/doc/adapter-api.txt @@ -0,0 +1,284 @@ +BlueZ D-Bus Adapter API description +*********************************** + +Copyright (C) 2004-2008 Marcel Holtmann <marcel@holtmann.org> +Copyright (C) 2005-2006 Johan Hedberg <johan.hedberg@nokia.com> +Copyright (C) 2005-2006 Claudio Takahasi <claudio.takahasi@indt.org.br> +Copyright (C) 2006-2007 Luiz von Dentz <luiz.dentz@indt.org.br> + + +Adapter hierarchy +================= + +Service org.bluez +Interface org.bluez.Adapter +Object path /{hci0,hci1,...} + +Methods dict GetProperties() + + Returns all properties for the adapter. See the + properties section for available properties. + + Possible Errors: org.bluez.Error.DoesNotExist + org.bluez.Error.InvalidArguments + + void SetProperty(string name, variant value) + + Changes the value of the specified property. Only + properties that are listed a read-write are changeable. + On success this will emit a PropertyChanged signal. + + Possible Errors: org.bluez.Error.DoesNotExist + org.bluez.Error.InvalidArguments + + void RequestMode(string mode) + + This method will request a mode change. The mode + change must be confirmed by the user via the agent. + + Possible modes for this call are "connectable" and + "discoverable". Any application that wants to use + Bluetooth functionality can use this method to + indicate which mode it needs to operate sucessfully. + + In case the user doesn't confirm the mode change it + will return an error to indicate this rejection. + + Possible Errors: org.bluez.Error.DoesNotExist + org.bluez.Error.InvalidArguments + org.bluez.Error.Rejected + + void ReleaseMode() + + Releases a mode requested via RequestMode. + + Possible Errors: org.bluez.Error.DoesNotExist + + void DiscoverDevices() + + This method starts the device discovery procedure. This + includes an inquiry procedure and remote device name + resolving. + + On start up this process will generate a DiscoveryStarted + signal and then return DeviceFound singals. If the + procedure has been finished an DiscoveryCompleted + signal will be sent. + + Possible errors: org.bluez.Error.NotReady + org.bluez.Error.Failed + org.bluez.Error.InProgress + org.bluez.Error.NoSuchAdapter + + void CancelDiscovery() + + This method will cancel any previous DiscoverDevices + transaction. + + Possible errors: org.bluez.Error.NotReady + org.bluez.Error.Failed + org.bluez.Error.NotAuthorized + org.bluez.Error.NoSuchAdapter + + object FindDevice(string address) + + Returns the object path of device for given address. + The device object needs to be first created via + CreateDevice or CreatePairedDevice. + + Possible Errors: org.bluez.Error.DoesNotExist + org.bluez.Error.InvalidArguments + + array{object} ListDevices() + + Returns list of device object paths. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.Failed + org.bluez.Error.OutOfMemory + + object CreateDevice(string address) + + Creates a new object path for a remote device. This + method will connect to the remote device and retrieve + all SDP records. + + If the object for the remote device already exists + this method will fail. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.Failed + + object CreatePairedDevice(string address, object agent, + string capability) + + Creates a new object path for a remote device. This + method will connect to the remote device and retrieve + all SDP records and then initiate the pairing. + + If previously CreateDevice was used successfully, + this method will only initiate the pairing. + + Compared to CreateDevice this method will fail if + the pairing already exists, but not if the object + path already has been created. This allows applications + to use CreateDevice first and the if needed use + CreatePairedDevice to initiate pairing. + + The capability parameter is the same as for the + RegisterAgent method. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.Failed + + void RemoveDevice(object device) + + This removes the remote device object at the given + path. It will remove also the pairing information. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.Failed + + void RegisterAgent(object agent, string capability) + + This registers the adapter wide agent. + + The object path defines the path the of the agent + that will be called when user input is needed. + + If an application disconnects from the bus all + of its registered agents will be removed. + + The capability parameter can have the values + "DisplayOnly", "DisplayYesNo", "KeyboardOnly" and + "NoInputNoOutput" which reflects the input and output + capabilities of the agent. If an empty string is + used it will fallback to "DisplayYesNo". + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.AlreadyExists + + void UnregisterAgent(object agent) + + This unregisters the agent that has been previously + registered. The object path parameter must match the + same value that has been used on registration. + + Possible errors: org.bluez.Error.DoesNotExist + + uint32 AddServiceRecord(string record) + + Adds a new service record from the XML description + and returns the assigned record handle. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.Failed + + void UpdateServiceRecord(uint32 handle, string record) + + Updates a given service record provided in the + XML format. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.NotAvailable + org.bluez.Error.Failed + + void RemoveServiceRecord(uint32 handle) + + Remove a service record identified by its handle. + + It is only possible to remove service records that + where added by the current connection. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.NotAuthorized + org.bluez.Error.DoesNotExist + org.bluez.Error.Failed + + void RequestAuthorization(string address, uint32 handle) + + Request an authorization for an incoming connection + for a specific service record. The service record + needs to be registered via AddServiceRecord first. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.NotAuthorized + org.bluez.Error.DoesNotExist + org.bluez.Error.Failed + + void CancelAuthorization() + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.NotAuthorized + org.bluez.Error.DoesNotExist + org.bluez.Error.Failed + +Signals PropertyChanged(string name, variant value) + + This signal indicates a changed value of the given + property. + + DiscoveryStarted() + + This signal indicates that a device discovery + procedure has been started. + + DiscoveryCompleted() + + This signal indicates that a device discovery + procedure has been completed. + + DeviceFound(string address, dict values) + + This signal will be send every time an inquiry result + has been found by the service daemon. In general they + only appear during a device discovery. + + The dictionary can contain bascially the same values + that we be returned by the GetProperties method + from the org.bluez.Device interface. In addition there + can be values for the RSSI and the TX power level. + + DeviceDisappeared(string address) + + This signal will be send when an inquiry session for + a periodic discovery finishes and previously found + devices are no longer in range or visible. + + DeviceCreated(object device) + + Parameter is object path of created device. + + DeviceRemoved(object device) + + Parameter is object path of removed device. + +Properties string Address [readonly] + + The Bluetooth device address. + + string Name [readwrite] + + The Bluetooth friendly name. This value can be + changed and a PropertyChanged signal will be emitted. + + string Mode [readwrite] + + The Bluetooth operation mode. + + Valid modes: "off", "connectable", + "discoverable", "limited" + + uint32 DiscoverableTimeout [readwrite] + + The discoverable timeout in seconds. A value of zero + means that the timeout is disabled and it will stay in + discoverable/limited mode forever. + + The default value for the discoverable timeout should + be 180 seconds (3 minutes). + + boolean PeriodicDiscovery [readwrite] + + Is peridoic inquiry active or not. Changing this + property will either enable or disable it. diff --git a/doc/agent-api.txt b/doc/agent-api.txt new file mode 100644 index 00000000..7e3fa3a9 --- /dev/null +++ b/doc/agent-api.txt @@ -0,0 +1,91 @@ +BlueZ D-Bus Agent API description +********************************** + +Copyright (C) 2004-2008 Marcel Holtmann <marcel@holtmann.org> +Copyright (C) 2005-2006 Johan Hedberg <johan.hedberg@nokia.com> + + +Agent hierarchy +=============== + +Service unique name +Interface org.bluez.Agent +Object path freely definable + +Methods void Release() + + This method gets called when the service daemon + unregisters the agent. An agent can use it to do + cleanup tasks. There is no need to unregister the + agent, because when this method gets called it has + already been unregistered. + + string RequestPinCode(object device) + + This method gets called when the service daemon + needs to get the passkey for an authentication. + + The return value should be a string of 1-16 characters + length. The string can be alphanumeric. + + Possible errors: org.bluez.Error.Rejected + org.bluez.Error.Canceled + + uint32 RequestPasskey(object device) + + This method gets called when the service daemon + needs to get the passkey for an authentication. + + The return value should be a numeric value + between 0-999999. + + Possible errors: org.bluez.Error.Rejected + org.bluez.Error.Canceled + + void DisplayPasskey(object device, uint32 passkey, uint8 entered) + + This method gets called when the service daemon + needs to display a passkey for an authentication. + + The entered parameter indicates the number of already + typed keys on the remote side. + + An empty reply should be returned. When the passkey + needs no longer to be displayed, the Cancel method + of the agent will be called. + + During the pairing process this method might be + called multiple times to update the entered value. + + void RequestConfirmation(object device, uint32 passkey) + + This method gets called when the service daemon + needs to confirm a passkey for an authentication. + + To confirm the value it should return an empty reply + or an error in case the passkey is invalid. + + Possible errors: org.bluez.Error.Rejected + org.bluez.Error.Canceled + + void Authorize(object device, string uuid) + + This method gets called when the service daemon + needs to authorize a connection/service request. + + Possible errors: org.bluez.Error.Rejected + org.bluez.Error.Canceled + + void ConfirmModeChange(string mode) + + This method gets called if a mode change is requested + that needs to be confirmed by the user. An example + would be leaving flight mode. + + Possible errors: org.bluez.Error.Rejected + org.bluez.Error.Canceled + + void Cancel() + + This method gets called to indicate that the agent + request failed before a reply was returned. diff --git a/doc/audio-api.txt b/doc/audio-api.txt new file mode 100644 index 00000000..b9f0a920 --- /dev/null +++ b/doc/audio-api.txt @@ -0,0 +1,136 @@ +BlueZ D-Bus Audio API description +********************************* + +Copyright (C) 2004-2008 Marcel Holtmann <marcel@holtmann.org> +Copyright (C) 2005-2007 Johan Hedberg <johan.hedberg@nokia.com> +Copyright (C) 2005-2006 Brad Midgley <bmidgley@xmission.com> + + +Headset hierarchy +================= + +Service org.bluez +Interface org.bluez.Headset +Object path /{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Methods void Connect() + + Connect to the HSP/HFP service on the remote device. + + void Disconnect() + + Disconnect from the HSP/HFP service on the remote + device. + + boolean IsConnected() + + Returns TRUE if there is a active connection to the + HSP/HFP connection on the remote device. + + void IndicateCall() + + Indicate an incoming call on the headset + connected to the stream. Will continue to + ring the headset about every 3 seconds. + + void CancelCall() + + Cancel the incoming call indication. + + void Play() + + Open the audio connection to the headset. + + void Stop() + + Close the audio connection. + + boolean IsPlaying() + + Returns true if an audio connection to the headset + is active. + + uint16 GetSpeakerGain() + + Returns the current speaker gain if available, + otherwise returns the error NotAvailable. + + uint16 GetMicrophoneGain() + + Returns the current microphone gain if available, + otherwise returns the error NotAvailable. + + void SetSpeakerGain(uint16 gain) + + Changes the current speaker gain if possible. + + void SetMicrophoneGain(uint16 gain) + + Changes the current speaker gain if possible. + +Signals void AnswerRequested() + + Sent when the answer button is pressed on the headset + + void Connected() + + Sent when the device has been connected to. + + void Disconnected() + + Sent when the device has been disconnected from. + + void Stopped() + + Sent when the audio connection is closed + + void Playing() + + Sent when the audio connection is opened + + void SpeakerGainChanged(uint16 gain) + + The speaker gain changed. + + void MicrophoneGainChanged(uint16 gain) + + The microphone gain changed. + + +Sink hierarchy +============== + +Service org.bluez +Interface org.bluez.Sink +Object path /{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Methods void Connect() + + Connect and setup a stream to a A2DP sink on the + remote device. + + void Disconnect() + + Disconnect from the remote device. + + boolean IsConnected() + + Returns TRUE if a stream is setup to a A2DP sink on + the remote device. + +Signals void Connected() + + Sent when a successful connection has been made to the + remote A2DP Sink + + void Disconnected() + + Sent when the device has been disconnected from. + + void Playing() + + Sent when a stream with remote device is started. + + void Stopped() + + Sent when a stream with remote device is suspended. diff --git a/doc/device-api.txt b/doc/device-api.txt new file mode 100644 index 00000000..059398df --- /dev/null +++ b/doc/device-api.txt @@ -0,0 +1,133 @@ +BlueZ D-Bus Device API description +********************************** + +Copyright (C) 2004-2008 Marcel Holtmann <marcel@holtmann.org> +Copyright (C) 2005-2006 Johan Hedberg <johan.hedberg@nokia.com> +Copyright (C) 2005-2006 Claudio Takahasi <claudio.takahasi@indt.org.br> +Copyright (C) 2006-2007 Luiz von Dentz <luiz.dentz@indt.org.br> + + +Device hierarchy +================ + +Service org.bluez +Interface org.bluez.Device +Object path /{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Methods dict GetProperties() + + Returns all properties for the adapter. See the + properties section for available properties. + + Possible Errors: org.bluez.Error.DoesNotExist + org.bluez.Error.InvalidArguments + + void SetProperty(string name, variant value) + + Changes the value of the specified property. Only + properties that are listed a read-write are changeable. + On success this will emit a PropertyChanged signal. + + Possible Errors: org.bluez.Error.DoesNotExist + org.bluez.Error.InvalidArguments + + dict DiscoverServices(string pattern) + + This method starts the service discovery to retrieve + remote service records. The pattern parameter can + be used to specific specific UUIDs. + + The return value is a dictionary with the record + handles as keys and the service record in XML format + as values. The key is uint32 and the value a string + for this dictionary. + + Possible errors: org.bluez.Error.NotReady + org.bluez.Error.Failed + org.bluez.Error.InProgress + + void CancelDiscovery() + + This method will cancel any previous DiscoverServices + transaction. + + Possible errors: org.bluez.Error.NotReady + org.bluez.Error.Failed + org.bluez.Error.NotAuthorized + + void Disconnect() + + This method disconnects a specific remote device by + terminating the low-level ACL connection. The use of + this method should be restricted to administrator + use. + + A DisconnectRequested signal will be sent and the + actual disconnection will only happen 2 seconds later. + This enables upper-level applications to terminate + their connections gracefully before the ACL connection + is terminated. + + Possible errors: org.bluez.Error.NotConnected + +Signals PropertyChanged(string name, variant value) + + This signal indicates a changed value of the given + property. + + DisconnectRequested() + + This signal will be sent when a low level + disconnection to a remote device has been requested. + The actual disconnection will happen 2 seconds later. + +Properties string Address [readonly] + + The Bluetooth device address of the remote device. + + string Name [readonly] + + The Bluetooth remote name. This value can not be + changed. Use the Alias property instead. + + uint32 Class [readonly] + + The Bluetooth class of device of the remote device. + + array{string} UUIDs [readonly] + + List of 128-bit UUIDs that represents the available + remote services. + + boolean Paired [readonly] + + Indicates if the remote device is paired. + + boolean Connected [readonly] + + Indicates if the remote device is currently connected. + A PropertyChanged signal indicate changes to this + status. + + boolean Trusted [readwrite] + + Indicates if the remote is seen as trusted. This + setting can be changed by the application. + + string Alias [readwrite] + + The name alias for the remote device. The alias can + be used to have a different friendly name for the + remote device. + + In case no alias is set, it will return the remote + device name. Setting an empty string as alias will + convert it back to the remote device name. + + When reseting the alias with an empty string, the + emitted PropertyChanged signal will show the remote + name again. + + object Adapter [readonly] + + The object path of the adpater the device belongs to. diff --git a/doc/input-api.txt b/doc/input-api.txt new file mode 100644 index 00000000..c0816eec --- /dev/null +++ b/doc/input-api.txt @@ -0,0 +1,36 @@ +BlueZ D-Bus Input API description +********************************* + +Copyright (C) 2004-2008 Marcel Holtmann <marcel@holtmann.org> + + +Input hierarchy +=============== + +Service org.bluez +Interface org.bluez.Input +Object path /{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Methods void Connect() + + Connect to the input device. + + Possible errors: org.bluez.Error.AlreadyConnected + org.bluez.Error.ConnectionAttemptFailed + + void Disconnect() + + Disconnect from the input device. + + To abort a connection attempt in case of errors or + timeouts in the client it is fine to call this method. + + Possible errors: org.bluez.Error.Failed + + bool IsConnected() + + Returns the connection status. + +Signals void Connected() + + void Disconnected() diff --git a/doc/manager-api.txt b/doc/manager-api.txt new file mode 100644 index 00000000..ba45504a --- /dev/null +++ b/doc/manager-api.txt @@ -0,0 +1,56 @@ +BlueZ D-Bus Manager API description +*********************************** + +Copyright (C) 2004-2008 Marcel Holtmann <marcel@holtmann.org> +Copyright (C) 2005-2006 Johan Hedberg <johan.hedberg@nokia.com> +Copyright (C) 2005-2006 Claudio Takahasi <claudio.takahasi@indt.org.br> +Copyright (C) 2006-2007 Luiz von Dentz <luiz.dentz@indt.org.br> + + +Manager hierarchy +================= + +Service org.bluez +Interface org.bluez.Manager +Object path / + +Methods object DefaultAdapter() + + Returns object path for the default adapter. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.NoSuchAdapter + + object FindAdapter(string pattern) + + Returns object path for the specified adapter. Valid + patterns are "hci0" or "00:11:22:33:44:55". + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.NoSuchAdapter + + array{object} ListAdapters() + + Returns list of adapter object paths under /org/bluez + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.Failed + org.bluez.Error.OutOfMemory + +Signals AdapterAdded(object adapter) + + Parameter is object path of added adapter. + + AdapterRemoved(object adapter) + + Parameter is object path of removed adapter. + + DefaultAdapterChanged(object adapter) + + Parameter is object path of the new default adapter, + or an empty string if there is no available adapters. + + In case all adapters are removed this signal will not + be emitted. The AdapterRemoved signal has to be used + to detect that no default adapter is selected or + available anymore. diff --git a/doc/network-api.txt b/doc/network-api.txt new file mode 100644 index 00000000..a59c8972 --- /dev/null +++ b/doc/network-api.txt @@ -0,0 +1,38 @@ +BlueZ D-Bus Network API description +*********************************** + +Copyright (C) 2004-2008 Marcel Holtmann <marcel@holtmann.org> + + +Network hierarchy +================= + +Service org.bluez +Interface org.bluez.Network +Object path /{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Methods string Connect(string uuid) + + Connect to the network device and return the network + device name. Examples of the device name are bnep0, + bnep1 etc. + + Possible errors: org.bluez.Error.AlreadyConnected + org.bluez.Error.ConnectionAttemptFailed + + void Disconnect() + + Disconnect from the network device. + + To abort a connection attempt in case of errors or + timeouts in the client it is fine to call this method. + + Possible errors: org.bluez.Error.Failed + + bool IsConnected() + + Returns the connection status. + +Signals void Connected(string device, string uuid) + + void Disconnected(string device) diff --git a/doc/serial-api.txt b/doc/serial-api.txt new file mode 100644 index 00000000..21c4f220 --- /dev/null +++ b/doc/serial-api.txt @@ -0,0 +1,37 @@ +BlueZ D-Bus Serial API description +********************************** + +Copyright (C) 2004-2008 Marcel Holtmann <marcel@holtmann.org> + + +Serial hierarchy +================ + +Service org.bluez +Interface org.bluez.Serial +Object path /{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Methods string Connect(string uuid) + + Connects to a specific RFCOMM based service on a + remote device and then creates a RFCOMM TTY + device for it. The RFCOMM TTY device is returned. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.InProgress + org.bluez.Error.ConnectionAttemptFailed + org.bluez.Error.NotSupported + + void Disconnect(string device) + + Disconnect a RFCOMM TTY device that has been + created by Connect method. + + To abort a connection attempt in case of errors or + timeouts in the client it is fine to call this method. + + In that case the UUID of the Connect method should + be suplied instead of the TTY device. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.DoesNotExist |