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
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
Hi Suraj,
>-----Original Message-----
>From: Suraj Sumangala [mailto:[email protected]]
>Sent: Tuesday, September 07, 2010 11:28 AM
>Hi Waldek,
>
>On 9/7/2010 2:06 PM, [email protected] wrote:
>> Hi Suraj,
>>
>>> From: Suraj Sumangala [mailto:[email protected]]
>>> 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
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
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
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
Hi Waldek,
On 9/7/2010 2:06 PM, [email protected] wrote:
> Hi Suraj,
>
>> From: Suraj Sumangala [mailto:[email protected]]
>> 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
Hi Suraj,
>From: Suraj Sumangala [mailto:[email protected]]
>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
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/ |