From 44dcf4b0947ed514b78ab313ffd76c2a5ad4682d Mon Sep 17 00:00:00 2001 From: cheerful_ricky Date: Fri, 24 Apr 2026 17:27:08 +0800 Subject: [PATCH] =?UTF-8?q?CAPI=E4=B8=80=E8=87=B4=E6=80=A7=E5=9B=9E?= =?UTF-8?q?=E5=88=B7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: cheerful_ricky Change-Id: I0e9014506067b99bb2ac62a9e542a0aca56de76a --- BasicServicesKit/commonevent/oh_commonevent.h | 658 ++++++++------- .../commonevent/oh_commonevent_support.h | 219 +++-- .../commonevent/oh_commonevent.h | 786 ++++++++++++++++++ .../commonevent/oh_commonevent_support.h | 576 +++++++++++++ 4 files changed, 1814 insertions(+), 425 deletions(-) create mode 100644 zh-cn/BasicServicesKit/commonevent/oh_commonevent.h create mode 100644 zh-cn/BasicServicesKit/commonevent/oh_commonevent_support.h diff --git a/BasicServicesKit/commonevent/oh_commonevent.h b/BasicServicesKit/commonevent/oh_commonevent.h index 85d01cf4b..e97391d74 100644 --- a/BasicServicesKit/commonevent/oh_commonevent.h +++ b/BasicServicesKit/commonevent/oh_commonevent.h @@ -4,7 +4,7 @@ * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * - * http://www.apache.org/licenses/LICENSE-2.0 + * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, @@ -12,7 +12,17 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - +/** + * @file oh_commonevent.h + * + * @brief Defines the APIs for subscribing to and unsubscribing from common events and enumerates the error codes. + * + * @library libohcommonevent.so + * @kit BasicServicesKit + * @syscap SystemCapability.Notification.CommonEvent + * @since 12 + * @version 1.0 + */ /** * @addtogroup OH_CommonEvent * @{ @@ -21,17 +31,6 @@ * * @since 12 */ -/** - * @file oh_commonevent.h - * - * @brief Declares the APIs to subscribe and unsubscribe common event, and so on. - * - * @library libohcommonevent.so - * @kit BasicServicesKit - * @syscap SystemCapability.Notification.CommonEvent - * @since 12 - * @version 1.0 - */ #ifndef OH_COMMONEVENT_H #define OH_COMMONEVENT_H @@ -44,700 +43,743 @@ extern "C" { #endif /** - * @brief Defines error codes. + * @brief Enumerates the error codes. * * @since 12 * @version 1.0 */ typedef enum CommonEvent_ErrCode { - /** @error Execution successful. */ + /** + * Operation successful. + * + * @since 12 + */ COMMONEVENT_ERR_OK = 0, - /** @error permission verification failed. */ + /** + * Permission denied. + * + * @since 12 + */ COMMONEVENT_ERR_PERMISSION_ERROR = 201, - /** @error invalid input parameter. */ + /** + * Invalid parameter. + * + * @since 12 + */ COMMONEVENT_ERR_INVALID_PARAMETER = 401, /** - * @error The common event send frequency too high. + * Event sending frequency is too high. * * @since 20 */ COMMONEVENT_ERR_SENDING_LIMIT_EXCEEDED = 1500003, - /** @error the application cannot send system common events. */ + /** + * The third-party application fails to send system common events. + * + * @since 12 + */ COMMONEVENT_ERR_NOT_SYSTEM_SERVICE = 1500004, - /** @error IPC request failed to send. */ + /** + * Failed to send IPC requests. + * + * @since 12 + */ COMMONEVENT_ERR_SENDING_REQUEST_FAILED = 1500007, - /** @error Common event service not init. */ + /** + * Services not initialized. + * + * @since 12 + */ COMMONEVENT_ERR_INIT_UNDONE = 1500008, - /** @error Failed to obtain system parameters. */ + /** + * System error. + * + * @since 12 + */ COMMONEVENT_ERR_OBTAIN_SYSTEM_PARAMS = 1500009, - /** @error The subscriber number exceed system specification */ + /** + * The number of subscribers exceeds the upper limit. + * + * @since 12 + */ COMMONEVENT_ERR_SUBSCRIBER_NUM_EXCEEDED = 1500010, - /** @error A memory allocation error occurs. */ + /** + * Failed to allocate memory. + * + * @since 12 + */ COMMONEVENT_ERR_ALLOC_MEMORY_FAILED = 1500011, } CommonEvent_ErrCode; /** - * @brief the information of the subscriber + * @brief Defines a struct for the subscriber information. * * @since 12 */ typedef struct CommonEvent_SubscribeInfo CommonEvent_SubscribeInfo; /** - * @brief the subscriber of common event + * @brief Defines a handle for the subscriber. * * @since 12 */ typedef void CommonEvent_Subscriber; /** - * @brief the common event publish information containing content and attributes of the common event + * @brief Defines the property object used for publishing a common event. * * @since 18 */ typedef struct CommonEvent_PublishInfo CommonEvent_PublishInfo; /** - * @brief the data of the commonEvent callback + * @brief Defines a struct for the common event data. * * @since 12 */ typedef struct CommonEvent_RcvData CommonEvent_RcvData; /** - * @brief The description of the parameters in a common event callback data. + * @brief Defines a handler for the additional information of a common event. * * @since 12 */ typedef void CommonEvent_Parameters; /** - * @brief Common event callback. + * @brief Defines the callback function of a common event. * - * @param data common event callback data. + * @param data Pointer to the callback data of a common event. * @since 12 */ typedef void (*CommonEvent_ReceiveCallback)(const CommonEvent_RcvData *data); /** - * @brief Create subscribe information. + * @brief Creates the subscriber information. * * @param events Indicates the subscribed events. - * @param eventsNum Indicates the subscribed events of number. - * @return Returns the CommonEvent_SubscribeInfo, if allocate memory failed, returns null. + * @param eventsNum Number of common events to subscribe. + * @return Returns the subscriber information created if the operation is successful; returns **NULL** otherwise. * @since 12 */ CommonEvent_SubscribeInfo* OH_CommonEvent_CreateSubscribeInfo(const char* events[], int32_t eventsNum); /** - * @brief Set the permission of the subscribe information. + * @brief Sets the permission of the publisher. * - * @param info Indicates the subscribe information. - * @param permission Indicates the permission. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. + * @param info Pointer to the subscriber information. + * @param permission Pointer to the permission name. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. * @since 12 */ CommonEvent_ErrCode OH_CommonEvent_SetPublisherPermission(CommonEvent_SubscribeInfo* info, const char* permission); /** - * @brief Set the bundleName of the subscribe information. + * @brief Sets a bundle name of the publisher. * - * @param info Indicates the subscribed events. - * @param bundleName Indicates the bundleName. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. + * @param info Pointer to the subscriber information. + * @param bundleName Pointer to the bundle name. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. * @since 12 */ CommonEvent_ErrCode OH_CommonEvent_SetPublisherBundleName(CommonEvent_SubscribeInfo* info, const char* bundleName); /** - * @brief Destroy the subscribe information. + * @brief Destroys the subscriber information. * - * @param info Indicates the subscribe info. + * @param info Pointer to the subscriber information. * @since 12 */ void OH_CommonEvent_DestroySubscribeInfo(CommonEvent_SubscribeInfo* info); /** - * @brief Create a subscriber. + * @brief Creates a subscriber. * - * @param info Indicates the created subscribe Info. - * @param callback Indicates the received common event callback. - * @return Returns the CommonEvent_Subscriber, if allocate memory failed, returns null. + * @param info Pointer to the subscriber information. + * @param callback Callback to be invoked when a common event is triggered. + * @return Returns the subscriber created if the operation is successful; returns **NULL** otherwise. * @since 12 */ CommonEvent_Subscriber* OH_CommonEvent_CreateSubscriber(const CommonEvent_SubscribeInfo* info, CommonEvent_ReceiveCallback callback); /** - * @brief Destroy the subscriber. + * @brief Destroys a subscriber. * - * @param subscriber Indicates the created subscriber. + * @param subscriber Pointer to the common event subscriber. * @since 12 */ void OH_CommonEvent_DestroySubscriber(CommonEvent_Subscriber* subscriber); /** - * @brief Subscribe event by a subscriber. + * @brief Subscribes to a common event. * - * @param subscriber Indicates the subscriber. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER } if the input parameter is invalid. - * Returns {@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED } if IPC request failed to send. - * Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done. - * Returns {@link COMMONEVENT_ERR_SUBSCRIBER_NUM_EXCEEDED } if the subscriber number is exceeded. - * Returns {@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED } if a memory allocation error occurs. + * @param subscriber Pointer to the common event subscriber. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. + *
{@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED}: Failed to send IPC requests. + *
{@link COMMONEVENT_ERR_INIT_UNDONE}: The common event service is not initialized. + *
{@link COMMONEVENT_ERR_SUBSCRIBER_NUM_EXCEEDED}: The number of subscribers exceeds 200. + *
{@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED}: Failed to allocate memory. * @since 12 */ CommonEvent_ErrCode OH_CommonEvent_Subscribe(const CommonEvent_Subscriber* subscriber); /** - * @brief Unsubscribe event by a subscriber. + * @brief Unsubscribes from a common event. * - * @param subscriber Indicates the subscriber. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER } if the input parameter is invalid. - * Returns {@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED } if IPC request failed to send. - * Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done. + * @param subscriber Pointer to the common event subscriber. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. + *
{@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED}: Failed to send IPC requests. + *
{@link COMMONEVENT_ERR_INIT_UNDONE}: The common event service is not initialized. * @since 12 */ CommonEvent_ErrCode OH_CommonEvent_UnSubscribe(const CommonEvent_Subscriber* subscriber); /** - * @brief Get event name from callback data. + * @brief Obtains the name of a common event. * - * @param rcvData Indicates the callback data. - * @return Returns the event name. + * @param rcvData Pointer to the callback data of a common event. + * @return Event name obtained. * @since 12 */ const char* OH_CommonEvent_GetEventFromRcvData(const CommonEvent_RcvData* rcvData); /** - * @brief Get event code from callback data. + * @brief Obtains the result code (integer type) of a common event. * - * @param rcvData Indicates the callback data. - * @return Returns the event of code, default is 0. + * @param rcvData Pointer to the callback data of a common event. + * @return Result code obtained. * @since 12 */ int32_t OH_CommonEvent_GetCodeFromRcvData(const CommonEvent_RcvData* rcvData); /** - * @brief Get event data from callback data. + * @brief Obtains the result data (string type) of a common event. * - * @param rcvData Indicates the callback data. - * @return Returns the event of data, default is null. + * @param rcvData Pointer to the callback data of a common event. + * @return Result data obtained. * @since 12 */ const char* OH_CommonEvent_GetDataStrFromRcvData(const CommonEvent_RcvData* rcvData); /** - * @brief Get event bundlename from callback data. + * @brief Obtains the bundle name of a common event. * - * @param rcvData Indicates the callback data. - * @return Returns the event of bundlename, default is null. + * @param rcvData Pointer to the callback data of a common event. + * @return Bundle name obtained. * @since 12 */ const char* OH_CommonEvent_GetBundleNameFromRcvData(const CommonEvent_RcvData* rcvData); /** - * @brief Get event parameters data from callback data. + * @brief Obtains the additional information of a common event. * - * @param rcvData Indicates the callback data. - * @return Returns the event parameters data, default is null. + * @param rcvData Pointer to the callback data of a common event. + * @return Additional information obtained. * @since 12 */ const CommonEvent_Parameters* OH_CommonEvent_GetParametersFromRcvData(const CommonEvent_RcvData* rcvData); /** - * @brief Create a common event publish information. + * @brief Creates a property object of a common event. * - * @param ordered Indicates whether the common event is ordered. - * @return Returns the CommonEvent_PublishInfo, if create failed, returns null. + * @param ordered Whether the common event is an ordered one. + *
**true**: ordered common event. + *
**false**: unordered common event. + * @return Returns the property object if the operation is successful; returns **null** otherwise. * @since 18 */ CommonEvent_PublishInfo* OH_CommonEvent_CreatePublishInfo(bool ordered); /** - * @brief Destroy the common event publish information. + * @brief Destroys a property object of a common event. * - * @param info Indicates the publish information. + * @param info Pointer to the property object of the common event to destroy. * @since 18 */ void OH_CommonEvent_DestroyPublishInfo(CommonEvent_PublishInfo* info); /** - * @brief Set the bundleName of publish information. + * @brief Sets the bundle name of a common event. * - * @param info Indicates the publish information. - * @param bundleName Indicates the bundleName. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. + * @param info Pointer to the property object of a common event. + * @param bundleName Pointer to the bundle name to set. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoBundleName(CommonEvent_PublishInfo* info, const char* bundleName); /** - * @brief Set the permissions of publish information. + * @brief Sets permissions for a common event. * - * @param info Indicates the publish information. + * @param info Pointer to the property object of a common event. * @param permissions Indicates the array of permissions. - * @param num Indicates the count of permissions. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. + * @param num Number of permissions. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoPermissions(CommonEvent_PublishInfo* info, const char* permissions[], int32_t num); /** - * @brief Set the code of publish information. + * @brief Sets the result code (integer type) of a common event. * - * @param info Indicates the publish information. - * @param code Indicates the code. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. + * @param info Pointer to the property object of a common event. + * @param code Result code to set. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoCode(CommonEvent_PublishInfo* info, int32_t code); /** - * @brief Set the data of publish information. + * @brief Sets the result data (string type) of a common event. * - * @param info Indicates the publish information. - * @param data Indicates the data. - * @param length Indicates the length of data. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. + * @param info Pointer to the property object of a common event. + * @param data Pointer to the result data to set. The effective data length is the smaller of **length** and + * the length of the **data** string. + * @param length Length of the result data. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoData(CommonEvent_PublishInfo* info, const char* data, size_t length); /** - * @brief Set the parameters of publish information. + * @brief Sets the additional information of a common event. * - * @param info Indicates the publish information. - * @param param Indicates the parameters. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. + * @param info Pointer to the property object of a common event. + * @param param Pointer to the additional information to set. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoParameters(CommonEvent_PublishInfo* info, CommonEvent_Parameters* param); /** - * @brief Create a common event publish information. + * @brief Creates an additional information object of a common event. * - * @return Returns the CommonEvent_PublishInfo, if create failed, returns null. + * @return Returns additional information of the common event if operation is successful; returns **null** otherwise. * @since 18 */ CommonEvent_Parameters* OH_CommonEvent_CreateParameters(); /** - * @brief Destroy the common event publish information. + * @brief Destroys the additional information object of a common event. * - * @param param Indicates the publish information. + * @param param Pointer to the additional information to destroy. * @since 18 */ void OH_CommonEvent_DestroyParameters(CommonEvent_Parameters* param); /** - * @brief Check whether the parameters data contains a key. + * @brief Checks whether the additional information of a common event contains a KV pair. * - * @param para Indicates the parameters data. - * @param key Indicates the key. - * @return Returns the result of check, true means it contains. + * @param para Pointer to the additional information to check. + * @param key Pointer to the key. + * @return Returns the check result. + *
**true**: The key exists. + *
**false**: The key does not exist. * @since 12 */ bool OH_CommonEvent_HasKeyInParameters(const CommonEvent_Parameters* para, const char* key); /** - * @brief Get int data from parameters data by key. + * @brief Obtains the int data with a specific key from the additional information of a common event. * - * @param para Indicates the parameters data. - * @param key Indicates the key. - * @param defaultValue Indicates default return value. - * @return Returns the int data of the key in the parameters. + * @param para Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param defaultValue Default value. + * @return The int data obtained. * @since 12 */ int OH_CommonEvent_GetIntFromParameters(const CommonEvent_Parameters* para, const char* key, const int defaultValue); /** - * @brief Set int data to parameters data by key. + * @brief Sets the int data with a specific key for the additional information of a common event. * - * @param param Indicates the parameters data. - * @param key Indicates the key. - * @param value Indicates the int data. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. + * @param param Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param value The int data to set. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetIntToParameters(CommonEvent_Parameters* param, const char* key, int value); /** - * @brief Get int array data from parameters data by key. + * @brief Obtains the int array with a specific key from the additional information of a common event. * - * @param para Indicates the parameters data. - * @param key Indicates the key. - * @param array Indicates the int array. - * @return Returns the length of the array. + * @param para Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param array Double pointer to the int array to obtain. + * @return Length of the array obtained. The default value is **0**. * @since 12 */ int32_t OH_CommonEvent_GetIntArrayFromParameters(const CommonEvent_Parameters* para, const char* key, int** array); /** - * @brief Set int array data to parameters data by key. + * @brief Sets the int array with a specific key for the additional information of a common event. * - * @param param Indicates the parameters data. - * @param key Indicates the key. - * @param value Indicates the int array data. - * @param num Indicates the length of the array. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. - * Returns {@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED} if a memory allocation error occurs. + * @param param Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param value The int array to set. + * @param num Number of elements in the int array. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. + *
{@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED}: Failed to allocate memory. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetIntArrayToParameters(CommonEvent_Parameters* param, const char* key, const int* value, size_t num); /** - * @brief Get long data from parameters data by key. + * @brief Obtains the long data with a specific key from the additional information of a common event. * - * @param para Indicates the parameters data. - * @param key Indicates the key. - * @param defaultValue Indicates default return value. - * @return Returns the long data of the key in the parameters. + * @param para Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param defaultValue Default value. + * @return The long data obtained. * @since 12 */ long OH_CommonEvent_GetLongFromParameters(const CommonEvent_Parameters* para, const char* key, const long defaultValue); /** - * @brief Set long data to parameters data by key. + * @brief Sets the long data with a specific key for the additional information of a common event. * - * @param param Indicates the parameters data. - * @param key Indicates the key. - * @param value Indicates the long data. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. + * @param param Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param value The long data to set. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetLongToParameters(CommonEvent_Parameters* param, const char* key, long value); /** - * @brief Get long array data from parameters data by key. + * @brief Obtains the long array with a specific key from the additional information of a common event. * - * @param para Indicates the parameters data. - * @param key Indicates the key. - * @param array Indicates the long array. - * @return Returns the length of the array. + * @param para Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param array Double pointer to the long array to obtain. + * @return Length of the array obtained. The default value is **0**. * @since 12 */ int32_t OH_CommonEvent_GetLongArrayFromParameters(const CommonEvent_Parameters* para, const char* key, long** array); /** - * @brief Set long array data to parameters data by key. + * @brief Sets the long array for the additional information of a common event. * - * @param param Indicates the parameters data. - * @param key Indicates the key. - * @param value Indicates the long array data. - * @param num Indicates the length of the array. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. - * Returns {@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED} if a memory allocation error occurs. + * @param param Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param value Pointer to the long array to set. + * @param num Number of elements in the long array. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. + *
{@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED}: Failed to allocate memory. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetLongArrayToParameters(CommonEvent_Parameters* param, const char* key, const long* value, size_t num); /** - * @brief Get bool data from parameters data by key. + * @brief Obtains the Boolean data with a specific key from the additional information of a common event. * - * @param para Indicates the parameters data. - * @param key Indicates the key. - * @param defaultValue Indicates default return value. - * @return Returns the bool data of the key in the parameters. + * @param para Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param defaultValue Default value. + * @return The Boolean data obtained. * @since 12 */ bool OH_CommonEvent_GetBoolFromParameters(const CommonEvent_Parameters* para, const char* key, const bool defaultValue); /** - * @brief Set bool data to parameters data by key. + * @brief Sets the Boolean data with a specific key for the additional information of a common event. * - * @param param Indicates the parameters data. - * @param key Indicates the key. - * @param value Indicates the bool data. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. + * @param param Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param value The Boolean data to set. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetBoolToParameters(CommonEvent_Parameters* param, const char* key, bool value); /** - * @brief Get bool array data from parameters data by key. + * @brief Obtains the Boolean array with a specific key from the additional information of a common event. * - * @param para Indicates the parameters data. - * @param key Indicates the key. - * @param array Indicates the bool array. - * @return Returns the length of the array. + * @param para Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param array Double pointer to the Boolean array to obtain. + * @return Length of the array obtained. The default value is **0**. * @since 12 */ int32_t OH_CommonEvent_GetBoolArrayFromParameters(const CommonEvent_Parameters* para, const char* key, bool** array); /** - * @brief Set bool array data to parameters data by key. + * @brief Sets the Boolean array with a specific key for the additional information of a common event. * - * @param param Indicates the parameters data. - * @param key Indicates the key. - * @param value Indicates the bool array data. - * @param num Indicates the length of the array. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. - * Returns {@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED} if a memory allocation error occurs. + * @param param Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param value Pointer to the Boolean array to set. + * @param num Number of elements in the Boolean array. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. + *
{@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED}: Failed to allocate memory. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetBoolArrayToParameters(CommonEvent_Parameters* param, const char* key, const bool* value, size_t num); /** - * @brief Get char data from parameters data by key. + * @brief Obtains the character data with a specific key from the additional information of a common event. * - * @param para Indicates the parameters data. - * @param key Indicates the key. - * @param defaultValue Indicates default return value. - * @return Returns the char data of the key in the parameters. + * @param para Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param defaultValue Default value. + * @return The character data obtained. * @since 12 */ char OH_CommonEvent_GetCharFromParameters(const CommonEvent_Parameters* para, const char* key, const char defaultValue); /** - * @brief Set char data to parameters data by key. + * @brief Sets the character data with a specific key for the additional information of a common event. * - * @param param Indicates the parameters data. - * @param key Indicates the key. - * @param value Indicates the char data. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. + * @param param Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param value The character data to set. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetCharToParameters(CommonEvent_Parameters* param, const char* key, char value); /** - * @brief Get char array data from parameters data by key. + * @brief Obtains the character array with a specific key from the additional information of a common event. * - * @param para Indicates the parameters data. - * @param key Indicates the key. - * @param array Indicates the char array. - * @return Returns the length of the array. + * @param para Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param array Double pointer to the character array to obtain. + * @return Length of the array obtained. The default value is **0**. * @since 12 */ int32_t OH_CommonEvent_GetCharArrayFromParameters(const CommonEvent_Parameters* para, const char* key, char** array); /** - * @brief Set char array data to parameters data by key. + * @brief Sets the character array with a specific key for the additional information of a common event. * - * @param param Indicates the parameters data. - * @param key Indicates the key. - * @param value Indicates the char array data. - * @param num Indicates the length of the array. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. + * @param param Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param value Pointer to the character array to set. + * @param num Number of elements in the character array. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetCharArrayToParameters(CommonEvent_Parameters* param, const char* key, const char* value, size_t num); /** - * @brief Get double data from parameters data by key. + * @brief Obtains the double data with a specific key from the additional information of a common event. * - * @param para Indicates the parameters data. - * @param key Indicates the key. - * @param defaultValue Indicates default return value. - * @return Returns the double data of the key in the parameters. + * @param para Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param defaultValue Default value. + * @return The double data obtained. * @since 12 */ double OH_CommonEvent_GetDoubleFromParameters(const CommonEvent_Parameters* para, const char* key, const double defaultValue); /** - * @brief Set double data to parameters data by key. + * @brief Sets the double data with a specific key for the additional information of a common event. * - * @param param Indicates the parameters data. - * @param key Indicates the key. - * @param value Indicates the double data. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. + * @param param Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param value The double data to set. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetDoubleToParameters(CommonEvent_Parameters* param, const char* key, double value); /** - * @brief Get double array data from parameters data by key. + * @brief Obtains the double array with a specific key from the additional information of a common event. * - * @param para Indicates the parameters data. - * @param key Indicates the key. - * @param array Indicates the double array. - * @return Returns the length of the array, default is 0. + * @param para Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param array Double pointer to the double array to obtain. + * @return Length of the array obtained. The default value is **0**. * @since 12 */ int32_t OH_CommonEvent_GetDoubleArrayFromParameters(const CommonEvent_Parameters* para, const char* key, double** array); /** - * @brief Set double array data to parameters data by key. + * @brief Sets the double array with a specific key for the additional information of a common event. * - * @param param Indicates the parameters data. - * @param key Indicates the key. - * @param value Indicates the double array data. - * @param num Indicates the length of the array. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. - * Returns {@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED} if a memory allocation error occurs. + * @param param Pointer to the additional information of a common event. + * @param key Pointer to the key. + * @param value Pointer to the double array to set. + * @param num Number of elements in the double array. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. + *
{@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED}: Failed to allocate memory. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_SetDoubleArrayToParameters(CommonEvent_Parameters* param, const char* key, const double* value, size_t num); /** - * @brief Publish a common event. + * @brief Publishes a common event. * - * @param event Indicates the name of the common event. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. - * Returns {@link COMMONEVENT_ERR_SENDING_LIMIT_EXCEEDED} if the common event sending frequency too high, - * add since api 20. - * Returns {@link COMMONEVENT_ERR_FAIL_SEND_REQUEST } if IPC request failed to send. - * Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done. + * @param event Pointer to the name of the common event. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. + *
{@link COMMONEVENT_ERR_SENDING_LIMIT_EXCEEDED}: Event sending frequency is too high. + *
{@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED}: Failed to send IPC requests. + *
{@link COMMONEVENT_ERR_INIT_UNDONE}: The common event service is not initialized. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_Publish(const char* event); /** - * @brief Publish a common event with specified publish information. + * @brief Publishes a common event with specified properties. * - * @param event Indicates the name of the common event. - * @param info Indicates the publish information. - * @return Returns the error code. - * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. - * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. - * Returns {@link COMMONEVENT_ERR_SENDING_LIMIT_EXCEEDED} if the common event sending frequency too high, - * add since api 20. - * Returns {@link COMMONEVENT_ERR_FAIL_SEND_REQUEST } if IPC request failed to send. - * Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done. + * @param event Pointer to the name of the common event. + * @param info Pointer to the property object of a common event. + * @return Returns an execution result. + *
{@link COMMONEVENT_ERR_OK}: Operation is successful. + *
{@link COMMONEVENT_ERR_INVALID_PARAMETER}: The parameter is invalid. + *
{@link COMMONEVENT_ERR_SENDING_LIMIT_EXCEEDED}: Event sending frequency is too high. + *
{@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED}: Failed to send IPC requests. + *
{@link COMMONEVENT_ERR_INIT_UNDONE}: The common event service is not initialized. * @since 18 */ CommonEvent_ErrCode OH_CommonEvent_PublishWithInfo(const char* event, const CommonEvent_PublishInfo* info); /** - * @brief Check an event by a subscriber whether it is ordered. + * @brief Checks whether a common event is an ordered one. * - * @param subscriber Indicates the subscriber. - * @return Returns the result of check, true means ordered. + * @param subscriber Pointer to the common event subscriber. + * @return Returns **true** if the common event is an ordered one; returns **false** if the common event is an + * unordered one. * @since 18 */ bool OH_CommonEvent_IsOrderedCommonEvent(const CommonEvent_Subscriber* subscriber); /** - * @brief Finish an ordered event by a subscriber. + * @brief Finishes an ordered common event. * - * @param subscriber Indicates the subscriber. - * @return Returns the result of operation, true means succeeded. + * @param subscriber Pointer to the common event subscriber. + * @return Returns **true** if the operation is successful; returns **false** otherwise. * @since 18 */ bool OH_CommonEvent_FinishCommonEvent(CommonEvent_Subscriber* subscriber); /** - * @brief Check an event by a subscriber whether it is aborted. + * @brief Checks whether an ordered common event is aborted. * - * @param subscriber Indicates the subscriber. - * @return Returns the result of check, true means aborted. + * @param subscriber Pointer to the common event subscriber. + * @return Returns **true** if the ordered common event is in the abort state; returns **false** otherwise. * @since 18 */ bool OH_CommonEvent_GetAbortCommonEvent(const CommonEvent_Subscriber* subscriber); /** - * @brief Abort an ordered event by a subscriber. + * @brief Aborts an ordered common event when used with {@link OH_CommonEvent_FinishCommonEvent}. After the abort, the + * common event is not sent to the next subscriber. * - * @param subscriber Indicates the subscriber. - * @return Returns the result of operation, true means succeeded. + * @param subscriber Pointer to the common event subscriber. + * @return Returns **true** if the operation is successful; returns **false** otherwise. * @since 18 */ bool OH_CommonEvent_AbortCommonEvent(CommonEvent_Subscriber* subscriber); /** - * @brief Clear the aborted flag of an ordered event by a subscriber. + * @brief Clears the abort state of an ordered common event when used with {@link OH_CommonEvent_FinishCommonEvent}. + * After the clearance, the common event is sent to the next subscriber. * - * @param subscriber Indicates the subscriber. - * @return Returns the result of operation, true means succeeded. + * @param subscriber Pointer to the common event subscriber. + * @return Returns **true** if the operation is successful; returns **false** otherwise. * @since 18 */ bool OH_CommonEvent_ClearAbortCommonEvent(CommonEvent_Subscriber* subscriber); /** - * @brief Get code from an ordered event by a subscriber. + * @brief Obtains the result code (integer type) of an ordered common event. * - * @param subscriber Indicates the subscriber. - * @return Returns the code, default is 0. + * @param subscriber Pointer to the common event subscriber. + * @return Returns the result code obtained if the operation is successful; returns **0** otherwise. * @since 18 */ int32_t OH_CommonEvent_GetCodeFromSubscriber(const CommonEvent_Subscriber* subscriber); /** - * @brief Set code to an ordered event by a subscriber. + * @brief Sets the result code (integer type) of an ordered common event. * - * @param subscriber Indicates the subscriber. - * @param code Indicates the code. - * @return Returns the result of operation, true means succeeded. + * @param subscriber Pointer to the common event subscriber. + * @param code Result code to set. + * @return Returns **true** if the operation is successful; returns **false** otherwise. * @since 18 */ bool OH_CommonEvent_SetCodeToSubscriber(CommonEvent_Subscriber* subscriber, int32_t code); /** - * @brief Get data from an ordered event by a subscriber. + * @brief Obtains the result data (string type) of an ordered common event. * - * @param subscriber Indicates the subscriber. - * @return Returns the data, default is null. + * @param subscriber Pointer to the common event subscriber. + * @return Returns the result data obtained if the operation is successful; returns **null** otherwise. * @since 18 */ const char* OH_CommonEvent_GetDataFromSubscriber(const CommonEvent_Subscriber* subscriber); /** - * @brief Set data to an ordered event by a subscriber. + * @brief Sets the result data (string type) of an ordered common event. * - * @param subscriber Indicates the subscriber. - * @param data Indicates the data. - * @param length Indicates the length of data. - * @return Returns the result of operation, true means succeeded. + * @param subscriber Pointer to the common event subscriber. + * @param data Pointer to the result data to set. The effective data length is the smaller of **length** and + * the length of the **data** string + * @param length Data length. + * @return Returns **true** if the operation is successful; returns **false** otherwise. * @since 18 */ bool OH_CommonEvent_SetDataToSubscriber(CommonEvent_Subscriber* subscriber, const char* data, size_t length); @@ -746,4 +788,4 @@ bool OH_CommonEvent_SetDataToSubscriber(CommonEvent_Subscriber* subscriber, cons } #endif #endif // OH_COMMONEVENT_H -/** @} */ +/** @} */ \ No newline at end of file diff --git a/BasicServicesKit/commonevent/oh_commonevent_support.h b/BasicServicesKit/commonevent/oh_commonevent_support.h index c049b7adb..38ad00d53 100644 --- a/BasicServicesKit/commonevent/oh_commonevent_support.h +++ b/BasicServicesKit/commonevent/oh_commonevent_support.h @@ -1,10 +1,11 @@ + /* * Copyright (c) 2024 Huawei Device Co., Ltd. * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * - * http://www.apache.org/licenses/LICENSE-2.0 + * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, @@ -13,6 +14,18 @@ * limitations under the License. */ +/** + * @file oh_commonevent_support.h + * + * @brief Provides common event constants defined by the system. + * + * @library libohcommonevent.so + * @kit BasicServicesKit + * @syscap SystemCapability.Notification.CommonEvent + * @since 12 + * @version 1.0 + */ + /** * @addtogroup OH_CommonEvent * @{ @@ -21,233 +34,224 @@ * * @since 12 */ -/** - * @file oh_commonevent_support.h - * - * @brief Declares the constants of system-defined common event. - * - * @library libohcommonevent.so - * @kit BasicServicesKit - * @syscap SystemCapability.Notification.CommonEvent - * @since 12 - * @version 1.0 - */ - #ifndef OH_COMMONEVENT_SUPPORT_H #define OH_COMMONEVENT_SUPPORT_H - #include - #ifdef __cplusplus extern "C" { #endif /** - * @brief This commonEvent means when the device is shutting down, note: turn off, not sleeping. + * @brief Indicates the common event that the device is being shut down and the final shutdown will proceed. * * @since 12 */ static const char* const COMMON_EVENT_SHUTDOWN = "usual.event.SHUTDOWN"; /** - * @brief This commonEvent means when the charging state, level and so on about the battery. + * @brief Indicates the common event that the charging state, level, and other information about the battery have + * changed. * * @since 12 */ static const char* const COMMON_EVENT_BATTERY_CHANGED = "usual.event.BATTERY_CHANGED"; /** - * @brief This commonEvent means when the device in low battery state. + * @brief Indicates the common event that the battery level is low. * * @since 12 */ static const char* const COMMON_EVENT_BATTERY_LOW = "usual.event.BATTERY_LOW"; /** - * @brief This commonEvent means when the battery level is an ok state. + * @brief Indicates the common event that the battery exits the low state. * * @since 12 */ static const char* const COMMON_EVENT_BATTERY_OKAY = "usual.event.BATTERY_OKAY"; /** - * @brief This commonEvent means when the other power is connected to the device. + * @brief Indicates the common event that the device is connected to an external power supply. * * @since 12 */ static const char* const COMMON_EVENT_POWER_CONNECTED = "usual.event.POWER_CONNECTED"; /** - * @brief This commonEvent means when the other power is removed from the device. + * @brief Indicates the common event that the device is disconnected from the external power supply. * * @since 12 */ static const char* const COMMON_EVENT_POWER_DISCONNECTED = "usual.event.POWER_DISCONNECTED"; /** - * @brief This commonEvent means when the screen is turned off. + * @brief Indicates the common event that the device screen is off and the device is sleeping. * * @since 12 */ static const char* const COMMON_EVENT_SCREEN_OFF = "usual.event.SCREEN_OFF"; /** - * @brief This commonEvent means when the device is awakened and interactive. + * @brief Indicates the common event that the device screen is on and the device is in interactive state. * * @since 12 */ static const char* const COMMON_EVENT_SCREEN_ON = "usual.event.SCREEN_ON"; /** - * @brief This commonEvent means when the device is about to enter the hibernate mode. + * @brief Indicates the common event that the device is about to enter the hibernation mode. * * @since 15 */ static const char* const COMMON_EVENT_ENTER_HIBERNATE = "usual.event.ENTER_HIBERNATE"; /** - * @brief This commonEvent means when the device exits the hibernate mode. + * @brief Indicates the common event that the device exits the hibernation mode. * * @since 15 */ static const char* const COMMON_EVENT_EXIT_HIBERNATE = "usual.event.EXIT_HIBERNATE"; /** - * @brief This commonEvent means when the thermal state level change + * @brief Indicates the common event that the device's thermal level has changed. * * @since 12 */ static const char* const COMMON_EVENT_THERMAL_LEVEL_CHANGED = "usual.event.THERMAL_LEVEL_CHANGED"; /** - * @brief This commonEvent means when the current time is changed. + * @brief Indicates the common event that the system time has changed. * * @since 12 */ static const char* const COMMON_EVENT_TIME_TICK = "usual.event.TIME_TICK"; /** - * @brief This commonEvent means when the time is set. + * @brief Indicates the common event that the system time has been set. * * @since 12 */ static const char* const COMMON_EVENT_TIME_CHANGED = "usual.event.TIME_CHANGED"; /** - * @brief This commonEvent means when the time zone is changed. + * @brief Indicates the common event that the system time zone has changed. * * @since 12 */ static const char* const COMMON_EVENT_TIMEZONE_CHANGED = "usual.event.TIMEZONE_CHANGED"; /** - * @brief This commonEvent means when a new application package is installed on the device. + * @brief Indicates the common event that a new application package has been installed on the device. * * @since 12 */ static const char* const COMMON_EVENT_PACKAGE_ADDED = "usual.event.PACKAGE_ADDED"; /** - * @brief This commonEvent means when an existing application package is removed from the device. + * @brief Indicates the common event that an installed application has been uninstalled from the device with the + * application data retained. * * @since 12 */ static const char* const COMMON_EVENT_PACKAGE_REMOVED = "usual.event.PACKAGE_REMOVED"; /** - * @brief This commonEvent means when an installed application's add-on package is removed from the device. + * @brief Indicates the common event that an installed bundle has been uninstalled from the device with the application + * data retained. * * @since 12 */ static const char* const COMMON_EVENT_BUNDLE_REMOVED = "usual.event.BUNDLE_REMOVED"; /** - * @brief This commonEvent means when an existing application package is completely removed from the device. + * @brief Indicates the common event that an installed application, including both the application data and code, has + * been completely uninstalled from the device. * * @since 12 */ static const char* const COMMON_EVENT_PACKAGE_FULLY_REMOVED = "usual.event.PACKAGE_FULLY_REMOVED"; /** - * @brief This commonEvent means when an existing application package has been changed. + * @brief Indicates the common event that an application package has been changed (for example, a component in the + * package has been enabled or disabled). * * @since 12 */ static const char* const COMMON_EVENT_PACKAGE_CHANGED = "usual.event.PACKAGE_CHANGED"; /** - * @brief This commonEvent means the user has restarted a package, and all of its processes have been killed. + * @brief Indicates the common event that the user has restarted the application package and killed all its processes. * * @since 12 */ static const char* const COMMON_EVENT_PACKAGE_RESTARTED = "usual.event.PACKAGE_RESTARTED"; /** - * @brief This commonEvent means the user has cleared the package data. + * @brief Indicates the common event that the user cleared the application package data. * * @since 12 */ static const char* const COMMON_EVENT_PACKAGE_DATA_CLEARED = "usual.event.PACKAGE_DATA_CLEARED"; /** - * @brief This commonEvent means the user has cleared the package cache. + * @brief Indicates the common event that the user has cleared the application package data cache. * * @since 12 */ static const char* const COMMON_EVENT_PACKAGE_CACHE_CLEARED = "usual.event.PACKAGE_CACHE_CLEARED"; /** - * @brief This commonEvent means the packages have been suspended. + * @brief Indicates the common event that application packages have been suspended. * * @since 12 */ static const char* const COMMON_EVENT_PACKAGES_SUSPENDED = "usual.event.PACKAGES_SUSPENDED"; /** - * @brief This commonEvent Sent to a package that has been suspended by the system. + * @brief Indicates the common event that application packages are suspended. * * @since 12 */ static const char* const COMMON_EVENT_MY_PACKAGE_SUSPENDED = "usual.event.MY_PACKAGE_SUSPENDED"; /** - * @brief Sent to a package that has been un-suspended. + * @brief Indicates the common event that application packages have not been suspended. * * @since 12 */ static const char* const COMMON_EVENT_MY_PACKAGE_UNSUSPENDED = "usual.event.MY_PACKAGE_UNSUSPENDED"; /** - * @brief The current device's locale has changed. + * @brief Indicates the common event that the device locale has changed. * * @since 12 */ static const char* const COMMON_EVENT_LOCALE_CHANGED = "usual.event.LOCALE_CHANGED"; /** - * @brief Indicates low memory condition notification acknowledged by user and package - * management should be started. + * @brief Indicates the common event that the device storage is insufficient. * * @since 12 */ static const char* const COMMON_EVENT_MANAGE_PACKAGE_STORAGE = "usual.event.MANAGE_PACKAGE_STORAGE"; /** - * @brief Remind new user of that the service has been unlocked. + * @brief Indicates the common event that the credential-encrypted storage has been unlocked for the current user when + * the device is unlocked upon restart. * * @since 12 */ static const char* const COMMON_EVENT_USER_UNLOCKED = "usual.event.USER_UNLOCKED"; /** - * @brief Distributed account logout successfully. + * @brief Indicates the common event that a distributed account is successfully logged out. * * @since 12 */ static const char* const COMMON_EVENT_DISTRIBUTED_ACCOUNT_LOGOUT = "common.event.DISTRIBUTED_ACCOUNT_LOGOUT"; /** - * @brief Distributed account is invalid. + * @brief Indicates the common event that the token of a distributed account is invalid. * * @since 12 */ @@ -255,91 +259,92 @@ static const char* const COMMON_EVENT_DISTRIBUTED_ACCOUNT_TOKEN_INVALID = "common.event.DISTRIBUTED_ACCOUNT_TOKEN_INVALID"; /** - * @brief Distributed account logs off. + * @brief Indicates the common event that a distributed account is deregistered. * * @since 12 */ static const char* const COMMON_EVENT_DISTRIBUTED_ACCOUNT_LOGOFF = "common.event.DISTRIBUTED_ACCOUNT_LOGOFF"; /** - * @brief WIFI state. + * @brief Indicates the common event that the Wi-Fi state has changed to a new state, such as enabled or disabled. * * @since 12 */ static const char* const COMMON_EVENT_WIFI_POWER_STATE = "usual.event.wifi.POWER_STATE"; /** - * @brief WIFI scan results. + * @brief Indicates the common event that the Wi-Fi access point has been scanned and proven to be available. * * @since 12 */ static const char* const COMMON_EVENT_WIFI_SCAN_FINISHED = "usual.event.wifi.SCAN_FINISHED"; /** - * @brief WIFI RSSI change. + * @brief Indicates the common event that the Wi-Fi signal strength (RSSI) has changed. * * @since 12 */ static const char* const COMMON_EVENT_WIFI_RSSI_VALUE = "usual.event.wifi.RSSI_VALUE"; /** - * @brief WIFI connect state. + * @brief Indicates the common event that the Wi-Fi connection state has changed. * * @since 12 */ static const char* const COMMON_EVENT_WIFI_CONN_STATE = "usual.event.wifi.CONN_STATE"; /** - * @brief WIFI hotspot state. + * @brief Indicates the common event that the Wi-Fi hotspot state has changed to a new state, such as enabled or + * disabled. * * @since 12 */ static const char* const COMMON_EVENT_WIFI_HOTSPOT_STATE = "usual.event.wifi.HOTSPOT_STATE"; /** - * @brief WIFI ap sta join. + * @brief Indicates the common event that a client has joined the Wi-Fi hotspot of the current device. * * @since 12 */ static const char* const COMMON_EVENT_WIFI_AP_STA_JOIN = "usual.event.wifi.WIFI_HS_STA_JOIN"; /** - * @brief WIFI ap sta join. + * @brief Indicates the common event that a client has leave the Wi-Fi hotspot of the current device. * * @since 12 */ static const char* const COMMON_EVENT_WIFI_AP_STA_LEAVE = "usual.event.wifi.WIFI_HS_STA_LEAVE"; /** - * @brief Indicates Wi-Fi MpLink state notification acknowledged by binding or unbinding MpLink. + * @brief Indicates the common event that the state of MPLINK (an enhanced Wi-Fi feature) has changed. * * @since 12 */ static const char* const COMMON_EVENT_WIFI_MPLINK_STATE_CHANGE = "usual.event.wifi.mplink.STATE_CHANGE"; /** - * @brief Indicates Wi-Fi P2P connection state notification acknowledged by connecting or disconnected P2P. + * @brief Indicates the common event that the Wi-Fi P2P connection state has changed. * * @since 12 */ static const char* const COMMON_EVENT_WIFI_P2P_CONN_STATE = "usual.event.wifi.p2p.CONN_STATE_CHANGE"; /** - * @brief Indicates that the Wi-Fi P2P state change. + * @brief Indicates the common event that the Wi-Fi P2P state has changed to enabled or disabled. * * @since 12 */ static const char* const COMMON_EVENT_WIFI_P2P_STATE_CHANGED = "usual.event.wifi.p2p.STATE_CHANGE"; /** - * @brief Indicates that the Wi-Fi P2P peers state change. + * @brief Indicates the common event that the state of the Wi-Fi P2P peer device has changed. * * @since 12 */ static const char* const COMMON_EVENT_WIFI_P2P_PEERS_STATE_CHANGED = "usual.event.wifi.p2p.DEVICES_CHANGE"; /** - * @brief Indicates that the Wi-Fi P2P discovery state change. + * @brief Indicates the common event that the Wi-Fi P2P discovery state has changed. * * @since 12 */ @@ -347,7 +352,7 @@ static const char* const COMMON_EVENT_WIFI_P2P_PEERS_DISCOVERY_STATE_CHANGED = "usual.event.wifi.p2p.PEER_DISCOVERY_STATE_CHANGE"; /** - * @brief Indicates that the Wi-Fi P2P current device state change. + * @brief Indicates the common event that the state of the Wi-Fi P2P local device has changed. * * @since 12 */ @@ -355,240 +360,220 @@ static const char* const COMMON_EVENT_WIFI_P2P_CURRENT_DEVICE_STATE_CHANGED = "usual.event.wifi.p2p.CURRENT_DEVICE_CHANGE"; /** - * @brief Indicates that the Wi-Fi P2P group info is changed. + * @brief Indicates the common event that the Wi-Fi P2P group information has changed. * * @since 12 */ static const char* const COMMON_EVENT_WIFI_P2P_GROUP_STATE_CHANGED = "usual.event.wifi.p2p.GROUP_STATE_CHANGED"; /** - * @brief Nfc state change. + * @brief Indicates the common event that the state of the device NFC adapter has changed. * * @since 12 */ static const char* const COMMON_EVENT_NFC_ACTION_ADAPTER_STATE_CHANGED = "usual.event.nfc.action.ADAPTER_STATE_CHANGED"; /** - * @brief Nfc field on detected. + * @brief Indicates the common event that the NFC RF field is on. * * @since 12 */ static const char* const COMMON_EVENT_NFC_ACTION_RF_FIELD_ON_DETECTED = "usual.event.nfc.action.RF_FIELD_ON_DETECTED"; /** - * @brief Nfc field off detected. + * @brief Indicates the common event that the NFC RF field is off. * * @since 12 */ static const char* const COMMON_EVENT_NFC_ACTION_RF_FIELD_OFF_DETECTED = "usual.event.nfc.action.RF_FIELD_OFF_DETECTED"; /** - * @brief Sent when stop charging battery. + * @brief Indicates the common event that the system stops charging the battery. * * @since 12 */ static const char* const COMMON_EVENT_DISCHARGING = "usual.event.DISCHARGING"; /** - * @brief Sent when start charging battery. + * @brief Indicates the common event that the system starts charging the battery. * * @since 12 */ static const char* const COMMON_EVENT_CHARGING = "usual.event.CHARGING"; /** - * @brief Sent when device's idle mode changed + * @brief Indicates the common event that the system standby mode has changed. * * @since 12 */ static const char* const COMMON_EVENT_DEVICE_IDLE_MODE_CHANGED = "usual.event.DEVICE_IDLE_MODE_CHANGED"; /** - * @brief Sent when device's charge idle mode changed. + * @brief Indicates the common event that the device enters the charging idle mode. * * @since 12 */ static const char* const COMMON_EVENT_CHARGE_IDLE_MODE_CHANGED = "usual.event.CHARGE_IDLE_MODE_CHANGED"; /** - * @brief Sent when device's power save mode changed + * @brief Indicates the common event that the system power saving mode is changed. * * @since 12 */ static const char* const COMMON_EVENT_POWER_SAVE_MODE_CHANGED = "usual.event.POWER_SAVE_MODE_CHANGED"; /** - * @brief The usb state change events. - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that the USB device state has changed. * * @since 12 */ static const char* const COMMON_EVENT_USB_STATE = "usual.event.hardware.usb.action.USB_STATE"; /** - * @brief The usb port changed. - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that the USB port state of the user device has changed. * * @since 12 */ static const char* const COMMON_EVENT_USB_PORT_CHANGED = "usual.event.hardware.usb.action.USB_PORT_CHANGED"; /** - * @brief The usb device attached. - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that a USB device has been attached when the user device functions as a USB host. * * @since 12 */ static const char* const COMMON_EVENT_USB_DEVICE_ATTACHED = "usual.event.hardware.usb.action.USB_DEVICE_ATTACHED"; /** - * @brief The usb device detached. - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that a USB device has been detached when the user device functions as a USB host. * * @since 12 */ static const char* const COMMON_EVENT_USB_DEVICE_DETACHED = "usual.event.hardware.usb.action.USB_DEVICE_DETACHED"; /** - * @brief Indicates the common event Action indicating that the airplane mode status of the device changes. - * Users can register this event to listen to the change of the airplane mode status of the device. + * @brief Indicates the common event that the airplane mode of a device has changed. * * @since 12 */ static const char* const COMMON_EVENT_AIRPLANE_MODE_CHANGED = "usual.event.AIRPLANE_MODE"; /** - * @brief sent by the window manager service when the window mode is split. + * @brief Indicates the common event of screen splitting. * * @since 12 */ static const char* const COMMON_EVENT_SPLIT_SCREEN = "common.event.SPLIT_SCREEN"; /** - * @brief Indicate the result of quick fix apply. - * This common event can be triggered only by system. + * @brief Indicates the common event that a quick fix is applied to an application. * * @since 12 */ static const char* const COMMON_EVENT_QUICK_FIX_APPLY_RESULT = "usual.event.QUICK_FIX_APPLY_RESULT"; /** - * @brief Indicate the result of quick fix revoke. - * This common event can be triggered only by system. + * @brief Indicates the common event that a quick fix is revoked. * * @since 12 */ static const char* const COMMON_EVENT_QUICK_FIX_REVOKE_RESULT = "usual.event.QUICK_FIX_REVOKE_RESULT"; /** - * @brief Indicate the action of a common event that the user information has been updated. - * This common event can be triggered only by system. + * @brief Indicates the common event that the user information has been updated. * * @since 12 */ static const char* const COMMON_EVENT_USER_INFO_UPDATED = "usual.event.USER_INFO_UPDATED"; /** - * @brief Indicates the action of a common event that the phone SIM card state has changed. - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that the SIM card state has been updated. * * @since 12 */ static const char* const COMMON_EVENT_SIM_STATE_CHANGED = "usual.event.SIM_STATE_CHANGED"; /** - * @brief Indicates the action of a common event that the call state has been changed. + * @brief Indicates the common event that the call state has been updated. + * * To subscribe to this protected common event, your application must have the ohos.permission.GET_TELEPHONY_STATE * permission. - * This is a protected common event that can only be sent by system. * * @since 12 */ static const char* const COMMON_EVENT_CALL_STATE_CHANGED = "usual.event.CALL_STATE_CHANGED"; /** - * @brief Indicates the action of a common event that the network state has been changed. - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that the network state has been updated. * * @since 12 */ static const char* const COMMON_EVENT_NETWORK_STATE_CHANGED = "usual.event.NETWORK_STATE_CHANGED"; /** - * @brief Indicates the action of a common event that the signal info has been changed. - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that the signal information has been updated. * * @since 12 */ static const char* const COMMON_EVENT_SIGNAL_INFO_CHANGED = "usual.event.SIGNAL_INFO_CHANGED"; /** - * @brief This commonEvent means when the screen is unlocked. + * @brief Indicates the common event that the screen has been unlocked. * * @since 12 */ static const char* const COMMON_EVENT_SCREEN_UNLOCKED = "usual.event.SCREEN_UNLOCKED"; /** - * @brief This commonEvent means when the screen is locked. + * @brief Indicates the common event that the screen has been locked. * * @since 12 */ static const char* const COMMON_EVENT_SCREEN_LOCKED = "usual.event.SCREEN_LOCKED"; /** - * @brief This commonEvent means when the http proxy change. - * - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that the HTTP proxy configuration has changed. * * @since 12 */ static const char* const COMMON_EVENT_HTTP_PROXY_CHANGE = "usual.event.HTTP_PROXY_CHANGE"; /** - * @brief This commonEvent means when the network connectivity change. - * - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that the network connection state has changed. * * @since 12 */ static const char* const COMMON_EVENT_CONNECTIVITY_CHANGE = "usual.event.CONNECTIVITY_CHANGE"; /** - * @brief This common event means that minors mode is enabled. - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that the minor mode is enabled. * * @since 12 */ static const char* const COMMON_EVENT_MINORSMODE_ON = "usual.event.MINORSMODE_ON"; /** - * @brief This common event means that minors mode is disabled. - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that the minor mode is disabled. * * @since 12 */ static const char* const COMMON_EVENT_MINORSMODE_OFF = "usual.event.MINORSMODE_OFF"; /** - * @brief This common event means that the managed browser policy is changed. - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that the browser hosting policy has been changed. * * @since 15 */ static const char* const COMMON_EVENT_MANAGED_BROWSER_POLICY_CHANGED = "usual.event.MANAGED_BROWSER_POLICY_CHANGED"; /** - * @brief This common event means that the open and closed state of the stand associated - * with the tablet mode has changed. - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that the tablet mode of a device has been changed. + * * @since 23 */ static const char* const COMMON_EVENT_TABLET_MODE_CHANGED = "usual.event.TABLET_MODE_CHANGED"; /** * @brief This common event indicates that specific volumes on the device have been decrypted. - * This is a protected common event that can only be sent by system. * * @since 26.0.0 */ @@ -596,7 +581,6 @@ static const char* const COMMON_EVENT_VOLUME_DECRYPTED = "usual.event.VOLUME_DEC /** * @brief This common event indicates that specific volumes on the device have been encrypted. - * This is a protected common event that can only be sent by system. * * @since 26.0.0 */ @@ -604,17 +588,17 @@ static const char* const COMMON_EVENT_VOLUME_ENCRYPTED = "usual.event.VOLUME_ENC /** * @brief This common event indicates that specific volumes on the device have had their encryption policy set. + * * To subscribe to this protected common event, your application must have the * ohos.permission.QUERY_VOLUME_ENCRYPTION_STATUS permission. - * This is a protected common event that can only be sent by system. * * @since 26.0.0 */ static const char* const COMMON_EVENT_VOLUME_ENCRYPTION_POLICY_SET = "usual.event.VOLUME_ENCRYPTION_POLICY_SET"; /** - * @brief This common event means that the state (open or closed) of the laptop lid has changed. - * This is a protected common event that can only be sent by system. + * @brief Indicates the common event that the lid state of a device has been changed. + * * @since 23 */ static const char* const COMMON_EVENT_LID_STATE_CHANGED = "usual.event.LID_STATE_CHANGED"; @@ -622,4 +606,5 @@ static const char* const COMMON_EVENT_LID_STATE_CHANGED = "usual.event.LID_STATE } #endif #endif // OH_COMMONEVENT_SUPPORT_H -/** @} */ + +/** @} */ \ No newline at end of file diff --git a/zh-cn/BasicServicesKit/commonevent/oh_commonevent.h b/zh-cn/BasicServicesKit/commonevent/oh_commonevent.h new file mode 100644 index 000000000..b0c6c95dc --- /dev/null +++ b/zh-cn/BasicServicesKit/commonevent/oh_commonevent.h @@ -0,0 +1,786 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/** + * @addtogroup OH_CommonEvent + * @{ + * + * @brief Provides the APIs of common event service. + * + * @since 12 + */ +/** + * @file oh_commonevent.h + * + * @brief 定义公共事件订阅与退订API接口与枚举错误码。 + * + * @library libohcommonevent.so + * @kit BasicServicesKit + * @syscap SystemCapability.Notification.CommonEvent + * @since 12 + * @version 1.0 + */ + +#ifndef OH_COMMONEVENT_H +#define OH_COMMONEVENT_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 枚举错误码。 + * + * @since 12 + * @version 1.0 + */ +typedef enum CommonEvent_ErrCode { + /** + * 成功。 + * + * @since 12 + */ + COMMONEVENT_ERR_OK = 0, + + /** + * 权限错误。 + * + * @since 12 + */ + COMMONEVENT_ERR_PERMISSION_ERROR = 201, + + /** + * 参数错误。 + * + * @since 12 + */ + COMMONEVENT_ERR_INVALID_PARAMETER = 401, + + /** + * 事件发送频率过高。 + * + * @since 20 + */ + COMMONEVENT_ERR_SENDING_LIMIT_EXCEEDED = 1500003, + + /** + * 三方应用无法发送系统公共事件。 + * + * @since 12 + */ + COMMONEVENT_ERR_NOT_SYSTEM_SERVICE = 1500004, + + /** + * IPC发送失败。 + * + * @since 12 + */ + COMMONEVENT_ERR_SENDING_REQUEST_FAILED = 1500007, + + /** + * 服务未初始化。 + * + * @since 12 + */ + COMMONEVENT_ERR_INIT_UNDONE = 1500008, + + /** + * 系统错误。 + * + * @since 12 + */ + COMMONEVENT_ERR_OBTAIN_SYSTEM_PARAMS = 1500009, + + /** + * 订阅者数量超过限制。 + * + * @since 12 + */ + COMMONEVENT_ERR_SUBSCRIBER_NUM_EXCEEDED = 1500010, + + /** + * 内存分配失败。 + * + * @since 12 + */ + COMMONEVENT_ERR_ALLOC_MEMORY_FAILED = 1500011, +} CommonEvent_ErrCode; + +/** + * @brief 提供CommonEvent_SubscribeInfo订阅者信息结构体声明。 + * + * @since 12 + */ +typedef struct CommonEvent_SubscribeInfo CommonEvent_SubscribeInfo; + +/** + * @brief 提供CommonEvent_Subscriber订阅者结构体声明。 + * + * @since 12 + */ +typedef void CommonEvent_Subscriber; + +/** + * @brief 发布公共事件时使用的公共事件属性对象。 + * + * @since 18 + */ +typedef struct CommonEvent_PublishInfo CommonEvent_PublishInfo; + +/** + * @brief 提供CommonEvent_RcvData公共事件回调数据结构体声明。 + * + * @since 12 + */ +typedef struct CommonEvent_RcvData CommonEvent_RcvData; + +/** + * @brief 提供CommonEvent_RcvData公共事件附加信息结构体声明。 + * + * @since 12 + */ +typedef void CommonEvent_Parameters; + +/** + * @brief 提供CommonEvent_ReceiveCallback回调函数声明。 + * + * @param data 公共事件回调数据。 + * @since 12 + */ +typedef void (*CommonEvent_ReceiveCallback)(const CommonEvent_RcvData *data); + +/** + * @brief 创建订阅者信息。 + * + * @param events Indicates the subscribed events. + * @param eventsNum 订阅的公共事件数量。 + * @return 成功则返回订阅者信息,失败则返回NULL。 + * @since 12 + */ +CommonEvent_SubscribeInfo* OH_CommonEvent_CreateSubscribeInfo(const char* events[], int32_t eventsNum); + +/** + * @brief 设置发布方权限。 + * + * @param info 订阅者信息。 + * @param permission 权限名称。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + * @since 12 + */ +CommonEvent_ErrCode OH_CommonEvent_SetPublisherPermission(CommonEvent_SubscribeInfo* info, const char* permission); + +/** + * @brief 设置发布方包名称。 + * + * @param info 订阅者信息。 + * @param bundleName 包名称。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + * @since 12 + */ +CommonEvent_ErrCode OH_CommonEvent_SetPublisherBundleName(CommonEvent_SubscribeInfo* info, const char* bundleName); + +/** + * @brief 释放订阅者信息。 + * + * @param info 订阅者信息。 + * @since 12 + */ +void OH_CommonEvent_DestroySubscribeInfo(CommonEvent_SubscribeInfo* info); + +/** + * @brief 创建订阅者。 + * + * @param info 订阅者信息。 + * @param callback 公共事件回调函数 + * @return 成功则返回订阅者,失败则返回NULL。 + * @since 12 + */ +CommonEvent_Subscriber* OH_CommonEvent_CreateSubscriber(const CommonEvent_SubscribeInfo* info, + CommonEvent_ReceiveCallback callback); + +/** + * @brief 释放订阅者。 + * + * @param subscriber 订阅者。 + * @since 12 + */ +void OH_CommonEvent_DestroySubscriber(CommonEvent_Subscriber* subscriber); + +/** + * @brief 订阅公共事件。 + * + * @param subscriber 订阅者。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数subscriber无效。 + *
返回{@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED}表示IPC请求发送失败。 + *
返回{@link COMMONEVENT_ERR_INIT_UNDONE}表示公共事件服务未初始化。 + *
返回{@link COMMONEVENT_ERR_SUBSCRIBER_NUM_EXCEEDED}表示进程订阅者数量超过200个。 + *
返回{@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED}系统分配内存失败。 + * @since 12 + */ +CommonEvent_ErrCode OH_CommonEvent_Subscribe(const CommonEvent_Subscriber* subscriber); + +/** + * @brief 退订公共事件。 + * + * @param subscriber 订阅者。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数subscriber无效。 + *
返回{@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED}表示IPC请求发送失败。 + *
返回{@link COMMONEVENT_ERR_INIT_UNDONE}表示公共事件服务未初始化。 + * @since 12 + */ +CommonEvent_ErrCode OH_CommonEvent_UnSubscribe(const CommonEvent_Subscriber* subscriber); + +/** + * @brief 获取当前接收的公共事件名称。 + * + * @param rcvData 公共事件回调数据。 + * @return 返回事件名称。 + * @since 12 + */ +const char* OH_CommonEvent_GetEventFromRcvData(const CommonEvent_RcvData* rcvData); + +/** + * @brief 获取公共事件传递的数据，整数类型。 + * + * @param rcvData 公共事件回调数据。 + * @return 返回公共事件传递的数据，整数类型。 + * @since 12 + */ +int32_t OH_CommonEvent_GetCodeFromRcvData(const CommonEvent_RcvData* rcvData); + +/** + * @brief 获取公共事件传递的数据，字符串类型。 + * + * @param rcvData 公共事件回调数据。 + * @return 返回公共事件传递的数据，字符串类型。 + * @since 12 + */ +const char* OH_CommonEvent_GetDataStrFromRcvData(const CommonEvent_RcvData* rcvData); + +/** + * @brief 获取接收到的公共事件的包名称信息。 + * + * @param rcvData 公共事件回调数据。 + * @return 返回公共事件的包名称。 + * @since 12 + */ +const char* OH_CommonEvent_GetBundleNameFromRcvData(const CommonEvent_RcvData* rcvData); + +/** + * @brief 获取公共事件附加信息。 + * + * @param rcvData 公共事件回调数据。 + * @return 返回公共事件附加信息。 + * @since 12 + */ +const CommonEvent_Parameters* OH_CommonEvent_GetParametersFromRcvData(const CommonEvent_RcvData* rcvData); + +/** + * @brief 创建公共事件属性对象。 + * + * @param ordered 是否为有序公共事件。 + *
true：有序公共事件。 + *
false：无序公共事件。 + * @return 创建的公共事件属性对象，创建失败时，返回null。 + * @since 18 + */ +CommonEvent_PublishInfo* OH_CommonEvent_CreatePublishInfo(bool ordered); + +/** + * @brief 销毁公共事件属性对象。 + * + * @param info 要销毁的公共事件属性对象。 + * @since 18 + */ +void OH_CommonEvent_DestroyPublishInfo(CommonEvent_PublishInfo* info); + +/** + * @brief 设置公共事件订阅者包名称。 + * + * @param info 公共事件属性对象。 + * @param bundleName 设置的订阅者包名称。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoBundleName(CommonEvent_PublishInfo* info, const char* bundleName); + +/** + * @brief 设置公共事件订阅者权限。 + * + * @param info 公共事件属性对象。 + * @param permissions Indicates the array of permissions. + * @param num 权限的数量。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoPermissions(CommonEvent_PublishInfo* info, + const char* permissions[], int32_t num); + +/** + * @brief 设置公共事件传递的数据，整数类型。 + * + * @param info 公共事件属性对象。 + * @param code 公共事件传递的数据，整数类型。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoCode(CommonEvent_PublishInfo* info, int32_t code); + +/** + * @brief 设置公共事件传递的数据，字符串类型。 + * + * @param info 公共事件属性对象。 + * @param data 公共事件传递的数据，字符串类型，实际有效数据长度为`length`和`data`字符串长度的最小值。 + * @param length 结果数据的长度。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoData(CommonEvent_PublishInfo* info, + const char* data, size_t length); + +/** + * @brief 设置公共事件附加信息。 + * + * @param info 公共事件属性对象。 + * @param param 设置的附加信息。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoParameters(CommonEvent_PublishInfo* info, + CommonEvent_Parameters* param); + +/** + * @brief 创建公共事件附加信息对象。 + * + * @return 返回公共事件附加信息，创建失败时，返回null。 + * @since 18 + */ +CommonEvent_Parameters* OH_CommonEvent_CreateParameters(); + +/** + * @brief 销毁公共事件附加信息对象。 + * + * @param param 公共事件附加信息。 + * @since 18 + */ +void OH_CommonEvent_DestroyParameters(CommonEvent_Parameters* param); + +/** + * @brief 检查附加信息中是否包含键值对信息。 + * + * @param para 公共事件附加信息。 + * @param key 数据键。 + * @return 返回数据键是否存在。 + *
true：存在。 + *
false：不存在。 + * @since 12 + */ +bool OH_CommonEvent_HasKeyInParameters(const CommonEvent_Parameters* para, const char* key); + +/** + * @brief 获取公共事件附加信息中键为key的int类型内容。 + * + * @param para 公共事件附加信息。 + * @param key 数据键。 + * @param defaultValue 默认值。 + * @return 返回查询的int类型数据。 + * @since 12 + */ +int OH_CommonEvent_GetIntFromParameters(const CommonEvent_Parameters* para, const char* key, const int defaultValue); + +/** + * @brief 设置公共事件附加信息的int类型内容。 + * + * @param param 公共事件附加信息。 + * @param key 数据键。 + * @param value 设置的int类型内容。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetIntToParameters(CommonEvent_Parameters* param, const char* key, int value); + +/** + * @brief 获取公共事件附加信息中键为key的int数组数据。 + * + * @param para 公共事件附加信息。 + * @param key 数据键。 + * @param array 查询的数组。 + * @return 返回查询的数组长度，默认值为0。 + * @since 12 + */ +int32_t OH_CommonEvent_GetIntArrayFromParameters(const CommonEvent_Parameters* para, const char* key, int** array); + +/** + * @brief 设置公共事件附加信息的int数组内容。 + * + * @param param 公共事件附加信息。 + * @param key 数据键。 + * @param value 设置的int数组内容。 + * @param num 设置的int数组内容中元素的个数。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + *
返回{@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED}表示内存分配失败。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetIntArrayToParameters(CommonEvent_Parameters* param, const char* key, + const int* value, size_t num); + +/** + * @brief 获取公共事件附加信息中键为key的long类型数据。 + * + * @param para 公共事件附加信息。 + * @param key 数据键。 + * @param defaultValue 默认值。 + * @return 返回查询的long类型数据。 + * @since 12 + */ +long OH_CommonEvent_GetLongFromParameters(const CommonEvent_Parameters* para, const char* key, const long defaultValue); + +/** + * @brief 设置公共事件附加信息的long类型内容。 + * + * @param param 公共事件附加信息。 + * @param key 数据键。 + * @param value 设置的long类型内容。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetLongToParameters(CommonEvent_Parameters* param, const char* key, long value); + +/** + * @brief 获取公共事件附加信息的long数组内容。 + * + * @param para 公共事件附加信息。 + * @param key 数据键。 + * @param array 查询的数组。 + * @return 返回查询的数组长度，默认值为0。 + * @since 12 + */ +int32_t OH_CommonEvent_GetLongArrayFromParameters(const CommonEvent_Parameters* para, const char* key, long** array); + +/** + * @brief 设置公共事件附加信息的long数组内容。 + * + * @param param 公共事件附加信息。 + * @param key 数据键。 + * @param value 设置的long数组内容。 + * @param num 设置的long数组内容中元素的个数。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + *
返回{@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED}表示内存分配失败。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetLongArrayToParameters(CommonEvent_Parameters* param, const char* key, + const long* value, size_t num); + +/** + * @brief 获取公共事件附加信息中键为key的布尔类型数据。 + * + * @param para 公共事件附加信息。 + * @param key 数据键。 + * @param defaultValue 默认值。 + * @return 返回查询的bool类型数据。 + * @since 12 + */ +bool OH_CommonEvent_GetBoolFromParameters(const CommonEvent_Parameters* para, const char* key, const bool defaultValue); + +/** + * @brief 设置公共事件附加信息的布尔类型内容。 + * + * @param param 公共事件附加信息。 + * @param key 数据键。 + * @param value 设置的布尔类型内容。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetBoolToParameters(CommonEvent_Parameters* param, const char* key, bool value); + +/** + * @brief 获取公共事件附加信息的布尔数组内容。 + * + * @param para 公共事件附加信息。 + * @param key 数据键。 + * @param array 查询的数组。 + * @return 返回查询的数组长度，默认值为0。 + * @since 12 + */ +int32_t OH_CommonEvent_GetBoolArrayFromParameters(const CommonEvent_Parameters* para, const char* key, bool** array); + +/** + * @brief 设置公共事件附加信息的布尔数组内容。 + * + * @param param 公共事件附加信息。 + * @param key 数据键。 + * @param value 设置的布尔数组内容。 + * @param num 设置的布尔数组内容中元素的个数。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + *
返回{@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED}表示内存分配失败。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetBoolArrayToParameters(CommonEvent_Parameters* param, const char* key, + const bool* value, size_t num); + +/** + * @brief 获取公共事件附加信息中键为key的字符类型数据。 + * + * @param para 公共事件附加信息。 + * @param key 数据键。 + * @param defaultValue 默认值。 + * @return 返回查询的char类型数据。 + * @since 12 + */ +char OH_CommonEvent_GetCharFromParameters(const CommonEvent_Parameters* para, const char* key, const char defaultValue); + +/** + * @brief 设置公共事件附加信息的字符类型内容。 + * + * @param param 公共事件附加信息。 + * @param key 数据键。 + * @param value 设置的字符类型内容。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetCharToParameters(CommonEvent_Parameters* param, const char* key, char value); + +/** + * @brief 获取公共事件附加信息的字符数组内容。 + * + * @param para 公共事件附加信息。 + * @param key 数据键。 + * @param array 查询的数组。 + * @return 返回查询的数组长度，默认值为0。 + * @since 12 + */ +int32_t OH_CommonEvent_GetCharArrayFromParameters(const CommonEvent_Parameters* para, const char* key, char** array); + +/** + * @brief 设置公共事件附加信息的字符数组内容。 + * + * @param param 公共事件附加信息。 + * @param key 数据键。 + * @param value 设置的字符数组内容。 + * @param num 设置的字符数组内容中元素的个数。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetCharArrayToParameters(CommonEvent_Parameters* param, const char* key, + const char* value, size_t num); + +/** + * @brief 获取公共事件附加信息的double类型内容。 + * + * @param para 公共事件附加信息。 + * @param key 数据键。 + * @param defaultValue 默认值。 + * @return 返回查询的double类型数据。 + * @since 12 + */ +double OH_CommonEvent_GetDoubleFromParameters(const CommonEvent_Parameters* para, const char* key, + const double defaultValue); + +/** + * @brief 设置公共事件附加信息的double类型内容。 + * + * @param param 公共事件附加信息。 + * @param key 数据键。 + * @param value 设置的double类型内容。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetDoubleToParameters(CommonEvent_Parameters* param, const char* key, + double value); + +/** + * @brief 获取公共事件附加信息中键为key的double数组数据。 + * + * @param para 公共事件附加信息。 + * @param key 数据键。 + * @param array 查询的数组。 + * @return 返回查询的数组长度，默认值为0。 + * @since 12 + */ +int32_t OH_CommonEvent_GetDoubleArrayFromParameters(const CommonEvent_Parameters* para, const char* key, + double** array); + +/** + * @brief 设置公共事件附加信息的double数组内容。 + * + * @param param 公共事件附加信息。 + * @param key 数据键。 + * @param value 设置的double数组内容。 + * @param num 设置的double数组内容中元素的个数。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + *
返回{@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED}表示内存分配失败。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_SetDoubleArrayToParameters(CommonEvent_Parameters* param, const char* key, + const double* value, size_t num); + +/** + * @brief 发布公共事件。 + * + * @param event 公共事件名称。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + *
返回{@link COMMONEVENT_ERR_SENDING_LIMIT_EXCEEDED}表示事件发送频率过高。 + *
返回{@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED}表示IPC请求发送失败。 + *
返回{@link COMMONEVENT_ERR_INIT_UNDONE}表示公共事件服务未初始化。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_Publish(const char* event); + +/** + * @brief 发布带有指定属性的公共事件。 + * + * @param event 公共事件名称。 + * @param info 设置的公共事件属性。 + * @return 返回错误码。 + *
返回{@link COMMONEVENT_ERR_OK}表示成功。 + *
返回{@link COMMONEVENT_ERR_INVALID_PARAMETER}表示参数错误。 + *
返回{@link COMMONEVENT_ERR_SENDING_LIMIT_EXCEEDED}表示事件发送频率过高。 + *
返回{@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED}表示IPC请求发送失败。 + *
返回{@link COMMONEVENT_ERR_INIT_UNDONE}表示公共事件服务未初始化。 + * @since 18 + */ +CommonEvent_ErrCode OH_CommonEvent_PublishWithInfo(const char* event, const CommonEvent_PublishInfo* info); + +/** + * @brief 查询当前公共事件是否为有序公共事件。 + * + * @param subscriber 公共事件的订阅者对象。 + * @return 返回true表示有序公共事件；返回false表示无序公共事件。 + * @since 18 + */ +bool OH_CommonEvent_IsOrderedCommonEvent(const CommonEvent_Subscriber* subscriber); + +/** + * @brief 用于订阅者结束对当前有序公共事件的处理。 + * + * @param subscriber 公共事件的订阅者对象。 + * @return 返回true表示操作成功；返回false表示操作失败。 + * @since 18 + */ +bool OH_CommonEvent_FinishCommonEvent(CommonEvent_Subscriber* subscriber); + +/** + * @brief 获取当前有序公共事件是否处于中止状态。 + * + * @param subscriber 公共事件的订阅者对象。 + * @return 返回true表示当前有序公共事件处于中止状态；返回false表示当前有序公共事件没有处于中止状态。 + * @since 18 + */ +bool OH_CommonEvent_GetAbortCommonEvent(const CommonEvent_Subscriber* subscriber); + +/** + * @brief 该接口与{@link OH_CommonEvent_FinishCommonEvent}配合使用，可以中止当前的有序公共事件，使该公共事件不再向下一个订阅者传递。 + * + * @param subscriber 公共事件的订阅者对象。 + * @return 返回true表示操作成功；返回false表示操作失败。 + * @since 18 + */ +bool OH_CommonEvent_AbortCommonEvent(CommonEvent_Subscriber* subscriber); + +/** + * @brief 该接口与{@link OH_CommonEvent_FinishCommonEvent}配合使用，可以取消当前有序公共事件的中止状态，使该公共事件继续向下一个订阅者传递。 + * + * @param subscriber 公共事件的订阅者对象。 + * @return 返回true表示操作成功；返回false表示操作失败。 + * @since 18 + */ +bool OH_CommonEvent_ClearAbortCommonEvent(CommonEvent_Subscriber* subscriber); + +/** + * @brief 获取有序公共事件传递的数据，整数类型。 + * + * @param subscriber 公共事件的订阅者对象。 + * @return 返回有序公共事件传递的数据，整数类型，无法获取时返回0。 + * @since 18 + */ +int32_t OH_CommonEvent_GetCodeFromSubscriber(const CommonEvent_Subscriber* subscriber); + +/** + * @brief 设置有序公共事件传递的数据，整数类型。 + * + * @param subscriber 公共事件的订阅者对象。 + * @param code 有序公共事件传递的数据，整数类型。 + * @return 返回true表示操作成功；返回false表示操作失败。 + * @since 18 + */ +bool OH_CommonEvent_SetCodeToSubscriber(CommonEvent_Subscriber* subscriber, int32_t code); + +/** + * @brief 获取有序公共事件传递的数据，字符串类型。 + * + * @param subscriber 公共事件的订阅者对象。 + * @return 返回有序公共事件传递的数据，字符串类型，无法获取时返回null。 + * @since 18 + */ +const char* OH_CommonEvent_GetDataFromSubscriber(const CommonEvent_Subscriber* subscriber); + +/** + * @brief 设置有序公共事件传递的数据，字符串类型。 + * + * @param subscriber 公共事件的订阅者对象。 + * @param data 有序公共事件传递的数据，字符串类型，实际有效数据长度为`length`与`data`字符串长度的较小值。 + * @param length 数据的长度。 + * @return 返回true表示操作成功；返回false表示操作失败。 + * @since 18 + */ +bool OH_CommonEvent_SetDataToSubscriber(CommonEvent_Subscriber* subscriber, const char* data, size_t length); + +#ifdef __cplusplus +} +#endif +#endif // OH_COMMONEVENT_H +/** @} */ \ No newline at end of file diff --git a/zh-cn/BasicServicesKit/commonevent/oh_commonevent_support.h b/zh-cn/BasicServicesKit/commonevent/oh_commonevent_support.h new file mode 100644 index 000000000..3e8946cfe --- /dev/null +++ b/zh-cn/BasicServicesKit/commonevent/oh_commonevent_support.h @@ -0,0 +1,576 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/** + * @addtogroup OH_CommonEvent + * @{ + * + * @brief Provides the APIs of common event service. + * + * @since 12 + */ +/** + * @file oh_commonevent_support.h + * + * @brief 提供系统定义的公共事件常量。 + * + * @library libohcommonevent.so + * @kit BasicServicesKit + * @syscap SystemCapability.Notification.CommonEvent + * @since 12 + * @version 1.0 + */ + +#ifndef OH_COMMONEVENT_SUPPORT_H +#define OH_COMMONEVENT_SUPPORT_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 表示设备正在关闭并将继续直至最终关闭的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_SHUTDOWN = "usual.event.SHUTDOWN"; + +/** + * @brief 表示电池充电状态、电平和其他信息发生变化的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_BATTERY_CHANGED = "usual.event.BATTERY_CHANGED"; + +/** + * @brief 表示电池电量低的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_BATTERY_LOW = "usual.event.BATTERY_LOW"; + +/** + * @brief 表示电池退出低电平状态的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_BATTERY_OKAY = "usual.event.BATTERY_OKAY"; + +/** + * @brief 表示设备连接到外部电源的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_POWER_CONNECTED = "usual.event.POWER_CONNECTED"; + +/** + * @brief 表示设备与外部电源断开的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_POWER_DISCONNECTED = "usual.event.POWER_DISCONNECTED"; + +/** + * @brief 表示设备屏幕关闭且设备处于睡眠状态的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_SCREEN_OFF = "usual.event.SCREEN_OFF"; + +/** + * @brief 表示设备屏幕打开且设备处于交互状态的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_SCREEN_ON = "usual.event.SCREEN_ON"; + +/** + * @brief 表示设备即将进入休眠模式的公共事件的动作。 + * + * @since 15 + */ +static const char* const COMMON_EVENT_ENTER_HIBERNATE = "usual.event.ENTER_HIBERNATE"; + +/** + * @brief 表示设备退出休眠模式的公共事件的动作。 + * + * @since 15 + */ +static const char* const COMMON_EVENT_EXIT_HIBERNATE = "usual.event.EXIT_HIBERNATE"; + +/** + * @brief 表示设备热状态的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_THERMAL_LEVEL_CHANGED = "usual.event.THERMAL_LEVEL_CHANGED"; + +/** + * @brief 表示系统时间更改的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_TIME_TICK = "usual.event.TIME_TICK"; + +/** + * @brief 表示设置系统时间的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_TIME_CHANGED = "usual.event.TIME_CHANGED"; + +/** + * @brief 表示系统时区更改的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_TIMEZONE_CHANGED = "usual.event.TIMEZONE_CHANGED"; + +/** + * @brief 表示设备上已安装新应用包的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_PACKAGE_ADDED = "usual.event.PACKAGE_ADDED"; + +/** + * @brief 表示已从设备卸载已安装的应用程序，但应用程序数据保留的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_PACKAGE_REMOVED = "usual.event.PACKAGE_REMOVED"; + +/** + * @brief 表示已从设备中卸载已安装的捆绑包，但应用程序数据仍保留的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_BUNDLE_REMOVED = "usual.event.BUNDLE_REMOVED"; + +/** + * @brief 表示已从设备中完全卸载已安装的应用程序（包括应用程序数据和代码）的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_PACKAGE_FULLY_REMOVED = "usual.event.PACKAGE_FULLY_REMOVED"; + +/** + * @brief 表示应用包已更改的公共事件（例如，包中的组件已启用或禁用）。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_PACKAGE_CHANGED = "usual.event.PACKAGE_CHANGED"; + +/** + * @brief 表示用户重启应用包并杀死其所有进程的普通事件的动作。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_PACKAGE_RESTARTED = "usual.event.PACKAGE_RESTARTED"; + +/** + * @brief 表示用户清除应用包数据的公共事件的动作。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_PACKAGE_DATA_CLEARED = "usual.event.PACKAGE_DATA_CLEARED"; + +/** + * @brief 表示用户清除应用包缓存数据的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_PACKAGE_CACHE_CLEARED = "usual.event.PACKAGE_CACHE_CLEARED"; + +/** + * @brief 表示应用包已挂起的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_PACKAGES_SUSPENDED = "usual.event.PACKAGES_SUSPENDED"; + +/** + * @brief 表示应用包被挂起的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_MY_PACKAGE_SUSPENDED = "usual.event.MY_PACKAGE_SUSPENDED"; + +/** + * @brief 表示应用包未挂起的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_MY_PACKAGE_UNSUSPENDED = "usual.event.MY_PACKAGE_UNSUSPENDED"; + +/** + * @brief 表示设备区域设置已更改的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_LOCALE_CHANGED = "usual.event.LOCALE_CHANGED"; + +/** + * @brief 表示设备存储空间不足的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_MANAGE_PACKAGE_STORAGE = "usual.event.MANAGE_PACKAGE_STORAGE"; + +/** + * @brief 表示设备重启后解锁时，当前用户的凭据加密存储已解锁的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_USER_UNLOCKED = "usual.event.USER_UNLOCKED"; + +/** + * @brief 表示分布式账号登出成功的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_DISTRIBUTED_ACCOUNT_LOGOUT = "common.event.DISTRIBUTED_ACCOUNT_LOGOUT"; + +/** + * @brief 表示分布式账号token令牌无效的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_DISTRIBUTED_ACCOUNT_TOKEN_INVALID = + "common.event.DISTRIBUTED_ACCOUNT_TOKEN_INVALID"; + +/** + * @brief 表示分布式账号注销的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_DISTRIBUTED_ACCOUNT_LOGOFF = "common.event.DISTRIBUTED_ACCOUNT_LOGOFF"; + +/** + * @brief 表示Wi-Fi状态公共事件，如启用和禁用。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_POWER_STATE = "usual.event.wifi.POWER_STATE"; + +/** + * @brief 表示Wi-Fi接入点已被扫描并证明可用的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_SCAN_FINISHED = "usual.event.wifi.SCAN_FINISHED"; + +/** + * @brief 表示Wi-Fi信号强度（RSSI）改变的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_RSSI_VALUE = "usual.event.wifi.RSSI_VALUE"; + +/** + * @brief 表示Wi-Fi连接状态发生改变的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_CONN_STATE = "usual.event.wifi.CONN_STATE"; + +/** + * @brief 表示Wi-Fi热点状态的公共事件，如启用或禁用。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_HOTSPOT_STATE = "usual.event.wifi.HOTSPOT_STATE"; + +/** + * @brief 表示客户端加入当前设备Wi-Fi热点的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_AP_STA_JOIN = "usual.event.wifi.WIFI_HS_STA_JOIN"; + +/** + * @brief 表示客户端加入当前设备Wi-Fi热点的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_AP_STA_LEAVE = "usual.event.wifi.WIFI_HS_STA_LEAVE"; + +/** + * @brief 表示MPLink（增强Wi-Fi功能）状态已更改的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_MPLINK_STATE_CHANGE = "usual.event.wifi.mplink.STATE_CHANGE"; + +/** + * @brief 表示Wi-Fi P2P连接状态改变的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_P2P_CONN_STATE = "usual.event.wifi.p2p.CONN_STATE_CHANGE"; + +/** + * @brief 表示Wi-Fi P2P状态公共事件，如启用和禁用。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_P2P_STATE_CHANGED = "usual.event.wifi.p2p.STATE_CHANGE"; + +/** + * @brief 表示Wi-Fi P2P对等体状态变化的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_P2P_PEERS_STATE_CHANGED = "usual.event.wifi.p2p.DEVICES_CHANGE"; + +/** + * @brief 表示Wi-Fi P2P发现状态变化的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_P2P_PEERS_DISCOVERY_STATE_CHANGED = + "usual.event.wifi.p2p.PEER_DISCOVERY_STATE_CHANGE"; + +/** + * @brief 表示Wi-Fi P2P当前设备状态变化的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_P2P_CURRENT_DEVICE_STATE_CHANGED = + "usual.event.wifi.p2p.CURRENT_DEVICE_CHANGE"; + +/** + * @brief 表示Wi-Fi P2P群组信息已更改的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_WIFI_P2P_GROUP_STATE_CHANGED = "usual.event.wifi.p2p.GROUP_STATE_CHANGED"; + +/** + * @brief 表示设备NFC状态已更改的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_NFC_ACTION_ADAPTER_STATE_CHANGED = "usual.event.nfc.action.ADAPTER_STATE_CHANGED"; + +/** + * @brief 表示检测到NFC场强进入的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_NFC_ACTION_RF_FIELD_ON_DETECTED = "usual.event.nfc.action.RF_FIELD_ON_DETECTED"; + +/** + * @brief 表示检测到NFC场强离开的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_NFC_ACTION_RF_FIELD_OFF_DETECTED = "usual.event.nfc.action.RF_FIELD_OFF_DETECTED"; + +/** + * @brief 表示系统停止为电池充电的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_DISCHARGING = "usual.event.DISCHARGING"; + +/** + * @brief 表示系统开始为电池充电的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_CHARGING = "usual.event.CHARGING"; + +/** + * @brief 表示系统待机空闲模式已更改的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_DEVICE_IDLE_MODE_CHANGED = "usual.event.DEVICE_IDLE_MODE_CHANGED"; + +/** + * @brief 表示设备进入充电空闲模式的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_CHARGE_IDLE_MODE_CHANGED = "usual.event.CHARGE_IDLE_MODE_CHANGED"; + +/** + * @brief 表示系统节能模式更改的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_POWER_SAVE_MODE_CHANGED = "usual.event.POWER_SAVE_MODE_CHANGED"; + +/** + * @brief 表示USB设备状态发生变化的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_USB_STATE = "usual.event.hardware.usb.action.USB_STATE"; + +/** + * @brief 表示用户设备的USB端口状态发生改变的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_USB_PORT_CHANGED = "usual.event.hardware.usb.action.USB_PORT_CHANGED"; + +/** + * @brief 当用户设备作为USB主机时，USB设备已挂载的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_USB_DEVICE_ATTACHED = "usual.event.hardware.usb.action.USB_DEVICE_ATTACHED"; + +/** + * @brief 当用户设备作为USB主机时，USB设备被卸载的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_USB_DEVICE_DETACHED = "usual.event.hardware.usb.action.USB_DEVICE_DETACHED"; + +/** + * @brief 表示设备飞行模式已更改的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_AIRPLANE_MODE_CHANGED = "usual.event.AIRPLANE_MODE"; + +/** + * @brief 表示分屏的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_SPLIT_SCREEN = "common.event.SPLIT_SCREEN"; + +/** + * @brief 表示快速修复应用的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_QUICK_FIX_APPLY_RESULT = "usual.event.QUICK_FIX_APPLY_RESULT"; + +/** + * @brief 表示撤销快速修复的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_QUICK_FIX_REVOKE_RESULT = "usual.event.QUICK_FIX_REVOKE_RESULT"; + +/** + * @brief 表示用户信息已更新的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_USER_INFO_UPDATED = "usual.event.USER_INFO_UPDATED"; + +/** + * @brief 表示SIM卡状态更新的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_SIM_STATE_CHANGED = "usual.event.SIM_STATE_CHANGED"; + +/** + * @brief 表示呼叫状态更新的公共事件。 + * 要订阅此事件，您的应用必须具备ohos.permission.GET_TELEPHONY_STATE权限。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_CALL_STATE_CHANGED = "usual.event.CALL_STATE_CHANGED"; + +/** + * @brief 表示网络状态更新的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_NETWORK_STATE_CHANGED = "usual.event.NETWORK_STATE_CHANGED"; + +/** + * @brief 表示信号信息更新的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_SIGNAL_INFO_CHANGED = "usual.event.SIGNAL_INFO_CHANGED"; + +/** + * @brief 表示屏幕解锁的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_SCREEN_UNLOCKED = "usual.event.SCREEN_UNLOCKED"; + +/** + * @brief 表示屏幕锁定的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_SCREEN_LOCKED = "usual.event.SCREEN_LOCKED"; + +/** + * @brief 表示HTTP代理的配置信息发生变化的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_HTTP_PROXY_CHANGE = "usual.event.HTTP_PROXY_CHANGE"; + +/** + * @brief 表示网络连接状态变化的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_CONNECTIVITY_CHANGE = "usual.event.CONNECTIVITY_CHANGE"; + +/** + * @brief 表示未成年人模式开启的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_MINORSMODE_ON = "usual.event.MINORSMODE_ON"; + +/** + * @brief 表示未成年人模式关闭的公共事件。 + * + * @since 12 + */ +static const char* const COMMON_EVENT_MINORSMODE_OFF = "usual.event.MINORSMODE_OFF"; + +/** + * @brief 表示浏览器托管策略已更改。 + * + * @since 15 + */ +static const char* const COMMON_EVENT_MANAGED_BROWSER_POLICY_CHANGED = "usual.event.MANAGED_BROWSER_POLICY_CHANGED"; + +/** + * @brief 表示可感知支架开合的设备，其支架开合状态变化的公共事件。 + * + * @since 23 + */ +static const char* const COMMON_EVENT_TABLET_MODE_CHANGED = "usual.event.TABLET_MODE_CHANGED"; + +/** + * @brief 表示可感知开合盖子的设备，其开合盖状态变化的公共事件。 + * + * @since 23 + */ +static const char* const COMMON_EVENT_LID_STATE_CHANGED = "usual.event.LID_STATE_CHANGED"; +#ifdef __cplusplus +} +#endif +#endif // OH_COMMONEVENT_SUPPORT_H +/** @} */