From 54f9ca94bc97394b9fb0ff27c76bc806387f648e Mon Sep 17 00:00:00 2001 From: Jihoon Jung Date: Thu, 26 Sep 2024 10:26:11 +0900 Subject: [PATCH] Enhance API descriptions Signed-off-by: Jihoon Jung --- .../SmartcardChannel.cs | 36 +++++++++++++------ .../SmartcardManager.cs | 9 +++-- .../SmartcardReader.cs | 20 ++++++++--- .../SmartcardSession.cs | 24 +++++++++---- 4 files changed, 66 insertions(+), 23 deletions(-) mode change 100755 => 100644 src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardManager.cs diff --git a/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardChannel.cs b/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardChannel.cs index 9845e0bf52d..d5312e515c0 100644 --- a/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardChannel.cs +++ b/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardChannel.cs @@ -21,7 +21,10 @@ namespace Tizen.Network.Smartcard { /// - /// The class for Smartcard channel information. It allows applications to handle the channel information. + /// The SmartcardChannel class represents a communication channel between the application and a Smartcard. + /// It provides properties and methods to handle channel-specific operations, + /// such as transmitting APDUs, retrieving responses, and checking channel states. + /// This class also implements the IDisposable interface, allowing for proper resource management. /// /// 3 /// http://tizen.org/privilege/secureelement @@ -32,7 +35,9 @@ public class SmartcardChannel : IDisposable private SmartcardSession _sessionObject; /// - /// Whether the kind of channel is basic. + /// The IsBasicChannel property indicates whether the channel is a basic channel. + /// Basic channels are used to communicate with the card's logical channel zero, + /// which is typically used for general-purpose applications. /// /// 3 public bool IsBasicChannel @@ -50,7 +55,9 @@ public bool IsBasicChannel } /// - /// Whether the kind of channel is logical. + /// The IsLogicalChannel property indicates whether the channel is a logical channel. + /// Logical channels are used to communicate with specific applications on the card, + /// other than the default basic channel. /// /// 3 public bool IsLogicalChannel @@ -68,7 +75,8 @@ public bool IsLogicalChannel } /// - /// Whether the channel is closed. + /// The IsClosed property indicates whether the channel is currently closed. + /// If true, the channel is not open and cannot be used for communication with the Smartcard. /// /// 3 public bool IsClosed @@ -86,7 +94,8 @@ public bool IsClosed } /// - /// The session that has opened the given channel. + /// The Session property returns the SmartcardSession object that opened the current channel. + /// This allows applications to access session-specific information and methods. /// /// 3 public SmartcardSession Session @@ -147,7 +156,9 @@ private void Dispose(bool disposing) } /// - /// Closes the given channel to the Secure Element. + /// The Close method closes the current channel to the Secure Element. + /// This method ensures that all resources allocated for the channel are released and that the channel is no longer available for communication. + /// Any subsequent attempts to use the channel after calling this method will result in an error. /// /// 3 /// Thrown when the Smartcard is not supported. @@ -164,7 +175,8 @@ public void Close() } /// - /// Gets the response to the select command. + /// The GetSelectedResponse method retrieves the response to the SELECT command sent during the opening of the channel. + /// This response contains information about the selected application on the Smartcard, such as its AID (Application Identifier). /// /// 3 /// Byte array to retrieve the select response. @@ -189,7 +201,8 @@ public byte[] GetSelectedResponse() } /// - /// Transmits the APDU command (as per ISO/IEC 7816-4) to the secure element. + /// The Transmit method sends an APDU (Application Protocol Data Unit) command to the Secure Element and receives the corresponding response. + /// This method allows applications to communicate with the Smartcard by sending commands and processing the responses. /// /// 3 /// Byte array for the response APDU plus status words. @@ -216,7 +229,8 @@ public byte[] Transmit(byte[] cmd) } /// - /// Helper function to retrieve the response APDU of the previous transmit() call. + /// The GetTransmittedResponse method retrieves the response APDU from the previous Transmit method call. + /// This method allows applications to access the response data without having to store it separately. /// /// 3 /// Byte array for the response APDU plus status words. @@ -241,7 +255,9 @@ public byte[] GetTransmittedResponse() } /// - /// Performs a selection of the next applet on the given channel that matches to the partial application ID (AID). + /// The SelectNext method selects the next applet on the current channel that matches the partial Application Identifier (AID). + /// This method allows applications to switch between different applets on the Smartcard, + /// enabling interaction with multiple applications within a single session. /// /// 3 /// True or false depending whether another applet with the partial application ID (AID). diff --git a/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardManager.cs b/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardManager.cs old mode 100755 new mode 100644 index f08ced3f181..2160a2b2e5c --- a/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardManager.cs +++ b/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardManager.cs @@ -21,14 +21,19 @@ namespace Tizen.Network.Smartcard { /// - /// The class for Smartcard management. It allows applications to use the Smartcard service. + /// The SmartcardManager class provides a interface for managing Smartcard services within Tizen applications. + /// It allows developers to interact with Smartcards, perform various operations, + /// and utilize the capabilities provided by the Smartcard framework. /// /// 3 /// http://tizen.org/privilege/secureelement static public class SmartcardManager { /// - /// Gets the list of available secure element readers. + /// The GetReaders method retrieves a list of available Smartcard readers. + /// This method returns a collection of SmartcardReader objects, + /// representing the different readers that are currently connected to the device. + /// Applications can use this method to enumerate the available readers and select one to establish a session with the Secure Element. /// /// 3 /// List of SmartcardReader objects. diff --git a/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardReader.cs b/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardReader.cs index 65eb3178612..6b5460c59e5 100644 --- a/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardReader.cs +++ b/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardReader.cs @@ -21,7 +21,9 @@ namespace Tizen.Network.Smartcard { /// - /// The class for Smartcard reader information. It allows applications to handle the reader information. + /// The SmartcardReader class provides information about the Smartcard readers connected to the device. + /// Applications can use this class to obtain details about the available readers, + /// such as their names and states, and to manage interactions with the readers. /// /// 3 /// http://tizen.org/privilege/secureelement @@ -33,7 +35,9 @@ public class SmartcardReader : IDisposable private List _sessionList = new List(); /// - /// The name of the reader. + /// The Name property represents the name of the Smartcard reader. + /// This property allows applications to retrieve the human-readable name assigned to the reader, + /// which can be useful for displaying information to the user or for logging purposes. /// /// 3 public string Name @@ -52,7 +56,9 @@ public string Name } /// - /// The existence of a secure element. + /// The IsSecureElementPresent property indicates whether a Secure Element is currently present in the Smartcard reader. + /// This property allows applications to determine if there is a Smartcard inserted into the reader, + /// which can be useful for deciding whether to proceed with further operations or display appropriate messages to the user. /// /// 3 public bool IsSecureElementPresent @@ -121,7 +127,9 @@ internal int GetSession() } /// - /// Connects to a secure element in the given reader. + /// The OpenSession method establishes a connection to the Secure Element in the specified Smartcard reader. + /// This method returns a SmartcardSession object, which represents the session with the Secure Element. + /// By calling this method, applications can initiate communication with the Secure Element and perform various operations. /// /// 3 /// The SmartcardSession object. @@ -139,7 +147,9 @@ public SmartcardSession OpenSession() } /// - /// Closes all the sessions opened on the given reader. + /// The CloseSessions method closes all the open sessions associated with the specified Smartcard reader. + /// This method ensures that any active sessions with the Secure Element are properly terminated. + /// By calling this method, applications can release resources and prevent potential conflicts or errors when interacting with the Smartcard. /// /// 3 /// Thrown when the Smartcard is not supported. diff --git a/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardSession.cs b/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardSession.cs index 1d9d0e554bf..98462cce2c7 100644 --- a/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardSession.cs +++ b/src/Tizen.Network.Smartcard/Tizen.Network.Smartcard/SmartcardSession.cs @@ -21,7 +21,8 @@ namespace Tizen.Network.Smartcard { /// - /// The class for the Smartcard session information. It allows applications to handle the session information. + /// The SmartcardSession class provides information about the Smartcard session established with the Secure Element. + /// Applications can use this class to manage the session, perform various operations, and interact with the Secure Element. /// /// 3 /// http://tizen.org/privilege/secureelement @@ -36,7 +37,9 @@ public class SmartcardSession : IDisposable private int _logicalChannel = 0; /// - /// The reader object that provides the given session. + /// The Reader property represents the SmartcardReader object associated with the current Smartcard session. + /// This property allows applications to access information about the reader that is providing the session, + /// such as its name and state. It can be useful for displaying relevant information to the user or for logging purposes. /// /// 3 public SmartcardReader Reader @@ -60,7 +63,10 @@ public SmartcardReader Reader } /// - /// The Answer to Reset (ATR) of this secure element. + /// The Atr property represents the Answer to Reset (ATR) of the Secure Element associated with the current Smartcard session. + /// The ATR is a sequence of bytes sent by the Secure Element during the initial communication phase, + /// providing information about the card's characteristics and capabilities. + /// Applications can use this property to retrieve the ATR and analyze the card's properties. /// /// 3 public byte[] Atr @@ -87,7 +93,9 @@ public byte[] Atr } /// - /// Whether the session is closed. + /// The IsClosed property indicates whether the current Smartcard session is closed. + /// This property allows applications to check the status of the session and determine if it is still active or has been terminated. + /// Knowing the session's status is important for managing resources and ensuring proper communication with the Secure Element. /// /// 3 public bool IsClosed @@ -158,7 +166,9 @@ internal int GetHandle() } /// - /// Closes the connection with the secure element. + /// The Close method terminates the connection with the Secure Element associated with the current Smartcard session. + /// This method ensures that any resources allocated for the session are released and the session is properly closed. + /// By calling this method, applications can free up resources and ensure that no further operations are performed on the session. /// /// 3 /// Thrown when the Smartcard is not supported. @@ -175,7 +185,9 @@ public void Close() } /// - /// Closes any channel opened on the given session. + /// The CloseChannels method closes all channels that have been opened within the current Smartcard session. + /// This method ensures that any active channels with the Secure Element are properly terminated. + /// By calling this method, applications can release resources and prevent potential conflicts or errors when interacting with the Smartcard. /// /// 3 /// Thrown when the Smartcard is not supported.