Return-Path: From: =?iso-8859-1?q?Jos=E9_Antonio_Santos_Cadenas?= Reply-To: jcaden@libresoft.es To: Elvis =?iso-8859-1?q?Pf=FCtzenreuter?= Subject: Re: HDP proposed api (ver 0.2) Date: Fri, 7 May 2010 12:03:23 +0200 References: <201005051255.09394.jcaden@libresoft.es> <3CCD92AC-1578-4E78-AEE8-80AEE73511EB@signove.com> In-Reply-To: <3CCD92AC-1578-4E78-AEE8-80AEE73511EB@signove.com> Cc: linux-bluetooth@vger.kernel.org MIME-Version: 1.0 Content-Type: Text/Plain; charset="iso-8859-1" Message-Id: <201005071203.23882.jcaden@libresoft.es> Sender: linux-bluetooth-owner@vger.kernel.org List-ID: 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