/* * Copyright (c) 2024 Huawei Device Co., Ltd. * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef CAPI_INCLUDE_IPC_CPARCEL_H #define CAPI_INCLUDE_IPC_CPARCEL_H /** * @addtogroup OHIPCParcel * @{ * * @brief Defines C interfaces for IPC serialization and deserialization. * * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ /** * @file ipc_cparcel.h * * @brief Defines C interfaces for IPC serialization and deserialization. * * @library libipc_capi.so * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ #include #ifdef __cplusplus extern "C" { #endif /** * @brief Defines an IPC serialized object. * * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ struct OHIPCParcel; /** * @brief Typedef an IPC serialized object. * * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ 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. * * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ 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. * * @syscap SystemCapability.Communication.IPC.Core * @since 12 */ typedef struct OHIPCRemoteStub OHIPCRemoteStub; /** * @brief Allocates memory. * * @syscap SystemCapability.Communication.IPC.Core * @param len Length of the memory to allocate. * @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. * * @syscap SystemCapability.Communication.IPC.Core * @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. * * @syscap SystemCapability.Communication.IPC.Core * @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. * * @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. * @since 12 */ int OH_IPCParcel_GetDataSize(const OHIPCParcel *parcel); /** * @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. * @since 12 */ int OH_IPCParcel_GetWritableBytes(const OHIPCParcel *parcel); /** * @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. * @since 12 */ int OH_IPCParcel_GetReadableBytes(const OHIPCParcel *parcel); /** * @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. * @since 12 */ int OH_IPCParcel_GetReadPosition(const OHIPCParcel *parcel); /** * @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. * @since 12 */ int OH_IPCParcel_GetWritePosition(const OHIPCParcel *parcel); /** * @brief Resets the position to read data in an IPC parcel. * * @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. * @since 12 */ int OH_IPCParcel_RewindReadPosition(OHIPCParcel *parcel, uint32_t newReadPos); /** * @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. * @since 12 */ int OH_IPCParcel_RewindWritePosition(OHIPCParcel *parcel, uint32_t newWritePos); /** * @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 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. * @since 12 */ int OH_IPCParcel_WriteInt8(OHIPCParcel *parcel, int8_t value); /** * @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. * @since 12 */ int OH_IPCParcel_ReadInt8(const OHIPCParcel *parcel, int8_t *value); /** * @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 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. * @since 12 */ int OH_IPCParcel_WriteInt16(OHIPCParcel *parcel, int16_t value); /** * @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. * @since 12 */ int OH_IPCParcel_ReadInt16(const OHIPCParcel *parcel, int16_t *value); /** * @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 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. * @since 12 */ int OH_IPCParcel_WriteInt32(OHIPCParcel *parcel, int32_t value); /** * @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. * @since 12 */ int OH_IPCParcel_ReadInt32(const OHIPCParcel *parcel, int32_t *value); /** * @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 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. * @since 12 */ int OH_IPCParcel_WriteInt64(OHIPCParcel *parcel, int64_t value); /** * @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. * @since 12 */ int OH_IPCParcel_ReadInt64(const OHIPCParcel *parcel, int64_t *value); /** * @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 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. * @since 12 */ int OH_IPCParcel_WriteFloat(OHIPCParcel *parcel, float value); /** * @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. * @since 12 */ int OH_IPCParcel_ReadFloat(const OHIPCParcel *parcel, float *value); /** * @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 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. * @since 12 */ int OH_IPCParcel_WriteDouble(OHIPCParcel *parcel, double value); /** * @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. * @since 12 */ int OH_IPCParcel_ReadDouble(const OHIPCParcel *parcel, double *value); /** * @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. * @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. * * @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. * @since 12 */ const char* OH_IPCParcel_ReadString(const OHIPCParcel *parcel); /** * @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 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. * @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. * * @syscap SystemCapability.Communication.IPC.Core * @param parcel Pointer to the target 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. * @since 12 */ const uint8_t* OH_IPCParcel_ReadBuffer(const OHIPCParcel *parcel, int32_t len); /** * @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. * @since 12 */ int OH_IPCParcel_WriteRemoteStub(OHIPCParcel *parcel, const OHIPCRemoteStub *stub); /** * @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. * @since 12 */ OHIPCRemoteStub* OH_IPCParcel_ReadRemoteStub(const OHIPCParcel *parcel); /** * @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. * @since 12 */ int OH_IPCParcel_WriteRemoteProxy(OHIPCParcel *parcel, const OHIPCRemoteProxy *proxy); /** * @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. * @since 12 */ OHIPCRemoteProxy* OH_IPCParcel_ReadRemoteProxy(const OHIPCParcel *parcel); /** * @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. * @since 12 */ int OH_IPCParcel_WriteFileDescriptor(OHIPCParcel *parcel, int32_t fd); /** * @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 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. * @since 12 */ int OH_IPCParcel_ReadFileDescriptor(const OHIPCParcel *parcel, int32_t *fd); /** * @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 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. * @since 12 */ int OH_IPCParcel_Append(OHIPCParcel *parcel, const OHIPCParcel *data); /** * @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 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. * @since 12 */ int OH_IPCParcel_WriteInterfaceToken(OHIPCParcel *parcel, const char *token); /** * @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 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. * @since 12 */ int OH_IPCParcel_ReadInterfaceToken(const OHIPCParcel *parcel, char **token, int32_t *len, OH_IPC_MemAllocator allocator); #ifdef __cplusplus } #endif /** @} */ #endif