Skip to contentSkip to conversation

HDP proposed api (ver 0.2)

DISCUSSION José Antonio Santos Cadenas 5 participants 15 messages May 5, 2010 – May 10, 2010 Bluetooth drivers

lore
Share & tools
lore
#0 lore raw

Hi all,

Here is a new proposoal that tries to integrate all that have been comented and proposed in the list, as well as we talked yesterday on the IRC.

There is still one thing that should be discussed, the fd passin issue. We think that we must talk about this and find the best way for the implementation as Elvis sugested.

Regards.

---------------------------------------

BlueZ D-Bus HDP API description
***********************************

Health Device Profile hierarchy
===============================

Service org.bluez
Interface org.bluez.Hdp
Object path [variable prefix]/{hci0,hci1,...}

Methods object CreateSession(object path, dict config)

Returns the object path for the new HDP session. The path parameter is the path of the remote object with the callbacks to nofity events (see org.bluez.HdpAgent at the end of this document) This petition starts an mcap session and also register in the SDP is needed
Dict is defined as bellow:
{ "data_spec" : The data_spec is the data exchange
specficication (see section 5.2.10 of the specification document), (optional)
"end_points" : [{ (optional)
"mdepid" : uint8, (optional) "role" : uint8, (mandatory) "specs" :[{ (mandatory)
"dtype" : uint16, (mandatory) "description" : string, (optional)
}]
}]
}

if "data_spec" is not set, no SDP record will be registerd, so all the other data in the dictionary will be ignored

Session will be closed by the call or implicitly when the programs leaves the bus.

Possible errors: org.bluez.Error.InvalidArguments

void DeleteSession(object path)

Delete the HDP session identified by the object path. Also session will be closed if the procces that started it is removed from the D-Bus.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound

array remote_session_properties GetRemotesSessions()

Returns an array with the remote session_properties of all the visible devices. remote_session_properties is a dictionary like:
[{"session_id": a_session_identification (int or string,
probably the SDP handler + btaddr)
"data_spec" : the remote data spec, "end_points":
["mdepid": uint8,
"role" : uint8,
"specs" : [{
"dtype" : uint16,
"description" : string, (optional)
}]
]
}]

Note that only remotes with a SDP record will be notified by this function.

--------------------------------------------------------------------------------

Service org.bluez
Interface org.bluez.HdpSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}

object Connect(remote_session_id)

Connects with the remote session and returns its object path.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.HdpError

void Disconnect(object device, boolean delete)

Disconnect from the remote device. If delete is true, any status will also be deleted. Otherwise, the status will be keeped for allowing future reconnections.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound org.bluez.Error.HdpError

--------------------------------------------------------------------------------

Service org.bluez
Interface org.bluez.HdpRemoteSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}/rem_session_id

boolean Echo(array{byte})

Sends an echo petition to the remote session. Return True if response matches with the buffer sended. If some error is detected False value is returned and the associated MCL is closed.

