[RFC] Sim Access Profile API doc

[RFC] Sim Access Profile API doc

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

diff --git a/doc/sap-api.txt b/doc/sap-api.txt
new file mode 100644
index 0000000..719cff6
--- /dev/null
+++ b/doc/sap-api.txt
@@ -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.
-- 
1.7.0.4

Re: [RFC] Sim Access Profile API doc

[Uwe Kleine-König]

Hello Suraj,

I don't know much about sim or bluetooth in general, so only a few minor
comments below.

On Tue, Sep 07, 2010 at 11:32:55AM +0530, Suraj Sumangala wrote:
> 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
> 
> diff --git a/doc/sap-api.txt b/doc/sap-api.txt
> new file mode 100644
> index 0000000..719cff6
> --- /dev/null
> +++ b/doc/sap-api.txt
> @@ -0,0 +1,197 @@
> +BlueZ D-Bus Adapter API description
this is a copy&paste leftover?

> +***********************************
> +
> +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
s/Databse/database/ (not sure about capitalization)

> +			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.
and you might want to add your file to EXTRA_DIST in Makefile.am.

Best regards
Uwe

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |

RE: [RFC] Sim Access Profile API doc

[Waldemar.Rymarkiewicz]

Hi Suraj, 

>From: Suraj Sumangala [mailto:suraj@atheros.com] 
>Sent: Tuesday, September 07, 2010 8:03 AM

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

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

Re: [RFC] Sim Access Profile API doc

[Suraj Sumangala]

Hi Waldek,

On 9/7/2010 2:06 PM, Waldemar.Rymarkiewicz@tieto.com wrote:
> Hi Suraj,
>
>> From: Suraj Sumangala [mailto:suraj@atheros.com]
>> Sent: Tuesday, September 07, 2010 8:03 AM
>
>> +
>> +		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.
>> +
>
> 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.

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?

>
> Thanks,
> /Waldek

Regards
Suraj

Re: [RFC] Sim Access Profile API doc

[Johan Hedberg]

Hi Suraj,

On Tue, Sep 07, 2010, Suraj Sumangala wrote:
> +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

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

Re: [RFC] Sim Access Profile API doc

[Suraj Sumangala]

Hi Johan,

On 9/7/2010 2:59 PM, Johan Hedberg wrote:
> Hi Suraj,
>
> On Tue, Sep 07, 2010, Suraj Sumangala wrote:
>> +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
>
> 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.

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.

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

>
> Johan

Regards
Suraj

Re: [RFC] Sim Access Profile API doc

[Johan Hedberg]

Hi,

On Tue, Sep 07, 2010, Suraj Sumangala wrote:
> 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

RE: [RFC] Sim Access Profile API doc

[Waldemar.Rymarkiewicz]

 Hi Suraj,

>-----Original Message-----
>From: Suraj Sumangala [mailto:suraj@Atheros.com] 
>Sent: Tuesday, September 07, 2010 11:28 AM

>Hi Waldek,
>
>On 9/7/2010 2:06 PM, Waldemar.Rymarkiewicz@tieto.com wrote:
>> Hi Suraj,
>>
>>> From: Suraj Sumangala [mailto:suraj@atheros.com]
>>> Sent: Tuesday, September 07, 2010 8:03 AM
>>
>>> +
>>> +		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.
>>> +
>>
>> 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.
>
>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

Re: [RFC] Sim Access Profile API doc

[Suraj Sumangala]

Hi Johan,

On 9/7/2010 3:42 PM, Johan Hedberg wrote:
> 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).
>

Got your point, Thanks.
Also, do let me know if you have any other suggestion regarding the 
interface.

Regards
Suraj