HDP proposed api (ver 0.2)

HDP proposed api (ver 0.2)

[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

			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.

Re: HDP proposed api (ver 0.2)

[Santiago Carot-Nemesio]

Hi,

El mié, 05-05-2010 a las 12:55 +0200, José Antonio Santos Cadenas
escribió:
> 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

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?

> 
> 		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 majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: HDP proposed api (ver 0.2)

[Santiago Carot-Nemesio]

El jue, 06-05-2010 a las 09:08 +0200, Santiago Carot-Nemesio escribió:
> Hi,
> 
> El mié, 05-05-2010 a las 12:55 +0200, José Antonio Santos Cadenas
> escribió:
> > 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
> 
> 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?
> 
> > 
> > 		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?

> > 
> > 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 majordomo@vger.kernel.org
> > 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 majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: HDP proposed api (ver 0.2)

[Elvis Pfützenreuter]

Hi, 

On 05/05/2010, at 07:55, José Antonio Santos Cadenas wrote:

> 
> 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)

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

> 			  "end_points" : [{ (optional)
> 				"mdepid" : uint8, (optional)
> 				"role" : uint8, (mandatory)

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

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

> 					"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

> 
> 			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()

typo

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

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

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

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? 

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

> 
> 		uint16 OpenDc(byte mdepid, byte config)

Could be OpenDataChannel?

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

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

> 
> 			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 :)

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

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

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

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

Perfect up to this part.

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

Could be "DataChannelCreated"?

> 
> 			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?

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

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

Re: HDP proposed api (ver 0.2)

[José Antonio Santos Cadenas]

El Friday 07 May 2010 01:49:10 escribió:
> Hi,
> 
> On 05/05/2010, at 07:55, José Antonio Santos Cadenas wrote:
> > 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)
> 
> 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.

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

> 
> > 				"specs" :[{ (mandatory)
> > 				
> > 					"dtype" : uint16, (mandatory)
> 
> IMHO the key names may be more descriptive, like data_type. More about this
> below.

Ok with this too.

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

> 
> > 					"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
> 
> > 			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()
> 
> typo
> 
> > 			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.
> 
> 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.

> 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


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

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

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

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

> 
> > 		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
> 
> > 		uint16 OpenDc(byte mdepid, byte config)
> 
> Could be OpenDataChannel?

Of course :). It's more clear

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

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.

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

Ok

> 
> > 			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 :)

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.

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

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

> 
> > 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.
> 
> Perfect up to this part.
> 
> > 		void CreatedDc(object path, uint16 mdlid, filedescriptor fd)
> 
> Could be "DataChannelCreated"?

Ok

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

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

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

Re: HDP proposed api (ver 0.2)

[José Antonio Santos Cadenas]

El Friday 07 May 2010 12:03:23 José Antonio Santos Cadenas escribió:
> El Friday 07 May 2010 01:49:10 escribió:
> > Hi,
> > 
> > On 05/05/2010, at 07:55, José Antonio Santos Cadenas wrote:
> > > 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)
> > 
> > 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.
> 
> > > 			  "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.
> 
> > > 				"specs" :[{ (mandatory)
> > > 				
> > > 					"dtype" : uint16, (mandatory)
> > 
> > IMHO the key names may be more descriptive, like data_type. More about
> > this below.
> 
> Ok with this too.
> 
> > 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.
> 
> > > 					"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
> > 
> > > 			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()
> > 
> > typo
> > 
> > > 			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.
> > 
> > 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.
> 
> > 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
> 
> > 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.
> 
> > > -----------------------------------------------------------------------
> > > -- -------
> > > 
> > > 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
> > 
> > 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.
> 
> > 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.
> 
> > 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.
> 
> > > 		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
> > 
> > > 		uint16 OpenDc(byte mdepid, byte config)
> > 
> > Could be OpenDataChannel?
> 
> Of course :). It's more clear
> 
> > > 			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.
> 
> 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.
> 
> > > 			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
> 
> Ok
> 
> > > 			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 :)
> 
> 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.
> 
> > > 			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
> > 
> > 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. 

I mean this messages:

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

> 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.
> 
> > > 		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.
> 
> > > 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.
> > 
> > Perfect up to this part.
> > 
> > > 		void CreatedDc(object path, uint16 mdlid, filedescriptor fd)
> > 
> > Could be "DataChannelCreated"?
> 
> Ok
> 
> > > 			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
> 
> > > 			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.)
> 
> 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.
> 
> > > 		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 majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: HDP proposed api (ver 0.2)

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


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

Authors:

	Santiago Carot-Nemesio <sancane@gmail.com>
	José Antonio Santos-Cadenas <santoscadenas@gmail.com>
	Elvis Pfützenreuter <epx@signove.com>

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.

Re: HDP proposed api (ver 0.2)

[José Antonio Santos Cadenas]

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 <sancane@gmail.com>
> 	José Antonio Santos-Cadenas <santoscadenas@gmail.com>
> 	Elvis Pfützenreuter <epx@signove.com>
> 
> 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()

still being discussed

> 
> 			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)

Wait till transport/fd-passing discussion is solved

> 
> 			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()
still in discussion

> 
> 			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)

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

> 
> 			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 majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: HDP proposed api (ver 0.2)

[Elvis Pfützenreuter]

>> "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 :)


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

Re: HDP proposed api (ver 0.2)

[Elvis Pfützenreuter]

On 07/05/2010, at 08:24, José Antonio Santos Cadenas wrote:

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

Re: HDP proposed api (ver 0.2)

[João Paulo Rechi Vita]

On Fri, May 7, 2010 at 10:46, Elvis Pfützenreuter <epx@signove.com> wrote:
>>> "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 :)
>
>
>>> 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.

-- 
João Paulo Rechi Vita
http://jprvita.wordpress.com/

Re: HDP proposed api (ver 0.2)

[Elvis Pfützenreuter]

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

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

Re: HDP proposed api (ver 0.2)

[Luiz Augusto von Dentz]

Hi,

On Sat, May 8, 2010 at 12:08 AM, Elvis Pfützenreuter <epx@signove.com> wrote:
>>
>> 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.

-- 
Luiz Augusto von Dentz
Computer Engineer

Re: HDP proposed api (ver 0.2)

[José Antonio Santos Cadenas]

Hi all,

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 <epx@signove.com> 
wrote:
> >> 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.

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

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

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

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

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

Re: HDP proposed api (ver 0.2)

[José Antonio Santos Cadenas]

El Monday 10 May 2010 10:42:50 José Antonio Santos Cadenas escribió:
> Hi all,
> 
> 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 <epx@signove.com>
> 
> wrote:
> > >> 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.
> 
> 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).
> 
> > 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.
> 
> > 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.
> 
> > 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".
> 
> > 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.

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.

> 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