uint16 OpenDc(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.
Returns the data channel id.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.HdpError

file_descriptor GetDcFd(uint16 mdlid)

Gets a file descriptor where data can be readed or writed for receive or sent by the data channel. Returns the file descriptor

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound org.bluez.Error.HdpError

void DeleteDc(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.HdpError

void DeleteAllDc()

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.HdpError

uint16 FirstRelDc()

Returns the identificator of the first reliable data channel (ERTM) connected for this device.

Possible errors: org.bluez.Error.HdpError

uint16 GetBestEfforDc()

Returns the id of a best effort (streamming) data channel if any.

Possible errors: org.bluez.Error.NotFound

array getStatus()

Returns an array with all the data channels available

returned array:
[uint16, ...]

Possible errors: org.bluez.Error.NotFound

HDPAgent hierarchy
==================

(this object is implemented by the HDP client an receives notifications)

Service         unique name
Interface       org.bluez.HdpAgent
Object path     freely definable

void DeviceConnected(object path)

This method is called whenever a new device connection has been established over the control channel of the current HDP session. The objectpath contains the object path of the remote device.

void DeviceDisconnected(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 CreatedDc(object path, uint16 mdlid, filedescriptor fd)

This method is called when a new data channel is created The path contains the object path of the device whith the new connection is created, the mdlid the data channel identificator and the fd is the file descriptor where the data can be readed or writed.

void DeletedDc(object path, uint16 mdlid)

This method is called when a data channel is closed. After this call the data channel will not be valid and can be reused for future created data channels.

void DataReady(object path, uint16 mdlid, filedescriptor fd)

This method is called when there is new data that can be readed in a data channel

void RemoteSession(dict remote_session_properties)

This methos is called when a new session is discorevered in a remote device. See Hdp.GetRemotes to know how the dictionary is formed.

#1 lore raw

Hi,

Quoted 159 lines · José Antonio Santos Cadenas

Hi all,

Here is a new proposoal that tries to integrate all that have been comented and proposed in the list, as well as we talked yesterday on the IRC.

There is still one thing that should be discussed, the fd passin issue. We think that we must talk about this and find the best way for the implementation as Elvis sugested.

Regards.

---------------------------------------

BlueZ D-Bus HDP API description
***********************************

Health Device Profile hierarchy
===============================

Service org.bluez
Interface org.bluez.Hdp
Object path [variable prefix]/{hci0,hci1,...}

Methods object CreateSession(object path, dict config)

Returns the object path for the new HDP session. The path parameter is the path of the remote object with the callbacks to nofity events (see org.bluez.HdpAgent at the end of this document) This petition starts an mcap session and also register in the SDP is needed
Dict is defined as bellow:
{ "data_spec" : The data_spec is the data exchange
specficication (see section 5.2.10 of the specification document), (optional)
"end_points" : [{ (optional)
"mdepid" : uint8, (optional) "role" : uint8, (mandatory) "specs" :[{ (mandatory)
"dtype" : uint16, (mandatory) "description" : string, (optional)
}]
}]
}

if "data_spec" is not set, no SDP record will be registerd, so all the other data in the dictionary will be ignored

Session will be closed by the call or implicitly when the programs leaves the bus.

Possible errors: org.bluez.Error.InvalidArguments

void DeleteSession(object path)

Delete the HDP session identified by the object path. Also session will be closed if the procces that started it is removed from the D-Bus.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound

array remote_session_properties GetRemotesSessions()

Returns an array with the remote session_properties of all the visible devices. remote_session_properties is a dictionary like:
[{"session_id": a_session_identification (int or string,
probably the SDP handler + btaddr)
"data_spec" : the remote data spec, "end_points":
["mdepid": uint8,
"role" : uint8,
"specs" : [{
"dtype" : uint16,
"description" : string, (optional)
}]
]
}]

Note that only remotes with a SDP record will be notified by this function.

--------------------------------------------------------------------------------

Service org.bluez
Interface org.bluez.HdpSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}

object Connect(remote_session_id)

Connects with the remote session and returns its object path.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.HdpError

void Disconnect(object device, boolean delete)

Disconnect from the remote device. If delete is true, any status will also be deleted. Otherwise, the status will be keeped for allowing future reconnections.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound org.bluez.Error.HdpError

--------------------------------------------------------------------------------

Service org.bluez
Interface org.bluez.HdpRemoteSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}/rem_session_id

boolean Echo(array{byte})

Sends an echo petition to the remote session. Return True if response matches with the buffer sended. If some error is detected False value is returned and the associated MCL is closed.

uint16 OpenDc(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.
Returns the data channel id.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.HdpError

file_descriptor GetDcFd(uint16 mdlid)

Gets a file descriptor where data can be readed or writed for receive or sent by the data channel. Returns the file descriptor

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound org.bluez.Error.HdpError

void DeleteDc(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.HdpError

void DeleteAllDc()

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

Quoted 8 lines

Possible errors: org.bluez.Error.HdpError

uint16 FirstRelDc()

Returns the identificator of the first reliable data channel (ERTM) connected for this device.

Possible errors: org.bluez.Error.HdpError

I miss a method to get a ReliableChannel, not only the first reliable used for association, confirmed services, faults or abnormal conditions defined in iso/ieee11073-20601. May be better next method instead above one:

uint16 GetReliableDc(boolean first)

Returns the identificator of a reliable data channel (ERTM) connected for this device. If first is True, the first reliable data channel file descriptor is returned.

Possible errors: org.bluez.Error.HdpError

Some coments?

Quoted 69 lines

uint16 GetBestEfforDc()

Returns the id of a best effort (streamming) data channel if any.

Possible errors: org.bluez.Error.NotFound

array getStatus()

Returns an array with all the data channels available

returned array:
[uint16, ...]

Possible errors: org.bluez.Error.NotFound

HDPAgent hierarchy
==================

(this object is implemented by the HDP client an receives notifications)

Service         unique name
Interface       org.bluez.HdpAgent
Object path     freely definable

void DeviceConnected(object path)

This method is called whenever a new device connection has been established over the control channel of the current HDP session. The objectpath contains the object path of the remote device.

void DeviceDisconnected(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 CreatedDc(object path, uint16 mdlid, filedescriptor fd)

This method is called when a new data channel is created The path contains the object path of the device whith the new connection is created, the mdlid the data channel identificator and the fd is the file descriptor where the data can be readed or writed.

void DeletedDc(object path, uint16 mdlid)

This method is called when a data channel is closed. After this call the data channel will not be valid and can be reused for future created data channels.

void DataReady(object path, uint16 mdlid, filedescriptor fd)

This method is called when there is new data that can be readed in a data channel

void RemoteSession(dict remote_session_properties)

This methos is called when a new session is discorevered in a remote device. See Hdp.GetRemotes to know how the dictionary is formed.

--
To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html

#2 lore raw
Quoted 179 lines · Santiago Carot-Nemesio

Hi,

Quoted 159 lines · José Antonio Santos Cadenas

Hi all,

Here is a new proposoal that tries to integrate all that have been comented and proposed in the list, as well as we talked yesterday on the IRC.

There is still one thing that should be discussed, the fd passin issue. We think that we must talk about this and find the best way for the implementation as Elvis sugested.

Regards.

---------------------------------------

BlueZ D-Bus HDP API description
***********************************

Health Device Profile hierarchy
===============================

Service org.bluez
Interface org.bluez.Hdp
Object path [variable prefix]/{hci0,hci1,...}

Methods object CreateSession(object path, dict config)

Returns the object path for the new HDP session. The path parameter is the path of the remote object with the callbacks to nofity events (see org.bluez.HdpAgent at the end of this document) This petition starts an mcap session and also register in the SDP is needed
Dict is defined as bellow:
{ "data_spec" : The data_spec is the data exchange
specficication (see section 5.2.10 of the specification document), (optional)
"end_points" : [{ (optional)
"mdepid" : uint8, (optional) "role" : uint8, (mandatory) "specs" :[{ (mandatory)
"dtype" : uint16, (mandatory) "description" : string, (optional)
}]
}]
}

if "data_spec" is not set, no SDP record will be registerd, so all the other data in the dictionary will be ignored

Session will be closed by the call or implicitly when the programs leaves the bus.

Possible errors: org.bluez.Error.InvalidArguments

void DeleteSession(object path)

Delete the HDP session identified by the object path. Also session will be closed if the procces that started it is removed from the D-Bus.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound

array remote_session_properties GetRemotesSessions()

Returns an array with the remote session_properties of all the visible devices. remote_session_properties is a dictionary like:
[{"session_id": a_session_identification (int or string,
probably the SDP handler + btaddr)
"data_spec" : the remote data spec, "end_points":
["mdepid": uint8,
"role" : uint8,
"specs" : [{
"dtype" : uint16,
"description" : string, (optional)
}]
]
}]

Note that only remotes with a SDP record will be notified by this function.

--------------------------------------------------------------------------------

Service org.bluez
Interface org.bluez.HdpSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}

object Connect(remote_session_id)

Connects with the remote session and returns its object path.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.HdpError

void Disconnect(object device, boolean delete)

Disconnect from the remote device. If delete is true, any status will also be deleted. Otherwise, the status will be keeped for allowing future reconnections.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound org.bluez.Error.HdpError

--------------------------------------------------------------------------------

Service org.bluez
Interface org.bluez.HdpRemoteSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}/rem_session_id

boolean Echo(array{byte})

Sends an echo petition to the remote session. Return True if response matches with the buffer sended. If some error is detected False value is returned and the associated MCL is closed.

uint16 OpenDc(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.
Returns the data channel id.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.HdpError

file_descriptor GetDcFd(uint16 mdlid)

Gets a file descriptor where data can be readed or writed for receive or sent by the data channel. Returns the file descriptor

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound org.bluez.Error.HdpError

void DeleteDc(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.HdpError

void DeleteAllDc()

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

Quoted 8 lines

Possible errors: org.bluez.Error.HdpError

uint16 FirstRelDc()

Returns the identificator of the first reliable data channel (ERTM) connected for this device.

Possible errors: org.bluez.Error.HdpError

I miss a method to get a ReliableChannel, not only the first reliable used for association, confirmed services, faults or abnormal conditions defined in iso/ieee11073-20601. May be better next method instead above one:

uint16 GetReliableDc(boolean first)

Quoted 25 lines

Returns the identificator of a reliable data channel (ERTM) connected for this device. If first is True, the first reliable data channel file descriptor is returned.

Possible errors: org.bluez.Error.HdpError

Some coments?

Quoted 16 lines

uint16 GetBestEfforDc()

Returns the id of a best effort (streamming) data channel if any.

Possible errors: org.bluez.Error.NotFound

array getStatus()

Returns an array with all the data channels available

returned array:
[uint16, ...]

Possible errors: org.bluez.Error.NotFound

Because different quality of service is used for specific data traffic in iso/ieee11073-20601, its possible that applications only are interested in to get one kind of data channel. May be that above three functions can be defined like next two:

array GetReliableDc()

Returns an array with all the data channels with ERTM configuration. First of all is the FirstReliable channel used for specific traffic.

Possible errors: org.bluez.Error.HdpError

array GetBestEffortDc()

Returns an array with all the data channels with Straming configuration.

Possible errors: org.bluez.Error.HdpError

Whit this change I don't see neccessary the getStatus() function. What do you think?

Quoted 59 lines
Quoted 45 lines

HDPAgent hierarchy
==================

(this object is implemented by the HDP client an receives notifications)

Service         unique name
Interface       org.bluez.HdpAgent
Object path     freely definable

void DeviceConnected(object path)

This method is called whenever a new device connection has been established over the control channel of the current HDP session. The objectpath contains the object path of the remote device.

void DeviceDisconnected(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 CreatedDc(object path, uint16 mdlid, filedescriptor fd)

This method is called when a new data channel is created The path contains the object path of the device whith the new connection is created, the mdlid the data channel identificator and the fd is the file descriptor where the data can be readed or writed.

void DeletedDc(object path, uint16 mdlid)

This method is called when a data channel is closed. After this call the data channel will not be valid and can be reused for future created data channels.

void DataReady(object path, uint16 mdlid, filedescriptor fd)

This method is called when there is new data that can be readed in a data channel

void RemoteSession(dict remote_session_properties)

Quoted 8 lines

This methos is called when a new session is discorevered in a remote device. See Hdp.GetRemotes to know how the dictionary is formed.

--
To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html

--
To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html

#3 lore raw
In reply to José Antonio Santos Cadenas

Hi,

Quoted 10 lines · José Antonio Santos Cadenas

Health Device Profile hierarchy
===============================

Service org.bluez
Interface org.bluez.Hdp
Object path [variable prefix]/{hci0,hci1,...}

Methods object CreateSession(object path, dict config)

Quoted 11 lines

Returns the object path for the new HDP session. The path parameter is the path of the remote object with the callbacks to nofity events (see org.bluez.HdpAgent at the end of this document) This petition starts an mcap session and also register in the SDP is needed
Dict is defined as bellow:
{ "data_spec" : The data_spec is the data exchange
specficication (see section 5.2.10 of the specification document), (optional)

Would be nice to include a "survival kit" about this 5.2.10, for completeness. Like (normally = 0x01 [IEEE xxxxx], 0x00 = reserved, 0x02 = other -- )

Quoted 3 lines
			  "end_points" : [{ (optional)
				"mdepid" : uint8, (optional)
				"role" : uint8, (mandatory)

We could use strings there, 'source' or 'sink'?

Quoted 2 lines
				"specs" :[{ (mandatory)
					"dtype" : uint16, (mandatory)

IMHO the key names may be more descriptive, like data_type. More about this below.

Another thing: as far as I understand, I may create a session, with well-defined MDEP IDs, roles etc. but then choose not to publish a SDP record. For example, I am an HDP source and want to have 5 MDEPs. An additional bool dict key like 'export' or 'publish' (not sure about correct BT nomenclature) would fit the bill.

"Forcing" a source to specify the MDEP IDs here, even if not publishing the record, makes checks easier further.

Quoted 8 lines

"description" : string, (optional)
}]
}]
}

if "data_spec" is not set, no SDP record will be registerd, so all the other data in the dictionary will be ignored

See comments above

Quoted 8 lines

Session will be closed by the call or implicitly when the programs leaves the bus.

Possible errors: org.bluez.Error.InvalidArguments

void DeleteSession(object path)

Quoted 8 lines

Delete the HDP session identified by the object path. Also session will be closed if the procces that started it is removed from the D-Bus.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound

array remote_session_properties GetRemotesSessions()

typo

Quoted 17 lines

Returns an array with the remote session_properties of all the visible devices. remote_session_properties is a dictionary like:
[{"session_id": a_session_identification (int or string,
probably the SDP handler + btaddr)
"data_spec" : the remote data spec, "end_points":
["mdepid": uint8,
"role" : uint8,
"specs" : [{
"dtype" : uint16,
"description" : string, (optional)
}]
]
}]

Quoted 2 lines

Note that only remotes with a SDP record will be notified by this function.

I don't get the concept of "remote sessions" of the current proposal. I understand the HDP session as a kind of "context" which holds the rest of HDP elements (published records, connections etc.)

Perhaps you meant "SDP records of HDP devices"? If so, IMHO this method should return just a list of device paths, which in turn would implement a BlueZ HDP interface that supplies further information (like my API proposal did).

I see some spread between org.bluez.Hdp and org.bluez.HdpSession. IMHO would be better to have just the context creation, as simple as possible, in org.bluez.Hdp and have everything else in org.bluez.HdpSession. (I still prefer the approach of "my" API, but I recognize that you are accomodating the notion of multiple records per [process, device] tuple.)

Quoted 25 lines

--------------------------------------------------------------------------------

Service org.bluez
Interface org.bluez.HdpSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}

object Connect(remote_session_id)

Connects with the remote session and returns its object path.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.HdpError

void Disconnect(object device, boolean delete)

Disconnect from the remote device. If delete is true, any status will also be deleted. Otherwise, the status will be keeped for allowing future reconnections.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound org.bluez.Error.HdpError

Quoted 5 lines

--------------------------------------------------------------------------------

Service org.bluez
Interface org.bluez.HdpRemoteSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}/rem_session_id

IMHO "remote session" feels funny. "Device record" would sound better (it is a device, so it is implied to be remote; and a record, which implies a given SDP record).

Also, I think that the device path (appended by an unique identifier of the record) would be better. After all, that path already exists when device is around.

Perhaps you tried to accomodate the notion that a data channel ID "survives" even if the device disappearrs for a short moment?

Quoted 7 lines

boolean Echo(array{byte})

Sends an echo petition to the remote session. Return True if response matches with the buffer sended. If some error is detected False value is returned and the associated MCL is closed.

Ok

Quoted 2 lines

uint16 OpenDc(byte mdepid, byte config)

Could be OpenDataChannel?

Quoted 11 lines

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.
Returns the data channel id.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.HdpError

file_descriptor GetDcFd(uint16 mdlid)

This FD should be delivered via HdpAgent exclusively. I have counted three ways an application can receive an FD, IMHO there should be exactly one.

Quoted 10 lines

Gets a file descriptor where data can be readed or writed for receive or sent by the data channel. Returns the file descriptor

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound org.bluez.Error.HdpError

void DeleteDc(uint16 mdlid)

DeleteDataChannel

Quoted 9 lines

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.HdpError

void DeleteAllDc()

Could be overloaded with DeleteDataChannel with MDL ID = 0, perhaps, but nothing incredibly important :)

Quoted 13 lines

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.HdpError

uint16 FirstRelDc()

Returns the identificator of the first reliable data channel (ERTM) connected for this device.

Quoted 8 lines

Possible errors: org.bluez.Error.HdpError

uint16 GetBestEfforDc()

Returns the id of a best effort (streamming) data channel if any.

Possible errors: org.bluez.Error.NotFound

An use case would be good. In my vision, the application should just have one way to get the whole data connection list, and do whatever it wants, and not one new method for each type. We can e.g. guarantee that such list is in order, so the application can trust e.g. the first reliable channel on list to be what FirstRelDc() meant to return. (HDP mandates the first data channel to be reliable anyway.)

Quoted 9 lines

array getStatus()

Returns an array with all the data channels available

returned array:
[uint16, ...]

Possible errors: org.bluez.Error.NotFound

Available = connected, open (MDL ID has been created) or...?

Quoted 17 lines

HDPAgent hierarchy
==================

(this object is implemented by the HDP client an receives notifications)

Service         unique name
Interface       org.bluez.HdpAgent
Object path     freely definable

void DeviceConnected(object path)

This method is called whenever a new device connection has been established over the control channel of the current HDP session. The objectpath contains the object path of the remote device.

Quoted 6 lines

void DeviceDisconnected(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.

Perfect up to this part.

Quoted 2 lines

void CreatedDc(object path, uint16 mdlid, filedescriptor fd)

Could be "DataChannelCreated"?

Quoted 8 lines

This method is called when a new data channel is created The path contains the object path of the device whith the new connection is created, the mdlid the data channel identificator and the fd is the file descriptor where the data can be readed or writed.

void DeletedDc(object path, uint16 mdlid)

DataChannelDeleted?

Quoted 9 lines

This method is called when a data channel is closed. After this call the data channel will not be valid and can be reused for future created data channels.

void DataReady(object path, uint16 mdlid, filedescriptor fd)

This method is called when there is new data that can be readed in a data channel

This one I don't understand. It seems to duplicate the function of CreatedDc, even the prototype is exactly the same. Has this something to have with reconnections? (Even so, CreatedDc could be overloaded with this.)

Quoted 6 lines

void RemoteSession(dict remote_session_properties)

This methos is called when a new session is discorevered in a remote device. See Hdp.GetRemotes to know how the dictionary is formed.

Same comment about the concept of remote session.

#4 lore raw
Quoted 21 lines · El Friday 07 May 2010 01:49:10 escribió:

Hi,

Quoted 18 lines · José Antonio Santos Cadenas

Health Device Profile hierarchy
===============================

Service org.bluez
Interface org.bluez.Hdp
Object path [variable prefix]/{hci0,hci1,...}

Methods object CreateSession(object path, dict config)

Returns the object path for the new HDP session. The path parameter is the path of the remote object with the callbacks to nofity events (see org.bluez.HdpAgent at the end of this document) This petition starts an mcap session and also register in the SDP is needed
Dict is defined as bellow:
{ "data_spec" : The data_spec is the data exchange

Quoted 7 lines
Quoted 3 lines

specficication (see section 5.2.10 of the specification document), (optional)

Would be nice to include a "survival kit" about this 5.2.10, for completeness. Like (normally = 0x01 [IEEE xxxxx], 0x00 = reserved, 0x02 = other -- )

I think that you mean to document the possible values that can be used here. We think its a good Idea.

Quoted 7 lines
Quoted 5 lines
			  "end_points" : [{ (optional)
				
				"mdepid" : uint8, (optional)
				"role" : uint8, (mandatory)

We could use strings there, 'source' or 'sink'?

Good idea, its clearer for the user this way.

Quoted 7 lines
Quoted 4 lines
				"specs" :[{ (mandatory)
				
					"dtype" : uint16, (mandatory)

IMHO the key names may be more descriptive, like data_type. More about this below.

Ok with this too.

Quoted 9 lines

Another thing: as far as I understand, I may create a session, with well-defined MDEP IDs, roles etc. but then choose not to publish a SDP record. For example, I am an HDP source and want to have 5 MDEPs. An additional bool dict key like 'export' or 'publish' (not sure about correct BT nomenclature) would fit the bill.

"Forcing" a source to specify the MDEP IDs here, even if not publishing the record, makes checks easier further.

Not sure about that. Note that when you don't publish a SDP record, nobody could connect to you, so you won't receive data channel connections request, so you don't need to check if the mdeps are in use or not.

Quoted 58 lines
Quoted 5 lines

"description" : string, (optional)

}]

Quoted 7 lines

}]

}

if "data_spec" is not set, no SDP record will be registerd, so all the other data in the dictionary will be ignored

See comments above

Quoted 11 lines

Session will be closed by the call or implicitly when the programs leaves the bus.

Possible errors: org.bluez.Error.InvalidArguments

void DeleteSession(object path)

Delete the HDP session identified by the object path. Also session will be closed if the procces that started it is removed from the D-Bus.

Quoted 5 lines

Possible errors: org.bluez.Error.InvalidArguments

org.bluez.Error.NotFound

array remote_session_properties GetRemotesSessions()

typo

Quoted 24 lines
			Returns an array with the remote session_properties
			of all the visible devices.
			remote_session_properties is a dictionary like:
			[{"session_id": a_session_identification (int or string,
			
					 probably the SDP handler + btaddr)
			 
			 "data_spec" : the remote data spec,
			 
			 "end_points":
				 ["mdepid": uint8,
				 
				  "role"  : uint8,
				  "specs" : [{
				  
					  "dtype"	: uint16,
					  "description"	: string, (optional)
				  
				  }]
				 
				 ]
			
			}]
Quoted 8 lines
Quoted 2 lines

Note that only remotes with a SDP record will be notified by this function.

I don't get the concept of "remote sessions" of the current proposal. I understand the HDP session as a kind of "context" which holds the rest of HDP elements (published records, connections etc.)

Perhaps you meant "SDP records of HDP devices"?

Yes, but not only the record, also the session. This includes the mcl (mcap nomenclature) that can be connected to it and also all the data channel management.

Quoted 4 lines

If so, IMHO this method
should return just a list of device paths, which in turn would implement a BlueZ HDP interface that supplies further information (like my API proposal did).

It's not a bad idea for requesting information, but we think that the connect method should be complicated. Note that the connections are performed between sessions, not between devices. So when you call the connect method, you will need to pass all this atributes:

- Remote mdep_id
- Configuration
- Remote session_id
- Local session

Quoted 6 lines

I see some spread between org.bluez.Hdp and org.bluez.HdpSession. IMHO would be better to have just the context creation, as simple as possible, in org.bluez.Hdp and have everything else in org.bluez.HdpSession. (I still prefer the approach of "my" API, but I recognize that you are accomodating the notion of multiple records per [process, device] tuple.)

It could be a little bit estrange, but we think is necessary for the session support.

Quoted 31 lines
Quoted 31 lines

-------------------------------------------------------------------------
-------

Service org.bluez
Interface org.bluez.HdpSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}

object Connect(remote_session_id)

Connects with the remote session and returns its object path.

Possible errors: org.bluez.Error.InvalidArguments

org.bluez.Error.HdpError

void Disconnect(object device, boolean delete)

Disconnect from the remote device. If delete is true, any status will also be deleted. Otherwise, the status will be keeped for allowing future reconnections.

Possible errors: org.bluez.Error.InvalidArguments

org.bluez.Error.NotFound org.bluez.Error.HdpError

-------------------------------------------------------------------------
-------

Quoted 8 lines
Quoted 4 lines

Service org.bluez
Interface org.bluez.HdpRemoteSession
Object path [variable
prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}/rem_session_id

IMHO "remote session" feels funny. "Device record" would sound better (it is a device, so it is implied to be remote; and a record, which implies a given SDP record).

Yes, "remove session" is not a good name, but as we said above, the session is more than a device and a record. This class represent a connection between two session (the local and the remote) not just a remote device + SDP record. Imagine that a source without a SDP connects to a sink. The sink will need perform operations over data channels (except connect and reconnect because the sink don't know the remote psm's). So may be id should depend on the SDP id.

Quoted 4 lines

Also, I think that the device path (appended by an unique identifier of the record) would be better. After all, that path already exists when device is around.

Using only the device path has a problem, the local session is not being taken in count. May be we could find a different representation of this, but we think that it should represent that this is a connection between two sessions, not between two devices or between a session and a device.

Quoted 3 lines

Perhaps you tried to accomodate the notion that a data channel ID "survives" even if the device disappearrs for a short moment?

Also this, remember that MCAP allow temporal disconnections to reestablish them in future connections to save state.

Quoted 8 lines
Quoted 7 lines

boolean Echo(array{byte})

Sends an echo petition to the remote session. Return True if response matches with the buffer sended. If some error is detected False value is returned and the associated MCL is closed.

Quoted 5 lines

Ok

Quoted 1 line

uint16 OpenDc(byte mdepid, byte config)

Could be OpenDataChannel?

Of course :). It's more clear

Quoted 7 lines
Quoted 7 lines

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.
Returns the data channel id.

Quoted 8 lines
Quoted 5 lines

Possible errors: org.bluez.Error.InvalidArguments

org.bluez.Error.HdpError

file_descriptor GetDcFd(uint16 mdlid)

This FD should be delivered via HdpAgent exclusively. I have counted three ways an application can receive an FD, IMHO there should be exactly one.

Yes, only one point sounds ok. Let's think about this. We think that first we should fixed the way the data will reach the l2cap socket from the application "crossing" dbus. We talked about fd-passing the l2cap socket but the pipe option may be also considered. Let's continue this in a different thread.

Quoted 5 lines
Quoted 5 lines

Gets a file descriptor where data can be readed or writed for receive or sent by the data channel. Returns the file descriptor

Quoted 8 lines
Quoted 6 lines

Possible errors: org.bluez.Error.InvalidArguments

org.bluez.Error.NotFound org.bluez.Error.HdpError

void DeleteDc(uint16 mdlid)

DeleteDataChannel

Ok

Quoted 6 lines
Quoted 6 lines

Deletes a data channel so it will not be available for use.

Possible errors: org.bluez.Error.InvalidArguments

Quoted 7 lines
Quoted 4 lines

org.bluez.Error.NotFound org.bluez.Error.HdpError

void DeleteAllDc()

Could be overloaded with DeleteDataChannel with MDL ID = 0, perhaps, but nothing incredibly important :)

