Return-Path: From: Jose Antonio Santos Cadenas To: linux-bluetooth@vger.kernel.org Cc: Jose Antonio Santos Cadenas Subject: [PATCH 01/32] Add Health api description Date: Wed, 2 Jun 2010 15:18:57 +0200 Message-Id: <1275484768-25838-2-git-send-email-santoscadenas@gmail.com> In-Reply-To: <1275484768-25838-1-git-send-email-santoscadenas@gmail.com> References: <1275484768-25838-1-git-send-email-santoscadenas@gmail.com> Sender: linux-bluetooth-owner@vger.kernel.org List-ID: This API describes the interface shown by the Health plugin through d-bus --- doc/health-api.txt | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 217 insertions(+), 0 deletions(-) create mode 100644 doc/health-api.txt diff --git a/doc/health-api.txt b/doc/health-api.txt new file mode 100644 index 0000000..83e29af --- /dev/null +++ b/doc/health-api.txt @@ -0,0 +1,217 @@ +BlueZ D-Bus Health API description +********************************** + + Santiago Carot-Nemesio + José Antonio Santos-Cadenas + Elvis Pfützenreuter + +Health Device Profile hierarchy +=============================== + +Service org.bluez +Interface org.bluez.HealthAdapter +Object path [variable prefix]/{hci0,hci1,...} + +Methods: + + uint32 CreateInstance(object path, dict config) + + Returns the id of the new created instance. The path parameter + is the path of the remote object with the callbacks to notify + events (see org.bluez.HealthAgent at the end of this document) + This petition starts an mcap instance and also register in the + SDP if is needed. + + Dict is defined as bellow: + { "data_spec" : The data_spec is the data exchange specification + (see section 5.2.10 of the specification + document) possible values: + 0x00 = reserved, + 0x01 [IEEE 11073-20601], + 0x02..0xff reserved, + (optional) + "end_points" : [{ (optional) + "mdepid" : uint8, (optional) + "role" : ("source" or "sink"), (mandatory) + "specs" :[{ (mandatory) + "data_type" : uint16, (mandatory) + "description" : string, (optional) + }] + }] + } + + if "data_spec" is not set, no SDP record will be registered, so + all the other data in the dictionary will be ignored. + + Instance will be closed by the call or implicitly when the + programs leaves the bus. + + Possible errors: org.bluez.Error.InvalidArguments + + void CloseInstance(uint32 ) + + Closes the HDP instance identified by the object path. Also + instance will be closed if the process that started leaves the + bus. If there is a SDP record associated to this instance it + will be removed. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.NotFound + +-------------------------------------------------------------------------------- + +Service org.bluez +Interface org.bluez.HealthDevice +Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Methods: + + array GetHealthInstances() + + Gets the information of the remote instances present in this + device and published on its SDP record. The returned data + follows this format. + + [{"id": uint32, + "data_spec" : data spec, + "end_points": + ["mdepid": uint8, + "role" : "source" or "sink" , + "specs" : [{ + "dtype" : uint16, + "description" : string, (optional) + }] + ] + }]; + + object Connect(uint32 local_instance_id, uint32 remote_instance_id) + + Connects the local instance with the remote instance and returns + the path of the HealthLink object. You should get the remote + instance id running GetHealthInstances. + + Only the bus client that created the local session will be able + to create connections using it. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.HealthError + + void Disconnect(object link, boolean cache) + + Disconnect from the link. If cache is false, state will also be + deleted. Otherwise, the state will be kept for allowing future + reconnections until the adapter holding the local session is + removed. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.NotFound + org.bluez.Error.HealthError + +-------------------------------------------------------------------------------- + +Service org.bluez +Interface org.bluez.HealthLink +Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}/rem_inst_id + +Methods: + + boolean Echo(array{byte}) + + Sends an echo petition to the remote intance. Returns True if + response matches with the buffer sent. If some error is detected + False value is returned and the associated MCL is closed. + + uint16 OpenDataChannel(byte mdepid, byte config) + + Creates a new data channel with the indicated config to the + remote MCAP Data End Point (MDEP). + The configuration should indicate the channel quality of + service. In the current version of HDP, valid values are 0x01 + for reliable channels and 0x02 for streaming data channel. + + Returns the data channel id. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.HealthError + + array GetDataChannelFileDescriptor(uint16 mdlid) + + Gets a file descriptor where data can be read or + written for receive or sent by the data channel. + Returns an array of file descriptors one for write + and other for read. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.NotFound + org.bluez.Error.HealthError + + void DeleteDataChannel(uint16 mdlid) + + Deletes a data channel so it will not be available for + use. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.NotFound + org.bluez.Error.HealthError + + void DeleteAllDataChannels() + + Deletes all data channels so it will not be available + for use. Typically this function is called when the + connection with the remote device will be closed + permanently + + Possible errors: org.bluez.Error.HealthError + + dict GetDataChannelStatus() + + Return a dictionary with all the data channels that + can be used to send data right now. The dictionary + is formed like follows: + { + "reliable": [mdlid_r1, mdlid_r2, ...], + "streaming" : [mdlid_s1, mdlid_s2, ...] + } + + The fist reliable data channel will always be the first + data channel in reliable array. + +HealthAgent hierarchy +===================== + +(this object is implemented by the HDP user in order to receive notifications) + +Service unique name +Interface org.bluez.HealthAgent +Object path freely definable + +Methods: + + void LinkConnected(object path) + + This method is called whenever a new connection has been + established over the control channel of the current HDP + instance. The object path paremeter contains the object path of + the created HealthLink. + + void LinkDisconnected(object path) + + This method is called when a remote device is disconnected + definitively. Any future reconnections will fail. Also all data + channels associated to this device will be closed. + + void CreatedDataChannel(object path, uint16 mdlid, byte conf) + + This method is called when a new data channel is created + + The path contains the object path of the HealthLink where the + new connection is created, the mdlid is the data channel + identificator and conf is the que quality of service of the data + channel (0x01 reliable, 0x02 streaming). + + void DeletedDataChannel(object path, uint16 mdlid) + + This method is called when a data channel is closed. + + After this call the data channel id will not be valid and can be + reused for future created data channels. -- 1.6.3.3