Update API documents

Change-Id: I5b716e672b0a43a9da77ba4ba9bf6591d971b0ea
Signed-off-by: Jihoon Jung <jh8801.jung@samsung.com>

diff --git a/include/smartcard.h b/include/smartcard.h
index 201617a9ff370aecf9fb82693dcacfe4019f2beb..a5b74696ff1d266206a2be9990634b60e9b4453a 100644 (file)
--- a/include/smartcard.h
+++ b/include/smartcard.h
@@ -187,6 +187,9 @@ int smartcard_reader_get_name(int reader, char **reader_name);
 
 /**
  * @brief Checks if a Secure Element is present in the given reader.
+ * @details This function checks if a Secure Element is present in the specified
+ * reader. It returns true if a Secure Element is present, and false if it is
+ * not. If an error occurs, the value of is_present is undefined.
  * @since_tizen 2.3.1
  * @ingroup CAPI_NETWORK_SMARTCARD_READER_MODULE
  *
@@ -207,6 +210,9 @@ int smartcard_reader_is_secure_element_present(int reader, bool *is_present);
 
 /**
  * @brief Connects to a Secure Element in the given reader.
+ * @details This function connects to a Secure Element in the specified reader
+ * and creates a session handle for the given reader. The session handle can be
+ * used to perform further operations on the Secure Element.
  * @since_tizen 2.3.1
  * @privlevel public
  * @privilege %http://tizen.org/privilege/secureelement
@@ -253,6 +259,9 @@ int smartcard_reader_close_sessions(int reader);
 
 /**
  * @brief Sets a callback function for receiving reader event.
+ * @details Registers a callback function to receive notifications about reader
+ * events. When a reader event occurs, the provided callback function will be
+ * called with the new state and the user data passed during registration.
  * @since_tizen 3.0
  * @ingroup CAPI_NETWORK_SMARTCARD_READER_MODULE
  *
@@ -271,6 +280,9 @@ int smartcard_reader_set_event_cb(smartcard_reader_event_cb cb, void *user_data)
 
 /**
  * @brief Unsets the reader event callback function.
+ * @details Unregisters the previously registered callback function for
+ * receiving reader event notifications. After calling this function, the
+ * callback function will no longer be called when a reader event occurs.
  * @since_tizen 3.0
  * @ingroup CAPI_NETWORK_SMARTCARD_READER_MODULE
  *
@@ -285,6 +297,8 @@ int smartcard_reader_unset_event_cb(void);
 
 /**
  * @brief Gets the reader that provides the given session.
+ * @details Retrieves the reader handle that provides the given session. The
+ * reader handle is stored in the location pointed to by the reader parameter.
  * @since_tizen 2.3.1
  * @ingroup CAPI_NETWORK_SMARTCARD_SESSION_MODULE
  *
@@ -304,6 +318,11 @@ int smartcard_session_get_reader(int session, int *reader);
 
 /**
  * @brief Gets the Answer to Reset(ATR) of this Secure Element.
+ * @details Retrieves the Answer to Reset (ATR) of the Secure Element associated
+ * with the given session. The ATR is stored in the byte array pointed to by the
+ * atr parameter, and its length is stored in the location pointed to by the
+ * length parameter. Note that the atr buffer must be released using free()
+ * after use.
  * @since_tizen 2.3.1
  * @privlevel public
  * @privilege %http://tizen.org/privilege/secureelement
@@ -353,6 +372,8 @@ int smartcard_session_close(int session);
 
 /**
  * @brief Checks if the given session is closed.
+ * @details Checks whether the given session is closed. The result is stored in
+ * the location pointed to by the is_closed parameter.
  * @since_tizen 2.3.1
  * @ingroup CAPI_NETWORK_SMARTCARD_SESSION_MODULE
  *
@@ -372,6 +393,9 @@ int smartcard_session_is_closed(int session, bool *is_closed);
 
 /**
  * @brief Closes any channel opened on the given session.
+ * @details Closes all channels that have been opened on the given session. This
+ * function can be used to ensure that all resources associated with the session
+ * are properly released.
  * @since_tizen 2.3.1
  * @privlevel public
  * @privilege %http://tizen.org/privilege/secureelement
@@ -457,6 +481,8 @@ int smartcard_session_open_logical_channel(int session, unsigned char *aid, int
 
 /**
  * @brief Closes the given channel to the Secure Element.
+ * @details Closes the given channel to the Secure Element. This function
+ * releases any resources associated with the channel.
  * @since_tizen 2.3.1
  * @privlevel public
  * @privilege %http://tizen.org/privilege/secureelement
@@ -480,6 +506,8 @@ int smartcard_channel_close(int channel);
 
 /**
  * @brief Checks if the given channel is the basic channel.
+ * @details Determines whether the given channel is a basic channel. The result
+ * is stored in the location pointed to by the is_basic_channel parameter.
  * @since_tizen 2.3.1
  * @ingroup CAPI_NETWORK_SMARTCARD_CHANNEL_MODULE
  *
@@ -500,6 +528,8 @@ int smartcard_channel_is_basic_channel(int channel, bool *is_basic_channel);
 
 /**
  * @brief Checks if the given channel is closed.
+ * @details Checks whether the given channel is closed. The result is stored in
+ * the location pointed to by the is_closed parameter.
  * @since_tizen 2.3.1
  * @ingroup CAPI_NETWORK_SMARTCARD_CHANNEL_MODULE
  *
@@ -520,6 +550,11 @@ int smartcard_channel_is_closed(int channel, bool *is_closed);
 
 /**
  * @brief Gets the response to the select command.
+ * @details Retrieves the response to the SELECT command for the given channel.
+ * The response is stored in the byte array pointed to by the select_resp
+ * parameter, and its length is stored in the location pointed to by the length
+ * parameter. Note that the select_resp buffer must be released using free()
+ * after use.
  * @since_tizen 2.3.1
  * @ingroup CAPI_NETWORK_SMARTCARD_CHANNEL_MODULE
  *
@@ -543,6 +578,8 @@ int smartcard_channel_get_select_response(int channel, unsigned char **select_re
 
 /**
  * @brief Gets the session that has opened the given channel.
+ * @details Retrieves the session handle that has opened the given channel. The
+ * session handle is stored in the location pointed to by the session parameter.
  * @since_tizen 2.3.1
  * @ingroup CAPI_NETWORK_SMARTCARD_CHANNEL_MODULE
  *
@@ -563,6 +600,11 @@ int smartcard_channel_get_session(int channel, int *session);
 
 /**
  * @brief Transmits an APDU command (as per ISO/IEC 7816-4) to the Secure Element.
+ * @details Transmits an APDU command to the Secure Element associated with the
+ given channel. The response to the command is stored in the byte array pointed
+ to by the resp parameter, and its length is stored in the location pointed to
+ by the length parameter. Note that the resp buffer must be released using
+ free() after use.
  * @since_tizen 2.3.1
  * @privlevel public
  * @privilege %http://tizen.org/privilege/secureelement
@@ -596,6 +638,11 @@ int smartcard_channel_transmit(int channel, unsigned char *cmd, int cmd_len, uns
 
 /**
  * @brief Retrieves the response APDU of the previous transmit() call (helper function).
+ * @details Retrieves the response APDU from the previous transmit() call for
+ * the given channel. The response is stored in the byte array pointed to by the
+ * resp parameter, and its length is stored in the location pointed to by the
+ * length parameter. Note that the resp buffer must be released using free()
+ * after use.
  * @since_tizen 2.3.1
  * @ingroup CAPI_NETWORK_SMARTCARD_CHANNEL_MODULE
  *
@@ -620,6 +667,9 @@ int smartcard_channel_transmit_retrieve_response(int channel, unsigned char **re
 
 /**
  * @brief Performs a selection of the next Applet on the given channel that matches to the partial Application ID (AID).
+ * @details Selects the next Applet on the given channel that matches the
+partial Application ID (AID). The result is stored in the location pointed to by
+the is_success parameter.
  * @since_tizen 2.3.1
  * @privlevel public
  * @privilege %http://tizen.org/privilege/secureelement