Sim Access Profile API doc
RFC 1/1 Sim Access Profile API doc
This RFC proposes the interface exposed by
Sim Access Profile Server role.
Please let me know your comments.
--- doc/sap-api.txt | 197 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 197 insertions(+), 0 deletions(-) create mode 100644 doc/sap-api.txt
doc/sap-api.txt new file +197 -0
@@ -0,0 +1,197 @@ +BlueZ D-Bus Adapter API description +*********************************** + +Copyright (C) 2009-2010 Atheros Communication Ltd + + +Sim Access Server hierarchy +=========================== + +Service org.bluez +Interface org.bluez.SimAccessServer +Object path [variable prefix]/{hci0,hci1,...} + +This interface is available for devices which can function in the +Server role of the Sim Access profiles. +It is intended to be used with external stacks / handlers of the Sim Access +protocol. + + +Methods void RegisterAgent(object agent) + + This registers the Sim Access adapter agent. + This also registers the profile with the service + Databse and start waiting for an RFCOMM connection + on the SAP server channel. + + The object path defines the path the of the agent. + + If an application disconnects from the bus all + of its registered agents will be removed. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.AlreadyExists + org.bluez.Error.Failed + + void UnregisterAgent(object agent) + + This unregisters the agent that has been previously + registered. The object path parameter must match the + same value that has been used on registration. + + Possible errors: org.bluez.Error.DoesNotExist + org.bluez.Error.InvalidArguments + org.bluez.Error.Failed + + void Response(string command, string result, object response) + + This sends a response to a received SAP command. + + The command parameter specifies the SAP command for + which response has to be sent. + + The result parameter specifies the ResultCode for the + operation. + + The object response specifies the response packet to + be sent if any. + + Below mentioned are the parameters and possible value. + + command result response + ---------------------------------------------------- + + Connect OkSuccess NA + ConnectFailed + OkOngoingCall + + APDU OkSuccess array{uint8} + NoReason + CardNotAccessible + CardPoweredOff + CardRemoved + + APDU7816 OkSuccess array{uint8} + NoReason + CardNotAccessible + CardPoweredOff + CardRemoved + + ATR OkSuccess array{uint8} + NoReason + CardPoweredOff + CardRemoved + DataNotAvailable + + SimPowerOn OkSuccess NA + NoReason + CardNotAccessible + CardRemoved + CardPoweredOn + + SimPowerOff OkSuccess NA + NoReason + CardPoweredOff + CardRemoved + + Reset OkSuccess NA + NoReason + CardNotAccessible + CardPoweredOff + CardRemoved + + CardReaderStatus OkSuccess uint8 + NoReason + DataNotAvailable + + TransportProtocol OkSuccess NA + NotSupported + + Disconnect NA NA + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.Failed + + void Disconnect(string type) + + This initiates a SAP disconnection from SAP server. + + The type parameter specifies the type of disconnection. + + "Graceful" -> lets the SAP client initiate a + garceful disconnection. + + "Immediate" -> disconnects the connection + immediately from the server. + + void SetProperty(string name, variant value) + + Changes the value of the specified property. Only + properties that are listed a read-write are changeable. + On success this will emit a PropertyChanged signal. + + Possible Errors: org.bluez.Error.DoesNotExist + org.bluez.Error.InvalidArguments + + dict GetProperties() + + Returns all properties for the interface. See the + properties section for available properties. + + Possible Errors: org.bluez.Error.InvalidArguments + +Signals Request(string command, variant value) + + This signal indicates a SAP command received from + SAP client. + + The command parameter specifies the SAP command + received. + + The value parameter specifies the command parameter + packet received from SAP client. + + Below mentioned is the parameters and possible value. + + command value + ---------------------------------------------------- + + Connect NA + APDU Aarray{uint8} + APDU7816 Aarray{uint8} + ATR NA + SimPowerOn NA + SimPowerOff NA + Reset NA + CardReaderStatus NA + TransportProtocol uint8 + Disconnect NA + + PropertyChanged(string name, variant value) + + This signal indicates a changed value of the given + property. + +Properties string SimStatus [readwrite] + + Specifies the availability of the SIM. + + The possible value are + + "UnknownError" + "CardReset" + "CardNotAccesible" + "CardRemoved" + "CardInsterted" + "CardRecovered" + + uint16 MaxMessageSize [readwrite] + + The maximum possible message size supported by + SAP server. + + uint16 MessageSize [readonly] + + The negotiated message size for the current connection. + This is valid only when there is an active + SAP connection.
Signature · 1 line
1.7.0.4
Hello Suraj,
I don't know much about sim or bluetooth in general, so only a few minor comments below.
Quoted 16 lines · Suraj Sumangala
This RFC proposes the interface exposed by
Sim Access Profile Server role.Please let me know your comments.
--- doc/sap-api.txt | 197 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 197 insertions(+), 0 deletions(-) create mode 100644 doc/sap-api.txtdoc/sap-api.txt new file +0
-0
doc/sap-api.txt line 1
Quoted 1 line
doc/sap-api.txt new file +1
-0@@ -0,0 +1,197 @@ +BlueZ D-Bus Adapter API description
this is a copy&paste leftover?
Quoted 13 lines
doc/sap-api.txt new file +13
-0+*********************************** + +Copyright (C) 2009-2010 Atheros Communication Ltd + + +Sim Access Server hierarchy +=========================== + +Service org.bluez +Interface org.bluez.SimAccessServer +Object path [variable prefix]/{hci0,hci1,...} + +This interface is available for devices which can function in the
doc/sap-api.txt line 24
Quoted 10 lines
doc/sap-api.txt new file +10
-0+Server role of the Sim Access profiles. +It is intended to be used with external stacks / handlers of the Sim Access +protocol. + + +Methods void RegisterAgent(object agent) + + This registers the Sim Access adapter agent. + This also registers the profile with the service + Databse and start waiting for an RFCOMM connection
s/Databse/database/ (not sure about capitalization)
Quoted 163 lines
doc/sap-api.txt new file +163
-0+ on the SAP server channel. + + The object path defines the path the of the agent. + + If an application disconnects from the bus all + of its registered agents will be removed. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.AlreadyExists + org.bluez.Error.Failed + + void UnregisterAgent(object agent) + + This unregisters the agent that has been previously + registered. The object path parameter must match the + same value that has been used on registration. + + Possible errors: org.bluez.Error.DoesNotExist + org.bluez.Error.InvalidArguments + org.bluez.Error.Failed + + void Response(string command, string result, object response) + + This sends a response to a received SAP command. + + The command parameter specifies the SAP command for + which response has to be sent. + + The result parameter specifies the ResultCode for the + operation. + + The object response specifies the response packet to + be sent if any. + + Below mentioned are the parameters and possible value. + + command result response + ---------------------------------------------------- + + Connect OkSuccess NA + ConnectFailed + OkOngoingCall + + APDU OkSuccess array{uint8} + NoReason + CardNotAccessible + CardPoweredOff + CardRemoved + + APDU7816 OkSuccess array{uint8} + NoReason + CardNotAccessible + CardPoweredOff + CardRemoved + + ATR OkSuccess array{uint8} + NoReason + CardPoweredOff + CardRemoved + DataNotAvailable + + SimPowerOn OkSuccess NA + NoReason + CardNotAccessible + CardRemoved + CardPoweredOn + + SimPowerOff OkSuccess NA + NoReason + CardPoweredOff + CardRemoved + + Reset OkSuccess NA + NoReason + CardNotAccessible + CardPoweredOff + CardRemoved + + CardReaderStatus OkSuccess uint8 + NoReason + DataNotAvailable + + TransportProtocol OkSuccess NA + NotSupported + + Disconnect NA NA + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.Failed + + void Disconnect(string type) + + This initiates a SAP disconnection from SAP server. + + The type parameter specifies the type of disconnection. + + "Graceful" -> lets the SAP client initiate a + garceful disconnection. + + "Immediate" -> disconnects the connection + immediately from the server. + + void SetProperty(string name, variant value) + + Changes the value of the specified property. Only + properties that are listed a read-write are changeable. + On success this will emit a PropertyChanged signal. + + Possible Errors: org.bluez.Error.DoesNotExist + org.bluez.Error.InvalidArguments + + dict GetProperties() + + Returns all properties for the interface. See the + properties section for available properties. + + Possible Errors: org.bluez.Error.InvalidArguments + +Signals Request(string command, variant value) + + This signal indicates a SAP command received from + SAP client. + + The command parameter specifies the SAP command + received. + + The value parameter specifies the command parameter + packet received from SAP client. + + Below mentioned is the parameters and possible value. + + command value + ---------------------------------------------------- + + Connect NA + APDU Aarray{uint8} + APDU7816 Aarray{uint8} + ATR NA + SimPowerOn NA + SimPowerOff NA + Reset NA + CardReaderStatus NA + TransportProtocol uint8 + Disconnect NA + + PropertyChanged(string name, variant value) + + This signal indicates a changed value of the given + property. + +Properties string SimStatus [readwrite] + + Specifies the availability of the SIM. + + The possible value are + + "UnknownError" + "CardReset" + "CardNotAccesible" + "CardRemoved" + "CardInsterted" + "CardRecovered" +
doc/sap-api.txt line 197
Quoted 10 lines
doc/sap-api.txt new file +10
-0+ uint16 MaxMessageSize [readwrite] + + The maximum possible message size supported by + SAP server. + + uint16 MessageSize [readonly] + + The negotiated message size for the current connection. + This is valid only when there is an active + SAP connection.
and you might want to add your file to EXTRA_DIST in Makefile.am.
Best regards
Uwe
Signature · 2 lines
Pengutronix e.K. | Uwe Kleine-König | Industrial Linux Solutions | http://www.pengutronix.de/ |
Hi Suraj,
Quoted 11 lines
From: Suraj Sumangala [mailto:[email protected]]
Sent: Tuesday, September 07, 2010 8:03 AMdoc/sap-api.txt new file +4
-0+ + void Disconnect(string type) + + This initiates a SAP disconnection fromSAP server.
(quoted diff) +2
-0+ + The type parameter specifies the typeof disconnection.
doc/sap-api.txt line 126
Quoted 7 lines
doc/sap-api.txt new file +7
-0+ + "Graceful" -> lets the SAP client initiate a + garceful disconnection. + + "Immediate" -> disconnects the connection + immediately from the server. +
In my view, the disconnection should be initiates by the sap server, not by the agent. In a typical use case the agent will communicate sim state change (card removed or not accessible) to sap server. Based on that, the sap server should make a decision whether disconnect or not. What's more the disconnect procedure is defined in the SAP spec, and would be nice to keep all those procedures in the sap server, not in the agent which will be specific for a sim provider. Therefore, I would remove this method call from the api. I would add the Disconnect signal instead.
Signal:Disconnect()
This signal will be send when SAP connectionis successfully removed.
In case of graceful disconnection sap server sends signal to the agent REQUEST(disconnect) and wait till SIM free its stuff and send back RESPONSE(disconnect). In case of immediate disconnection sap server will send Disconnect() signal to the agent.
Thanks,
/Waldek
Hi Waldek,
Quoted 23 lines · On 9/7/2010 2:06 PM, [email protected] wrote:
Hi Suraj,
Quoted 11 lines
From: Suraj Sumangala [mailto:[email protected]]
Sent: Tuesday, September 07, 2010 8:03 AMdoc/sap-api.txt new file +4
-0+ + void Disconnect(string type) + + This initiates a SAP disconnection fromSAP server.
(quoted diff) +2
-0+ + The type parameter specifies the typeof disconnection.
doc/sap-api.txt line 126
Quoted 7 lines
doc/sap-api.txt new file +7
-0+ + "Graceful" -> lets the SAP client initiate a + garceful disconnection. + + "Immediate" -> disconnects the connection + immediately from the server. +In my view, the disconnection should be initiates by the sap server, not by the agent. In a typical use case the agent will communicate sim state change (card removed or not accessible) to sap server. Based on that, the sap server should make a decision whether disconnect or not. What's more the disconnect procedure is defined in the SAP spec, and would be nice to keep all those procedures in the sap server, not in the agent which will be specific for a sim provider. Therefore, I would remove this method call from the api. I would add the Disconnect signal instead.
Quoted 5 lines
Signal:
Disconnect()
This signal will be send when SAP connectionis successfully removed.In case of graceful disconnection sap server sends signal to the agent REQUEST(disconnect) and wait till SIM free its stuff and send back RESPONSE(disconnect). In case of immediate disconnection sap server will send
Disconnect()signal to the agent.
Ok, In which all situations should the SAP server decide that the SAP connection has to be disconnected (you have mentioned Sim Status change as one candidate)?
Also, based on what should the server decide to initiate a "Graceful" or "Immediate" disconnection?
Quoted 3 lines
Thanks,
/Waldek
Regards
Suraj
Hi Suraj,
Quoted 50 lines
-----Original Message-----
From: Suraj Sumangala [mailto:[email protected]]
Sent: Tuesday, September 07, 2010 11:28 AMHi Waldek,
Quoted 14 lines · On 9/7/2010 2:06 PM, [email protected] wrote:
Hi Suraj,
Quoted 12 lines
From: Suraj Sumangala [mailto:[email protected]]
Sent: Tuesday, September 07, 2010 8:03 AMdoc/sap-api.txt new file +4
-0+ + void Disconnect(string type) + + This initiates a SAP disconnection fromSAP server.
(quoted diff) +2
-0+ + The type parameter specifies the typeof disconnection.
+Quoted 8 lines
doc/sap-api.txt line 126
Quoted 6 lines
doc/sap-api.txt new file +6
-0+ "Graceful" -> lets the SAP client initiate a + garceful disconnection. + + "Immediate" -> disconnects the connection + immediately from the server. +In my view, the disconnection should be initiates by the sap
server, not by the agent. In a typical use case the agent will communicate sim state change (card removed or not accessible) to sap server. Based on that, the sap server should make a decision whether disconnect or not. What's more the disconnect procedure is defined in the SAP spec, and would be nice to keep all those procedures in the sap server, not in the agent which will be specific for a sim provider. Therefore, I would remove this method call from the api. I would add the Disconnect signal instead.
Quoted 4 lines
Signal:
Disconnect()
This signal will be send when SAP connectionissuccessfully removed.
Quoted 2 lines
In case of graceful disconnection sap server sends signal
to the agent REQUEST(disconnect) and wait till SIM free its stuff and send back RESPONSE(disconnect). In case of immediate disconnection sap server will send
Disconnect()signal to the agent.
Quoted 5 lines
Ok, In which all situations should the SAP server decide that the SAP connection has to be disconnected (you have mentioned Sim Status change as one candidate)?
Also, based on what should the server decide to initiate a "Graceful" or "Immediate" disconnection?
Well, I thought this over and in case of sim state change sap should propagate this change to sap client, not disconnect. The only place when sap sever uses immediate disconnection imho are problems on the connection with agent (dbus errors), and the graceful disconnection should be used in case when the user want to stop sap server. In this point Enable/Disable methods are missing to let the User chance to stop/run sap server.
/Waldek
Hi Suraj,
Quoted 15 lines · Suraj Sumangala
doc/sap-api.txt new file +15
-0+Methods void RegisterAgent(object agent) + + This registers the Sim Access adapter agent. + This also registers the profile with the service + Databse and start waiting for an RFCOMM connection + on the SAP server channel. + + The object path defines the path the of the agent. + + If an application disconnects from the bus all + of its registered agents will be removed. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.AlreadyExists + org.bluez.Error.Failed
doc/sap-api.txt line 44
Quoted 10 lines
doc/sap-api.txt new file +10
-0+ + void UnregisterAgent(object agent) + + This unregisters the agent that has been previously + registered. The object path parameter must match the + same value that has been used on registration. + + Possible errors: org.bluez.Error.DoesNotExist + org.bluez.Error.InvalidArguments + org.bluez.Error.Failed
So you have these nice agent registration methods, however where's the definition of the agent interface? And if you're going to use an agent for this (which seems like a good idea) the SAP commands should map to D-Bus method calls to the agent and the D-Bus method replies from the agent should map to the SAP replies. I.e. please get rid of the D-Bus signals and methods you currently have for this.
Btw, I'm not 100% convinced that this is the most sensible architecture for implementing SAP, but assuming that it is the above comments apply :)
Johan
Hi Johan,
Quoted 27 lines · Johan Hedberg
Hi Suraj,
Quoted 24 lines · Suraj Sumangala
doc/sap-api.txt new file +24
-0+Methods void RegisterAgent(object agent) + + This registers the Sim Access adapter agent. + This also registers the profile with the service + Databse and start waiting for an RFCOMM connection + on the SAP server channel. + + The object path defines the path the of the agent. + + If an application disconnects from the bus all + of its registered agents will be removed. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.AlreadyExists + org.bluez.Error.Failed + + void UnregisterAgent(object agent) + + This unregisters the agent that has been previously + registered. The object path parameter must match the + same value that has been used on registration. + + Possible errors: org.bluez.Error.DoesNotExist + org.bluez.Error.InvalidArguments
Quoted 8 lines
Review
Quoted 1 line
(quoted diff) +1
-0+ org.bluez.Error.FailedSo you have these nice agent registration methods, however where's the definition of the agent interface? And if you're going to use an agent for this (which seems like a good idea) the SAP commands should map to D-Bus method calls to the agent and the D-Bus method replies from the agent should map to the SAP replies. I.e. please get rid of the D-Bus signals and methods you currently have for this.
The idea was to let the agent implementation be written depending on the actual SIM card reader implementation used in the back end. The agent can then map its signal/methods to the corresponding SAP server calls.
Quoted 4 lines
Btw, I'm not 100% convinced that this is the most sensible architecture for implementing SAP, but assuming that it is the above comments apply :)
Yep, I understand. There were doubts raised on this methods. That is the reason why I thought about getting comments from the community.
Your comments are most welcome.
Quoted 2 lines
Johan
Regards
Suraj
Hi,
Quoted 4 lines · Suraj Sumangala
The idea was to let the agent implementation be written depending on the actual SIM card reader implementation used in the back end. The agent can then map its signal/methods to the corresponding SAP server calls.
We're defining an API here, not implementation specific details, so I don't quite understand your concern. What's the point of defining an agent object if it will not receive any method calls? The RegisterAgent might as well be called EnableServer in that case and not contain any object path parameter at all.
Having a proper agent interface and methods in it corresponding to SAP commands makes much more sense imho than emiting signals for SAP commands and receiving method calls for the SAP replies. It also doesn't in any way restrict the agent side implementation details. A D-Bus method call-method reply pair is a more intuitive mapping to a SAP-command-SAP-response pair compared to a D-Bus signal + method call which don't have any tight API level association (anybody can catch the signal and anybody can send the method call).
Johan
Hi Johan,
Quoted 6 lines · Johan Hedberg
We're defining an API here, not implementation specific details, so I don't quite understand your concern. What's the point of defining an agent object if it will not receive any method calls? The RegisterAgent might as well be called EnableServer in that case and not contain any object path parameter at all.
Quoted 9 lines
Having a proper agent interface and methods in it corresponding to SAP commands makes much more sense imho than emiting signals for SAP commands and receiving method calls for the SAP replies. It also doesn't in any way restrict the agent side implementation details. A D-Bus method call-method reply pair is a more intuitive mapping to a SAP-command-SAP-response pair compared to a D-Bus signal + method call which don't have any tight API level association (anybody can catch the signal and anybody can send the method call).
Got your point, Thanks.
Also, do let me know if you have any other suggestion regarding the interface.
Regards
Suraj