MDLID 0 is reserved in mcap. Could be 0xffff value, that is reserved in mcap for the delete all petition. But we think that using this we are passing mcap logic to the upper layer.

Quoted 20 lines
Quoted 20 lines

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.HdpError

uint16 FirstRelDc()

Returns the identificator of the first reliable data channel (ERTM) connected for this device.

Possible errors: org.bluez.Error.HdpError

uint16 GetBestEfforDc()

Returns the id of a best effort (streamming) data channel if any.

Quoted 8 lines
Quoted 1 line

Possible errors: org.bluez.Error.NotFound

An use case would be good. In my vision, the application should just have one way to get the whole data connection list, and do whatever it wants, and not one new method for each type. We can e.g. guarantee that such list is in order, so the application can trust e.g. the first reliable channel on list to be what FirstRelDc() meant to return. (HDP mandates the first data channel to be reliable anyway.)

You are ok with this. Santiago sent 1 or 2 emails yesterday with proposals about this. We think that the best approach is (like you suggested) one pettion that returns a dictionary of arrays sorted as you mentioned:
{ "reliable": [id1, id2,...], "best_effort": [id3, id4, ...] }

In this case, the first reliable will be id1.

Quoted 11 lines
Quoted 9 lines

array getStatus()

Returns an array with all the data channels available

