diff --git a/IPCKit/ipc_cparcel.h b/IPCKit/ipc_cparcel.h index 6903bb621..03fb944e2 100644 --- a/IPCKit/ipc_cparcel.h +++ b/IPCKit/ipc_cparcel.h @@ -1,10 +1,10 @@ /* - * Copyright (c) 2024 Huawei Device Co., Ltd. + * Copyright (C) 2024-2026 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, @@ -12,7 +12,6 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - /** * @addtogroup OHIPCParcel * @{ @@ -22,12 +21,11 @@ * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ - /** * @file ipc_cparcel.h * - * @brief Defines C interfaces for IPC serialization and deserialization. - * + * @brief Provides C APIs for IPC serialization and deserialization. + * * @library libipc_capi.so * @kit IPCKit * @syscap SystemCapability.Communication.IPC.Core @@ -45,15 +43,15 @@ extern "C" { /** * @brief Defines an IPC serialized object. -* +* * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ struct OHIPCParcel; /** -* @brief Typedef an IPC serialized object. -* +* @brief Defines an IPC serialized object. +* * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ @@ -61,15 +59,15 @@ typedef struct OHIPCParcel OHIPCParcel; /** * @brief Defines an IPC remote proxy object. -* +* * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ struct OHIPCRemoteProxy; /** -* @brief Typedef an IPC remote proxy object. -* +* @brief Defines an IPC remote proxy object. +* * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ @@ -77,448 +75,447 @@ typedef struct OHIPCRemoteProxy OHIPCRemoteProxy; /** * @brief Defines an IPC remote service object. -* +* * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ struct OHIPCRemoteStub; /** -* @brief Typedef an IPC remote service object. -* +* @brief Defines an IPC remote service object. +* * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ typedef struct OHIPCRemoteStub OHIPCRemoteStub; /** - * @brief Allocates memory. - * + * @brief Defines the type of a memory allocation function. + * * @syscap SystemCapability.Communication.IPC.Core - * @param len Length of the memory to allocate. + * @param len Length of the memory to be allocated. * @return Returns the address of the memory allocated if the operation is successful; returns NULL otherwise. * @since 12 */ typedef void* (*OH_IPC_MemAllocator)(int32_t len); /** - * @brief Creates an OHIPCParcel object, which cannot exceed 204,800 bytes. - * + * @brief Creates an **OHIPCParcel** object, which cannot exceed 204,800 bytes. + * * @syscap SystemCapability.Communication.IPC.Core - * @return Returns the pointer to the OHIPCParcel object created if the operation is successful; - * returns NULL otherwise. + * @return Returns the pointer to the **OHIPCParcel** object created if the operation is successful; returns NULL + * otherwise. * @since 12 */ OHIPCParcel* OH_IPCParcel_Create(void); /** - * @brief Destroys an OHIPCParcel object. - * + * @brief Destroys an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the OHIPCParcel object to destroy. + * @param parcel Pointer to the **OHIPCParcel** object to destroy. * @since 12 */ void OH_IPCParcel_Destroy(OHIPCParcel *parcel); /** - * @brief Obtains the size of the data contained in an OHIPCParcel object. - * + * @brief Obtains the size of the data contained in an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @return Returns the data size obtained if the operation is successful.\n - * Returns -1 if invalid parameters are found. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @return Returns the data size obtained if the operation is successful; returns **-1** if invalid parameters are + * found. * @since 12 */ int OH_IPCParcel_GetDataSize(const OHIPCParcel *parcel); /** - * @brief Obtains the number of bytes that can be written to an OHIPCParcel object. - * + * @brief Obtains the number of bytes that can be written to an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @return Returns the number of bytes that can be written to the OHIPCParcel object. \n - * Returns -1 if invalid parameters are found. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @return Returns the number of bytes that can be written to the **OHIPCParcel** object; returns **-1** if invalid + * parameters are found. * @since 12 */ int OH_IPCParcel_GetWritableBytes(const OHIPCParcel *parcel); /** - * @brief Obtains the number of bytes that can be read from an OHIPCParcel object. - * + * @brief Obtains the number of bytes that can be read from an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @return Returns the number of bytes that can be read from the OHIPCParcel object. \n - * Returns -1 if invalid parameters are found. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @return Returns the number of bytes that can be read from the **OHIPCParcel** object. + * Returns **-1** if invalid parameters are found. * @since 12 */ int OH_IPCParcel_GetReadableBytes(const OHIPCParcel *parcel); /** - * @brief Obtains the position where data is read in an OHIPCParcel object. - * + * @brief Obtains the position where data is read in an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @return Returns the position obtained if the operation is successful. \n - * Returns -1 if invalid parameters are found. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @return Returns the current read position obtained if the operation is successful; returns **-1** if invalid + * parameters are found. * @since 12 */ int OH_IPCParcel_GetReadPosition(const OHIPCParcel *parcel); /** - * @brief Obtains the position where data is written in an OHIPCParcel object. - * + * @brief Obtains the position where data is written in an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @return Returns the position obtained if the operation is successful. \n - * Returns -1 if invalid parameters are found. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @return Returns the current write position obtained if the operation is successful; returns **-1** if invalid + * parameters are found. * @since 12 */ int OH_IPCParcel_GetWritePosition(const OHIPCParcel *parcel); /** - * @brief Resets the position to read data in an IPC parcel. - * + * @brief Resets the position to read data in an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @param newReadPos New position to read data. The value ranges from 0 to the current data size. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @param newReadPos New position to read data. The value ranges from **0** to the current data size. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. * @since 12 */ int OH_IPCParcel_RewindReadPosition(OHIPCParcel *parcel, uint32_t newReadPos); /** - * @brief Resets the position to write data in an OHIPCParcel object. - * + * @brief Resets the position to write data in an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @param newWritePos New position to write data. The value ranges from 0 to the current data size. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @param newWritePos New position to write data. The value ranges from **0** to the current data size. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. * @since 12 */ int OH_IPCParcel_RewindWritePosition(OHIPCParcel *parcel, uint32_t newWritePos); /** - * @brief Writes an int8_t value to an OHIPCParcel object. - * + * @brief Writes an int8_t value to an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. * @param value Value to write. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the write operation fails. * @since 12 */ int OH_IPCParcel_WriteInt8(OHIPCParcel *parcel, int8_t value); /** - * @brief Reads an int8_t value from an OHIPCParcel object. - * + * @brief Reads an int8_t value from an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @param value Pointer to the data to read. It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @param value Pointer to the buffer for holding the read data. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. * @since 12 */ int OH_IPCParcel_ReadInt8(const OHIPCParcel *parcel, int8_t *value); /** - * @brief Writes an int16_t value to an OHIPCParcel object. - * + * @brief Writes an int16_t value to an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. * @param value Value to write. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the write operation fails. * @since 12 */ int OH_IPCParcel_WriteInt16(OHIPCParcel *parcel, int16_t value); /** - * @brief Reads an int16_t value from an OHIPCParcel object. - * + * @brief Reads an int16_t value from an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @param value Pointer to the data to read. It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @param value Pointer to the buffer for holding the read data. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. * @since 12 */ int OH_IPCParcel_ReadInt16(const OHIPCParcel *parcel, int16_t *value); /** - * @brief Writes an int32_t value to an OHIPCParcel object. + * @brief Writes an int32_t value to an **OHIPCParcel** object. * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. * @param value Value to write. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the write operation fails. * @since 12 */ int OH_IPCParcel_WriteInt32(OHIPCParcel *parcel, int32_t value); /** - * @brief Reads an int32_t value from an OHIPCParcel object. - * + * @brief Reads an int32_t value from an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @param value Pointer to the data to read. It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @param value Pointer to the buffer for holding the read data. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. * @since 12 */ int OH_IPCParcel_ReadInt32(const OHIPCParcel *parcel, int32_t *value); /** - * @brief Writes an int64_t value to an OHIPCParcel object. - * + * @brief Writes an int64_t value to an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. * @param value Value to write. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the write operation fails. * @since 12 */ int OH_IPCParcel_WriteInt64(OHIPCParcel *parcel, int64_t value); /** - * @brief Reads an int64_t value from an OHIPCParcel object. - * + * @brief Reads an int64_t value from an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @param value Pointer to the data to read. It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @param value Pointer to the buffer for holding the read data. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. * @since 12 */ int OH_IPCParcel_ReadInt64(const OHIPCParcel *parcel, int64_t *value); /** - * @brief Writes a float value to an OHIPCParcel object. - * + * @brief Writes a float value to an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. * @param value Value to write. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the write operation fails. * @since 12 */ int OH_IPCParcel_WriteFloat(OHIPCParcel *parcel, float value); /** - * @brief Reads a float value from an OHIPCParcel object. - * + * @brief Reads a float value from an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @param value Pointer to the data to read. It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @param value Pointer to the buffer for holding the read data. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. * @since 12 */ int OH_IPCParcel_ReadFloat(const OHIPCParcel *parcel, float *value); /** - * @brief Writes a double value to an OHIPCParcel object. - * + * @brief Writes a double value to an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. * @param value Value to write. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the write operation fails. * @since 12 */ int OH_IPCParcel_WriteDouble(OHIPCParcel *parcel, double value); /** - * @brief Reads a double value from an OHIPCParcel object. - * + * @brief Reads a double value from an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @param value Pointer to the data to read. It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @param value Pointer to the buffer for holding the read data. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. * @since 12 */ int OH_IPCParcel_ReadDouble(const OHIPCParcel *parcel, double *value); /** - * @brief Writes a string including a string terminator to an OHIPCParcel object. - * + * @brief Writes a string including a string terminator to an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @param str String to write, which cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @param str Pointer to the string to write. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the write operation fails. * @since 12 */ int OH_IPCParcel_WriteString(OHIPCParcel *parcel, const char *str); /** - * @brief Reads a string from an OHIPCParcel object. You can obtain the length of the string from strlen. - * + * @brief Reads a string from an **OHIPCParcel** object. You can obtain the length of the string from **strlen**. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @return Returns the address of the string read if the operation is successful; - * returns NULL if the operation fails or invalid parameters are found. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @return Returns the address of the string read if the operation is successful; returns NULL if the operation fails + * or invalid parameters are found. * @since 12 */ const char* OH_IPCParcel_ReadString(const OHIPCParcel *parcel); /** - * @brief Writes data of the specified length from the memory to an OHIPCParcel object. - * + * @brief Writes data of the specified length from the memory to an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. * @param buffer Pointer to the address of the memory information to write. * @param len Length of the data to write. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the write operation fails. * @since 12 */ int OH_IPCParcel_WriteBuffer(OHIPCParcel *parcel, const uint8_t *buffer, int32_t len); /** - * @brief Reads memory information of the specified length from an OHIPCParcel object. - * + * @brief Reads memory information of the specified length from an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. * @param len Length of the memory to be read. - * @return Returns the memory address read if the operation is successful; - * returns NULL if invalid parameters are found or len exceeds the readable length of parcel. + * @return Returns the memory address read if the operation is successful; returns NULL if invalid parameters are found + * or **len** exceeds the readable length of **parcel**. * @since 12 */ const uint8_t* OH_IPCParcel_ReadBuffer(const OHIPCParcel *parcel, int32_t len); /** - * @brief Writes an OHIPCRemoteStub object to an OHIPCParcel object. - * + * @brief Writes an **OHIPCRemoteStub** object to an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @param stub Pointer to the OHIPCRemoteStub object to write. It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @param stub Pointer to the **OHIPCRemoteStub** object to write. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the write operation fails. * @since 12 */ int OH_IPCParcel_WriteRemoteStub(OHIPCParcel *parcel, const OHIPCRemoteStub *stub); /** - * @brief Reads the OHIPCRemoteStub object from an OHIPCParcel object. - * + * @brief Reads the **OHIPCRemoteStub** object from an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @return Returns the pointer to the OHIPCRemoteStub object read if the operation is successful; - * returns NULL otherwise. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @return Returns the pointer to the **OHIPCRemoteStub** object read if the operation is successful; returns NULL + * otherwise. * @since 12 */ OHIPCRemoteStub* OH_IPCParcel_ReadRemoteStub(const OHIPCParcel *parcel); /** - * @brief Writes an OHIPCRemoteProxy object to an OHIPCParcel object. - * + * @brief Writes an **OHIPCRemoteProxy** object to an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @param proxy Pointer to the OHIPCRemoteProxy object to write. It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @param proxy Pointer to the **OHIPCRemoteProxy** object to write. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the write operation fails. * @since 12 */ int OH_IPCParcel_WriteRemoteProxy(OHIPCParcel *parcel, const OHIPCRemoteProxy *proxy); /** - * @brief Reads the OHIPCRemoteProxy object from an OHIPCParcel object. - * + * @brief Reads the **OHIPCRemoteProxy** object from an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @return Returns the pointer to the OHIPCRemoteProxy object read if the operation is successful; - * returns NULL otherwise. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @return Returns the pointer to the **OHIPCRemoteProxy** object created if the operation is successful; returns NULL + * otherwise. * @since 12 */ OHIPCRemoteProxy* OH_IPCParcel_ReadRemoteProxy(const OHIPCParcel *parcel); /** - * @brief Writes a file descriptor to an OHIPCParcel object. - * + * @brief Writes a file descriptor to an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @param fd File descriptor to write. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @param fd Pointer to the file descriptor to write. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the write operation fails. * @since 12 */ int OH_IPCParcel_WriteFileDescriptor(OHIPCParcel *parcel, int32_t fd); /** - * @brief Reads a file descriptor from an OHIPCParcel object. - * + * @brief Reads a file descriptor from an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. * @param fd Pointer to the file descriptor to read. It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. * @since 12 */ int OH_IPCParcel_ReadFileDescriptor(const OHIPCParcel *parcel, int32_t *fd); /** - * @brief Appends data to an OHIPCParcel object. - * + * @brief Appends data to an **OHIPCParcel** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. * @param data Pointer to the data to append. It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the operation fails. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the concatenation fails. * @since 12 */ int OH_IPCParcel_Append(OHIPCParcel *parcel, const OHIPCParcel *data); /** - * @brief Writes an interface token to an OHIPCParcel object for interface identity verification. - * + * @brief Writes an interface token to an **OHIPCParcel** object for interface identity verification. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. * @param token Pointer to the interface token to write. It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the write operation fails. * @since 12 */ int OH_IPCParcel_WriteInterfaceToken(OHIPCParcel *parcel, const char *token); /** - * @brief Reads an interface token from an OHIPCParcel object for interface identity verification. - * + * @brief Reads an interface token from an **OHIPCParcel** object for interface identity verification. + * * @syscap SystemCapability.Communication.IPC.Core - * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. - * @param token Pointer to the address of the memory for storing the interface token. - * The memory is allocated by the allocator provided by the user and needs to be released. This pointer cannot be NULL. - * If an error code is returned, you still need to check whether the memory is empty and release the memory. - * Otherwise, memory leaks may occur. + * @param parcel Pointer to the **OHIPCParcel** object. It cannot be NULL. + * @param token Double pointer to the interface token to read. The memory is allocated by the allocator provided by the + * user and needs to be released. This pointer cannot be NULL. If an error code is returned, you still need to check + * whether the memory is empty and release the memory. Otherwise, memory leaks may occur. * @param len Pointer to the length of the interface token read, including the terminator. It cannot be NULL. - * @param allocator Memory allocator specified by the user for allocating memory for token. It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @param allocator Memory allocator specified by the user for allocating memory for **token**. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. Returns + * {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. * @since 12 */ int OH_IPCParcel_ReadInterfaceToken(const OHIPCParcel *parcel, char **token, int32_t *len, diff --git a/IPCKit/ipc_cremote_object.h b/IPCKit/ipc_cremote_object.h index 1f04f78dd..58bf460bc 100644 --- a/IPCKit/ipc_cremote_object.h +++ b/IPCKit/ipc_cremote_object.h @@ -1,10 +1,10 @@ /* - * Copyright (c) 2024 Huawei Device Co., Ltd. + * Copyright (C) 2024-2026 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, @@ -12,24 +12,22 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - /** * @addtogroup OHIPCRemoteObject * @{ * * @brief Provides C interfaces for creating and destroying a remote object, transferring data, - * and observing the dead status of a remote object. + * and observing the dead status of a remote object. * * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ - /** * @file ipc_cremote_object.h * - * @brief Defines C interfaces for creating and destroying a remote object, transferring data, - * and observing the dead status of a remote object. - * + * @brief Provides C APIs for creating and destroying a remote object, transferring data, and observing the dead status + * of a remote object. + * * @library libipc_capi.so * @kit IPCKit * @syscap SystemCapability.Communication.IPC.Core @@ -48,34 +46,34 @@ extern "C" { #endif /** -* @brief Defines an OHIPCDeathRecipient object, which is used to receive a notification -* when the OHIPCRemoteStub object dies unexpectedly. -* +* @brief Defines an object that receives death notifications. +* * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ struct OHIPCDeathRecipient; /** -* @brief Typedef an OHIPCDeathRecipient object. -* +* @brief Defines an object that receives death notifications. +* * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ typedef struct OHIPCDeathRecipient OHIPCDeathRecipient; /** - * @brief Called to process the remote data request at the stub. - * + * @brief Called to process the peer request at the stub. + * * @syscap SystemCapability.Communication.IPC.Core - * @param code Custom command word for communication, in the range [0x01, 0x00ffffff]. - * @param data Pointer to the request data object. It cannot be NULL or released in the function. - * @param reply Pointer to the response data object. It cannot be NULL or released in the function. - * If this function returns an error, data cannot be written to this parameter. - * @param userData Pointer to the user data. It can be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns a custom error code in the range [1909001, 1909999] or a system error code otherwise. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_INVALID_USER_ERROR_CODE} if the custom error code is out of the value range. + * @param code Customized communication command word. + * Value range: [0x01, 0x00ffffff] + * @param data Pointer to the requested data object. It cannot be NULL or released in the function. + * @param reply Pointer to the response data object. It cannot be NULL or released in the function. If this function + * returns an error, data cannot be written to this parameter. + * @param userData Pointer to the private user data. It can be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns a custom error code in the range [1909001, 1909999] or a system error code otherwise. + * If the custom error code is out of range, {@link OH_IPC_ErrorCode#OH_IPC_INVALID_USER_ERROR_CODE} is returned. * @since 12 */ typedef int (*OH_OnRemoteRequestCallback)(uint32_t code, const OHIPCParcel *data, @@ -83,55 +81,59 @@ typedef int (*OH_OnRemoteRequestCallback)(uint32_t code, const OHIPCParcel *data /** * @brief Called when an observed object is destroyed. - * + * * @syscap SystemCapability.Communication.IPC.Core - * @param userData Pointer to the user data. It can be NULL. + * @param userData Pointer to the private user data. It can be NULL. * @since 12 */ typedef void (*OH_OnRemoteDestroyCallback)(void *userData); /** - * @brief Creates an OHIPCRemoteStub object. - * + * @brief Creates an **OHIPCRemoteStub** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param descriptor Pointer to the descriptor of the OHIPCRemoteStub object to create. It cannot be NULL. + * @param descriptor Pointer to the descriptor of the **OHIPCRemoteStub** object to create. It cannot be NULL. * @param requestCallback Callback used to process the data request. It cannot be NULL. * @param destroyCallback Callback to be invoked when the object is destroyed. It can be NULL. - * @param userData Pointer to the user data. It can be NULL. - * @return Returns the pointer to the OHIPCRemoteStub object created if the operation is successful; - * returns NULL otherwise. + * @param userData Pointer to the private user data. It can be NULL. + * @return Returns the pointer to the **OHIPCRemoteStub** object created if the operation is successful; returns NULL + * otherwise. * @since 12 */ OHIPCRemoteStub* OH_IPCRemoteStub_Create(const char *descriptor, OH_OnRemoteRequestCallback requestCallback, OH_OnRemoteDestroyCallback destroyCallback, void *userData); /** - * @brief Destroys an OHIPCRemoteStub object. - * + * @brief Destroys an **OHIPCRemoteStub** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param stub Pointer to the OHIPCRemoteStub object to destroy. + * @param stub Pointer to the **OHIPCRemoteStub** object to destroy. * @since 12 */ void OH_IPCRemoteStub_Destroy(OHIPCRemoteStub *stub); /** - * @brief Destroys an OHIPCRemoteProxy object. - * + * @brief Destroys an **OHIPCRemoteProxy** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param proxy Pointer to the OHIPCRemoteProxy object to destroy. + * @param proxy Pointer to the **OHIPCRemoteProxy** object to destroy. * @since 12 */ void OH_IPCRemoteProxy_Destroy(OHIPCRemoteProxy *proxy); /** * @brief Enumerates the IPC request modes. - * + * * @since 12 */ typedef enum { - /** Synchronous request. */ + /** + * Synchronous request. + */ OH_IPC_REQUEST_MODE_SYNC = 0, - /** Asynchronous request. */ + /** + * Asynchronous request. + */ OH_IPC_REQUEST_MODE_ASYNC = 1, } OH_IPC_RequestMode; @@ -153,18 +155,18 @@ typedef struct { /** * @brief Sends an IPC message. - * + * * @syscap SystemCapability.Communication.IPC.Core - * @param proxy Pointer to the OHIPCRemoteProxy object. It cannot be NULL. - * @param code Custom IPC command word, in the range [0x01, 0x00ffffff]. - * @param data Pointer to the request data object. It cannot be NULL. - * @param reply Pointer to the response data object. It cannot be NULL in the case of a synchronous request, - * and can be NULL in the case of an asynchronous request. - * @param option Pointer to the message options. It can be NULL, which indicates a synchronous request. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT} if the OHIPCRemoteStub object is dead. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CODE_OUT_OF_RANGE} if the error code is out of the value range. \n + * @param proxy Pointer to the **OHIPCRemoteProxy** object. It cannot be NULL. + * @param code Customized IPC command word, in the range [0x01, 0x00ffffff]. + * @param data Pointer to the requested data object. It cannot be NULL. + * @param reply Pointer to the response data object. It cannot be NULL in the case of a synchronous request, and can be + * NULL in the case of an asynchronous request. + * @param option Pointer to the message option. It can be NULL, which indicates a synchronous request. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the message is sent successfully. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT} if the remote **OHIPCRemoteStub** object dies. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CODE_OUT_OF_RANGE} if the code is out of range. * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} or a custom error code in other cases. * @since 12 */ @@ -173,108 +175,104 @@ int OH_IPCRemoteProxy_SendRequest(const OHIPCRemoteProxy *proxy, uint32_t code, /** * @brief Obtains the interface descriptor from the stub. - * + * * @syscap SystemCapability.Communication.IPC.Core - * @param proxy Pointer to the OHIPCRemoteProxy object. It cannot be NULL. - * @param descriptor Double pointer to the address of the memory for holding the interface descriptor. - * The memory is allocated by the allocator provided by the user and needs to be released. This pointer cannot be NULL. - * If an error code is returned, you still need to check whether the memory is empty and release the memory. - * Otherwise, memory leaks may occur. - * @param len Pointer to the length of the data to be written to the descriptor, including the terminator. - * This parameter cannot be NULL. - * @param allocator Memory allocator specified by the user for allocating memory for descriptor. - * It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT} if the OHIPCRemoteStub object is dead. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_MEM_ALLOCATOR_ERROR} if memory allocation fails. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the data in the serialized object failed to be read. + * @param proxy Pointer to the **OHIPCRemoteProxy** object. It cannot be NULL. + * @param descriptor Pointer to the address of the memory for holding the interface descriptor. The memory is allocated + * by the allocator provided by the user and needs to be released. This pointer cannot be NULL. If an error code is + * returned, you still need to check whether the memory is empty and release the memory. Otherwise, memory leaks may + * occur. + * @param len Pointer to the length of the data written to the descriptor, including the terminator. It cannot be NULL. + * @param allocator Memory allocator specified by the user for allocating memory for **identity**. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the message is sent successfully. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if the parameters are incorrect. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT} if the remote **OHIPCRemoteStub** object dies. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_MEM_ALLOCATOR_ERROR} if the memory allocation fails. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} or a custom error code if the data in the serialized + * object fails to be read. * @since 12 */ int OH_IPCRemoteProxy_GetInterfaceDescriptor(OHIPCRemoteProxy *proxy, char **descriptor, int32_t *len, OH_IPC_MemAllocator allocator); /** - * @brief Called when the OHIPCRemoteStub object dies unexpectedly. - * + * @brief Defines a callback to be invoked when the remote **OHIPCRemoteStub** object dies unexpectedly. + * * @syscap SystemCapability.Communication.IPC.Core - * @param userData Pointer to the user data. It can be NULL. + * @param userData Pointer to the private user data. It can be NULL. * @since 12 */ typedef void (*OH_OnDeathRecipientCallback)(void *userData); /** - * @brief Called when the OHIPCDeathRecipient object is destroyed. - * + * @brief Defines a callback to be invoked when the **OHIPCDeathRecipient** object is destroyed. + * * @syscap SystemCapability.Communication.IPC.Core - * @param userData Pointer to the user data. It can be NULL. + * @param userData Pointer to the private user data. It can be NULL. * @since 12 */ typedef void (*OH_OnDeathRecipientDestroyCallback)(void *userData); /** - * @brief Creates an OHIPCDeathRecipient object, which allows a notification to be received - * when the OHIPCRemoteStub object dies unexpectedly. - * + * @brief Creates an **OHIPCDeathRecipient** object, which triggers a notification when the **OHIPCRemoteStub** object + * dies unexpectedly. + * * @syscap SystemCapability.Communication.IPC.Core - * @param deathRecipientCallback Callback to be invoked when the OHIPCRemoteStub object is dead. - * It cannot be NULL. + * @param deathRecipientCallback Callback to be invoked when the **OHIPCRemoteStub** object is dead. It cannot be NULL. * @param destroyCallback Callback to be invoked when the object is destroyed. It can be NULL. - * @param userData Pointer to the user data. It can be NULL. - * @return Returns the pointer to the OHIPCDeathRecipient object created if the operation is successful; - * returns NULL otherwise. + * @param userData Pointer to the private user data. It can be NULL. + * @return Returns the pointer to the **OHIPCDeathRecipient** object created if the operation is successful; returns + * NULL otherwise. * @since 12 */ OHIPCDeathRecipient* OH_IPCDeathRecipient_Create(OH_OnDeathRecipientCallback deathRecipientCallback, OH_OnDeathRecipientDestroyCallback destroyCallback, void *userData); /** - * @brief Destroys an OHIPCDeathRecipient object. - * + * @brief Destroys an **OHIPCDeathRecipient** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param recipient Pointer to the OHIPCDeathRecipient object to destroy. + * @param recipient Pointer to the **OHIPCDeathRecipient** object to destroy. * @since 12 */ void OH_IPCDeathRecipient_Destroy(OHIPCDeathRecipient *recipient); /** - * @brief Subscribes to the death of an OHIPCRemoteStub object for an OHIPCRemoteProxy object. - * + * @brief Subscribes to the death of an **OHIPCRemoteStub** object for an **OHIPCRemoteProxy** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param proxy Pointer to the OHIPCRemoteProxy object that subscribes to the death notification. - * It cannot be NULL. - * @param recipient Pointer to the object that receives the death notification of the OHIPCRemoteStub object. - * It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n + * @param proxy Pointer to the **OHIPCRemoteProxy** object that subscribes to the death notification. It cannot be NULL. + * @param recipient Pointer to the object that receives the death notification of the **OHIPCRemoteStub** object. It + * cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if the parameters are incorrect. * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. * @since 12 */ int OH_IPCRemoteProxy_AddDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient); /** - * @brief Unsubscribes from the death of the OHIPCRemoteStub object for an OHIPCRemoteProxy object. - * + * @brief Unsubscribes from the death of the **OHIPCRemoteStub** object for an **OHIPCRemoteProxy** object. + * * @syscap SystemCapability.Communication.IPC.Core - * @param proxy Pointer to the OHIPCRemoteProxy object that unsubscribes from the death notification. - * It cannot be NULL. - * @param recipient Pointer to the object that receives the death notification of the OHIPCRemoteStub object. - * It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n + * @param proxy Pointer to the **OHIPCRemoteProxy** object that unsubscribes from the death notification. It cannot be + * NULL. + * @param recipient Pointer to the object that receives the death notification of the **OHIPCRemoteStub** object. It + * cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if the parameters are incorrect. * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. * @since 12 */ int OH_IPCRemoteProxy_RemoveDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient); /** - * @brief Checks whether the OHIPCRemoteStub object corresponding to the OHIPCRemoteProxy object is dead. - * + * @brief Checks whether the **OHIPCRemoteStub** object corresponding to the **OHIPCRemoteProxy** object is dead. + * * @syscap SystemCapability.Communication.IPC.Core - * @param proxy Pointer to the OHIPCRemoteProxy object to check. It cannot be NULL. - * @return Returns 1 if the OHIPCRemoteStub object is dead; returns 0 otherwise. - * If an invalid parameter is found, the OHIPCRemoteStub object does not exist. - * In this case, 1 is returned. + * @param proxy Pointer to the **OHIPCRemoteProxy** object to check. It cannot be NULL. + * @return Returns **1** if the **OHIPCRemoteStub** object is dead or invalid parameters are found; returns **0** + * otherwise. If invalid parameters are found, the **OHIPCRemoteStub** object does not exist. * @since 12 */ int OH_IPCRemoteProxy_IsRemoteDead(const OHIPCRemoteProxy *proxy); diff --git a/IPCKit/ipc_cskeleton.h b/IPCKit/ipc_cskeleton.h index fbbac7452..8ac72473c 100644 --- a/IPCKit/ipc_cskeleton.h +++ b/IPCKit/ipc_cskeleton.h @@ -1,10 +1,10 @@ /* - * Copyright (c) 2024 Huawei Device Co., Ltd. + * Copyright (C) 2024-2026 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, @@ -12,7 +12,6 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - /** * @addtogroup OHIPCSkeleton * @{ @@ -23,13 +22,12 @@ * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ - /** * @file ipc_cskeleton.h * - * @brief Defines C interfaces for managing the token IDs, credentials, PIDs, UIDs, and thread - * pool in the IPC framework. - * + * @brief Provides C APIs for managing the token IDs, credentials, process IDs (PIDs), user IDs (UIDs), and thread pool + * in the IPC framework. + * * @library libipc_capi.so * @kit IPCKit * @syscap SystemCapability.Communication.IPC.Core @@ -49,7 +47,7 @@ extern "C" { /** * @brief Joins this thread to the IPC worker thread pool. - * + * * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ @@ -57,118 +55,119 @@ void OH_IPCSkeleton_JoinWorkThread(void); /** * @brief Stops this thread. - * + * * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ void OH_IPCSkeleton_StopWorkThread(void); /** - * @brief Obtains the token ID of the caller. This function must be called in the IPC context. - * Otherwise, the local token ID is returned. - * + * @brief Obtains the token ID of the caller. This function must be called in the IPC context. Otherwise, the local + * token ID is returned. + * * @syscap SystemCapability.Communication.IPC.Core - * @return Returns the token ID of the caller. + * @return Returns the caller token ID. * @since 12 */ uint64_t OH_IPCSkeleton_GetCallingTokenId(void); /** * @brief Obtains the token ID of the first caller. - * + * * @syscap SystemCapability.Communication.IPC.Core - * @return Returns the token ID obtained. + * @return Returns the token ID of the first caller. * @since 12 */ uint64_t OH_IPCSkeleton_GetFirstTokenId(void); /** * @brief Obtains the local token ID. - * + * * @syscap SystemCapability.Communication.IPC.Core - * @return Returns the token ID obtained. + * @return Returns the local token ID. * @since 12 */ uint64_t OH_IPCSkeleton_GetSelfTokenId(void); /** - * @brief Obtains the process ID of the caller. This function must be called in the IPC context. - * Otherwise, the current process ID is returned. - * + * @brief Obtains the PID of the caller. This function must be called in the IPC context. Otherwise, the local PID is + * returned. + * * @syscap SystemCapability.Communication.IPC.Core - * @return Returns the process ID of the caller. + * @return Returns the caller PID. * @since 12 */ uint64_t OH_IPCSkeleton_GetCallingPid(void); /** - * @brief Obtains the UID of the caller. This function must be called in the IPC context. - * Otherwise, the current UID is returned. - * + * @brief Obtains the UID of the caller. This function must be called in the IPC context. Otherwise, the local UID is + * returned. + * * @syscap SystemCapability.Communication.IPC.Core - * @return Returns the UID of the caller. + * @return Returns the caller UID. * @since 12 */ uint64_t OH_IPCSkeleton_GetCallingUid(void); /** * @brief Checks whether a local calling is being made. - * + * * @syscap SystemCapability.Communication.IPC.Core - * @return Returns 1 if a local calling is in progress; returns 0 otherwise. + * @return Returns **1** if a local calling is in progress; returns **0** otherwise. * @since 12 */ int OH_IPCSkeleton_IsLocalCalling(void); /** * @brief Sets the maximum number of worker threads. - * + * * @syscap SystemCapability.Communication.IPC.Core - * @param maxThreadNum Maximum number of worker threads to set. The default value is 16. - * The value range is [1, 32]. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. + * @param maxThreadNum Maximum number of worker threads. + * Value range: [1, 32] + * Default value: **16** + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if the parameters are incorrect. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. * @since 12 */ int OH_IPCSkeleton_SetMaxWorkThreadNum(const int maxThreadNum); /** * @brief Resets the caller identity credential (including the token ID, UID, and PID) to that of this process and - * returns the caller credential information. - * The identity information is used in OH_IPCSkeleton_SetCallingIdentity. - * + * returns the caller credential information. The credential information is used in + * **OH_IPCSkeleton_SetCallingIdentity**. + * * @syscap SystemCapability.Communication.IPC.Core - * @param identity Pointer to the address of the memory for holding the caller identity information. - * The memory is allocated by the allocator provided by the user and needs to be released. This pointer cannot be NULL. - * @param len Pointer to the length of the identity information. It cannot be NULL. - * @param allocator Memory allocator specified by the user for allocating memory for identity. It cannot be NULL. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_MEM_ALLOCATOR_ERROR} if memory allocation fails. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. + * @param identity Double pointer to the address of the memory for holding the caller identity information. The memory + * is allocated by the allocator provided by the user and needs to be released. This pointer cannot be NULL. + * @param len Pointer to the length of the data written to the identity. The value cannot be empty. + * @param allocator Memory allocator specified by the user for allocating memory for **identity**. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if the parameters are incorrect. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_MEM_ALLOCATOR_ERROR} if the memory allocation fails. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. * @since 12 */ int OH_IPCSkeleton_ResetCallingIdentity(char **identity, int32_t *len, OH_IPC_MemAllocator allocator); /** * @brief Sets the caller credential information to the IPC context. - * + * * @syscap SystemCapability.Communication.IPC.Core - * @param identity Pointer to the caller identity, which cannot be NULL. - * The value is returned by OH_IPCSkeleton_ResetCallingIdentity. - * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n - * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. + * @param identity Pointer to the caller credential, which cannot be empty. The value is returned by + * **OH_IPCSkeleton_ResetCallingIdentity**. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if the parameters are incorrect. + * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. * @since 12 */ int OH_IPCSkeleton_SetCallingIdentity(const char *identity); /** * @brief Checks whether an IPC request is being handled. - * + * * @syscap SystemCapability.Communication.IPC.Core - * @return Returns 1 if an IPC request is being handled; returns 0 otherwise. + * @return Returns **1** if an IPC request is being handled; returns **0** otherwise. * @since 12 */ int OH_IPCSkeleton_IsHandlingTransaction(void); diff --git a/IPCKit/ipc_error_code.h b/IPCKit/ipc_error_code.h index 5fa109e5b..79c2cd156 100644 --- a/IPCKit/ipc_error_code.h +++ b/IPCKit/ipc_error_code.h @@ -1,10 +1,10 @@ /* - * Copyright (c) 2024 Huawei Device Co., Ltd. + * Copyright (C) 2024-2026 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, @@ -12,7 +12,6 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - /** * @addtogroup OHIPCErrorCode * @{ @@ -22,12 +21,11 @@ * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ - /** * @file ipc_error_code.h * - * @brief Defines IPC error codes. - * + * @brief Defines the IPC error codes. + * * @library libipc_capi.so * @kit IPCKit * @syscap SystemCapability.Communication.IPC.Core @@ -38,36 +36,62 @@ #define CAPI_INCLUDE_IPC_ERROR_CODE_H /** -* @brief Enumerates IPC error codes. -* +* @brief Enumerates the IPC error codes. +* * @since 12 */ typedef enum { - /** @error Execution successful. */ + /** + * Execution successful. + */ OH_IPC_SUCCESS = 0, - /** @error Start error code. */ + /** + * Start error code. + */ OH_IPC_ERROR_CODE_BASE = 1901000, - /** @error Invalid parameters. */ + /** + * Invalid parameter. + */ OH_IPC_CHECK_PARAM_ERROR = OH_IPC_ERROR_CODE_BASE, - /** @error Failed to write data to the serialized object. */ + /** + * Failed to write data to the serialized object. + */ OH_IPC_PARCEL_WRITE_ERROR = OH_IPC_ERROR_CODE_BASE + 1, - /** @error Failed to read data from the serialized object. */ + /** + * Failed to read data from the serialized object. + */ OH_IPC_PARCEL_READ_ERROR = OH_IPC_ERROR_CODE_BASE + 2, - /** @error Failed to allocate memory. */ + /** + * Failed to allocate memory. + */ OH_IPC_MEM_ALLOCATOR_ERROR = OH_IPC_ERROR_CODE_BASE + 3, - /** @error The command word is out of the value range [0x01,0x00ffffff]. */ + /** + * The command word is out of the value range [0x01, 0x00ffffff]. + */ OH_IPC_CODE_OUT_OF_RANGE = OH_IPC_ERROR_CODE_BASE + 4, - /** @error The remote object is dead. */ + /** + * The remote object is dead. + */ OH_IPC_DEAD_REMOTE_OBJECT = OH_IPC_ERROR_CODE_BASE + 5, - /** @error The custom error code is out of range [1900001, 1999999]. */ + /** + * The custom error code is out of the range [1900001, 1999999]. + */ OH_IPC_INVALID_USER_ERROR_CODE = OH_IPC_ERROR_CODE_BASE + 6, - /** @error IPC internal error. */ + /** + * IPC internal error. + */ OH_IPC_INNER_ERROR = OH_IPC_ERROR_CODE_BASE + 7, - /** @error Maximum error code. */ + /** + * Maximum error code. + */ OH_IPC_ERROR_CODE_MAX = OH_IPC_ERROR_CODE_BASE + 1000, - /** @error Minimum value for a custom error code. */ + /** + * Minimum value for a custom error code. + */ OH_IPC_USER_ERROR_CODE_MIN = 1909000, - /** @error Maximum value for a custom error code. */ + /** + * Maximum value for a custom error code. + */ OH_IPC_USER_ERROR_CODE_MAX = 1909999, } OH_IPC_ErrorCode; diff --git a/IPCKit/ipc_kit.h b/IPCKit/ipc_kit.h index 8d0fdfb99..8c31c3635 100644 --- a/IPCKit/ipc_kit.h +++ b/IPCKit/ipc_kit.h @@ -1,10 +1,10 @@ /* - * Copyright (c) 2024 Huawei Device Co., Ltd. + * Copyright (C) 2024-2026 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, @@ -12,7 +12,6 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - /** * @addtogroup IPCKit * @{ @@ -22,12 +21,11 @@ * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ - /** * @file ipc_kit.h * * @brief Provides an entry to the IPC header files for you to reference. - * + * * @library libipc_capi.so * @kit IPCKit * @syscap SystemCapability.Communication.IPC.Core