diff --git a/apis/20230220/inner_api/core/hdf_device_class.h b/apis/20230220/inner_api/core/hdf_device_class.h deleted file mode 100755 index e5af1c03d02c27fb885faffdd0967a87f406fb77..0000000000000000000000000000000000000000 --- a/apis/20230220/inner_api/core/hdf_device_class.h +++ /dev/null @@ -1,51 +0,0 @@ -/* - * Copyright (c) 2020-2021 Huawei Device Co., Ltd. - * - * HDF is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * See the LICENSE file in the root of this repository for complete details. - */ - -/** - * @addtogroup Core - * @{ - * - * @brief Provides Hardware Driver Foundation (HDF) APIs. - * - * The HDF implements driver framework capabilities such as driver loading, service management, - * and driver message model. You can develop drivers based on the HDF. - * - * @since 1.0 - */ - -/** - * @file hdf_device_class.h - * - * @brief 按照业务类别定义设备类型，业务模块可以按照该枚举类型监听特定设备类型的服务。 - * - * @since 1.0 - */ - -#ifndef HDF_DEVICE_CLASS_H -#define HDF_DEVICE_CLASS_H - -/** - * @brief Enumerates different classes of driver devices. - * - * @since 1.0 - */ -typedef enum { - DEVICE_CLASS_DEFAULT = 0x1 << 0, /** Default device */ - DEVICE_CLASS_PLAT = 0x1 << 1, /** Platform device */ - DEVICE_CLASS_SENSOR = 0x1 << 2, /** Sensor device */ - DEVICE_CLASS_INPUT = 0x1 << 3, /** Input device */ - DEVICE_CLASS_DISPLAY = 0x1 << 4, /** Display device */ - DEVICE_CLASS_AUDIO = 0x1 << 5, /** Audio device */ - DEVICE_CLASS_CAMERA = 0x1 << 6, /** Camera device */ - DEVICE_CLASS_USB = 0x1 << 7, /** USB device */ - DEVICE_CLASS_USERAUTH = 0x1 << 8, /** UserAuth device */ - DEVICE_CLASS_MAX = 0x1 << 9, /** Maximum value of a device class */ -} DeviceClass; - -#endif /* HDF_DEVICE_CLASS_H */ -/** @} */ diff --git a/apis/20230220/inner_api/core/hdf_service_status.h b/apis/20230220/inner_api/core/hdf_service_status.h deleted file mode 100755 index d60d54aaf771a2ade37e0b88681223ca75d895f1..0000000000000000000000000000000000000000 --- a/apis/20230220/inner_api/core/hdf_service_status.h +++ /dev/null @@ -1,95 +0,0 @@ -/* - * Copyright (c) 2021 Huawei Device Co., Ltd. - * - * HDF is dual licensed: you can use it either under the terms of - * the GPL, or the BSD license, at your option. - * See the LICENSE file in the root of this repository for complete details. - */ - -/** - * @addtogroup Core - * @{ - * - * @brief Provides Hardware Driver Foundation (HDF) APIs. - * - * The HDF implements driver framework capabilities such as driver loading, service management, - * and driver message model. You can develop drivers based on the HDF. - * - * @since 1.0 - */ - -/** - * @file hdf_service_status.h - * - * @brief 定义服务状态以及服务状态监听回调等数据结构。 - * - * @since 1.0 - */ - -#ifndef HDF_SERVICE_STATUS_H -#define HDF_SERVICE_STATUS_H - -#include "hdf_types.h" - -#ifdef __cplusplus -extern "C" { -#endif /* __cplusplus */ - -struct ServiceStatusListener; - -/** - * @brief 定义服务状态的枚举类型。 - * - * @since 1.0 - */ -enum ServiceStatusType { - /** 表示服务已启动 */ - SERVIE_STATUS_START, - /** 表示服务状态已变更 */ - SERVIE_STATUS_CHANGE, - /** 表示服务已停止 */ - SERVIE_STATUS_STOP, - /** 表示服务状态的最大值 */ - SERVIE_STATUS_MAX, -}; - -/** - * @brief 定义服务状态结构体，该结构体为HDF框架通知业务模块服务状态类型。 - * - * @since 1.0 - */ -struct ServiceStatus { - /** 服务名 */ - std::string serviceName; - /** 设备类型 */ - uint16_t deviceClass; - /** 服务状态 */ - uint16_t status; - /** 服务信息 */ - std::string info; -}; - -/** - * @brief 定义服务状态监听函数类型。 - * - * @param listener 业务模块的服务状态监听类型。 - * @param status 表示监听到的服务状态。 - */ -typedef void (*OnServiceStatusReceived)(struct ServiceStatusListener *listener, struct ServiceStatus *status); - -/** - * @brief 定义服务状态监听类型结构体。 - * - * @since 1.0 - */ -struct ServiceStatusListener { - /** 服务状态监听回调函数 */ - OnServiceStatusReceived callback; - /** 业务模块私有参数，业务模块可以根据业务需要把该参数传递到业务的回调函数，在回调函数中把HDF框架的服务状态类型转换为需要的类型 */ - void *priv; -}; - -#ifdef __cplusplus -} -#endif /* __cplusplus */ -#endif /* HDF_SERVICE_STATUS_H */ \ No newline at end of file diff --git a/apis/20230220/inner_api/hdi/base/buffer_handle.h b/apis/20230220/inner_api/hdi/base/buffer_handle.h index 7109eea8f7607037dc227258ecc4b9067d1fe217..73f4d74c324412794b3f07927063a5ce5ee123e7 100755 --- a/apis/20230220/inner_api/hdi/base/buffer_handle.h +++ b/apis/20230220/inner_api/hdi/base/buffer_handle.h @@ -17,9 +17,9 @@ * @addtogroup DriverHdi * @{ * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 +* @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in interface description language (IDL). * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 + * The HDF and IDL code generated allow the system ability to accesses HDI driver services. * * @since 1.0 */ @@ -27,8 +27,8 @@ /** * @file buffer_handle.h * - * @brief BufferHandle是图形处理常用的数据结构，需要把BufferHandle作为idl语法的基本类型进行支持， - * 业务模块只需要在idl中定义该结构，序列号及反序列化操作由HDI模块处理。 + * @brief Defines the common data struct for graphics processing. The BufferHandle must comply with the IDL syntax. + * You only need to define the struct in IDL for the service module. The HDI module implements serialization and deserialization of this struct. * * @since 1.0 */ @@ -43,24 +43,24 @@ extern "C" { #endif /** - * @brief 定义BufferHandle结构体对象。 + * @brief Defines the BufferHandle struct. * * @since 1.0 */ typedef struct { - int32_t fd; /**< buffer fd, -1 if not supported */ - int32_t width; /**< the width of memory */ - int32_t stride; /**< the stride of memory */ - int32_t height; /**< the height of memory */ - int32_t size; /* < size of memory */ - int32_t format; /**< the format of memory */ - uint64_t usage; /**< the usage of memory */ - void *virAddr; /**< Virtual address of memory */ + int32_t fd; /**< Buffer file descriptor (FD). The value -1 indicates a invalid FD. */ + int32_t width; /**< Width of the image */ + int32_t stride; /**< Stride of the image */ + int32_t height; /**< Height of the image */ + int32_t size; /* < Size of the buffer */ + int32_t format; /**< Format of the image */ + uint64_t usage; /**< Usage of the buffer */ + void *virAddr; /**< Virtual address of the buffer */ uint64_t phyAddr; /**< Physical address */ int32_t key; /**< Shared memory key */ - uint32_t reserveFds; /**< the number of reserved fd value */ - uint32_t reserveInts; /**< the number of reserved integer value */ - int32_t reserve[0]; /**< the data */ + uint32_t reserveFds; /**< Number of the reserved FDs */ + uint32_t reserveInts; /**< Number of the reserved integers */ + int32_t reserve[0]; /**< Data */ } BufferHandle; #ifdef __cplusplus diff --git a/apis/20230220/inner_api/hdi/base/buffer_util.h b/apis/20230220/inner_api/hdi/base/buffer_util.h index 04a4823c981c757896e1ae8c7b3b092b58662fdf..ea8b65cef11b631058b0de362811967abb9aba50 100755 --- a/apis/20230220/inner_api/hdi/base/buffer_util.h +++ b/apis/20230220/inner_api/hdi/base/buffer_util.h @@ -1,117 +1,117 @@ -/* - * Copyright (c) 2022 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 DriverHdi - * @{ - * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 - * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 - * - * @since 1.0 - */ - -/** - * @file buffer_util.h - * - * @brief 提供BufferHandle对象分配、释放、序列号及反序列化等操作接口。 - * - * @since 1.0 - */ - -#ifndef HDI_BUFFER_UTIL_H -#define HDI_BUFFER_UTIL_H - -#include "buffer_handle.h" -#include "hdf_sbuf.h" - -/** - * @brief BufferHandle成员reserveFds的取值上限。 - */ -#define MAX_RESERVE_FDS 1024 - -/** - * @brief BufferHandle成员reserveInts的取值上限。 - */ -#define MAX_RESERVE_INTS 1024 - -#ifdef __cplusplus -extern "C" { -#endif /* __cplusplus */ - -/** - * @brief 创建BufferHandle对象 - * - * 根据给定的reserveFds和reserveInts创建默认的BufferHandle对象 - * - * @param reserveFds 位于reserve[0]中文件描述符个数 (0~MAX_RESERVE_FDS) - * @param reserveInts 位于reserve[reserveFds]中int个数 (0~MAX_RESERVE_FDS) - * @return 成功时返回新创建的BufferHandle对象指针，失败时返回NULL - * - * @since 1.0 - */ -BufferHandle *AllocateNativeBufferHandle(uint32_t reserveFds, uint32_t reserveInts); - -/** - * @brief 克隆BufferHandle对象 - * - * 根据给定的BufferHandle对象创建另一个新的BufferHandle对象 - * - * @param other 源BufferHandle对象指针 - * @return 成功时返回新创建的BufferHandle对象地址，失败时返回NULL - * - * @since 1.0 - */ -BufferHandle *CloneNativeBufferHandle(const BufferHandle *other); - -/** - * @brief 释放BufferHandle对象 - * - * @param handle 待释放的BufferHandle对象指针 - * - * @since 1.0 - */ -void FreeNativeBufferHandle(BufferHandle *handle); - -/** - * @brief 序列化BufferHandle对象 - * - * 将BufferHandle对象序列化写入HdfSBuf对象中，和函数HdfSbufReadNativeBufferHandle配对使用。 - * - * @param data HdfSBuf对象指针 - * @param handle 待序列化的BufferHandle对象指针 - * - * @since 1.0 - */ -bool HdfSbufWriteNativeBufferHandle(struct HdfSBuf *data, const BufferHandle *handle); - -/** - * @brief 反序列化BufferHandle对象 - * - * 从HdfSBuf对象中读取并创建新的BufferHandle对象，和函数HdfSbufWriteNativeBufferHandle配对使用。 - * - * @param data HdfSBuf对象指针 - * @return 读取成功时返回新创建的BufferHandle对象地址，失败时返回NULL - * - * @since 1.0 - */ -BufferHandle *HdfSbufReadNativeBufferHandle(struct HdfSBuf *data); - -#ifdef __cplusplus -} -#endif /* __cplusplus */ - -#endif // HDI_BUFFER_UTIL_H \ No newline at end of file +/* + * Copyright (c) 2022 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 DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in interface description language (IDL). + * + * The HDF and IDL code generated allow the system ability to accesses HDI driver services. + * + * @since 1.0 + */ + +/** + * @file buffer_util.h + * + * @brief Provides the APIs for allocating, releasing, serializing, and deserializing the BufferHandle object. + * + * @since 1.0 + */ + +#ifndef HDI_BUFFER_UTIL_H +#define HDI_BUFFER_UTIL_H + +#include "buffer_handle.h" +#include "hdf_sbuf.h" + +/** + * @brief Defines the maximum value of the reserveFds in BufferHandle. + */ +#define MAX_RESERVE_FDS 1024 + +/** + * @brief Defines the maximum value of the reserveInts in BufferHandle. + */ +#define MAX_RESERVE_INTS 1024 + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/** + * @brief Allocates a BufferHandle object. + * + * You can use this API to create the default BufferHandle object based on the specified reserveFds and reserveInts. + * + * @param reserveFds Indicates the file descriptor (FD) count (0 to MAX_RESERVE_FDS) in reserve[0]. + * @param reserveInts Indicates the integer count (0 to MAX_RESERVE_FDS) in reserve[reserveFds]. + * @return Returns the pointer to the BufferHandle allocated if the operation is successful; returns NULL otherwise. + * + * @since 1.0 + */ +BufferHandle *AllocateNativeBufferHandle(uint32_t reserveFds, uint32_t reserveInts); + +/** + * @brief Clones a BufferHandle object. + * + * You can use this API to create a BufferHandle object from a given BufferHandle object. + * + * @param other Indicates the pointer to the BufferHandle object to clone. + * @return Returns the pointer to the BufferHandle created if the operation is successful; returns NULL otherwise. + * + * @since 1.0 + */ +BufferHandle *CloneNativeBufferHandle(const BufferHandle *other); + +/** + * @brief Releases a BufferHandle object. + * + * @param handle Indicates the pointer to the BufferHandle object to release. + * + * @since 1.0 + */ +void FreeNativeBufferHandle(BufferHandle *handle); + +/** + * @brief Serializes a BufferHandle object. + * + * You can use this API to write a BufferHandle object to a HdfSBuf object. HdfSbufWriteNativeBufferHandle and HdfSbufReadNativeBufferHandle are used in pairs. + * + * @param data Indicates the pointer to the HdfSBuf object. + * @param handle Indicates the pointer to the BufferHandle object to serialize. + * + * @since 1.0 + */ +bool HdfSbufWriteNativeBufferHandle(struct HdfSBuf *data, const BufferHandle *handle); + +/** + * @brief Deserializes a BufferHandle object. + * + * You can use this API to read a BufferHandle object from a HdfSBuf object according to the serialization format and create a new BufferHandle object. HdfSbufWriteNativeBufferHandle and HdfSbufReadNativeBufferHandle are used in pairs. + * + * @param data Indicates the pointer to the HdfSBuf object. + * @return Returns the pointer to the BufferHandle obtained if the operation is successful; returns NULL otherwise. + * + * @since 1.0 + */ +BufferHandle *HdfSbufReadNativeBufferHandle(struct HdfSBuf *data); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif // HDI_BUFFER_UTIL_H diff --git a/apis/20230220/inner_api/hdi/base/hdi_smq.h b/apis/20230220/inner_api/hdi/base/hdi_smq.h index 43769334833648e7ff65d530892041181d5ac5b7..cbe05dfef3e9b1b46c1c4c43ec34d3472039c59c 100755 --- a/apis/20230220/inner_api/hdi/base/hdi_smq.h +++ b/apis/20230220/inner_api/hdi/base/hdi_smq.h @@ -17,9 +17,9 @@ * @addtogroup DriverHdi * @{ * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 +* @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in interface description language (IDL). * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 + * The HDF and IDL code generated allow the system ability to accesses HDI driver services. * * @since 1.0 */ @@ -27,8 +27,8 @@ /** * @file hdi_smq.h * - * @brief 内存共享队列机制是进程间通信的常用机制，需要把内存共享队列机制作为idl语法的基本类型进行支持， - * 业务模块在idl中只需要定义该结构，HDI模块提供常用的读写队列等常见的操作。 + * @brief Provides APIs for the shared memory queue (SMQ). + * The SMQ is a common mechanism for inter-process communication. The SMQ must comply with the IDL syntax. You only need to define the SMQ struct in IDL for the service module. The HDI module provides common operations for reading and writing the SMQ. * * @since 1.0 */ @@ -63,9 +63,9 @@ namespace OHOS { namespace HDI { namespace Base { /** - * @brief 定义共享内存队列类 + * @brief Defines the SharedMemQueue class. * - * SMQ是一种用于进程间单工方式通信的消息队列，支持一端写入，另一端读取，支持阻塞或非阻塞式读写 + * The SMQ is a message queue used for simplex communication between processes. It allows data write from one end and read at the other end, in either blocking or non-blocking mode. * * @since 1.0 */ @@ -73,17 +73,17 @@ template class SharedMemQueue { public: /** - * @brief 共享内存队列构造函数 + * @brief A constructor used to create a SharedMemQueue object. * - * @param elementCount 队列大小，表示队列固定大小，可以存储的最大元素个数 - * @param type 表明SMQ是同步/异步类型，其值必须为SYNCED_SMQ（同步队列）或UNSYNC_SMQ（异步队列） + * @param elementCount Indicates the queue size, that is, the maximum number of elements allowed in the queue. + * @param type Indicates whether the SMQ is synchronous (SYNCED_SMQ) or asynchronous (UNSYNC_SMQ). * * @since 1.0 */ SharedMemQueue(uint32_t elementCount, SmqType type); /** - * @brief 共享内存队列拷贝函数 + * @brief A function used to copy the SharedMemQueue object. * * @since 1.0 */ @@ -91,184 +91,184 @@ public: ~SharedMemQueue(); /** - * @brief 阻塞方式写入共享内存队列 + * @brief Writes an array of elements to the SMQ in blocking mode. * - * 以阻塞方式向共享内存队列中写元素，共享内存队列满时此接口阻塞直到队列可写 + * When the SMQ is full, this API is blocked until the queue is writeable. * - * @param data 指向要写入共享内存队列的对象数组地址 - * @param count 写入元素个数 - * @return 成功返回0，失败返回非0 + * @param data Indicates the pointer to the array of elements to write. + * @param count Indicates the number of elements to write. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. * * @since 1.0 */ int Write(const T *data, size_t count); /** - * @brief 阻塞方式读取共享内存队列 + * @brief Reads an array of elements from the SMQ in blocking mode. * - * 以阻塞方式从队列中读元素，共享内存队列为空时此接口阻塞直到队列可读 + * When the SMQ is empty, this API is blocked until the queue is readable. * - * @param data 指向从共享内存队列读取的对象要拷贝到的内存地址 - * @param count 读取元素个数 - * @return 成功返回0，失败返回非0 + * @param data Indicates the pointer to the buffer for storing the elements read. + * @param count Indicates the number of elements to read. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. * * @since 1.0 */ int Read(T *data, size_t count); /** - * @brief 阻塞方式写入共享内存队列 + * @brief Writes a single element to the SMQ in blocking mode. * - * 以阻塞方式向共享内存队列写入单个元素，共享内存队列满时此接口阻塞直到队列可写 + * When the SMQ is full, this API is blocked until the queue is writeable. * - * @param data 指向要写入SQM的对象指针 - * @return 成功返回0，失败返回非0 + * @param data Indicates the pointer to the single element to write. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. * * @since 1.0 */ int Write(const T *data); /** - * @brief 阻塞方式读取共享内存队列 + * @brief Reads a single element from the SMQ in blocking mode. * - * 以阻塞方式从共享内存队列中读取单个元素，共享内存队列为空时此接口阻塞直到队列可读 + * When the SMQ is empty, this API is blocked until the queue is readable. * - * @param data 指向从S共享内存队列读取的对象要拷贝到的内存地址 - * @return 成功返回0，失败返回非0 + * @param data Indicates the pointer to the buffer for storing the single element read. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. * * @since 1.0 */ int Read(T *data); /** - * @brief 阻塞写入共享内存队列 + * @brief Writes a fixed number of elements to the SMQ in blocking mode. * - * 以阻塞方式向共享内存队列中写入固定数量元素，共享内存队列满时此接口阻塞直到可写入或写入超时返回 + * When the SMQ is full, this API is blocked until the queue is writeable or the write operation times out. * - * @param data 指向要写入共享内存队列的对象数组地址 - * @param count 写入元素个数 - * @param waitTimeNanoSec 写入超时时间，（单位：纳秒） - * @return 成功返回0，失败返回非0 + * @param data Indicates the pointer to the array of elements to write. + * @param count Indicates the number of elements to write. + * @param waitTimeNanoSec Indicates the write operation timeout period, in nanoseconds. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. * * @since 1.0 */ int Write(const T *data, size_t count, int64_t waitTimeNanoSec); /** - * @brief 阻塞读取共享内存队列 + * @brief Reads a fixed number of elements from the SMQ in blocking mode. * - * 以阻塞方式从共享内存队列中读元素，共享内存队列元素数小于读取数时此接口阻塞直到队列可读或读取超时 + * When the number of elements in the SMQ is less than the number of elements to read, this API is blocked until the queue is readable or the read operation times out. * - * @param data 指向从SQM读取的对象要拷贝到的内存地址 - * @param count 读取个数 - * @param waitTimeNanoSec 读取超时时间，（单位：纳秒） - * @return 成功返回0，失败返回非0 + * @param data Indicates the pointer to the buffer for storing the elements read. + * @param count Indicates the number of elements to read. + * @param waitTimeNanoSec Indicates the read operation timeout period, in nanoseconds. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. * * @since 1.0 */ int Read(T *data, size_t count, int64_t waitTimeNanoSec); /** - * @brief 非阻塞写入SMQ + * @brief Writes a single element to the SMQ in non-blocking mode. * - * 以非阻塞方式向SMQ中写单个元素。SMQ队列满时写入溢出，溢出的元素会覆盖前面的元素数据 + * When the SMQ queue is full, the SMPQ overflows. The overflowed element will be overwritten. * - * @param data 指向要写入SQM的对象地址 - * @return 成功返回0，失败返回非零 + * @param data Indicates the pointer to the single element to write. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. * * @since 1.0 */ int WriteNonBlocking(const T *data); /** - * @brief 非阻塞读取SMQ + * @brief Reads a single element from the SMQ in non-blocking mode. + * * - * 以非阻塞方式从SMQ中读单个元素 * - * @param data 指向从SQM读取的对象要拷贝到的内存地址 - * @return 成功返回0，失败返回非0 + * @param data Indicates the pointer to the buffer for storing the element read. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. * * @since 1.0 */ int ReadNonBlocking(T *data); /** - * @brief 非阻塞写入SMQ + * @brief Writes a fixed number of elements to the SMQ in non-blocking mode. * - * 以非阻塞方式向SMQ中写入固定数量元素，写入溢出的元素会覆盖前面的元素数据 + * When the SMQ is full, the SMQ overflows. The overflowed elements will be overwritten. * - * @param data 指向要写入SQM的对象地址 - * @param count 写入元素个数 - * @return 成功返回0，失败返回非0 + * @param data Indicates the pointer to the elements to write. + * @param count Indicates the number of elements to write. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. * * @since 1.0 */ int WriteNonBlocking(const T *data, size_t count); /** - * @brief 非阻塞读取SMQ + * @brief Reads a fixed number of elements from the SMQ in non-blocking mode. * - * 以非阻塞方式从队列中读取固定数量元素，SMQ队列没有足够的元素读取时会立即返回 + * If the SMQ queue does not have sufficient elements to read, a failure is returned immediately. * - * @param data 读取后存储的缓冲区，缓冲区可容纳元素个数需大于读取个数 - * @param count 期望读取个数 - * @return 成功返回0，失败返回非0 + * @param data Indicates the pointer to the buffer for storing the data read. The number of elements that can be held in the buffer must be greater than the number of elements read. + * @param count Indicates the number of elements to read. + * @return Returns 0 if the operation is successful; returns a non-zero value otherwise. * * @since 1.0 */ int ReadNonBlocking(T *data, size_t count); /** - * @brief 获取当前SMQ可写入元素个数 + * @brief Obtains the number of elements that can be written to the SMQ. * - * @return 返回当前SMQ队列中可写入元素个数 + * @return Returns the number of elements that can be written to the SMQ. * * @since 1.0 */ size_t GetAvalidWriteSize(); /** - * @brief 获取当前SMQ可读取元素个数 + * @brief Obtains the number of elements that can be read from the SMQ. * - * @return 返回当前SMQ队列中可读取元素个数 + * @return Returns the number of elements that can be read from the SMQ. * * @since 1.0 */ size_t GetAvalidReadSize(); /** - * @brief SMQ队列字节大小 + * @brief Obtains the size of the SMQ, in bytes. * - * @return 返回SMQ队列所占字节大小 + * @return Returns the number of bytes occupied by the SMQ. * * @since 1.0 */ size_t GetSize(); /** - * @brief 获取元数据对象 + * @brief Obtains the metadata object. * - * @return 返回元数据对象 + * @return Returns the metadata object obtained. * * @since 1.0 */ std::shared_ptr> GetMeta(); /** - * @brief 检查SMQ对象是否有效 + * @brief Checks whether the SMQ object is valid. * - * @return 对象有效返回true，无效对象返回false + * @return Returns true if the object is valid; returns false otherwise. * * @since 1.0 */ bool IsGood(); /** - * @brief 获取当前时间戳 + * @brief Obtains the current timestamp, in nanoseconds. * - * 获取当前时间戳，单位：纳秒 * - * @return 当前时间戳 + * + * @return Returns the timestamp obtained. * * @since 1.0 */ diff --git a/apis/20230220/inner_api/hdi/base/hdi_smq_meta.h b/apis/20230220/inner_api/hdi/base/hdi_smq_meta.h index 72730eeee09089f9762c504168cbae9a6ae0bb32..a57e0dad6a0f7ef864e10e5f1ec69dfe1745c410 100755 --- a/apis/20230220/inner_api/hdi/base/hdi_smq_meta.h +++ b/apis/20230220/inner_api/hdi/base/hdi_smq_meta.h @@ -17,9 +17,9 @@ * @addtogroup DriverHdi * @{ * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in interface description language (IDL). * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 + * The HDF and IDL code generated allow the system ability to accesses HDI driver services. * * @since 1.0 */ @@ -27,7 +27,7 @@ /** * @file hdi_smq_meta.h * - * @brief 提供内存共享队列的元数据结构、获取数据结构成员的接口函数，以及内存共享队列元数据结构序列化和反序列化的相关操作接口。 + * @brief Defines the metadata struct of the shared memory queue (SMQ) and provides APIs for obtaining the data struct members and serializing and deserializing the metadata struct. * * @since 1.0 */ @@ -51,31 +51,31 @@ namespace HDI { namespace Base { /** - * @brief 定义共享内存队列的同步枚举类型 + * @brief Enumerates the SMQ types. * * @since 1.0 */ enum SmqType : uint32_t { - /** 同步通信共享内存队列类型 */ + /** SMQ for synchronous communication */ SYNCED_SMQ = 0x01, - /** 异步通信共享内存队列类型 */ + /** SMQ for asynchronous communication */ UNSYNC_SMQ = 0x02, }; /** - * @brief 定义内存区数据结构 + * @brief Defines the MemZone struct. * * @since 1.0 */ struct MemZone { - /** 内存大小 */ + /** Memory zone size */ uint32_t size; - /** 内存偏移量 */ + /** Memory zone offset */ uint32_t offset; }; /** - * @brief 定义共享内存队列元数据模板类型 + * @brief Defines the metadata template type of the SMQ. * * @since 1.0 */ @@ -83,35 +83,35 @@ template class SharedMemQueueMeta { public: /** - * @brief 共享内存队列元数据缺省构造函数 + * @brief Default constructor used to create a SharedMemQueueMeta object. * * @since 1.0 */ SharedMemQueueMeta() : SharedMemQueueMeta(-1, 0, 0) {} /** - * @brief 共享内存队列元数据构造函数 + * @brief A constructor used to create a SharedMemQueueMeta object. * - * @param elementCount 队列大小 - * @param type 共享内存队列的同步类型 + * @param elementCount Indicates the queue size. + * @param type Indicates the SMQ type. * * @since 1.0 */ SharedMemQueueMeta(size_t elementCount, SmqType type) : SharedMemQueueMeta(-1, elementCount, type) {} /** - * @brief 共享内存队列元数据构造函数 + * @brief A constructor used to create a SharedMemQueueMeta object. * - * @param fd 共享内存文件标识符 - * @param elementCount 队列大小 - * @param type 共享内存队列的同步类型 + * @param fd Indicates the file descriptor (FD) of the shared memory file. + * @param elementCount Indicates the queue size. + * @param type Indicates the SMQ type. * * @since 1.0 */ SharedMemQueueMeta(int fd, size_t elementCount, SmqType type); /** - * @brief 共享内存队列元数据拷贝构造函数 + * @brief A constructor used to copy a SharedMemQueueMeta object. * - * @param other 待拷贝的共享内存队列元数据类型对象 + * @param other Indicates the SharedMemQueueMeta object to copy. * * @since 1.0 */ @@ -119,122 +119,122 @@ public: ~SharedMemQueueMeta() = default; /** - * @brief 共享内存队列元数据赋值构造函数 + * @brief A constructor used to assign values to the SharedMemQueueMeta object. * - * @param other 待拷贝的共享内存队列元数据类型对象 + * @param other Indicates the SharedMemQueueMeta object to copy. * * @since 1.0 */ SharedMemQueueMeta &operator=(const SharedMemQueueMeta &other); /** - * @brief 设置共享内存文件标识符 + * @brief Sets an FD. * - * @param fd 共享内存文件标识符 + * @param fd Indicates the FD to set. * * @since 1.0 */ void SetFd(int fd); /** - * @brief 获取共享内存文件标识符 + * @brief Obtains the FD. * - * @return 返回共享内存文件标识符 + * @return Returns the FD obtained. * * @since 1.0 */ int GetFd(); /** - * @brief 获取共享内存大小 + * @brief Obtains the shared memory size. * - * @return 返回共享内存大小 + * @return Returns the shared memory size obtained. * * @since 1.0 */ size_t GetSize(); /** - * @brief 获取共享内存队列的同步类型 + * @brief Obtains the SMQ type. * - * @return 返回共享内存队列的同步类型 + * @return Returns the SMQ type obtained. * * @since 1.0 */ uint32_t GetType(); /** - * @brief 获取共享内存队列元素个数 + * @brief Obtains the number of elements in the SMQ. * - * @return 返回队列元素个数 + * @return Returns the number of elements in the SMQ obtained. * * @since 1.0 */ size_t GetElementCount(); /** - * @brief 获取共享内存队列中单个元素大小 + * @brief Obtains the size of a single element in the SMQ. * - * @return 返回共享内存队列中单个元素大小 + * @return Returns the size of a single element obtained. * * @since 1.0 */ size_t GetElemenetSize() const; /** - * @brief 定义共享内存枚举类型 + * @brief Enumerates the shared memory zone types. * * @since 1.0 */ enum MemZoneType : uint32_t { - /** 共享内存读指针类型 */ + /** Read pointer */ MEMZONE_RPTR, - /** 共享内存写指针类型 */ + /** Write pointer */ MEMZONE_WPTR, - /** 共享内存同步字类型 */ + /** Syncword */ MEMZONE_SYNCER, - /** 共享内存数据类型 */ + /** Data */ MEMZONE_DATA, - /** 共享内存个数类型 */ + /** Number of shared memory zones */ MEMZONE_COUNT, }; /** - * @brief 获取共享内存特定类型的控制块 + * @brief Obtains the memory zone of the specified type. * - * @param type 共享内存类型 - * @return SMQ共享内存控制块 + * @param type Indicates the type of the shared memory zone. + * @return Returns the shared memory zone obtained. * * @since 1.0 */ MemZone *GetMemZone(uint32_t type); /** - * @brief 将共享内存队列写入MessageParcel中 + * @brief Writes the SMQ to a MessageParcel object. * - * @param parcel 要写入的数据对象 - * @return 成功返回true，失败返回false + * @param parcel Indicates the MessageParcel object. + * @return Returns true if the operation is successful; returns false otherwise. * * @since 1.0 */ bool Marshalling(MessageParcel &parcel); /** - * @brief 从MessageParcel对象读取共享内存队列 + * @brief Reads the SMQ from a MessageParcel object. * - * @param parcel 要读取的数据对象 + * @param parcel Indicates the MessageParcel object from which the SMQ is to read. * - * @return 返回一个SharedMemQueueMeta对象，用于创建sqm对象 + * @return Returns a SharedMemQueueMeta object, which can be used to create an SQM object. * * @since 1.0 */ static std::shared_ptr> UnMarshalling(MessageParcel &parcel); /** - * @brief 对内存大小按8字节对齐计算 + * @brief Aligns the buffer by 8 bytes. * - * @param num 给定字节数大小 - * @return 返回对齐后的字节数大小 + * @param num Indicates the number of bytes for aligning the buffer. + * @return Returns the number of bytes after alignment. * * @since 1.0 */ @@ -245,29 +245,29 @@ public: } private: - /** 共享内存文件标识符 */ + /** FD of the shared memory file */ int ashmemFd_; - /** 共享内存大小 */ + /** Size of the shared memory */ size_t size_; - /** 共享内存队列元素个数 */ + /** Number of elements in the SMQ */ size_t elementCount_; - /** 共享内存队列中元素大小 */ + /** Size of an element in the SMQ */ size_t elementSize_; - /** 共享内存队列类型 */ + /** SMQ type */ SmqType type_; - /** 共享内存控制块 */ + /** Number of shared memory zones */ MemZone memzone_[MEMZONE_COUNT]; }; /** - * @brief 共享内存队列元数据赋值构造函数 + * @brief A constructor used to assign values to the SharedMemQueueMeta object. * - * @param other 待拷贝的共享内存队列元数据类型对象 + * @param other Indicates the SharedMemQueueMeta object to copy. * @since 1.0 * */ @@ -338,9 +338,9 @@ SharedMemQueueMeta::SharedMemQueueMeta(const SharedMemQueueMeta &other) } /** - * @brief 设置共享内存文件标识符 + * @brief Sets an FD. * - * @param fd 共享内存文件标识符 + * @param fd Indicates the FD to set. * * @since 1.0 */ @@ -354,9 +354,9 @@ void SharedMemQueueMeta::SetFd(int fd) } /** - * @brief 获取共享内存文件标识符 + * @brief Obtains the FD. * - * @return 返回共享内存文件标识符 + * @return Returns the FD obtained. * * @since 1.0 */ @@ -367,9 +367,9 @@ int SharedMemQueueMeta::GetFd() } /** - * @brief 获取共享内存大小 + * @brief Obtains the shared memory size. * - * @return 返回共享内存大小 + * @return Returns the shared memory size obtained. * * @since 1.0 */ @@ -380,9 +380,9 @@ size_t SharedMemQueueMeta::GetSize() } /** - * @brief 获取共享内存队列的同步类型 + * @brief Obtains the SMQ type. * - * @return 返回共享内存队列的同步类型 + * @return Returns the SMQ type obtained. * * @since 1.0 */ @@ -393,9 +393,9 @@ uint32_t SharedMemQueueMeta::GetType() } /** - * @brief 获取共享内存队列元素个数 + * @brief Obtains the number of elements in the SMQ. * - * @return 返回队列元素个数 + * @return Returns the number of elements in the SMQ obtained. * * @since 1.0 */ @@ -406,9 +406,9 @@ size_t SharedMemQueueMeta::GetElementCount() } /** - * @brief 获取共享内存队列中单个元素大小 + * @brief Obtains the size of a single element in the SMQ. * - * @return 返回共享内存队列中单个元素大小 + * @return Returns the size of a single element obtained. * * @since 1.0 */ @@ -419,10 +419,10 @@ size_t SharedMemQueueMeta::GetElemenetSize() const } /** - * @brief 获取共享内存特定类型的控制块 + * @brief Obtains the memory zone of the specified type. * - * @param type 共享内存类型 - * @return SMQ共享内存控制块 + * @param type Indicates the type of the shared memory zone. + * @return Returns the shared memory zone obtained. * * @since 1.0 */ @@ -437,10 +437,10 @@ MemZone *SharedMemQueueMeta::GetMemZone(uint32_t type) } /** - * @brief 把共享内存队列序列化为MessageParcel对象 + * @brief Marshals the SMQ into a MessageParcel object. * - * @param parcel 序列化后的对象 - * @return 成功返回true，失败返回false + * @param parcel Indicates the MessageParcel object after marshalling. + * @return Returns true if the operation is successful; returns false otherwise. * * @since 1.0 */ @@ -455,10 +455,10 @@ bool SharedMemQueueMeta::Marshalling(MessageParcel &parcel) } /** - * @brief 从MessageParcel对象反序列化出共享内存队列 + * @brief Unmarshals the SMQ from a MessageParcel object. * - * @param parcel 待反序列化的对象 - * @return 返回一个SharedMemQueueMeta对象，用于创建sqm对象 + * @param parcel Indicates the MessageParcel object to unmarshal. + * @return Returns a SharedMemQueueMeta object, which can be used to create an SQM object. * * @since 1.0 */ diff --git a/apis/20230220/inner_api/hdi/base/hdi_smq_syncer.h b/apis/20230220/inner_api/hdi/base/hdi_smq_syncer.h index 6f0211d77674cb70f35b0aca0cd057a254184ee8..c34fa078fcd92cea98a33afc71de4c91a8b683a6 100755 --- a/apis/20230220/inner_api/hdi/base/hdi_smq_syncer.h +++ b/apis/20230220/inner_api/hdi/base/hdi_smq_syncer.h @@ -17,9 +17,9 @@ * @addtogroup DriverHdi * @{ * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in interface description language (IDL). * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 + * The HDF and IDL code generated allow the system ability to accesses HDI driver services. * * @since 1.0 */ @@ -27,7 +27,7 @@ /** * @file native_buffer.h * - * @brief 提供共享内存队列同步机制，包括唤醒、等待接口。 + * @brief Provides communication mechanisms, including the wait() and wake() APIs, for the shared memory queue (SMQ). * * @since 1.0 */ @@ -43,7 +43,7 @@ namespace OHOS { namespace HDI { namespace Base { /** - * @brief 定义共享内存队列同步类。 + * @brief Defines the SharedMemQueueSyncer class. * * @since 1.0 */ @@ -52,31 +52,31 @@ public: explicit SharedMemQueueSyncer(std::atomic *syncerPtr); ~SharedMemQueueSyncer() = default; /** - * @brief 定义同步枚举类型。 + * @brief Enumerates the synchronization types. * * @since 1.0 */ enum SyncWord : uint32_t { - /** 同步写 */ + /** Synchronous write */ SYNC_WORD_WRITE = 0x01, - /** 同步读 */ + /** Synchronous read */ SYNC_WORD_READ = 0x02, }; /** - * @brief 该函数用于等待，调用私有的成员函数FutexWait。 + * @brief Waits until a certain condition becomes true. This API will invoke the private member function FutexWait. * - * @param bitset 同步枚举类型。 - * @param timeoutNanoSec 等待时长，单位为纳秒。 - * @return 返回0表示调用者被唤醒。 + * @param bitset Indicates the synchronization type. + * @param timeoutNanoSec Indicates the time to wait, in nanoseconds. + * @return Returns 0 if the caller is woken up. * * @since 1.0 */ int Wait(uint32_t bitset, int64_t timeoutNanoSec); /** - * @brief 该函数用于唤醒等待者。 + * @brief Wakes up a waiter. * - * @param bitset 同步枚举类型。 - * @return 返回0代表唤醒成功。 + * @param bitset Indicates the synchronization type. + * @return Returns 0 if the waiter is woken up. * * @since 1.0 */ @@ -84,20 +84,20 @@ public: private: /** - * @brief 该函数用于等待。 + * @brief Waits until a certain condition becomes true. * - * @param bitset 同步枚举类型。 - * @param timeoutNanoSec 等待时长，单位为纳秒。 - * @return 返回0表示调用者被唤醒。 + * @param bitset Indicates the synchronization type. + * @param timeoutNanoSec Indicates the time to wait, in nanoseconds. + * @return Returns 0 if the caller is woken up. * * @since 1.0 */ int FutexWait(uint32_t bitset, int64_t timeoutNanoSec); /** - * @brief 该函数用于将等待时间转换为实际时间。 + * @brief Converts the wait time to real time. * - * @param timeout 等待时间。 - * @param realtime 实际时间。 + * @param timeout Indicates the wait time. + * @param realtime Indicates the real time. * * @since 1.0 */ diff --git a/apis/20230220/inner_api/hdi/base/native_buffer.h b/apis/20230220/inner_api/hdi/base/native_buffer.h index 9f37ddf094e26ab8d69ea703d56ecf9615344409..c22d4870b91eeb7b655b19527710db65dda6e515 100755 --- a/apis/20230220/inner_api/hdi/base/native_buffer.h +++ b/apis/20230220/inner_api/hdi/base/native_buffer.h @@ -1,159 +1,159 @@ -/* - * Copyright (c) 2022 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 DriverHdi - * @{ - * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 - * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 - * - * @since 1.0 - */ - -/** - * @file native_buffer.h - * - * @brief 提供NativeBuffer的C++接口。 - * - * NativeBuffer是BufferHandle的包装器，管理所持有的BufferHandle对象资源，适用于HDI层 - * - * @since 1.0 - */ - -#ifndef HDI_NATIVE_BUFFER_H -#define HDI_NATIVE_BUFFER_H - -#include -#include "buffer_handle.h" - -namespace OHOS { -namespace HDI { -namespace Base { -using OHOS::MessageParcel; -using OHOS::Parcelable; - -/** - * @brief 定义NativeBuffer类 - * - */ -class NativeBuffer : public Parcelable { -public: - NativeBuffer(); - virtual ~NativeBuffer(); - explicit NativeBuffer(const BufferHandle *handle); - - NativeBuffer(const NativeBuffer &other); - NativeBuffer(NativeBuffer &&other) noexcept; - - NativeBuffer &operator=(const NativeBuffer &other); - NativeBuffer &operator=(NativeBuffer &&other) noexcept; - - /** - * @brief 将NativeBuffer对象序列化写入MessageParcel对象 - * - * 和函数Unmarshalling配对使用 - * - * @param parcel 写入目标 须传入MessageParcel类型对象 - * @return 成功返回true，失败返回false - * - * @since 1.0 - */ - bool Marshalling(Parcel &parcel) const override; - - /** - * @brief 从MessageParcel对象中读取并创建新的NativeBuffer对象 - * - * 和函数Marshalling配对使用 - * - * @param parcel 读取源 须传入MessageParcel类型对象 - * @return 成功返回新NativeBuffer对象，失败返回nullptr - * - * @since 1.0 - */ - static sptr Unmarshalling(Parcel &parcel); - - /** - * @brief 克隆BufferHandle对象 - * - * 克隆NativeBuffer对象所持有的BufferHandle对象 - * - * @return 成功返回克隆后的BufferHandle对象指针，失败返回nullptr - * - * @since 1.0 - */ - BufferHandle *Clone(); - - /** - * @brief 移动BufferHandle对象 - * - * 转移NativeBuffer对象所持有的BufferHandle对象所有权，转移所有权后， - * 需使用FreeNativeBufferHandle释放BufferHandle对象 - * - * @return 成功返回移动后的BufferHandle对象指针，失败返回nullptr - * - * @since 1.0 - */ - BufferHandle *Move() noexcept; - - /** - * @brief 设置BufferHandle对象 - * - * 设置BufferHandle对象，并自定义BufferHandle的所有权 - * - * @param handle 设置的BufferHandle对象 - * @param isOwner 设置BufferHandle对象所有权，true表示NativeBuffer对象管理 - * BufferHandle对象资源，false表示不管理BufferHandle对象的资源，默认为false - * @param destructor 设置BufferHandle对象的释放函数，默认使用FreeNativeBufferHandle释放 - * - * @since 1.0 - */ - void SetBufferHandle(BufferHandle *handle, bool isOwner = false, - std::function destructor = nullptr); - - /** - * @brief 借用BufferHandle对象 - * - * 借用BufferHandle对象，NativeBuffer对象仍持有其内部BufferHandle对象的所有权 - * - * @return 成功返回NativeBuffer对象所持有的BufferHandle对象指针，失败返回nullptr - * - * @since 1.0 - */ - BufferHandle *GetBufferHandle() noexcept; - - /** - * @brief 打印dump信息 - * - * @return 返回BufferHandle对象dump信息 - * - * @since 1.0 - */ - std::string Dump() const; -private: - bool ExtractFromParcel(Parcel &parcel); - static bool WriteReserveData(MessageParcel &messageParcel, const BufferHandle &handle); - static bool ReadReserveData(MessageParcel &messageParcel, BufferHandle &handle); - void DestroyBuffer(); - BufferHandle *handle_; - bool isOwner_; - std::function bufferDestructor_; -}; -} // namespace Base -} // namespace HDI -} // namespace OHOS - -#endif // HDI_NATIVE_BUFFER_H +/* + * Copyright (c) 2022 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 DriverHdi + * @{ + * + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in interface description language (IDL). + * + * The HDF and IDL code generated allow the system ability to accesses HDI driver services. + * + * @since 1.0 + */ + +/** + * @file native_buffer.h + * + * @brief Provides C++ interfaces for NativeBuffer. + * + * NativeBuffer is the wrapper of BufferHandle. It manages the BufferHandle objects and applies to the HDI layer. + * + * @since 1.0 + */ + +#ifndef HDI_NATIVE_BUFFER_H +#define HDI_NATIVE_BUFFER_H + +#include +#include "buffer_handle.h" + +namespace OHOS { +namespace HDI { +namespace Base { +using OHOS::MessageParcel; +using OHOS::Parcelable; + +/** + * @brief Defines the NativeBuffer class. + * + */ +class NativeBuffer : public Parcelable { +public: + NativeBuffer(); + virtual ~NativeBuffer(); + explicit NativeBuffer(const BufferHandle *handle); + + NativeBuffer(const NativeBuffer &other); + NativeBuffer(NativeBuffer &&other) noexcept; + + NativeBuffer &operator=(const NativeBuffer &other); + NativeBuffer &operator=(NativeBuffer &&other) noexcept; + + /** + * @brief Marshals this NativeBuffer object into a MessageParcel object. + * + * Marshalling() and Unmarshalling() are used in pairs. + * + * @param parcel Indicates the MessageParcel object to which the NativeBuffer object is marshalled. + * @return Returns true if the operation is successful; returns false otherwise. + * + * @since 1.0 + */ + bool Marshalling(Parcel &parcel) const override; + + /** + * @brief Unmarshals a NativeBuffer object from a MessageParcel object. + * + * Marshalling() and Unmarshalling() are used in pairs. + * + * @param parcel Indicates the MessageParcel object from which the BufferHandle object is unmarshalled. + * @return Returns the NativeBuffer object obtained if the operation is successful; returns nullptr otherwise. + * + * @since 1.0 + */ + static sptr Unmarshalling(Parcel &parcel); + + /** + * @brief Clones a BufferHandle object. + * + * You can use this API to clone the BufferHandle object held by a NativeBuffer object. + * + * @return Returns the pointer to the BufferHandle cloned if the operation is successful; returns nullptr otherwise. + * + * @since 1.0 + */ + BufferHandle *Clone(); + + /** + * @brief Moves this BufferHandle object. + * + * This API transfers the ownership of the BufferHandle object held by the NativeBuffer object. After the ownership is transferred, + * you need to use FreeNativeBufferHandle to release the BufferHandle object. + * + * @return Returns the pointer to the BufferHandle object after the move if the operation is successful; returns nullptr otherwise. + * + * @since 1.0 + */ + BufferHandle *Move() noexcept; + + /** + * @brief Sets a BufferHandle object. + * + * You can use this API to set the owner of a BufferHandle object. + * + * @param handle Indicates the BufferHandle object to set. + * @param isOwner Indicates whether the BufferHandle object is managed by a NativeBuffer object. The value true means the BufferHandle object is managed by theNativeBuffer object; + * the value false means the opposite. The default value is false. + * @param destructor Indicates the function used to release the BufferHandle object. By default, FreeNativeBufferHandle is used. + * + * @since 1.0 + */ + void SetBufferHandle(BufferHandle *handle, bool isOwner = false, + std::function destructor = nullptr); + + /** + * @brief Obtains this BufferHandle object. + * + * The NativeBuffer object still hold the BufferHandle object. + * + * @return Returns the pointer to the BufferHandle object obtained if the operation is successful; returns nullptr otherwise. + * + * @since 1.0 + */ + BufferHandle *GetBufferHandle() noexcept; + + /** + * @brief Prints dump information. + * + * @return Returns dump information about this BufferHandle object. + * + * @since 1.0 + */ + std::string Dump() const; +private: + bool ExtractFromParcel(Parcel &parcel); + static bool WriteReserveData(MessageParcel &messageParcel, const BufferHandle &handle); + static bool ReadReserveData(MessageParcel &messageParcel, BufferHandle &handle); + void DestroyBuffer(); + BufferHandle *handle_; + bool isOwner_; + std::function bufferDestructor_; +}; +} // namespace Base +} // namespace HDI +} // namespace OHOS + +#endif // HDI_NATIVE_BUFFER_H diff --git a/apis/20230220/inner_api/hdi/devmgr_hdi.h b/apis/20230220/inner_api/hdi/devmgr_hdi.h deleted file mode 100755 index 8b8c70ec9ef749fc61dac2f8bed83ce12a2c7ec7..0000000000000000000000000000000000000000 --- a/apis/20230220/inner_api/hdi/devmgr_hdi.h +++ /dev/null @@ -1,165 +0,0 @@ -/* - * Copyright (c) 2021 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 DriverHdi - * @{ - * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 - * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 - * - * @since 1.0 - */ - -/** - * @file devmgr_hdi.h - * - * @brief 定义基于C语言的设备管理相关的数据结构和接口类型。 - * - * @since 1.0 - */ - -#ifndef HDI_DEVICE_MANAGER_INF_H -#define HDI_DEVICE_MANAGER_INF_H - -#include "hdf_base.h" -#include "hdf_dlist.h" - -#ifdef __cplusplus -extern "C" { -#endif /* __cplusplus */ - -struct HdfRemoteService; - -/** - * @brief 定义设备服务枚举类型。 - * - * @since 1.0 - */ -enum HDF_DEVICE_TYPE { - /** 定义本地服务类型 */ - HDF_LOCAL_SERVICE, - /** 定义远端服务类型 */ - HDF_REMOTE_SERVICE, -}; - -/** - * @brief 定义设备信息结构体类型。 - * - * @since 1.0 - */ -struct DeviceInfoNode { - /** 设备服务名字 */ - char *svcName; - /** 设备类型 */ - enum HDF_DEVICE_TYPE deviceType; - /** 设备信息节点，使用该节点把设备信息插入到设备链表中 */ - struct DListHead node; -}; - -/** - * @brief 定义设备信息链表数据结构。 - * - * @since 1.0 - */ -struct DeviceInfoList { - /** 链表中的设备数量 */ - uint32_t deviceCnt; - /** 设备信息链表 */ - struct DListHead list; -}; - -/** - * @brief 定义设备管理HDI接口，C语言开发者可以使用该接口获取设备信息以及加载、卸载设备等。 - * - * @since 1.0 - */ -struct HDIDeviceManager { - /** 远端服务对象 */ - struct HdfRemoteService *remote; - /** - * @brief 该函数用于释放查询到的设备信息链表。 - * 当调用者调用QueryUsableDeviceInfo或者QueryUnusableDeviceInfo查询到设备信息列表后，可以使用该函数释放设备信息链表数据结构。 - * @param self 设备管理对象。 - * @param list 表示待释放的设备信息链表。 - * - * @since 1.0 - */ - void (*FreeQueryDeviceList)(struct HDIDeviceManager *self, struct DeviceInfoList *list); - - /** - * @brief 该函数用于查询可用的设备信息。 - * 当调用者使用完设备信息后，需要调用FreeQueryDeviceList函数释放设备信息链表数据结构。 - * @param self 设备管理对象。 - * @param list 设备信息链表，用于存放查询到的设备信息。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 - * - * @since 1.0 - */ - int32_t (*QueryUsableDeviceInfo)(struct HDIDeviceManager *self, struct DeviceInfoList *list); - - /** - * @brief 该函数用于查询不可用的设备信息。 - * 当调用者使用完设备信息后，需要调用FreeQueryDeviceList函数释放设备信息链表数据结构。 - * @param self 设备管理对象。 - * @param list 设备信息链表，用于存放查询到的设备信息。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 - * - * @since 1.0 - */ - int32_t (*QueryUnusableDeviceInfo)(struct HDIDeviceManager *self, struct DeviceInfoList *list); - - /** - * @brief 该函数用于加载设备驱动。 - * @param self 设备管理对象。 - * @param serviceName 待加载设备的服务名字。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 - * - * @since 1.0 - */ - int32_t (*LoadDevice)(struct HDIDeviceManager *self, const char *serviceName); - - /** - * @brief 该函数用于卸载设备驱动。 - * @param self 设备管理对象。 - * @param serviceName 待卸载设备的服务名字。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 - * - * @since 1.0 - */ - int32_t (*UnloadDevice)(struct HDIDeviceManager *self, const char *serviceName); -}; - -/** - * @brief 该函数用于获取HDI设备管理对象。 - * @return 返回创建的设备管理对象。 - * - * @since 1.0 - */ -struct HDIDeviceManager *HDIDeviceManagerGet(void); - -/** - * @brief 该函数用于释放HDI设备管理对象。 - * @param devmgr 表示待释放的设备管理对象。 - * - * @since 1.0 - */ -void HDIDeviceManagerRelease(struct HDIDeviceManager *devmgr); -#ifdef __cplusplus -} -#endif /* __cplusplus */ - -#endif /* HDI_DEVICE_MANAGER_INF_H */ \ No newline at end of file diff --git a/apis/20230220/inner_api/hdi/hdi_base.h b/apis/20230220/inner_api/hdi/hdi_base.h deleted file mode 100755 index 61fe385c17ed660b7a98e4d451e32b5304092a29..0000000000000000000000000000000000000000 --- a/apis/20230220/inner_api/hdi/hdi_base.h +++ /dev/null @@ -1,68 +0,0 @@ -/* - * Copyright (c) 2022 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 DriverHdi - * @{ - * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 - * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 - * - * @since 1.0 - */ - -/** - * @file hdi_base.h - * - * @brief 定义HDI基类，用于管理HDI对象 - * - * @since 1.0 - */ - -#ifndef HDI_BASE_INTERFACE_H -#define HDI_BASE_INTERFACE_H - -#include -#include - -namespace OHOS { -namespace HDI { -/** - * @brief 定义HDI基类，用于管理HDI对象 - * @since 1.0 - */ -class HdiBase : virtual public OHOS::RefBase { -public: - HdiBase() = default; - virtual ~HdiBase() = default; -}; - -/** - * @brief 定义HDI接口描述的宏。 - * @param DESCRIPTOR 接口描述。 - * @since 1.0 - */ - -#define DECLARE_HDI_DESCRIPTOR(DESCRIPTOR) \ - const static inline std::u16string metaDescriptor_ = {DESCRIPTOR}; \ - const static inline std::u16string &GetDescriptor() \ - { \ - return metaDescriptor_; \ - } -} // namespace HDI -} // namespace OHOS - -#endif // HDI_BASE_INTERFACE_H diff --git a/apis/20230220/inner_api/hdi/hdi_support.h b/apis/20230220/inner_api/hdi/hdi_support.h deleted file mode 100755 index 45819906ea3c7f21ab5ca815d3afbd61ea52a7ce..0000000000000000000000000000000000000000 --- a/apis/20230220/inner_api/hdi/hdi_support.h +++ /dev/null @@ -1,67 +0,0 @@ -/* - * Copyright (c) 2022 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 DriverHdi - * @{ - * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 - * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 - * - * @since 1.0 - */ - -/** - * @file hdi_support.h - * - * @brief 定义加载和卸载HDI驱动的接口。 - * - * @since 1.0 - */ - -#ifndef HDF_HDI_SUPPORT_H -#define HDF_HDI_SUPPORT_H - -#include "hdf_base.h" - -#ifdef __cplusplus -extern "C" { -#endif /* __cplusplus */ -/** - * @brief 该函数用于加载业务模块的HDI驱动。 - * 该函数根据接口描述和服务名组合获取驱动名字，然后把设备驱动加载到系统中。 - * @param desc HDI接口描述。 - * @param serviceName 待加载驱动的服务名。 - * @return HDI驱动对象。 - */ - -void *LoadHdiImpl(const char *desc, const char *serviceName); - -/** - * @brief 该函数用于卸载业务模块的HDI驱动。 - * 该函数根据接口描述和服务名组合获取驱动名字，然后调用驱动的卸载函数进行卸载。 - * @param desc HDI接口描述。 - * @param serviceName 待卸载驱动的服务名字。 - * @param impl 待卸载的HDI驱动对象。 - */ - -void UnloadHdiImpl(const char *desc, const char *serviceName, void *impl); -#ifdef __cplusplus -} -#endif /* __cplusplus */ - -#endif /* HDF_HDI_SUPPORT_H */ - diff --git a/apis/20230220/inner_api/hdi/idevmgr_hdi.h b/apis/20230220/inner_api/hdi/idevmgr_hdi.h deleted file mode 100755 index edcea355859c4698831892588d9d57be695680de..0000000000000000000000000000000000000000 --- a/apis/20230220/inner_api/hdi/idevmgr_hdi.h +++ /dev/null @@ -1,118 +0,0 @@ -/* - * Copyright (c) 2021-2022 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 DriverHdi - * @{ - * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 - * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 - * - * @since 1.0 - */ - -/** - * @file idevmgr_hdi.h - * - * @brief 定义基于C++语言的设备管理相关的数据结构和接口类型。 - * - * @since 1.0 - */ -#ifndef HDI_DEVICE_MANAGER_HDI_INF_H -#define HDI_DEVICE_MANAGER_HDI_INF_H - -#include -#include - -namespace OHOS { -namespace HDI { -namespace DeviceManager { -namespace V1_0 { -/** - * @brief 定义设备信息结构体。 - * @since 1.0 - */ - -struct DevInfo { - /** 设备id */ - uint32_t devId; - /** 服务名 */ - std::string servName; - /** 设备名 */ - std::string deviceName; -}; - -/** - * @brief 定义设备信息列表结构体。 - * @since 1.0 - */ -struct HdiDevHostInfo { - /** host名称 */ - std::string hostName; - /** host的id */ - uint32_t hostId; - /** host节点所管理的各个设备信息列表 */ - std::vector devInfo; -}; - -/** - * @brief 定义设备管理HDI接口，C++语言开发者可以使用该接口获取设备信息以及加载、卸载设备等。 - * @since 1.0 - */ -class IDeviceManager : public HdiBase { -public: - /** HDI接口描述，用于HDI接口访问权限校验 */ - DECLARE_HDI_DESCRIPTOR(u"HDI.IDeviceManager.V1_0"); - IDeviceManager() = default; - virtual ~IDeviceManager() = default; - - /** - * @brief 该函数用于获取设备管理对象。 - * @return 返回创建的设备管理对象。 - * @since 1.0 - */ - static ::OHOS::sptr Get(); - /** - * @brief 该函数用于加载设备驱动。 - * @param serviceName 待加载设备的服务名。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 - * @since 1.0 - */ - - virtual int32_t LoadDevice(const std::string &serviceName) = 0; - - /** - * @brief 该函数用于卸载设备驱动。 - * @param serviceName 待卸载设备的服务名。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 - * @since 1.0 - */ - virtual int32_t UnloadDevice(const std::string &serviceName) = 0; - - /** - * @brief 该函数用于获取所有已加载的设备信息。 - * @param deviceInfos 查询到的所有已加载设备的信息。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 - * @since 1.0 - */ - virtual int32_t ListAllDevice(std::vector &deviceInfos) = 0; -}; -} // namespace V1_0 -} // namespace DeviceManager -} // namespace HDI -} // namespace OHOS - -#endif /* HDI_DEVICE_MANAGER_HDI_INF_H */ \ No newline at end of file diff --git a/apis/20230220/inner_api/hdi/iservmgr_hdi.h b/apis/20230220/inner_api/hdi/iservmgr_hdi.h deleted file mode 100755 index 3fd0d5078436b8ecf7149ecf39a275afd418eb4e..0000000000000000000000000000000000000000 --- a/apis/20230220/inner_api/hdi/iservmgr_hdi.h +++ /dev/null @@ -1,128 +0,0 @@ -/* - * Copyright (c) 2021-2022 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 DriverHdi - * @{ - * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 - * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 - * - * @since 1.0 - */ - -/** - * @file iservmgr_hdi.h - * - * @brief 定义基于C++语言的服务管理相关的数据结构和接口类型。 - * - * @since 1.0 - */ - -#ifndef HDI_ISERVICE_MANAGER_INF_H -#define HDI_ISERVICE_MANAGER_INF_H - -#include -#include -#include -#include - -#include "iservstat_listener_hdi.h" - -namespace OHOS { -namespace HDI { -namespace ServiceManager { -namespace V1_0 { -/** - * @brief 定义HDI服务信息结构体。 - * - * @since 1.0 - */ - -struct HdiServiceInfo { - /** hdi服务名 */ - std::string serviceName; - /** 设备类型 */ - uint16_t devClass; - /** 设备id */ - uint32_t devId; -}; - -/** - * @brief 定义服务管理HDI接口，C++语言开发者可以使用该接口获取服务、获取服务集合、注册服务状态监听等。 - * - * @since 1.0 - */ -class IServiceManager : public HdiBase { -public: - /** HDI接口描述，用于HDI接口访问权限校验 */ - DECLARE_HDI_DESCRIPTOR(u"HDI.IServiceManager.V1_0"); - - /** - * @brief 该函数用于获取服务管理对象。 - * @return 返回创建的服务管理对象。 - * @since 1.0 - */ - static ::OHOS::sptr Get(); - - /** - * @brief 该函数根据服务名获取HDI服务。 - * @param serviceName HDI服务名。 - * @return 返回查询到的HDI服务。 - * @since 1.0 - */ - virtual ::OHOS::sptr GetService(const char *serviceName) = 0; - - /** - * @brief 该函数获取所有的已加载HDI服务。 - * @param serviceInfos 查询到的所有已加载服务的信息。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 - * @since 1.0 - */ - virtual int32_t ListAllService(std::vector &serviceInfos) = 0; - - /** - * @brief 该函数给业务模块提供注册服务状态监听接口。 - * @param listener 待注册的监听器对象。 - * @param deviceClass 监听的设备服务类别。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 - * @since 1.0 - */ - - virtual int32_t RegisterServiceStatusListener(::OHOS::sptr listener, uint16_t deviceClass) = 0; - /** - * @brief 该函数用于注销服务状态监听器。 - * @param listener 待注销的监听器对象。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 - * @since 1.0 - */ - virtual int32_t UnregisterServiceStatusListener(::OHOS::sptr listener) = 0; - - /** - * @brief 该函数用于通过接口描述查询HDI服务。 - * @param serviceNames 保存查询到的服务名称。 - * @param interfaceDesc 接口描述。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 - * @since 1.0 - */ - virtual int32_t ListServiceByInterfaceDesc(std::vector &serviceNames, const char *interfaceDesc) = 0; -}; -} // namespace V1_0 -} // namespace ServiceManager -} // namespace HDI -} // namespace OHOS - -#endif /* HDI_ISERVICE_MANAGER_INF_H */ \ No newline at end of file diff --git a/apis/20230220/inner_api/hdi/iservstat_listener_hdi.h b/apis/20230220/inner_api/hdi/iservstat_listener_hdi.h deleted file mode 100755 index 37bd30ae43f1d8290b33545029d839e6fb8f148e..0000000000000000000000000000000000000000 --- a/apis/20230220/inner_api/hdi/iservstat_listener_hdi.h +++ /dev/null @@ -1,137 +0,0 @@ -/* - * Copyright (c) 2021 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 DriverHdi - * @{ - * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 - * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 - * - * @since 1.0 - */ - -/** - * @file iservstat_listener_hdi.h - * - * @brief 定义基于C++语言的服务状态监听相关的数据结构和接口类型。 - * - * @since 1.0 - */ - -#ifndef HDI_SERVICE_STATUS_LISTENER_INF_H -#define HDI_SERVICE_STATUS_LISTENER_INF_H - -#include -#include -#include - -#include "hdf_device_class.h" - -namespace OHOS { -namespace HDI { -namespace ServiceManager { -namespace V1_0 { - -/** - * @brief 定义服务状态的枚举类型。 - * - * @since 1.0 - */ -enum ServiceStatusType { - /** 表示服务已启动 */ - SERVIE_STATUS_START, - /** 表示服务状态已变更 */ - SERVIE_STATUS_CHANGE, - /** 表示服务已停止 */ - SERVIE_STATUS_STOP, - /** 表示服务状态的最大值 */ - SERVIE_STATUS_MAX, -}; - -/** - * @brief 定义服务状态结构体，该结构体为HDF框架通知业务模块服务状态类型。 - * - * @since 1.0 - */ -struct ServiceStatus { - /** 服务名 */ - std::string serviceName; - /** 设备类型 */ - uint16_t deviceClass; - /** 服务状态 */ - uint16_t status; - /** 服务信息 */ - std::string info; -}; - -/** - * @brief 定义业务模块的服务状态监听的接口类。 - * - * @since 1.0 - */ -class IServStatListener : public ::OHOS::IRemoteBroker { -public: - /** HDI接口描述，用于HDI接口访问权限校验 */ - DECLARE_INTERFACE_DESCRIPTOR(u"HDI.IServiceStatusListener.V1_0"); - - /** - * @brief 该虚函数代表监听器的回调函数，需要业务模块实现该函数。 - * @param status 表示监听到的服务状态。 - * @since 1.0 - */ - virtual void OnReceive(const ServiceStatus &status) = 0; -}; - -/** - * @brief 定义监听器桩类，提供接口参数的序列化/反序列化能力，监听器实现类需继承此类并实现OnReceive接口。 - */ -class ServStatListenerStub : public ::OHOS::IRemoteStub { -public: - ServStatListenerStub() = default; - virtual ~ServStatListenerStub() {} - - /** - * @brief 根据调用编号进行消息分发的函数，在该函数中会调用私有函数ServStatListenerStubOnReceive。 - * @param code IPC调用的分发命令字。 - * @param data 函数入参，HDF框架通过该参数把服务状态信息返回到业务模块 - * @param reply 函数出参，业务模块需要返回给HDF框架的参数。 - * @param option 调用类型。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示操作失败。 - * @since 1.0 - */ - int OnRemoteRequest(uint32_t code, ::OHOS::MessageParcel &data, ::OHOS::MessageParcel &reply, - ::OHOS::MessageOption &option) override; - -private: - /** - * @brief 用于处理OnReceive接口参数序列化/反序列化的函数。 - * @param code IPC调用的分发命令字。 - * @param data 函数入参，HDF框架通过该参数把服务状态信息返回到业务模块 - * @param reply 函数出参，业务模块需要返回给HDF框架的参数。 - * @param option 调用类型 - * @return 返回HDF_SUCCESS表示操作成功，否则表示操作失败。 - * @since 1.0 - */ - int32_t ServStatListenerStubOnReceive( - ::OHOS::MessageParcel &data, ::OHOS::MessageParcel &reply, ::OHOS::MessageOption &option); -}; -} // namespace V1_0 -} // namespace ServiceManager -} // namespace HDI -} // namespace OHOS - -#endif /* HDI_SERVICE_STATUS_LISTENER_INF_H */ \ No newline at end of file diff --git a/apis/20230220/inner_api/hdi/object_collector.h b/apis/20230220/inner_api/hdi/object_collector.h index 7f1f4d20acfd063890b2501def5860e2f2c5d228..eadc26f3c06e5a65fb50db6d08e8b928e5ccb471 100755 --- a/apis/20230220/inner_api/hdi/object_collector.h +++ b/apis/20230220/inner_api/hdi/object_collector.h @@ -17,9 +17,9 @@ * @addtogroup DriverHdi * @{ * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 + * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to automatically generate code in the interface description language (IDL). * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 + * The HDF and the IDL code generated allow system abilities to access HDI driver services. * * @since 1.0 */ @@ -27,10 +27,10 @@ /** * @file object_collector.h * - * @brief 定义对象收集器，提供对象构造函数管理以及对象管理的功能，供idl代码生成工具使用。 - * idl工具在生成类时，定义ObjectDelegator类型的静态内联对象，把接口名称和构造函数注册到对象收集器里面。 - * 在业务模块驱动初始化时，根据接口名称获取注册的构造函数，把接口实现作为构造对象的参数生成对象， - * 此处为IPC的stub对象，然后把stub对象注册到HDF的设备管理器里面。 + * @brief Defines an object collector for the hdi-gen tool to manage constructors and objects. + * When generating a class, the hdi-gen tool defines a static inline object of the ObjectDelegator type and registers the interface name and constructor with the object collector. + * When the service module driver is initialized, the registered constructor (obtained based on the interface name) is used to create and register the IPC stub object. + * * * @since 1.0 */ @@ -48,52 +48,52 @@ namespace OHOS { namespace HDI { /** - * @brief 定义对象收集器类型，提供对象构造函数管理以及对象管理的功能，供idl代码生成工具使用。 + * @brief Defines the ObjectCollector class for the hdi-gen tool to manage constructors and objects. * * @since 1.0 */ class ObjectCollector { public: - /** 定义构造函数接口类型 */ + /** Define the constructor interface type. */ using Constructor = std::function(const sptr &interface)>; - /** 获取对象收集器的管理对象实例 */ + /** Obtain the object instance managed by the ObjectCollector. */ static ObjectCollector &GetInstance(); - /** 根据接口名字注册构造函数 */ + /** Register a constructor based on the interface name. */ bool ConstructorRegister(const std::u16string &interfaceName, const Constructor &constructor); - /** 根据接口名字删除构造函数 */ + /** Unregister a constructor based on the interface name. */ void ConstructorUnRegister(const std::u16string &interfaceName); - /** 根据接口名字和接口实现生成对象 */ + /** Create an object based on the interface name and implementation. */ sptr NewObject(const sptr &interface, const std::u16string &interfaceName); - /** 根据接口名字和接口实现生成或者获取已有的对象 */ + /** Create or obtain an object based on the interface name and implementation. */ sptr GetOrNewObject(const sptr &interface, const std::u16string &interfaceName); - /** 根据接口实现删除对象 */ + /** Remove an object based on the interface implementation. */ bool RemoveObject(const sptr &interface); private: ObjectCollector() = default; - /** 根据接口名字和接口实现生成新的对象 */ + /** Create an object based on the interface name and implementation. */ sptr NewObjectLocked(const sptr &interface, const std::u16string &interfaceName); - /** 对象收集器的管理对象实例 */ + /** Instance of the object managed by the ObjectCollector. */ static ObjectCollector *instance_; - /** 定义接口名字和构造函数的映射表 */ + /** Define the mapping between the interface name and the constructor. */ std::map constructorMapper_; - /** 定义接口实现和对象的映射表 */ + /** Define the mapping between the interface implementation and the object. */ std::map interfaceObjectCollector_; - /** 支持对象收集器能并发访问的互斥锁 */ + /** Define a mutex to support concurrent access to the ObjectCollector. */ std::mutex mutex_; }; /** - * @brief 定义对象委托者模板类型，用于模板对象构造函数的注册和删除，供idl代码生成工具使用。 + * @brief Defines a ObjectDelegator template, which is used to register and unregister a template object constructor. * * @since 1.0 */ template class ObjectDelegator { public: - /** 构造函数，通过对象收集器完成模板类对象构造函数的注册 */ + /** Constructor, which registers a template object constructor through the ObjectCollector. */ ObjectDelegator(); - /** 析构函数，通过对象收集器完成模板类对象构造函数的删除 */ + /** Destructor, which unregisters a template object constructor through the ObjectCollector. */ ~ObjectDelegator(); private: @@ -104,10 +104,10 @@ private: }; /** - * @brief 对象委托者模板类构造函数，通过对象收集器完成模板类对象构造函数的注册。 + * @brief A constructor used to register an object constructor of the ObjectDelegator template through the ObjectCollector. * - * @param OBJECT 待生成的对象类型。 - * @param INTERFACE 业务模块的HDI接口类。 + * @param OBJECT Indicates the type of the object to create. + * @param INTERFACE Indicates the HDI interface of the service module. * @since 1.0 */ template @@ -120,10 +120,10 @@ ObjectDelegator::ObjectDelegator() } /** - * @brief 对象委托者模板类析构函数，通过对象收集器完成模板类对象构造函数的删除。 + * @brief A destructor used to unregister an object constructor of the ObjectDelegator template through the ObjectCollector. * - * @param OBJECT 待生成的对象类型。 - * @param INTERFACE 业务模块的HDI接口类。 + * @param OBJECT Indicates the type of the object. + * @param INTERFACE Indicates the HDI interface of the service module. * @since 1.0 */ template diff --git a/apis/20230220/inner_api/hdi/servmgr_hdi.h b/apis/20230220/inner_api/hdi/servmgr_hdi.h deleted file mode 100755 index 079ac619ce2ebc871f24c1dcf81755ebc057b15e..0000000000000000000000000000000000000000 --- a/apis/20230220/inner_api/hdi/servmgr_hdi.h +++ /dev/null @@ -1,115 +0,0 @@ -/* - * Copyright (c) 2021 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 DriverHdi - * @{ - * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 - * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 - * - * @since 1.0 - */ - -/** - * @file servmgr_hdi.h - * - * @brief 定义基于C语言的服务管理相关的数据结构和接口类型。 - * - * @since 1.0 - */ - -#ifndef HDI_SERVICE_MANAGER_INF_H -#define HDI_SERVICE_MANAGER_INF_H - -#include "hdf_remote_service.h" -#include "servstat_listener_hdi.h" -#ifdef __cplusplus -extern "C" { -#endif /* __cplusplus */ - -/** - * @brief 定义HDI服务集合，供系统服务获取HDI服务使用 - */ -struct HdiServiceSet { - /** hdi服务名集合 */ - const char **serviceNames; - /** hdi服务个数 */ - uint32_t count; -}; - -/** - * @brief 定义服务管理HDI接口，C语言开发者可以使用该接口获取服务、获取服务集合、注册服务状态监听等。 - */ -struct HDIServiceManager { - /** - * @brief 该函数根据服务名获取HDI服务。 - * @param self 服务管理对象。 - * @param serviceName HDI服务名。 - * @return 返回查询到的HDI服务。 - */ - - struct HdfRemoteService *(*GetService)(struct HDIServiceManager *self, const char *serviceName); - /** - * @brief 该函数给业务模块提供注册服务状态监听接口。 - * @param self 服务管理对象。 - * @param listener 待注册的监听器对象。 - * @param deviceClass 监听的设备服务类别。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 - */ - - int32_t (*RegisterServiceStatusListener)( - struct HDIServiceManager *self, struct ServiceStatusListener *listener, uint16_t deviceClass); - /** - * @brief 该函数用于注销服务状态监听器。 - * @param self 表示当前对象。 - * @param listener 待注销的监听器对象。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 - */ - - int32_t (*UnregisterServiceStatusListener)(struct HDIServiceManager *self, struct ServiceStatusListener *listener); - /** - * @brief 该函数用于通过接口描述查询HDI服务集合。 - * @param interfaceName 接口描述。 - * @return 返回查询到的服务名集合。 - */ - - struct HdiServiceSet *(*ListServiceByInterfaceDesc)(struct HDIServiceManager *self, const char *interfaceName); -}; - -/** - * @brief 该函数用于获取HDIServiceManager对象。 - * @return 返回HDIServiceManager对象。 - */ - -struct HDIServiceManager *HDIServiceManagerGet(void); -/** - * @brief 该函数用于释放HDIServiceManager对象。 - * @param servmgr 待释放的HDIServiceManager对象。 - */ - -void HDIServiceManagerRelease(struct HDIServiceManager *servmgr); -/** - * @brief 该函数用于释放HdiServiceSet对象。 - * @return 返回0表示释放成功，否则返回负数。 - */ -int32_t HdiServiceSetRelease(struct HdiServiceSet *serviceSet); - -#ifdef __cplusplus -} -#endif /* __cplusplus */ - -#endif /* HDI_SERVICE_MANAGER_INF_H */ \ No newline at end of file diff --git a/apis/20230220/inner_api/hdi/servstat_listener_hdi.h b/apis/20230220/inner_api/hdi/servstat_listener_hdi.h deleted file mode 100755 index 53338d38ee5396038196a3fb71e07a4a9e9f9579..0000000000000000000000000000000000000000 --- a/apis/20230220/inner_api/hdi/servstat_listener_hdi.h +++ /dev/null @@ -1,60 +0,0 @@ -/* - * Copyright (c) 2021 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 DriverHdi - * @{ - * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 - * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 - * - * @since 1.0 - */ - -/** - * @file servstat_listener_hdi.h - * - * @brief 定义基于C语言的服务状态监听相关的数据结构和接口类型。 - * - * @since 1.0 - */ - -#ifndef HDI_SERVICE_STATUS_LISTENER_INF_H -#define HDI_SERVICE_STATUS_LISTENER_INF_H -#include "hdf_types.h" -#include "hdf_service_status.h" - -#ifdef __cplusplus -extern "C" { -#endif /* __cplusplus */ -/** - * @brief 该函数用于创建一个HDI服务状态监听者对象，开发者设置自己的服务状态接受函数，然后通过函数RegisterServiceStatusListener注册该监听对象。 - * @return 返回创建的监听者对象。 - */ - -struct ServiceStatusListener *HdiServiceStatusListenerNewInstance(void); -/** - * @brief 该函数用于释放HDI服务状态监听者对象。 - * @param listener 待释放的监听者对象。 - */ -void HdiServiceStatusListenerFree(struct ServiceStatusListener *listener); - -#ifdef __cplusplus -} -#endif /* __cplusplus */ - - -#endif /* HDI_SERVICE_STATUS_LISTENER_INF_H */ \ No newline at end of file diff --git a/apis/20230220/inner_api/hdi/stub_collector.h b/apis/20230220/inner_api/hdi/stub_collector.h deleted file mode 100755 index 03b2f15b195569ef6cfda38181a7b72711cbd3c6..0000000000000000000000000000000000000000 --- a/apis/20230220/inner_api/hdi/stub_collector.h +++ /dev/null @@ -1,93 +0,0 @@ -/* - * Copyright (c) 2022 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 DriverHdi - * @{ - * - * @brief 提供给系统服务获取HDI服务、加载及卸载设备、监听服务状态、以及提供自动生成idl接口代码的工具所需要的能力。 - * - * 系统服务通过该模块以及该模块支撑的代码生成工具所生成idl代码，获取访问HDI驱动服务的能力。 - * - * @since 1.0 - */ - -/** - * @file stub_collector.h - * - * @brief 定义stub对象收集器，提供对象构造函数管理以及对象管理的功能，供idl代码生成工具使用。 - * 业务模块先根据接口名称和构造函数把构造函数注册到对象收集器里面，然后根据接口名称和注册的构造函数生成stub对象。 - * - * @since 1.0 - */ -#ifndef HDI_STUB_COLLECTOR_H -#define HDI_STUB_COLLECTOR_H - -#include - -#ifdef __cplusplus -extern "C" { -#endif /* __cplusplus */ - -/** - * @brief 定义stub构造函数类型，提供stub对象构造函数管理以及对象管理的功能，供idl代码生成工具使用。 - * - * @since 1.0 - */ -struct StubConstructor { - /** 定义stub对象的构造函数接口类型 */ - struct HdfRemoteService **(*constructor)(void *); - /** 定义stub对象的析构函数接口类型 */ - void (*destructor)(struct HdfRemoteService **); -}; - -/** - * @brief 定义stub构造函数注册接口。 - * @param ifDesc stub对象的接口描述。 - * @param constructor stub对象的构造函数。 - * @since 1.0 - */ -void StubConstructorRegister(const char *ifDesc, struct StubConstructor *constructor); - -/** - * @brief 定义stub构造函数解注册接口。 - * @param ifDesc stub对象的接口描述。 - * @param constructor stub对象的构造函数。 - * @since 1.0 - */ -void StubConstructorUnregister(const char *ifDesc, const struct StubConstructor *constructor); - -/** - * @brief 定义生成stub对象的接口，并把stub对象保持到对象管理器里面。 - * @param ifDesc stub对象的接口描述。 - * @param servPtr 构造函数对象的地址。 - * @return 返回stub对象。 - * @since 1.0 - */ -struct HdfRemoteService **StubCollectorGetOrNewObject(const char *ifDesc, void *servPtr); - -/** - * @brief 定义删除对象管理器中stub对象的接口。 - * @param ifDesc stub对象的接口描述。 - * @param servPtr 构造函数对象的地址。 - * @since 1.0 - */ -void StubCollectorRemoveObject(const char *ifDesc, void *servPtr); - -#ifdef __cplusplus -} -#endif /* __cplusplus */ - -#endif // HDI_STUB_COLLECTOR_H diff --git a/apis/20230220/inner_api/ipc/hdf_dump_reg.h b/apis/20230220/inner_api/ipc/hdf_dump_reg.h index 7f9f50d4a0f3eb70dc096f76f62c768e9b997124..834159adc09f40ec0063e33b9dd05d9cdfb59e01 100755 --- a/apis/20230220/inner_api/ipc/hdf_dump_reg.h +++ b/apis/20230220/inner_api/ipc/hdf_dump_reg.h @@ -17,10 +17,10 @@ * @addtogroup HDF_IPC_ADAPTER * @{ * - * @brief 提供用户态驱动使用IPC的能力. + * @brief Provides capabilities for the user-mode driver to use inter-process communication (IPC). * - * 驱动部分为C语言实现，IPC能力为C++实现，该模块基于C++语言的IPC实现来C语言的IPC接口能力. - * 包括注册服务对象、注册服务对象的死亡监听处理函数、dump机制等功能。 + * The driver is implemented in C, while IPC is implemented in C++. This module implements IPC APIs in C based on the IPC over C++. + * It provides APIs for registering a service object, registering a function for processing the death notification of a service object, and implementing the dump mechanism. * * @since 1.0 */ @@ -28,7 +28,7 @@ /** * @file hdf_dump_reg.h * - * @brief 基于C++语言的IPC的dump功能，提供C语言的dump能力。 + * @brief Provides the dump feature in C based on the IPC dump over C++. * * @since 1.0 */ @@ -43,18 +43,18 @@ extern "C" { #endif /* __cplusplus */ /** - * @brief 定义dump函数接口类型 - * @param data 入参，从命令行获取的参数 - * @param reply 出参，业务模块需要返回到命令行显示的参数 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 + * @brief Implements IPC dump. + * @param data Indicates the pointer to the input parameter, which is obtained from the command line. + * @param reply Indicates the pointer to the output parameter, which is returned by the service module to the command line for display. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. * * @since 1.0 */ typedef int32_t (*DevHostDumpFunc)(struct HdfSBuf *data, struct HdfSBuf *reply); /** - * @brief 定义注册模块的dump函数接口 - * @param dump 模块的dump函数 + * @brief Registers the dump function. + * @param dump Indicates the dump function to register. * * @since 1.0 */ diff --git a/apis/20230220/inner_api/ipc/hdf_remote_service.h b/apis/20230220/inner_api/ipc/hdf_remote_service.h index 6085a1fe4d97ccae70a659149fc3f7d8b07a764d..880e07ce29b3916b8f1de1e7b7ca984b23cc5c08 100755 --- a/apis/20230220/inner_api/ipc/hdf_remote_service.h +++ b/apis/20230220/inner_api/ipc/hdf_remote_service.h @@ -17,10 +17,10 @@ * @addtogroup HDF_IPC_ADAPTER * @{ * - * @brief 提供用户态驱动使用IPC的能力. + * @brief Provides capabilities for the user-mode driver to use inter-process communication (IPC). * - * 驱动部分为C语言实现，IPC能力为C++实现，该模块基于C++语言的IPC实现C语言的IPC接口能力. - * 包括注册服务对象、注册服务对象的死亡监听处理函数、dump机制等功能。 + * The driver is implemented in C, while IPC is implemented in C++. This module implements IPC APIs in C based on the IPC over C++. + * It provides APIs for registering a service object, registering a function for processing the death notification of a service, and implementing the dump mechanism. * * @since 1.0 */ @@ -28,7 +28,7 @@ /** * @file hdf_remote_service.h * - * @brief 提供C语言的IPC接口能力。 + * @brief Provides IPC interface capabilities in C. * * @since 1.0 */ @@ -43,113 +43,113 @@ extern "C" { #endif /* __cplusplus */ /** - * @brief 定义IPC对象的消息分发函数类型。 + * @brief Defines the HdfRemoteDispatcher struct. * @since 1.0 */ struct HdfRemoteDispatcher { - /** 消息同步分发接口 */ + /** Interface for synchronous message dispatching */ int (*Dispatch)(struct HdfRemoteService *, int, struct HdfSBuf *, struct HdfSBuf *); - /** 消息异步分发接口 */ + /** Interface for asynchronous message dispatching */ int (*DispatchAsync)(struct HdfRemoteService *, int, struct HdfSBuf *, struct HdfSBuf *); }; /** - * @brief 定义服务对象的死亡监听结构体 + * @brief Defines the HdfDeathRecipient struct. * @since 1.0 */ struct HdfDeathRecipient { - /** 定义服务对象的死亡监听接口 */ + /** Interface for listening for the death notification of a service. */ void (*OnRemoteDied)(struct HdfDeathRecipient *, struct HdfRemoteService *); }; /** - * @brief 定义远端服务对象结构体 + * @brief Defines the HdfRemoteService struct. * @since 1.0 */ struct HdfRemoteService { - /** 远端服务对象的自身定义 */ + /** Remote service object */ struct HdfObject object; - /** 定义远端服务对象指向的目标对象 */ + /** Target object to which the remote service object points */ struct HdfObject *target; - /** 远端服务对象的消息分发接口 */ + /** Message dispatching interface of the remote service object */ struct HdfRemoteDispatcher *dispatcher; - /** IPC对象的地址 */ + /** Address of the IPC object */ uint64_t index; }; /** - * @brief 定义获取远端对象的接口 - * @param object 服务对象。 - * @param dispatcher 服务对象的消息分发接口。 - * @return 成功返回远端服务对象，失败返回空指针。 + * @brief Obtains a remote service. + * @param object Indicates the pointer to the service. + * @param dispatcher Indicates the pointer to the message dispatching interface of the service. + * @return Returns the remote service obtained if the operation is successful; returns a null pointer otherwise. * @since 1.0 */ struct HdfRemoteService *HdfRemoteServiceObtain( struct HdfObject *object, struct HdfRemoteDispatcher *dispatcher); /** - * @brief 定义回收远端对象的接口 - * @param object 待回收的远端服务对象。 + * @brief Recycles a remote service. + * @param object Indicates the pointer to the remote service to recycle. * @since 1.0 */ void HdfRemoteServiceRecycle(struct HdfRemoteService *service); /** - * @brief 添加对服务对象的死亡事件进行监听处理的接口 - * @param service 需要监听的对象。 - * @param recipient 死亡事件回调处理函数结构体对象。 + * @brief Adds a function for processing the the death notification of a service. + * @param service Indicates the pointer to the service to be listened for. + * @param recipient Indicates the pointer to the callback object containing the code to be executed when the death notification is received. * @since 1.0 */ void HdfRemoteServiceAddDeathRecipient(struct HdfRemoteService *service, struct HdfDeathRecipient *recipient); /** - * @brief 移除对服务对象的死亡事件进行监听处理的接口 - * @param service 需要监听的对象。 - * @param recipient 死亡事件回调处理函数结构体对象。 + * @brief Removes the function for processing the the death notification of a service. + * @param service Indicates the pointer to the target service. + * @param recipient Indicates the pointer to the callback object to remove. * @since 1.0 */ void HdfRemoteServiceRemoveDeathRecipient(struct HdfRemoteService *service, struct HdfDeathRecipient *recipient); /** - * @brief 定义添加系统服务能力的接口 - * @param saId 系统服务ID。 - * @param service 服务对象。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 + * @brief Registers a service. + * @param serviceId Indicates the ID of the service to add. + * @param service Indicates the pointer to the service. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. * @since 1.0 */ int HdfRemoteServiceRegister(int32_t serviceId, struct HdfRemoteService *service); /** - * @brief 定义获取系统服务对象的接口 - * @param saId 系统服务ID。 - * @return 成功返回服务对象，失败返回空指针。 + * @brief Obtains a service. + * @param serviceId Indicates the ID of the service to obtain. + * @return Returns the service object obtained if the operation is successful; returns a null pointer otherwise. * @since 1.0 */ struct HdfRemoteService *HdfRemoteServiceGet(int32_t serviceId); /** - * @brief 设置服务对象的接口标识 - * @param service 需要监听的对象。 - * @param descriptor 接口标识。 - * @return 成功返回true，失败返回false。 + * @brief Sets an interface descriptor for a service. + * @param service Indicates the pointer to the target service. + * @param descriptor Indicates the interface descriptor to set. + * @return Returns true if the operation is successful; returns false otherwise. * @since 1.0 */ bool HdfRemoteServiceSetInterfaceDesc(struct HdfRemoteService *service, const char *descriptor); /** - * @brief 使用服务对象的接口标识设置HdfSBuf对象的接口标识 - * @param service 服务对象。 - * @param data 需要被设置接口标识的HdfSBuf对象。 - * @return 成功返回true，失败返回false。 + * @brief Sets an interface token for an HdfSBuf with the interface descriptor of a service. + * @param service Indicates the pointer to the service. + * @param data Indicates the pointer to the targetHdfSBuf object to be set with an interface token. + * @return Returns true if the operation is successful; returns false otherwise. * @since 1.0 */ bool HdfRemoteServiceWriteInterfaceToken(struct HdfRemoteService *service, struct HdfSBuf *data); /** - * @brief 判断服务对象的接口标识和HdfSBuf对象的接口标识是否一样 - * @param service 服务对象。 - * @param data HdfSBuf对象。 - * @return 两个对象的接口标识一样返回true，不一样返回false。 + * @brief Checks the interface tokens of a service and an HdfSBuf for consistency. + * @param service Indicates the pointer to the service. + * @param data Indicates the pointer to the HdfSBuf. + * @return Returns true if the two interface tokens are the same; returns true otherwise. * @since 1.0 */ bool HdfRemoteServiceCheckInterfaceToken(struct HdfRemoteService *service, struct HdfSBuf *data); diff --git a/apis/20230220/inner_api/ipc/hdf_sbuf_ipc.h b/apis/20230220/inner_api/ipc/hdf_sbuf_ipc.h index 327df80ec5f79c306e8542cc9de66d7e2b9fdf92..18287d415f273be879d2c96de0a7d9fc84a107a0 100755 --- a/apis/20230220/inner_api/ipc/hdf_sbuf_ipc.h +++ b/apis/20230220/inner_api/ipc/hdf_sbuf_ipc.h @@ -17,10 +17,10 @@ * @addtogroup HDF_IPC_ADAPTER * @{ * - * @brief 提供用户态驱动使用IPC的能力. + * @brief Provides capabilities for the user-mode driver to use inter-process communication (IPC). * - * 驱动部分为C语言实现，IPC能力为C++实现，该模块基于C++语言的IPC实现C语言的IPC接口能力. - * 包括注册服务对象、注册服务对象的死亡监听处理函数、dump机制等功能。 + * The driver is implemented in C, while IPC is implemented in C++. This module implements IPC APIs in C based on the IPC over C++. + * It provides APIs for registering a service object, registering a function for processing the death notification of a service, and implementing the dump mechanism. * * @since 1.0 */ @@ -28,7 +28,7 @@ /** * @file hdf_sbuf_ipc.h * - * @brief 提供C++类型的MessageParcel对象和C语言的HdfSBuf对象互相转换的接口能力。 + * @brief Provides APIs for converting between the MessageParcel objects (in C++) and HdfSBuf objects (in C). * * @since 1.0 */ @@ -44,18 +44,18 @@ extern "C" { #endif /* __cplusplus */ /** - * @brief 把MessageParcel对象转换为HdfSBuf对象 - * @param parcel MessageParcel对象。 - * @return 返回sbuf对象。 + * @brief Converts a MessageParcel object into an HdfSBuf object. + * @param parcel Indicates the pointer to the MessageParcel object to convert. + * @return Returns the HdfSBuf object obtained. * @since 1.0 */ struct HdfSBuf *ParcelToSbuf(OHOS::MessageParcel *parcel); /** - * @brief 把HdfSBuf对象转换为MessageParcel对象 - * @param sbuf HdfSBuf对象指针。 - * @param parcel MessageParcel对象指针的地址。 - * @return 返回HDF_SUCCESS表示操作成功，否则表示失败。 + * @brief Converts an HdfSBuf object into a MessageParcel object. + * @param sbuf Indicates the pointer to the HdfSBuf object to convert. + * @param parcel Indicates the pointer to the MessageParcel object obtained. + * @return Returns HDF_SUCCESS if the operation is successful; otherwise, the operation fails. * @since 1.0 */ int32_t SbufToParcel(struct HdfSBuf *sbuf, OHOS::MessageParcel **parcel); diff --git a/apis/20230220/inner_api/osal/uhdf/hdf_log_adapter.h b/apis/20230220/inner_api/osal/uhdf/hdf_log_adapter.h index d7edfa57dae043b92a9de7a342f1e7f9b67f6636..ea399cd1560b62895896e5b68a5be21457abbceb 100755 --- a/apis/20230220/inner_api/osal/uhdf/hdf_log_adapter.h +++ b/apis/20230220/inner_api/osal/uhdf/hdf_log_adapter.h @@ -19,7 +19,7 @@ * * @brief Defines common macros and interfaces of the driver module. * - * This module provides interfaces such as log printing, doubly linked list operations, and work queues. + * This module provides interfaces for log printing, doubly linked list operations, and work queues. * * @since 1.0 * @version 1.0 @@ -28,7 +28,7 @@ /** * @file hdf_log_adapter.h * - * @brief 该文件为hdf_log的具体实现，用hilog的宏实现HDF_LOGV等宏的功能，业务模块不需要关注该文件。 + * @brief Provides the implementation of hdf_log. HiLog macros are used to implement the functions of macros, such as HDF_LOGV. Service modules do not use this file. * * @since 1.0 * @version 1.0 @@ -44,40 +44,40 @@ extern "C" { #endif /* __cplusplus */ /** - * @brief 定义HDF 的log域。 + * @brief Defines the log domain of the HDF. */ #undef LOG_DOMAIN #define LOG_DOMAIN 0xD002500 /** - * @brief 定义HDF缺省的log标签。 + * @brief Defines the default log label of the HDF. */ #ifndef LOG_TAG #define LOG_TAG HDF #endif /** - * @brief 适配到hilog模块verbose级别的打印接口。 + * @brief Adapts to printing information of the verbose level of the HiLog module. */ #define HDF_LOGV_WRAPPER(fmt, arg...) HILOG_DEBUG(LOG_CORE, fmt, ##arg) /** - * @brief 适配到hilog模块debug级别的打印接口。 + * @brief Adapts to printing information of the debug level of the HiLog module. */ #define HDF_LOGD_WRAPPER(fmt, arg...) HILOG_DEBUG(LOG_CORE, fmt, ##arg) /** - * @brief 适配到hilog模块info级别的打印接口。 + * @brief Adapts to printing information of the info level of the HiLog module. */ #define HDF_LOGI_WRAPPER(fmt, arg...) HILOG_INFO(LOG_CORE, fmt, ##arg) /** - * @brief 适配到hilog模块warning级别的打印接口。 + @brief Adapts to printing information of the warning level of the HiLog module. */ #define HDF_LOGW_WRAPPER(fmt, arg...) HILOG_WARN(LOG_CORE, fmt, ##arg) /** - * @brief 适配到hilog模块error级别的打印接口。 + * @brief Adapts to printing information of the error level of the HiLog module. */ #define HDF_LOGE_WRAPPER(fmt, arg...) HILOG_ERROR(LOG_CORE, fmt, ##arg) @@ -86,4 +86,3 @@ extern "C" { #endif /* __cplusplus */ #endif /* HDF_LOG_ADAPTER_H */ - diff --git a/apis/20230220/inner_api/utils/hdf_base.h b/apis/20230220/inner_api/utils/hdf_base.h index e5ee979221065190a143789b4462d0faa8911790..ab9247ad1147f96e5fe4dd8b11f4c2703c1e9e71 100755 --- a/apis/20230220/inner_api/utils/hdf_base.h +++ b/apis/20230220/inner_api/utils/hdf_base.h @@ -12,7 +12,7 @@ * * @brief Defines common macros and interfaces of the driver module. * - * This module provides interfaces such as log printing, doubly linked list operations, and work queues. + * This module provides interfaces for log printing, doubly linked list operations, and work queues. * * @since 1.0 * @version 1.0 @@ -38,24 +38,24 @@ extern "C" { #ifdef __LITEOS__ /** - * @brief 定义HDF模块库所在的完整路径。 + * @brief Declares the full path of the HDF module library. */ #define HDF_LIBRARY_FULL_PATH(x) "/usr/lib/" x ".so" /** - * @brief 定义HDF模块库所在的目录。 + * @brief Declares the directory of the HDF module library. */ #define HDF_LIBRARY_DIR "/usr/lib" /** - * @brief 定义HDF模块配置文件等目录。 + * @brief Declares the directory of the HDF module configuration files. */ #define HDF_ETC_DIR "/etc" /** - * @brief 定义HDF模块配置目录。 + * @brief Declares the configuration directory of the HDF module. */ #define HDF_CONFIG_DIR "/etc" #else /** - * @brief 定义HDF模块库所在的完整路径。 + * @brief Declares the full path of the HDF module library. */ #ifdef __aarch64__ #define HDF_LIBRARY_FULL_PATH(x) "/vendor/lib64/" x ".z.so" @@ -63,23 +63,23 @@ extern "C" { #define HDF_LIBRARY_FULL_PATH(x) "/vendor/lib/" x ".z.so" #endif /** - * @brief 定义HDF模块库所在的目录。 + * @brief Declares the directory of the HDF module library. */ #define HDF_LIBRARY_DIR "/vendor/lib" /** - * @brief 定义HDF模块配置文件等目录。 + * @brief Declares the directory of the HDF module configuration files. */ #define HDF_ETC_DIR "/vendor/etc" /** - * @brief 定义HDF模块配置目录。 + * @brief Declares the configuration directory of the HDF module. */ #define HDF_CONFIG_DIR "/vendor/etc/hdfconfig" /** - * @brief 定义HDF的HCS配置文件所在目录。 + * @brief Declares the directory of the HCS configuration file of the HDF. */ #define HDF_CHIP_PROD_CONFIG_DIR "/chip_prod/etc/hdfconfig" /** - * @brief 定义HDF内核态业务模块驱动安装目录。 + * @brief Declares the installation directory of the HDF kernel-mode service module driver. */ #define HDF_MODULE_DIR "/vendor/modules/" #endif