returned array:
[uint16, ...]

Possible errors: org.bluez.Error.NotFound

Available = connected, open (MDL ID has been created) or...?

Available means all data channels that the user can use to send data. Connected or not (the applicaction does not know this status with implicit reconnections) where it can send data. We think that this petition can be removed and changed by the described above.

Quoted 24 lines
Quoted 17 lines

HDPAgent hierarchy
==================

(this object is implemented by the HDP client an receives notifications)

Service         unique name
Interface       org.bluez.HdpAgent
Object path     freely definable

void DeviceConnected(object path)

This method is called whenever a new device connection has been established over the control channel of the current HDP session. The objectpath contains the object path of the remote device.

Quoted 6 lines

void DeviceDisconnected(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.

Quoted 5 lines

Perfect up to this part.

Quoted 1 line

void CreatedDc(object path, uint16 mdlid, filedescriptor fd)

Could be "DataChannelCreated"?

Ok

Quoted 10 lines
Quoted 8 lines

This method is called when a new data channel is created The path contains the object path of the device whith the new connection is created, the mdlid the data channel identificator and the fd is the file descriptor where the data can be readed or writed.

void DeletedDc(object path, uint16 mdlid)

DataChannelDeleted?

Ok

Quoted 7 lines
Quoted 7 lines

This method is called when a data channel is closed. After this call the data channel will not be valid and can be reused for future created data channels.

void DataReady(object path, uint16 mdlid, filedescriptor fd)

Quoted 7 lines
Quoted 2 lines

This method is called when there is new data that can be readed in a data channel

This one I don't understand. It seems to duplicate the function of CreatedDc, even the prototype is exactly the same. Has this something to have with reconnections? (Even so, CreatedDc could be overloaded with this.)

This is related with reconnections but from the other side. When the remote reconnects and send data. Nevertheless we should fix the way the data flows (as mentioned above) before discuss this API issues.

Quoted 8 lines
Quoted 6 lines

void RemoteSession(dict remote_session_properties)

This methos is called when a new session is discorevered in a remote device. See Hdp.GetRemotes to know how the dictionary is formed.

Same comment about the concept of remote session.--

Hope solved with the above comment.

Regards

#5 lore raw
Quoted 317 lines · El Friday 07 May 2010 12:03:23 José Antonio Santos Cadenas escribió:
Quoted 21 lines · El Friday 07 May 2010 01:49:10 escribió:

Hi,

Quoted 18 lines · José Antonio Santos Cadenas

Health Device Profile hierarchy
===============================

Service org.bluez
Interface org.bluez.Hdp
Object path [variable prefix]/{hci0,hci1,...}

Methods object CreateSession(object path, dict config)

Returns the object path for the new HDP session. The path parameter is the path of the remote object with the callbacks to nofity events (see org.bluez.HdpAgent at the end of this document) This petition starts an mcap session and also register in the SDP is needed
Dict is defined as bellow:
{ "data_spec" : The data_spec is the data exchange

Quoted 7 lines
Quoted 3 lines

specficication (see section 5.2.10 of the specification document), (optional)

Would be nice to include a "survival kit" about this 5.2.10, for completeness. Like (normally = 0x01 [IEEE xxxxx], 0x00 = reserved, 0x02 = other -- )

I think that you mean to document the possible values that can be used here. We think its a good Idea.

Quoted 6 lines
Quoted 4 lines
			  "end_points" : [{ (optional)
				
				"mdepid" : uint8, (optional)
				"role" : uint8, (mandatory)

We could use strings there, 'source' or 'sink'?

Good idea, its clearer for the user this way.

Quoted 6 lines
Quoted 3 lines
				"specs" :[{ (mandatory)
				
					"dtype" : uint16, (mandatory)

IMHO the key names may be more descriptive, like data_type. More about this below.

Ok with this too.

Quoted 8 lines

Another thing: as far as I understand, I may create a session, with well-defined MDEP IDs, roles etc. but then choose not to publish a SDP record. For example, I am an HDP source and want to have 5 MDEPs. An additional bool dict key like 'export' or 'publish' (not sure about correct BT nomenclature) would fit the bill.

"Forcing" a source to specify the MDEP IDs here, even if not publishing the record, makes checks easier further.

Not sure about that. Note that when you don't publish a SDP record, nobody could connect to you, so you won't receive data channel connections request, so you don't need to check if the mdeps are in use or not.

Quoted 57 lines
Quoted 11 lines

"description" : string, (optional)

}]

}]

}

if "data_spec" is not set, no SDP record will be registerd, so all the other data in the dictionary will be ignored

See comments above

Quoted 11 lines

Session will be closed by the call or implicitly when the programs leaves the bus.

Possible errors: org.bluez.Error.InvalidArguments

void DeleteSession(object path)

Delete the HDP session identified by the object path. Also session will be closed if the procces that started it is removed from the D-Bus.

Quoted 5 lines

Possible errors: org.bluez.Error.InvalidArguments

org.bluez.Error.NotFound

array remote_session_properties GetRemotesSessions()

typo

Quoted 24 lines
			Returns an array with the remote session_properties
			of all the visible devices.
			remote_session_properties is a dictionary like:
			[{"session_id": a_session_identification (int or string,
			
					 probably the SDP handler + btaddr)
			 
			 "data_spec" : the remote data spec,
			 
			 "end_points":
				 ["mdepid": uint8,
				 
				  "role"  : uint8,
				  "specs" : [{
				  
					  "dtype"	: uint16,
					  "description"	: string, (optional)
				  
				  }]
				 
				 ]
			
			}]
Quoted 8 lines
Quoted 2 lines

Note that only remotes with a SDP record will be notified by this function.

I don't get the concept of "remote sessions" of the current proposal. I understand the HDP session as a kind of "context" which holds the rest of HDP elements (published records, connections etc.)

Perhaps you meant "SDP records of HDP devices"?

Yes, but not only the record, also the session. This includes the mcl (mcap nomenclature) that can be connected to it and also all the data channel management.

Quoted 4 lines

If so, IMHO this method
should return just a list of device paths, which in turn would implement a BlueZ HDP interface that supplies further information (like my API proposal did).

It's not a bad idea for requesting information, but we think that the connect method should be complicated. Note that the connections are performed between sessions, not between devices. So when you call the connect method, you will need to pass all this atributes:

- Remote mdep_id
- Configuration
- Remote session_id
- Local session

Quoted 5 lines

I see some spread between org.bluez.Hdp and org.bluez.HdpSession. IMHO would be better to have just the context creation, as simple as possible, in org.bluez.Hdp and have everything else in org.bluez.HdpSession. (I still prefer the approach of "my" API, but I recognize that you are accomodating the notion of multiple records per [process, device] tuple.)

It could be a little bit estrange, but we think is necessary for the session support.

Quoted 30 lines
Quoted 30 lines

-----------------------------------------------------------------------
-- -------

Service org.bluez
Interface org.bluez.HdpSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}

