From ac176304ae8d951a9f87736f0173d74c054c0258 Mon Sep 17 00:00:00 2001 From: Jihoon Jung Date: Wed, 25 Sep 2024 15:49:25 +0900 Subject: [PATCH] Update API documents Change-Id: I5b716e672b0a43a9da77ba4ba9bf6591d971b0ea Signed-off-by: Jihoon Jung --- include/smartcard.h | 50 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/include/smartcard.h b/include/smartcard.h index 201617a..a5b7469 100644 --- 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 -- 2.34.1