From e1e2b56c27050f8fbb259d86858ec95bee836416 Mon Sep 17 00:00:00 2001 From: chenchong_666 Date: Fri, 2 Sep 2022 11:37:04 +0800 Subject: [PATCH] style: Update IDL file comment Signed-off-by: chenchong_666 --- motion/v1_0/IMotionCallback.idl | 46 ++++++++++++++++- motion/v1_0/IMotionInterface.idl | 87 +++++++++++++++++++++++++++++++- motion/v1_0/MotionTypes.idl | 58 ++++++++++++++++++++- 3 files changed, 185 insertions(+), 6 deletions(-) diff --git a/motion/v1_0/IMotionCallback.idl b/motion/v1_0/IMotionCallback.idl index 2538f4cc..265596f9 100644 --- a/motion/v1_0/IMotionCallback.idl +++ b/motion/v1_0/IMotionCallback.idl @@ -13,15 +13,57 @@ * limitations under the License. */ +/** + * @addtogroup Motion + * @{ + * + * @brief Provides common APIs for hardware services to access the motion driver module. + * + * A service can obtain a motion driver object or agent and then call APIs provided by this object or agent to + * enable or disable motion and subscribe to or unsubscribe from motion data. + * + * @since 3.2 + */ + +/** + * @file IMotionCallback.idl + * + * @brief Defines the callback for reporting motion data. + * + * To subscribe to motion data, an instance of this callback must be registered. + * + * @since 3.2 + * @version 1.0 + */ + +/** + * @brief Defines the package path of the motion driver module APIs. + * + * @since 3.2 + */ package ohos.hdi.motion.v1_0; import ohos.hdi.motion.v1_0.MotionTypes; +/** + * @brief Defines the callback for reporting motion data. + * + * Motion users need to register this callback to subscribe to motion data and can receive the data only when motion is enabled. + * For details, see {@link IMotionInterface}. + * + * @since 3.2 + */ [callback] interface IMotionCallback { /** - * @brief Defines the function for reporting sensor data. + * @brief Called to report motion data. + * + * @param event Motion data to report. For details, see {@link HdfMotionEvent}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. * * @since 3.2 */ OnDataEvent([in] struct HdfMotionEvent event); -} \ No newline at end of file +} +/** @} */ diff --git a/motion/v1_0/IMotionInterface.idl b/motion/v1_0/IMotionInterface.idl index 5705c58c..1ff547cd 100644 --- a/motion/v1_0/IMotionInterface.idl +++ b/motion/v1_0/IMotionInterface.idl @@ -12,15 +12,98 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - + +/** + * @addtogroup Motion + * @{ + * + * @brief Provides common APIs for hardware services to access the motion driver module. + * + * A service can obtain a motion driver object or agent and then call APIs provided by this object or agent to + * enable or disable motion and subscribe to or unsubscribe from motion data. + * + * @since 3.2 + */ + +/** + * @file IMotionInterface.idl + * + * @brief Defines the APIs for enabling or disabling motion and subscribing to or unsubscribing from motion data. + * + * The APIs defined here can be called to implement various motion features, such as pickup, flipping, shaking, and screen rotation. + * + * @since 3.2 + * @version 1.0 + */ + +/** + * @brief Defines the package path of the motion driver module APIs. + * + * @since 3.2 + */ package ohos.hdi.motion.v1_0; import ohos.hdi.motion.v1_0.MotionTypes; import ohos.hdi.motion.v1_0.IMotionCallback; +/** + * @brief Defines the APIs for performing basic operations on motion devices. + * + * The APIs can be used to enable or disable motion and subscribe to or unsubscribe from motion data. + */ interface IMotionInterface { + /** + * @brief Enables motion. + * + * @param motionType Motion type. For details, see {@link HdfMotionTypeTag}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 3.2 + * @version 1.0 + */ EnableMotion([in] int motionType); + + /** + * @brief Disables motion. + * + * @param motionType Motion type. For details, see {@link HdfMotionTypeTag}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 3.2 + * @version 1.0 + */ DisableMotion([in] int motionType); + + /** + * @brief Registers the callback for motion data. + * + * If the registration is successful, the system reports the obtained motion data to the subscriber. + * + * @param callbackObj Callback to register, which only needs to be registered only once. For details, see {@link IMotionCallback}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 3.2 + * @version 1.0 + */ Register([in] IMotionCallback callbackObj); + + /** + * @brief Unregisters the callback for motion data. + * + * @param callbackObj Callback to unregister, which only needs to be unregistered only once. For details, see {@link IMotionCallback}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 3.2 + * @version 1.0 + */ Unregister([in] IMotionCallback callbackObj); -} \ No newline at end of file +} +/** @} */ diff --git a/motion/v1_0/MotionTypes.idl b/motion/v1_0/MotionTypes.idl index 14bd6ad0..5b630c11 100644 --- a/motion/v1_0/MotionTypes.idl +++ b/motion/v1_0/MotionTypes.idl @@ -12,26 +12,80 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - + +/** + * @addtogroup Motion + * @{ + * + * @brief Provides common APIs for hardware services to access the motion driver module. + * + * A service can obtain a motion driver object or agent and then call APIs provided by this object or agent to + * enable or disable motion and subscribe to or unsubscribe from motion data. + * + * @since 3.2 + */ + +/** + * @file MotionTypes.idl + * + * @brief Defines the data structures used by the motion module, including the motion types and reported motion data structure. + * + * @since 3.2 + * @version 1.0 + */ + +/** + * @brief Defines the package path of the motion driver module APIs. + * + * @since 3.2 + */ package ohos.hdi.motion.v1_0; +/** + * @brief Enumerates motion types. + * + * @since 3.2 + */ enum HdfMotionTypeTag { + /** Pickup */ HDF_MOTION_TYPE_PICKUP = 0, + /** Flip */ HDF_MOTION_TYPE_FLIP, + /** Closing to the ear */ HDF_MOTION_CLOSE_TO_EAR, + /** Shaking */ HDF_MOTION_TYPE_SHAKE, + /** Screen rotation */ HDF_MOTION_TYPE_ROTATION, + /** Pocket mode */ HDF_MOTION_TYPE_POCKET_MODE, + /** Taking away from the ear */ HDF_MOTION_TYPE_LEAVE_EAR, + /** Wrist-up */ HDF_MOTION_TYPE_WRIST_UP, + /** Wrist-down */ HDF_MOTION_TYPE_WRIST_DOWN, + /** Maximum motion type */ HDF_MOTION_TYPE_MAX, }; +/** + * @brief Defines the motion event data structure. + * + * The motion event data includes the motion type, motion result, motion status, length of motion data, and motion data. + * + * @since 3.2 + */ struct HdfMotionEvent { + /** Provides the motion type. */ int motion; + /** Provides the motion result. */ int result; + /** Provides the motion status. */ int status; + /** Provides the length of motion data. */ int datalen; + /** Provides the motion data. */ int [] data; -}; \ No newline at end of file +}; +/** @} */ -- Gitee