object Connect(remote_session_id)

Connects with the remote session and returns its object path.

Possible errors: org.bluez.Error.InvalidArguments

org.bluez.Error.HdpError

void Disconnect(object device, boolean delete)

Disconnect from the remote device. If delete is true, any status will also be deleted. Otherwise, the status will be keeped for allowing future reconnections.

Possible errors: org.bluez.Error.InvalidArguments

org.bluez.Error.NotFound org.bluez.Error.HdpError

-----------------------------------------------------------------------
-- -------

Quoted 8 lines
Quoted 4 lines

Service org.bluez
Interface org.bluez.HdpRemoteSession
Object path [variable
prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}/rem_session_id

IMHO "remote session" feels funny. "Device record" would sound better (it is a device, so it is implied to be remote; and a record, which implies a given SDP record).

Yes, "remove session" is not a good name, but as we said above, the session is more than a device and a record. This class represent a connection between two session (the local and the remote) not just a remote device + SDP record. Imagine that a source without a SDP connects to a sink. The sink will need perform operations over data channels (except connect and reconnect because the sink don't know the remote psm's). So may be id should depend on the SDP id.

Quoted 3 lines

Also, I think that the device path (appended by an unique identifier of the record) would be better. After all, that path already exists when device is around.

Using only the device path has a problem, the local session is not being taken in count. May be we could find a different representation of this, but we think that it should represent that this is a connection between two sessions, not between two devices or between a session and a device.

Quoted 2 lines

Perhaps you tried to accomodate the notion that a data channel ID "survives" even if the device disappearrs for a short moment?

Also this, remember that MCAP allow temporal disconnections to reestablish them in future connections to save state.

