From 246f60f6a2c5393159df8e9b0225e46ddb767609 Mon Sep 17 00:00:00 2001 From: Johan Hedberg Date: Tue, 25 Sep 2012 17:26:16 +0300 Subject: [PATCH] doc: Add profile API documentation --- Makefile.am | 2 +- doc/bluez-docs.xml | 7 +++++ doc/device-api.txt | 23 ++++++++++++++ doc/manager-api.txt | 77 +++++++++++++++++++++++++++++++++++++++++++++ doc/profile-api.txt | 53 +++++++++++++++++++++++++++++++ 5 files changed, 161 insertions(+), 1 deletion(-) create mode 100644 doc/profile-api.txt diff --git a/Makefile.am b/Makefile.am index 372111a1a..315077f45 100644 --- a/Makefile.am +++ b/Makefile.am @@ -380,7 +380,7 @@ CLEANFILES += $(rules_DATA) EXTRA_DIST += scripts/bluetooth-hid2hci.rules scripts/bluetooth-serial.rules EXTRA_DIST += doc/manager-api.txt \ - doc/adapter-api.txt doc/device-api.txt \ + doc/adapter-api.txt doc/device-api.txt doc/profile-api.txt \ doc/service-api.txt doc/agent-api.txt doc/attribute-api.txt \ doc/network-api.txt doc/input-api.txt doc/audio-api.txt \ doc/control-api.txt doc/hfp-api.txt doc/health-api.txt \ diff --git a/doc/bluez-docs.xml b/doc/bluez-docs.xml index 74a8bd191..a90dde7d7 100644 --- a/doc/bluez-docs.xml +++ b/doc/bluez-docs.xml @@ -68,6 +68,13 @@ + + Profile interface + + + + + Agent interface diff --git a/doc/device-api.txt b/doc/device-api.txt index cd96ef54d..76af34c59 100644 --- a/doc/device-api.txt +++ b/doc/device-api.txt @@ -83,6 +83,29 @@ Methods dict GetProperties() Possible errors: org.bluez.Error.NotConnected + void ConnectProfile(string uuid) + + This method connects a specific profile of this + device. The profile needs to be registered client + profile. + + Possible errors: org.bluez.Error.DoesNotExist + org.bluez.Error.AlreadyConnected + org.bluez.Error.ConnectFailed + + void DisconnectProfile(string uuid) + + This method disconnects a specific profile of + this device. The profile needs to be registered + client profile. + + There is no connection tracking for a profile, so + as long as the profile is registered this will always + succeed. + + Possible errors: org.bluez.Error.DoesNotExist + org.bluez.Error.NotConnected + Signals PropertyChanged(string name, variant value) This signal indicates a changed value of the given diff --git a/doc/manager-api.txt b/doc/manager-api.txt index 4e6653b23..6efa58b3f 100644 --- a/doc/manager-api.txt +++ b/doc/manager-api.txt @@ -37,6 +37,83 @@ Methods dict GetProperties() Possible errors: org.bluez.Error.InvalidArguments org.bluez.Error.NoSuchAdapter + void RegisterProfile(object profile, string uuid, dict options) + + This registers a profile implementation. + + If an application disconnects from the bus all + its registered profiles will be removed. + + HFP HS UUID: 0000111e-0000-1000-8000-00805f9b34fb + + Default RFCOMM channel is 6. And this requires + authentication. + + Available options: + + string Name + + Human readable name for the profile + + string Role + + For asymmetric profiles that do not + have UUIDs available to uniquely + identify each side this + parameter allows specifying the + precise local role. + + Possible values: "client", "server" + + uint16 Channel + + RFCOMM channel number that is used + for client and server UUIDs. + + If applicable it will be used in the + SDP record as well. + + uint16 PSM + + PSM number that is used for client + and server UUIDs. + + If applicable it will be used in the + SDP record as well. + + boolean RequireAuthentication + + Pairing is required before connections + will be established. No devices will + be connected if not paired. + + boolean RequireAuthorization + + Request authorization before any + connection will be established. + + boolean AutoConnect + + In case of a client UUID this will + force connection of the RFCOMM or + L2CAP channels when a remote device + is connected. + + string ServiceRecord + + Provide a manual SDP record. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.AlreadyExists + + void UnregisterProfile(object profile) + + This unregisters the profile 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 diff --git a/doc/profile-api.txt b/doc/profile-api.txt new file mode 100644 index 000000000..639202fbf --- /dev/null +++ b/doc/profile-api.txt @@ -0,0 +1,53 @@ +BlueZ D-Bus Profile API description +*********************************** + +Copyright (C) 2012 Intel Corporation. All rights reserved. + + +Profile hierarchy +================= + +Service unique name +Interface org.bluez.Profile +Object path freely definable + +Methods void Release() + + This method gets called when the service daemon + unregisters the profile. A profile can use it to do + cleanup tasks. There is no need to unregister the + profile, because when this method gets called it has + already been unregistered. + + void NewConnection(object device, fd) + + This method gets called when a new service level + connection has been made and authorized. + + Possible errors: org.bluez.Error.Rejected + org.bluez.Error.Canceled + + void RequestDisconnection(object device) + + This method gets called when a profile gets + disconnected. + + The file descriptor is no longer owned by the service + daemon and the profile implementation needs to take + care of cleaning up all connections. + + If multiple file descriptors are indicated via + NewConnection, it is expected that all of them + are disconnected before returning from this + method call. + + Possible errors: org.bluez.Error.Rejected + org.bluez.Error.Canceled + + void Cancel() + + This method gets called to indicate that the profile + request failed before a reply was returned. + + All request are queued and there will be only one + pending pequest at a time per profile. -- 2.47.3