From: Yunhee Seo Date: Fri, 27 Sep 2024 10:15:43 +0000 (+0900) Subject: input: Enhance API description X-Git-Tag: accepted/tizen/unified/20241006.053304~6 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=7ebfd68985e6a5fda1be2ef70c827dae5c0dda92;p=platform%2Fcore%2Fapi%2Fdevice.git input: Enhance API description To improve readability and facilitate comprehension, more detailed API descriptions are added. Change-Id: I59745efa269c63b223690b91fe4053174d57feff Signed-off-by: Yunhee Seo --- diff --git a/include/input-internal.h b/include/input-internal.h index c750f19..4e3f88d 100644 --- a/include/input-internal.h +++ b/include/input-internal.h @@ -41,85 +41,193 @@ typedef enum } device_input_type_e; /** - * @brief Get input default device id by input device type + * @brief Gets the input default device ID for a specified input device type. + * @details Retrieves the default device ID for a specified input device type. + * The input device type is specified in the @a input_device_type parameter, \n + * and the corresponding default device ID is returned in the @a input_device_id parameter. * @since_tizen 7.0 * @remarks #DEVICE_ERROR_NOT_SUPPORTED is returned, when the trying to control DEVICE_INPUT_TYPE_KEYBOARD device * and following feature is not supported: %http://tizen.org/feature/input.keyboard \n * @param[in] input_device_type The type to get input device information \n - * @param[out] input_device_id The id value to be get from the input devices by input_device_type \n - * @return @c 0 on success, - * otherwise a negative error value + * @param[out] input_device_id The ID value to be get from the input devices by input_device_type \n + * @return @c 0 on success, otherwise a negative error value * @retval #DEVICE_ERROR_NONE Successful * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported in this device * @retval #DEVICE_ERROR_OPERATION_FAILED Operation not permitted + * @code + * #include + * ... + * device_input_type_e input_device_type = DEVICE_INPUT_TYPE_MOUSE; + * int input_device_id = 0; + * int ret = 0; + * ... + * ret = device_input_get_default_device(input_device_type, &input_device_id); + * if (ret == DEVICE_ERROR_NONE) { + * ... + * } + * ... + * @endcode + * @see device_input_type_e */ int device_input_get_default_device(device_input_type_e input_device_type, int *input_device_id); /** - * @brief Get input device id list by input device type. + * @brief Gets input device ID list for a specified input device type. + * @details Retrieves a list of device IDs for a specified input device type. \n + * The input device type is specified in the @a input_device_type parameter, \n + * and the corresponding list of device IDs is returned in the @a input_device_ids parameter. \n + * The number of device IDs in the list is returned in the @a num_input_device_ids parameter. * @since_tizen 7.0 * @remarks #DEVICE_ERROR_NOT_SUPPORTED is returned, when the trying to control DEVICE_INPUT_TYPE_KEYBOARD device * and following feature is not supported: %http://tizen.org/feature/input.keyboard \n * after using input_device_ids, it should be freed by caller \n * @param[in] input_device_type The type to get input devices information \n - * @param[out] input_deivce_ids The id list value to be get from the input devices \n - * @param[out] num_input_device_ids The number of ids to be get from the input devices \n - * @return @c 0 on success, - * otherwise a negative error value + * @param[out] input_deivce_ids The ID list value to be get from the input devices \n + * @param[out] num_input_device_ids The number of IDs to be get from the input devices \n + * @return @c 0 on success, otherwise a negative error value * @retval #DEVICE_ERROR_NONE Successful * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported in this device * @retval #DEVICE_ERROR_OPERATION_FAILED Operation not permitted + * @code + * #include + * ... + * device_input_type_e input_device_type = DEVICE_INPUT_TYPE_ALL; + * int *input_device_ids = NULL; + * int num_of_input_device_ids = 0; + * int ret = 0; + * ... + * ret = device_input_get_devices(input_device_type, &input_device_ids, &num_of_input_device_ids); + * if (ret != DEVICE_ERROR_NONE) { + * return -1; + * } + * ... + * if (input_device_ids) { + * free(input_device_ids); + * } + * ... + * @endcode + * @see device_input_type_e */ int device_input_get_devices(device_input_type_e input_device_type, int **input_deivce_ids, int *num_input_device_ids); /** - * @brief Change input device event state by input device id. + * @brief Changes the event state of an input device by input device ID. + * @details The input device ID is specified in the @a input_device_id parameter, \n + * and the desired event state is specified in the @a on parameter. + * The event state is represented by a boolean value, \n + * where @c true indicates that events should be inhibited, and @c false indicates that events should be enabled. * @since_tizen 7.0 * @remarks #DEVICE_ERROR_NOT_SUPPORTED is returned, when the trying to control DEVICE_INPUT_TYPE_KEYBOARD device * and following feature is not supported: %http://tizen.org/feature/input.keyboard \n - * @param[in] input_device_id The input id of the input device under the sys/class/input node \n - * This is for the distinction and control of input devices. \n + * @param[in] input_device_id The input ID of the input device under the sys/class/input node \n + * This is for the distinction and control of input devices \n * @param[in] on The value to be set for the input device event state \n - * @return @c 0 on success, - * otherwise a negative error value + * @c true means inhibit events, @c false means enable events \n + * @return @c 0 on success, otherwise a negative error value * @retval #DEVICE_ERROR_NONE Successful * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported in this device * @retval #DEVICE_ERROR_OPERATION_FAILED Operation not permitted + * @code + * #include + * ... + * device_input_type_e input_device_type = DEVICE_INPUT_TYPE_ALL; + * int *input_device_ids = NULL; + * int num_of_input_device_ids = 0; + * int ret = 0; + * ... + * ret = device_input_get_devices(input_device_type, &input_device_ids, &num_of_input_device_ids); + * if (ret != DEVICE_ERROR_NONE) { + * return -1; + * } + * for (int i = 0; i < num_of_input_device_ids; i++) { + * ret = device_input_set_event_state(input_device_ids[i], true); + * ... + * } + * ... + * if (input_device_ids) { + * free(input_device_ids); + * } + * ... + * @endcode + * @see device_input_get_default_device() + * @see device_input_get_devices() + * @see device_input_get_event_state() */ int device_input_set_event_state(int input_device_id, bool on); /** - * @brief Get input device event state by input device id. + * @brief Gets the event state of an input device by the input device ID. + * @details The input device ID is specified in the @a input_device_id parameter, \n + * The event state is represented by a @a on boolean parameter, \n + * where @c true indicates that events was inhibited, and @c false indicates that events was enabled. * @since_tizen 7.0 * @remarks #DEVICE_ERROR_NOT_SUPPORTED is returned, when the trying to control DEVICE_INPUT_TYPE_KEYBOARD device * and following feature is not supported: %http://tizen.org/feature/input.keyboard \n - * @param[in] input_device_id The input id of the input device under the sys/class/input node \n - * This is for the distinction and control of input devices. \n + * @param[in] input_device_id The input ID of the input device under the sys/class/input node \n + * This is for the distinction and control of input devices \n * @param[out] on The value to be get from the input device event state \n - * @return @c 0 on success, - * otherwise a negative error value + * @return @c 0 on success, otherwise a negative error value * @retval #DEVICE_ERROR_NONE Successful * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported in this device * @retval #DEVICE_ERROR_OPERATION_FAILED Operation not permitted + * @code + * #include + * ... + * device_input_type_e input_device_type = DEVICE_INPUT_TYPE_CUSTOM_KNOB; + * bool inhibited = false; + * int defalt_input_device_id = 0; + * int ret = 0; + * ... + * ret = device_input_get_default_device(input_device_type, &defalt_input_device_id); + * if (ret == DEVICE_ERROR_NONE) { + * ret = device_input_get_event_state(defalt_input_device_id, &inhibited); + * ... + * } + * ... + * @endcode + * @see device_input_get_default_device() + * @see device_input_get_devices() + * @see device_input_set_event_state() */ int device_input_get_event_state(int input_device_id, bool *on); /** - * @brief Get input device name by input device id. + * @brief Gets the name of an input device matched with the input device ID. + * @details Retrieves the name of an input device by input device ID. \n + * The input device ID is specified in the @a input_device_id parameter, \n + * and the corresponding name of the input device is returned in the @a input_device_name parameter. * @since_tizen 7.0 * @remarks #DEVICE_ERROR_NOT_SUPPORTED is returned, when the trying to control DEVICE_INPUT_TYPE_KEYBOARD device * and following feature is not supported: %http://tizen.org/feature/input.keyboard \n - * after using input_device_name, it should be freed by caller \n + * after using @a input_device_name, it should be freed by caller \n * @param[in] input_device_type The type to get input device information \n - * @param[out] input_device_name The name value to be get from the input devices by input_device_type \n - * @return @c 0 on success, - * otherwise a negative error value + * @param[out] input_device_name The name value to be get from the input devices by @a input_device_type \n + * @return @c 0 on success, otherwise a negative error value * @retval #DEVICE_ERROR_NONE Successful * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported in this device * @retval #DEVICE_ERROR_OPERATION_FAILED Operation not permitted + * @code + * #include + * ... + * int input_device_id = 0; + * char *input_device_name = NULL; + * int ret = device_input_get_default_device(DEVICE_INPUT_TYEP_CUSTOM_KNOB, &input_device_id); + * if (ret != DEVICE_ERROR_NONE) { + * return -1; + * } + * ... + * ret = device_input_get_device_name(input_device_id, &input_device_name); + * ... + * if (input_device_name) { + * free(input_device_name); + * } + * ... + * @endcode + * @see device_input_get_default_device() + * @see device_input_get_devices() */ int device_input_get_device_name(int input_device_id, char **input_device_name);