Quoted 7 lines
Quoted 6 lines

boolean Echo(array{byte})

Sends an echo petition to the remote session. Return True if response matches with the buffer sended. If some error is detected False value is returned and the associated MCL is closed.

Quoted 5 lines

Ok

Quoted 1 line

uint16 OpenDc(byte mdepid, byte config)

Could be OpenDataChannel?

Of course :). It's more clear

Quoted 8 lines
Quoted 8 lines

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.
Returns the data channel id.

Possible errors: org.bluez.Error.InvalidArguments

Quoted 7 lines
Quoted 3 lines

org.bluez.Error.HdpError

file_descriptor GetDcFd(uint16 mdlid)

This FD should be delivered via HdpAgent exclusively. I have counted three ways an application can receive an FD, IMHO there should be exactly one.

Yes, only one point sounds ok. Let's think about this. We think that first we should fixed the way the data will reach the l2cap socket from the application "crossing" dbus. We talked about fd-passing the l2cap socket but the pipe option may be also considered. Let's continue this in a different thread.

Quoted 4 lines
Quoted 4 lines

Gets a file descriptor where data can be readed or writed for receive or sent by the data channel. Returns the file descriptor

Quoted 8 lines
Quoted 6 lines

Possible errors: org.bluez.Error.InvalidArguments

org.bluez.Error.NotFound org.bluez.Error.HdpError

void DeleteDc(uint16 mdlid)

DeleteDataChannel

Ok

Quoted 5 lines
Quoted 5 lines

Deletes a data channel so it will not be available for use.

Possible errors: org.bluez.Error.InvalidArguments

Quoted 7 lines
Quoted 4 lines

org.bluez.Error.NotFound org.bluez.Error.HdpError

void DeleteAllDc()

Could be overloaded with DeleteDataChannel with MDL ID = 0, perhaps, but nothing incredibly important :)

MDLID 0 is reserved in mcap. Could be 0xffff value, that is reserved in mcap for the delete all petition. But we think that using this we are passing mcap logic to the upper layer.

Quoted 19 lines
Quoted 19 lines

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.HdpError

uint16 FirstRelDc()

Returns the identificator of the first reliable data channel (ERTM) connected for this device.

Possible errors: org.bluez.Error.HdpError

uint16 GetBestEfforDc()

Returns the id of a best effort (streamming) data channel if any.

Quoted 8 lines
Quoted 1 line

Possible errors: org.bluez.Error.NotFound

An use case would be good. In my vision, the application should just have one way to get the whole data connection list, and do whatever it wants, and not one new method for each type. We can e.g. guarantee that such list is in order, so the application can trust e.g. the first reliable channel on list to be what FirstRelDc() meant to return. (HDP mandates the first data channel to be reliable anyway.)

Quoted 2 lines

You are ok with this. Santiago sent 1 or 2 emails yesterday with proposals about this.

I mean this messages:

http://www.spinics.net/lists/linux-bluetooth/msg05231.html
http://www.spinics.net/lists/linux-bluetooth/msg05244.html

Quoted 101 lines

We think that the best approach is (like you suggested) one pettion that returns a dictionary of arrays sorted as you mentioned:
{ "reliable": [id1, id2,...], "best_effort": [id3, id4, ...] }

In this case, the first reliable will be id1.

Quoted 10 lines
Quoted 8 lines

array getStatus()

Returns an array with all the data channels available

returned array:
[uint16, ...]

Possible errors: org.bluez.Error.NotFound

Available = connected, open (MDL ID has been created) or...?

Available means all data channels that the user can use to send data. Connected or not (the applicaction does not know this status with implicit reconnections) where it can send data. We think that this petition can be removed and changed by the described above.

Quoted 24 lines
Quoted 17 lines

HDPAgent hierarchy
==================

(this object is implemented by the HDP client an receives notifications)

Service         unique name
Interface       org.bluez.HdpAgent
Object path     freely definable

void DeviceConnected(object path)

This method is called whenever a new device connection has been established over the control channel of the current HDP session. The objectpath contains the object path of the remote device.

Quoted 6 lines

void DeviceDisconnected(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.

Quoted 5 lines

Perfect up to this part.

Quoted 1 line

void CreatedDc(object path, uint16 mdlid, filedescriptor fd)

Could be "DataChannelCreated"?

Ok

Quoted 9 lines
Quoted 7 lines

This method is called when a new data channel is created The path contains the object path of the device whith the new connection is created, the mdlid the data channel identificator and the fd is the file descriptor where the data can be readed or writed.

void DeletedDc(object path, uint16 mdlid)

DataChannelDeleted?

Ok

Quoted 6 lines
Quoted 6 lines

This method is called when a data channel is closed. After this call the data channel will not be valid and can be reused for future created data channels.

void DataReady(object path, uint16 mdlid, filedescriptor fd)

Quoted 7 lines
Quoted 2 lines

This method is called when there is new data that can be readed in a data channel

This one I don't understand. It seems to duplicate the function of CreatedDc, even the prototype is exactly the same. Has this something to have with reconnections? (Even so, CreatedDc could be overloaded with this.)

This is related with reconnections but from the other side. When the remote reconnects and send data. Nevertheless we should fix the way the data flows (as mentioned above) before discuss this API issues.

Quoted 7 lines
Quoted 5 lines

void RemoteSession(dict remote_session_properties)

This methos is called when a new session is discorevered in a remote device. See Hdp.GetRemotes to know how the dictionary is formed.

Same comment about the concept of remote session.--

Hope solved with the above comment.

Regards

--
To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html

#6 lore raw

I cleaned up the API with the changes suggested in the thread. There are still some parts that are being discussed.

BlueZ D-Bus HDP API description
***********************************

Authors:

Santiago Carot-Nemesio <[email protected]> José Antonio Santos-Cadenas <[email protected]> Elvis Pfützenreuter <[email protected]>

Health Device Profile hierarchy
===============================

Service org.bluez
Interface org.bluez.Hdp
Object path [variable prefix]/{hci0,hci1,...}

Methods object CreateSession(object path, dict config)

Returns the object path for the new HDP session. The path parameter is the path of the remote object with the callbacks to notify events (see org.bluez.HdpAgent at the end of this document) This petition starts an mcap session and also register in the SDP is needed
Dict is defined as bellow:
{ "data_spec" : The data_spec is the data exchange
specficication (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

Session will be closed by the call or implicitly when the programs leaves the bus.

Possible errors: org.bluez.Error.InvalidArguments

void DeleteSession(object path)

Delete the HDP session identified by the object path. Also session will be closed if the process that started it is removed from the D-Bus.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound

array remote_session_properties GetRemoteSessions()

Returns an array with the remote session_properties of all the visible devices. remote_session_properties is a dictionary like:
[{"session_id": a_session_identification (int or string,
probably the SDP handler + btaddr)
"data_spec" : the remote data spec, "end_points":
["mdepid": uint8,
"role" : uint8,
"specs" : [{
"dtype" : uint16,
"description" : string, (optional)
}]
]
}]

Note that only remotes with a SDP record will be notified by this function.

--------------------------------------------------------------------------------

Service org.bluez
Interface org.bluez.HdpSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}

object Connect(remote_session_id)

Connects with the remote session and returns its object path.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.HdpError

void Disconnect(object device, boolean delete)

Disconnect from the remote device. If delete is true, any status will also be deleted. Otherwise, the status will be kept for allowing future reconnections.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound org.bluez.Error.HdpError

--------------------------------------------------------------------------------

Service org.bluez
Interface org.bluez.HdpRemoteSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}/rem_session_id

boolean Echo(array{byte})

Sends an echo petition to the remote session. Return 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.
Returns the data channel id.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.HdpError

file_descriptor GetDcFd(uint16 mdlid)

Gets a file descriptor where data can be read or written for receive or sent by the data channel. Returns the file descriptor

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound org.bluez.Error.HdpError

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.HdpError

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.HdpError

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": [id1, ..., idz], "best_effort" : [idx, ..., idy]
}

The fist reliable data channel will always be the first data channel in reliable array.

HDPAgent hierarchy
==================

(this object is implemented by the HDP client an receives notifications)

Service         unique name
Interface       org.bluez.HdpAgent
Object path     freely definable

