api: Add documentation

Change-Id: I2a9a913e3a329f9134ecd7fe511b38fea1cc2efc

diff --git a/libsessiond/include/sessiond.h b/libsessiond/include/sessiond.h
index ccc3846..de45306 100644 (file)
--- 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
 }