Skip to contentSkip to conversation

Sim Access Profile API doc

RFC In review Suraj Sumangala 4 participants 9 messages Sep 7, 2010 Bluetooth drivers

lore
Share & tools
lore
#0 lore raw

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
new file mode 100644
index 0000000..719cff6
@@ -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
#1 lore raw

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.txt
doc/sap-api.txt new file +0 -0
new file mode 100644
index 0000000..719cff6

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/  |
#2 lore raw
In reply to Suraj Sumangala

Hi Suraj,

Quoted 11 lines

From: Suraj Sumangala [mailto:[email protected]]
Sent: Tuesday, September 07, 2010 8:03 AM

doc/sap-api.txt new file +4 -0
+
+		void Disconnect(string type)
+
+			This initiates a SAP disconnection from 

SAP server.

(quoted diff) +2 -0
+
+			The type parameter specifies the type 

of 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

#3 lore raw

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 AM

doc/sap-api.txt new file +4 -0
+
+		void Disconnect(string type)
+
+			This initiates a SAP disconnection from

SAP server.

(quoted diff) +2 -0
+
+			The type parameter specifies the type

of 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

#4 lore raw

Hi Suraj,

Quoted 50 lines

-----Original Message-----
From: Suraj Sumangala [mailto:[email protected]]
Sent: Tuesday, September 07, 2010 11:28 AM

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

doc/sap-api.txt new file +4 -0
+
+		void Disconnect(string type)
+
+			This initiates a SAP disconnection from

SAP server.

(quoted diff) +2 -0
+
+			The type parameter specifies the type

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

successfully 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

#5 lore raw
In reply to Suraj Sumangala

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

#6 lore raw

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

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

#7 lore raw

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

#8 lore raw

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