void DeviceConnected(object path)

This method is called whenever a new device connection has been established over the control channel of the current HDP session. The object path contains the object path of the remote device.

void DeviceDisconnected(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,
filedescriptor fd)

This method is called when a new data channel is created The path contains the object path of the device whith the new connection is created, the mdlid the data channel identificator and the fd is the file descriptor where the data can be readed or writed.

void DeletedDataChannel(object path, uint16 mdlid)

This method is called when a data channel is closed. After this call the data channel will not be valid and can be reused for future created data channels.

void DataReady(object path, uint16 mdlid, filedescriptor fd)

This method is called when there is new data that can be read in a data channel

void RemoteSession(dict remote_session_properties)

This method is called when a new session is discorevered in a remote device. See Hdp.GetRemotes to know how the dictionary is formed.

#7 lore raw
Quoted 58 lines · El Friday 07 May 2010 13:24:01 José Antonio Santos Cadenas escribió:

I cleaned up the API with the changes suggested in the thread. There are still some parts that are being discussed.

BlueZ D-Bus HDP API description
***********************************

Authors:

Santiago Carot-Nemesio <[email protected]> José Antonio Santos-Cadenas <[email protected]> Elvis Pfützenreuter <[email protected]>

Health Device Profile hierarchy
===============================

Service org.bluez
Interface org.bluez.Hdp
Object path [variable prefix]/{hci0,hci1,...}

Methods object CreateSession(object path, dict config)

Returns the object path for the new HDP session. The path parameter is the path of the remote object with the callbacks to notify events (see org.bluez.HdpAgent at the end of this document) This petition starts an mcap session and also register in the SDP is needed
Dict is defined as bellow:
{ "data_spec" : The data_spec is the data exchange
specficication (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

Session will be closed by the call or implicitly when the programs leaves the bus.

Possible errors: org.bluez.Error.InvalidArguments

void DeleteSession(object path)

Quoted 8 lines

Delete the HDP session identified by the object path. Also session will be closed if the process that started it is removed from the D-Bus.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound

array remote_session_properties GetRemoteSessions()

still being discussed

Quoted 65 lines

Returns an array with the remote session_properties of all the visible devices. remote_session_properties is a dictionary like:
[{"session_id": a_session_identification (int or string,
probably the SDP handler + btaddr)
"data_spec" : the remote data spec, "end_points":
["mdepid": uint8,
"role" : uint8,
"specs" : [{
"dtype" : uint16,
"description" : string, (optional)
}]
]
}]

Note that only remotes with a SDP record will be notified by this function.

--------------------------------------------------------------------------------

Service org.bluez
Interface org.bluez.HdpSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}

object Connect(remote_session_id)

Connects with the remote session and returns its object path.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.HdpError

void Disconnect(object device, boolean delete)

Disconnect from the remote device. If delete is true, any status will also be deleted. Otherwise, the status will be kept for allowing future reconnections.

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound org.bluez.Error.HdpError

--------------------------------------------------------------------------------

Service org.bluez
Interface org.bluez.HdpRemoteSession
Object path [variable prefix]/{hci0,hci1,...}/{hdp0,hdp1,...}/rem_session_id

boolean Echo(array{byte})

Sends an echo petition to the remote session. Return 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.
Returns the data channel id.

Quoted 4 lines

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.HdpError

file_descriptor GetDcFd(uint16 mdlid)

Wait till transport/fd-passing discussion is solved

Quoted 11 lines

Gets a file descriptor where data can be read or written for receive or sent by the data channel. Returns the file descriptor

Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.NotFound org.bluez.Error.HdpError

void DeleteDataChannel(uint16 mdlid)

Quoted 8 lines

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.HdpError

void DeleteAllDataChannels()

still in discussion

Quoted 53 lines

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.HdpError

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": [id1, ..., idz], "best_effort" : [idx, ..., idy]
}

The fist reliable data channel will always be the first data channel in reliable array.

HDPAgent hierarchy
==================

(this object is implemented by the HDP client an receives notifications)

Service         unique name
Interface       org.bluez.HdpAgent
Object path     freely definable

void DeviceConnected(object path)

This method is called whenever a new device connection has been established over the control channel of the current HDP session. The object path contains the object path of the remote device.

void DeviceDisconnected(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,
filedescriptor fd)

This method is called when a new data channel is created The path contains the object path of the device whith the new connection is created, the mdlid the data channel identificator and the fd is the file descriptor where the data can be readed or writed.

Quoted 7 lines

void DeletedDataChannel(object path, uint16 mdlid)

This method is called when a data channel is closed. After this call the data channel will not be valid and can be reused for future created data channels.

void DataReady(object path, uint16 mdlid, filedescriptor fd)

probably it will disappear, depends on transport/fd-passing discussion

Quoted 14 lines

This method is called when there is new data that can be read in a data channel

void RemoteSession(dict remote_session_properties)

This method is called when a new session is discorevered in a remote device. See Hdp.GetRemotes to know how the dictionary is formed.
--
To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html

#8 lore raw
In reply to José Antonio Santos Cadenas
Quoted 2 lines · José Antonio Santos Cadenas

I cleaned up the API with the changes suggested in the thread. There are still some parts that are being discussed.

It felt a whole lot better for me now, and HdpRemoteSession has been clarified in last e-mail, so now the pieces fit together. The remaining discussion points (forcing early list of MDEP IDs, remote session path etc.) have been mentioned at other e-mails.

#9 lore raw
In reply to José Antonio Santos Cadenas
Quoted 6 lines
Quoted 2 lines

"Forcing" a source to specify the MDEP IDs here, even if not publishing the record, makes checks easier further.

Not sure about that. Note that when you don't publish a SDP record, nobody could connect to you, so you won't receive data channel connections request, so you don't need to check if the mdeps are in use or not.

Indeed, you are right; from spec point of view I am not forced to define MDEP IDs beforehand (my old habits of TCP/IP, having ports both sides, sometimes overwhelm me :)

The actual argument is higher level: whether should we *force* the application to specify the MDEP IDs / data types beforehand (as I "voted", with "my" API) or not (as you "voted").

This is the point we need more opinions, from people in the list :)

Quoted 5 lines
Quoted 2 lines

Perhaps you tried to accomodate the notion that a data channel ID "survives" even if the device disappearrs for a short moment?

Also this, remember that MCAP allow temporal disconnections to reestablish them in future connections to save state.

Ok, I need to see whether BlueZ keeps the device objects in D-BUS tree after disconnection of if it removees it immediately. If it keeps the object, the sessions should be there as sub-paths (to be consistent with HdpSession being a part of adapter path.). If it doesn't, indeed they need to go somewhere else.

#10 lore raw
Quoted 14 lines · Elvis Pfützenreuter
Quoted 6 lines
Quoted 2 lines

"Forcing" a source to specify the MDEP IDs here, even if not publishing the record, makes checks easier further.

Not sure about that. Note that when you don't publish a SDP record, nobody could connect to you, so you won't receive data channel connections request, so you don't need to check if the mdeps are in use or not.

Indeed, you are right; from spec point of view I am not forced to define MDEP IDs beforehand (my old habits of TCP/IP, having ports both sides, sometimes overwhelm me :)

The actual argument is higher level: whether should we *force* the application to specify the MDEP IDs / data types beforehand (as I "voted", with "my" API) or not (as you "voted").

This is the point we need more opinions, from people in the list :)

Quoted 7 lines
Quoted 5 lines
Quoted 2 lines

Perhaps you tried to accomodate the notion that a data channel ID "survives" even if the device disappearrs for a short moment?

Also this, remember that MCAP allow temporal disconnections to reestablish them in future connections to save state.

Ok, I need to see whether BlueZ keeps the device objects in D-BUS tree after disconnection of if it removees it immediately. If it keeps the object, the sessions should be there as sub-paths (to be consistent with HdpSession being a part of adapter path.). If it doesn't, indeed they need to go somewhere else.

Device objects exists for each paired device. If the pairing is removed the object is also removed and a new pairing is needed before connecting to it (as imposed by the whole bluetooth stack logic anyway).

Re-using the device path and adding sessions as sub-paths seems reasonable, but I would wait on comments from Johan / Luiz / Marcel if this is desirable or might have any side-implication before defining this topic as closed.

