diff options
Diffstat (limited to 'doc/adapter-api.txt')
| -rw-r--r-- | doc/adapter-api.txt | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/doc/adapter-api.txt b/doc/adapter-api.txt new file mode 100644 index 0000000..f34d58f --- /dev/null +++ b/doc/adapter-api.txt @@ -0,0 +1,286 @@ +BlueZ D-Bus Adapter API description +*********************************** + +Copyright (C) 2004-2010 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 [variable prefix]/{hci0,hci1,...} + +Methods dict GetProperties() + + Returns all properties for the adapter. See the + properties section for available properties. + + Possible Errors: org.bluez.Error.NotReady + + 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.InvalidArguments + + void RequestSession() + + This method requests a client session that provides + operational Bluetooth. A possible mode change must be + confirmed by the user via the agent. + + Clients may request multiple sessions. All sessions + are released when adapter's mode is changed to off + state. + + Possible Errors: org.bluez.Error.Rejected + + void ReleaseSession() + + Release a previously requested session. It sets + adapter to the mode in use on the moment of session + request. + + SetProperty method call changes adapter's mode + persistently, such that session release will not + modify it. + + Possible Errors: org.bluez.Error.DoesNotExist + + void StartDiscovery() + + This method starts the device discovery session. This + includes an inquiry procedure and remote device name + resolving. Use StopDiscovery to release the sessions + acquired. + + This process will start emitting DeviceFound and + PropertyChanged "Discovering" signals. + + Possible errors: org.bluez.Error.NotReady + org.bluez.Error.Failed + + void StopDiscovery() + + This method will cancel any previous StartDiscovery + transaction. + + Note that a discovery procedure is shared between all + discovery sessions thus calling StopDiscovery will only + release a single session. + + Possible errors: org.bluez.Error.NotReady + org.bluez.Error.Failed + org.bluez.Error.NotAuthorized + + 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() {deprecated} + + Returns list of device object paths. + This method is deprecated, instead use the Devices + Property to get the list of devices 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 agent object path is assumed to reside within the + process (D-Bus connection instance) that calls this + method. No separate registration procedure is needed + for it and it gets automatically released once the + pairing operation is complete. + + The capability parameter is the same as for the + RegisterAgent method. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.Failed + + void CancelDeviceCreation(string address) + + Aborts either a CreateDevice call or a + CreatePairedDevice call. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.NotInProgress + + 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 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 + +Signals PropertyChanged(string name, variant value) + + This signal indicates a changed value of the given + property. + + DeviceFound(string address, dict values) + + This signal will be sent 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 basically the same values + that are returned by the GetProperties method + from the org.bluez.Device interface. In addition there + can be values for the RSSI, the TX power level and + Broadcaster role. + + DeviceDisappeared(string address) + + This signal will be sent 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. + + uint32 Class [readonly] + + The Bluetooth class of device. + + boolean Powered [readwrite] + + Switch an adapter on or off. This will also set the + appropiate connectable state. + + boolean Discoverable [readwrite] + + Switch an adapter to discoverable or non-discoverable + to either make it visible or hide it. This is a global + setting and should only be used by the settings + application. + + If the DiscoverableTimeout is set to a non-zero + value then the system will set this value back to + false after the timer expired. + + In case the adapter is switched off, setting this + value will fail. + + When changing the Powered property the new state of + this property will be updated via a PropertyChanged + signal. + + boolean Pairable [readwrite] + + Switch an adapter to pairable or non-pairable. This is + a global setting and should only be used by the + settings application. + + Note that this property only affects incoming pairing + requests. + + uint32 PaireableTimeout [readwrite] + + The pairable timeout in seconds. A value of zero + means that the timeout is disabled and it will stay in + pareable mode forever. + + 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 Discovering [readonly] + + Indicates that a device discovery procedure is active. + + array{object} Devices [readonly] + + List of device object paths. + + array{string} UUIDs [readonly] + + List of 128-bit UUIDs that represents the available + local services. |