From e2f21302ecc0f27e37bd8e81df51595a99f6bb41 Mon Sep 17 00:00:00 2001 From: Karol Lewandowski Date: Thu, 5 May 2022 13:05:16 +0200 Subject: [PATCH] api: Add documentation Change-Id: I2a9a913e3a329f9134ecd7fe511b38fea1cc2efc --- libsessiond/include/sessiond.h | 172 ++++++++++++++++++++++++++++++++- 1 file changed, 167 insertions(+), 5 deletions(-) diff --git a/libsessiond/include/sessiond.h b/libsessiond/include/sessiond.h index ccc3846..de45306 100644 --- a/libsessiond/include/sessiond.h +++ b/libsessiond/include/sessiond.h @@ -74,18 +74,180 @@ typedef union subsession_event_info { } switch_user; } subsession_event_info; +/** + * @brief Callback fired when registered events occur. + * @since_tizen 7.0 + * + * @param[in] info Information associated with the event itself + * @param[in] cb_data The user data passed from the callback registration function + * @remarks Return value from callback is currently unused. + */ +typedef int (*subsession_event_callback) (subsession_event_info info, void *cb_data); + +/** + * @brief Register the event "wait lock" + * @since_tizen 7.0 + * + * @param[in] session_uid User ID of the session + * @param[in] event_bits Events to register for + * @param[in] cb Callback which will handle requested events + * @param[in] cb_data User defined data + * @remarks Client can register "wait lock" only for its own process. + * + * @return 0 on success, otherwise a negative error value + * @retval #SUBSESSION_ERROR_NONE Success + * @retval #SUBSESSION_ERROR_INVALID_PARAMETER Provided parameter is invalid + * @retval #SUBSESSION_ERROR_IO_ERROR Internal error occurred + * @retval #SUBSESSION_ERROR_PERMISSION_DENIED Not permitted + * @retval #SUBSESSION_ERROR_NOT_SUPPORTED Not supported + */ +int subsession_register_event_callback(int session_uid, subsession_event_type_e event_bits, subsession_event_callback cb, void *cb_data); + +/** + * @brief Unregister the event "wait lock" + * @since_tizen 7.0 + * + * @param[in] session_uid User ID of the session + * @param[in] event_bits Events to remove callbacks for \n + * It will be impossible to distinguish for which event unregistration failed if more than one bit is set in event_bits. + * + * @return 0 on success, otherwise a negative error value + * @retval #SUBSESSION_ERROR_NONE Success + * @retval #SUBSESSION_ERROR_INVALID_PARAMETER Provided parameter is invalid + * If one bit was set in event_bits then this errors means that this particular event was not registered previously \n + * If more than one bit was set in event_bit then this error means that at least one of specified events was not registered + * @retval #SUBSESSION_ERROR_IO_ERROR Internal error occurred + * @retval #SUBSESSION_ERROR_PERMISSION_DENIED Not permitted + * @retval #SUBSESSION_ERROR_NOT_SUPPORTED Not supported + */ +int subsession_unregister_event_callback(int session_uid, subsession_event_type_e event_bits); + +/** + * @brief Callback fired when requested operation completes. + * @since_tizen 7.0 + * + * @param[in] result Status code (currently unused) + * @param[in] cb_data The user data passed from the callback registration function + * @remarks Return value from callback is currently unused. + */ typedef int (*subsession_reply_callback) (int result, void *cb_data); + +/** + * @brief Request new subsession to be created. + * @since_tizen 7.0 + * + * @param[in] session_uid User ID of the session + * @param[in] user Subsession ID to be created + * @param[in] cb Callback to be called when operation completes or error is reported + * @param[in] cb_data User defined data + * + * @return 0 on success, otherwise a negative error value + * @retval #SUBSESSION_ERROR_NONE Success + * @retval #SUBSESSION_ERROR_INVALID_PARAMETER Provided parameter is invalid + * @retval #SUBSESSION_ERROR_ALREADY_EXISTS Subsession already exists + * @retval #SUBSESSION_ERROR_IO_ERROR Internal error occurred + * @retval #SUBSESSION_ERROR_PERMISSION_DENIED Not permitted + * @retval #SUBSESSION_ERROR_NOT_SUPPORTED Not supported + * @remarks Use `subsession_get_user_list()` to list currently used session IDs. + */ int subsession_add_user(int session_uid, int user, subsession_reply_callback cb, void *cb_data); + +/** + * @brief Request existing subsession to be removed. + * @since_tizen 7.0 + * + * @param[in] session_uid User ID of the session + * @param[in] user Subsession ID to be removed + * @param[in] cb Callback to be called when operation completes or error is reported + * @param[in] cb_data User defined data + * + * @return 0 on success, otherwise a negative error value + * @retval #SUBSESSION_ERROR_NONE Success + * @retval #SUBSESSION_ERROR_INVALID_PARAMETER Provided parameter is invalid + * @retval #SUBSESSION_ERROR_NOT_AVAILABLE Subsession does not exist + * @retval #SUBSESSION_ERROR_IO_ERROR Internal error occurred + * @retval #SUBSESSION_ERROR_PERMISSION_DENIED Not permitted + * @retval #SUBSESSION_ERROR_NOT_SUPPORTED Not supported + * @remarks Only inactive session ID can be removed. \n + * In order remove currently used session ID first switch to special session ID 0, and \n + * only after switch completes remove previously active session ID. + */ int subsession_remove_user(int session_uid, int user, subsession_reply_callback cb, void *cb_data); + +/** + * @brief Switch subsession. + * @since_tizen 7.0 + * + * @param[in] session_uid User ID of the session + * @param[in] next_user Target subsession ID + * @param[in] cb Callback to be called when operation completes or error is reported + * @param[in] cb_data User defined data + * + * @return 0 on success, otherwise a negative error value + * @retval #SUBSESSION_ERROR_NONE Success + * @retval #SUBSESSION_ERROR_INVALID_PARAMETER Provided parameter is invalid + * @retval #SUBSESSION_ERROR_NOT_AVAILABLE Subsession does not exist + * @retval #SUBSESSION_ERROR_IO_ERROR Internal error occurred + * @retval #SUBSESSION_ERROR_PERMISSION_DENIED Not permitted + * @retval #SUBSESSION_ERROR_NOT_SUPPORTED Not supported + * @remarks Special subsession ID 0 can be switched to, when it's required to deactivate current subsession \n + * (this step is needed when current session is to be removed). + */ int subsession_switch_user(int session_uid, int next_user, subsession_reply_callback cb, void *cb_data); +/** + * @brief Mark registered "wait lock" for specified event as completed + * @since_tizen 7.0 + * + * @param[in] session_uid User ID of the session + * @param[in] event One bit marking which event to mark as done + * @remarks Only client's own "wait lock" can be marked as completed. \n + * This function should be called from previously registered callback. + * + * @return 0 on success, otherwise a negative error value + * @retval #SUBSESSION_ERROR_NONE Success + * @retval #SUBSESSION_ERROR_INVALID_PARAMETER Provided parameter is invalid + * @retval #SUBSESSION_ERROR_IO_ERROR Internal error occurred + * @retval #SUBSESSION_ERROR_PERMISSION_DENIED Not permitted + * @retval #SUBSESSION_ERROR_NOT_SUPPORTED Not supported + */ +int subsession_event_wait_done(int session_uid, subsession_event_type_e event, subsession_event_info info); + +/** + * @brief Get list of all available subsessions for given session ID + * @since_tizen 7.0 + * + * @param[in] session_uid User ID of the session + * @param[out] user_list Array of active subsession IDs + * @param[out] user_out Size of user_list array + * + * @return 0 on success, otherwise a negative error value + * @retval #SUBSESSION_ERROR_NONE Success + * @retval #SUBSESSION_ERROR_INVALID_PARAMETER Provided parameter is invalid + * @retval #SUBSESSION_ERROR_OUT_OF_MEMORY Out of memory + * @retval #SUBSESSION_ERROR_IO_ERROR Internal error occurred + * @retval #SUBSESSION_ERROR_PERMISSION_DENIED Not permitted + * @retval #SUBSESSION_ERROR_NOT_SUPPORTED Not supported + * @remarks You must free user_list using free() + */ int subsession_get_user_list(int session_uid, int **user_list, int *user_count); -int subsession_get_current_user(int session_uid, int *user); -typedef int (*subsession_event_callback) (subsession_event_info info, void *cb_data); -int subsession_register_event_callback(int session_uid, subsession_event_type_e event_bits, subsession_event_callback cb, void *cb_data); -int subsession_unregister_event_callback(int session_uid, subsession_event_type_e event_bits); -int subsession_event_wait_done(int session_uid, subsession_event_type_e event, subsession_event_info info); +/** + * @brief Get currently active subsession ID for given session ID + * @since_tizen 7.0 + * + * @param[in] session_uid User ID of the session + * @param[out] user Currently active subsession ID + * + * @return 0 on success, otherwise a negative error value + * @retval #SUBSESSION_ERROR_NONE Success + * @retval #SUBSESSION_ERROR_INVALID_PARAMETER Provided parameter is invalid + * @retval #SUBSESSION_ERROR_OUT_OF_MEMORY Out of memory + * @retval #SUBSESSION_ERROR_IO_ERROR Internal error occurred + * @retval #SUBSESSION_ERROR_PERMISSION_DENIED Not permitted + * @retval #SUBSESSION_ERROR_NOT_SUPPORTED Not supported + */ +int subsession_get_current_user(int session_uid, int *user); #ifdef __cplusplus } -- 2.34.1