Signature · 2 lines
João Paulo Rechi Vita
http://jprvita.wordpress.com/
#11 lore raw
Quoted 5 lines

Device objects exists for each paired device. If the pairing is removed the object is also removed and a new pairing is needed before connecting to it (as imposed by the whole bluetooth stack logic anyway).

AFAIK the HDP source and sink must be paired before any session can be established, so the relevant device objects will always be there, so the path can be (re)used.

Quoted 4 lines

Re-using the device path and adding sessions as sub-paths seems reasonable, but I would wait on comments from Johan / Luiz / Marcel if this is desirable or might have any side-implication before defining this topic as closed.

#12 lore raw

Hi,

Quoted 7 lines · Elvis Pfützenreuter
Quoted 5 lines

Device objects exists for each paired device. If the pairing is removed the object is also removed and a new pairing is needed before connecting to it (as imposed by the whole bluetooth stack logic anyway).

AFAIK the HDP source and sink must be paired before any session can be established, so the relevant device objects will always be there, so the path can be (re)used.

Exactly, I tried to explain this before that device objects is a better way to expose any relevant API since that would be created anyway. It also has integration with the sdp record cache and are reloaded during the initialization and I hardly see us doing anything to revert this, since pretty much every plugin depend on this to work.

So, with this in mind, IMHO, the whole concept of exposure the sessions won't fit nicely in BlueZ API, first because it uses the adapter path to create session passing a device path, which btw already is associated with adapter anyway, second because any client seems to be able to create those sessions even if they are unable to control them because they don't hold an agent, and third I don't think we should be exposing protocol internals in a D-Bus API, this id's make as much sense as the bdaddr in the ui (read _none_), it is as usable as we starting exposing local and remote seid (Stream Endpoint id, surprisingly similar to endpoint here) to pulseaudio to carry on with all avdtp protocol details, this will only fragment the logic around those bits and certainly won't make it work better.

Signature · 2 lines
Luiz Augusto von Dentz
Computer Engineer
#13 lore raw

Hi all,

Quoted 3 lines · El Sunday 09 May 2010 17:14:39 Luiz Augusto von Dentz escribió:

Hi,

On Sat, May 8, 2010 at 12:08 AM, Elvis Pfützenreuter <[email protected]>

Quoted 9 lines · wrote:
Quoted 8 lines
Quoted 4 lines

Device objects exists for each paired device. If the pairing is removed the object is also removed and a new pairing is needed before connecting to it (as imposed by the whole bluetooth stack logic anyway).

AFAIK the HDP source and sink must be paired before any session can be established, so the relevant device objects will always be there, so the path can be (re)used.

Quoted 5 lines

Exactly, I tried to explain this before that device objects is a better way to expose any relevant API since that would be created anyway. It also has integration with the sdp record cache and are reloaded during the initialization and I hardly see us doing anything to revert this, since pretty much every plugin depend on this to work.

We agree that the best way to expose a remote device is using the path already created by bluez. We are thinking, as Elvis suggested, in changing some functions to that path for discovering remove services.

The main problem here is that sessions exist in HDP even if bluez is not concerned about them. Imagine that we perform an implementation without session management, this not implies that other implementations do the same so a remote device could expose multiple HDP session (each one of them could expose a SDP record). Now if you are not concern of the sessions and you try to connect to a remote device that holds more than one session, you can't decide which one of that sessions connect. A simple example of this situation is described in the HDP implementation whitepaper (page 18, figure 2.4).

Quoted 5 lines

So, with this in mind, IMHO, the whole concept of exposure the sessions won't fit nicely in BlueZ API, first because it uses the adapter path to create session passing a device path, which btw already is associated with adapter anyway,

We think that the main problem here is that we don't choose a good path name. But we are open to suggestion for a better one.

Quoted 3 lines

second because any client
seems to be able to create those sessions even if they are unable to control them because they don't hold an agent,

We think that this is not a good reason, the same could happend with other profiles. Any client could connect to an Audio or Serial device even if they are unable to use them or the don't know how to do it.

Quoted 2 lines

and third I don't think
we should be exposing protocol internals in a D-Bus API,

We don't understand this. What do you mean with protocol internal? Nothing exposed in D-Bus in internal we just propose to concert the client about the remote session (remote hdp instance) because it need to decide with one to connect, as it decides the device that it will connect with a Serial connection. Probably we need a better name than "session id".

Quoted 6 lines

this id's
make as much sense as the bdaddr in the ui (read _none_), it is as usable as we starting exposing local and remote seid (Stream Endpoint id, surprisingly similar to endpoint here) to pulseaudio to carry on with all avdtp protocol details, this will only fragment the logic around those bits and certainly won't make it work better.

Ok, we shouldn't expose mdepid. But we still need to expose the remote hdp session or instances. Note that in Audio profile the psm is fixed, so there is just one listening on each device, but HDP is different because the psm are not fixed and multiple instances can exist in the same device.

#14 lore raw
Quoted 69 lines · El Monday 10 May 2010 10:42:50 José Antonio Santos Cadenas escribió:

Hi all,

Quoted 3 lines · El Sunday 09 May 2010 17:14:39 Luiz Augusto von Dentz escribió:

Hi,

On Sat, May 8, 2010 at 12:08 AM, Elvis Pfützenreuter <[email protected]>

Quoted 9 lines · wrote:
Quoted 8 lines
Quoted 4 lines

Device objects exists for each paired device. If the pairing is removed the object is also removed and a new pairing is needed before connecting to it (as imposed by the whole bluetooth stack logic anyway).

AFAIK the HDP source and sink must be paired before any session can be established, so the relevant device objects will always be there, so the path can be (re)used.

Quoted 5 lines

Exactly, I tried to explain this before that device objects is a better way to expose any relevant API since that would be created anyway. It also has integration with the sdp record cache and are reloaded during the initialization and I hardly see us doing anything to revert this, since pretty much every plugin depend on this to work.

We agree that the best way to expose a remote device is using the path already created by bluez. We are thinking, as Elvis suggested, in changing some functions to that path for discovering remove services.

The main problem here is that sessions exist in HDP even if bluez is not concerned about them. Imagine that we perform an implementation without session management, this not implies that other implementations do the same so a remote device could expose multiple HDP session (each one of them could expose a SDP record). Now if you are not concern of the sessions and you try to connect to a remote device that holds more than one session, you can't decide which one of that sessions connect. A simple example of this situation is described in the HDP implementation whitepaper (page 18, figure 2.4).

Quoted 4 lines

So, with this in mind, IMHO, the whole concept of exposure the sessions won't fit nicely in BlueZ API, first because it uses the adapter path to create session passing a device path, which btw already is associated with adapter anyway,

We think that the main problem here is that we don't choose a good path name. But we are open to suggestion for a better one.

Quoted 3 lines

second because any client
seems to be able to create those sessions even if they are unable to control them because they don't hold an agent,

We think that this is not a good reason, the same could happend with other profiles. Any client could connect to an Audio or Serial device even if they are unable to use them or the don't know how to do it.

Quoted 2 lines

and third I don't think
we should be exposing protocol internals in a D-Bus API,

We don't understand this. What do you mean with protocol internal? Nothing exposed in D-Bus in internal we just propose to concert the client about the remote session (remote hdp instance) because it need to decide with one to connect, as it decides the device that it will connect with a Serial connection. Probably we need a better name than "session id".

Quoted 6 lines

this id's
make as much sense as the bdaddr in the ui (read _none_), it is as usable as we starting exposing local and remote seid (Stream Endpoint id, surprisingly similar to endpoint here) to pulseaudio to carry on with all avdtp protocol details, this will only fragment the logic around those bits and certainly won't make it work better.

Quoted 2 lines

Ok, we shouldn't expose mdepid. But we still need to expose the remote hdp session or instances.

Sorry, I was wrong with this. I think that we need a way to identify the end point (or feature or something) that will be connected in the remote hdp session. Because the application should be able to select where to connect.

Quoted 5 lines

Note that in Audio profile the psm is fixed, so there
is just one listening on each device, but HDP is different because the psm are not fixed and multiple instances can exist in the same device.

Regards