1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef CAPI_INCLUDE_IPC_CREMOTE_OBJECT_H 17 #define CAPI_INCLUDE_IPC_CREMOTE_OBJECT_H 18 19 /** 20 * @addtogroup OHIPCRemoteObject 21 * @{ 22 * 23 * @brief Provides C interfaces for creating and destroying a remote object, transferring data, 24 * and observing the dead status of a remote object. 25 * 26 * @syscap SystemCapability.Communication.IPC.Core 27 * @since 12 28 */ 29 30 /** 31 * @file ipc_cremote_object.h 32 * 33 * @brief Defines C interfaces for creating and destroying a remote object, transferring data, 34 * and observing the dead status of a remote object. 35 * 36 * @library libipc_capi.so 37 * @syscap SystemCapability.Communication.IPC.Core 38 * @since 12 39 */ 40 41 #include <stdint.h> 42 43 #include "ipc_cparcel.h" 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Defines an <b>OHIPCDeathRecipient</b> object, which is used to receive a notification 51 * when the <b>OHIPCRemoteStub</b> object dies unexpectedly. 52 * 53 * @syscap SystemCapability.Communication.IPC.Core 54 * @since 12 55 */ 56 struct OHIPCDeathRecipient; 57 58 /** 59 * @brief Typedef an <b>OHIPCDeathRecipient</b> object. 60 * 61 * @syscap SystemCapability.Communication.IPC.Core 62 * @since 12 63 */ 64 typedef struct OHIPCDeathRecipient OHIPCDeathRecipient; 65 66 /** 67 * @brief Called to process the remote data request at the stub. 68 * 69 * @syscap SystemCapability.Communication.IPC.Core 70 * @param code Custom command word for communication, in the range [0x01, 0x00ffffff]. 71 * @param data Pointer to the request data object. It cannot be NULL or released in the function. 72 * @param reply Pointer to the response data object. It cannot be NULL or released in the function. 73 * If this function returns an error, data cannot be written to this parameter. 74 * @param userData Pointer to the user data. It can be NULL. 75 * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n 76 * Returns a custom error code in the range [1909001, 1909999] or a system error code otherwise. \n 77 * Returns {@link OH_IPC_ErrorCode#OH_IPC_INVALID_USER_ERROR_CODE} if the custom error code is out of the value range. 78 * @since 12 79 */ 80 typedef int (*OH_OnRemoteRequestCallback)(uint32_t code, const OHIPCParcel *data, 81 OHIPCParcel *reply, void *userData); 82 83 /** 84 * @brief Called when an observed object is destroyed. 85 * 86 * @syscap SystemCapability.Communication.IPC.Core 87 * @param userData Pointer to the user data. It can be NULL. 88 * @since 12 89 */ 90 typedef void (*OH_OnRemoteDestroyCallback)(void *userData); 91 92 /** 93 * @brief Creates an <b>OHIPCRemoteStub</b> object. 94 * 95 * @syscap SystemCapability.Communication.IPC.Core 96 * @param descriptor Pointer to the descriptor of the <b>OHIPCRemoteStub</b> object to create. It cannot be NULL. 97 * @param requestCallback Callback used to process the data request. It cannot be NULL. 98 * @param destroyCallback Callback to be invoked when the object is destroyed. It can be NULL. 99 * @param userData Pointer to the user data. It can be NULL. 100 * @return Returns the pointer to the <b>OHIPCRemoteStub</b> object created if the operation is successful; 101 * returns NULL otherwise. 102 * @since 12 103 */ 104 OHIPCRemoteStub* OH_IPCRemoteStub_Create(const char *descriptor, OH_OnRemoteRequestCallback requestCallback, 105 OH_OnRemoteDestroyCallback destroyCallback, void *userData); 106 107 /** 108 * @brief Destroys an <b>OHIPCRemoteStub</b> object. 109 * 110 * @syscap SystemCapability.Communication.IPC.Core 111 * @param stub Pointer to the <b>OHIPCRemoteStub</b> object to destroy. 112 * @since 12 113 */ 114 void OH_IPCRemoteStub_Destroy(OHIPCRemoteStub *stub); 115 116 /** 117 * @brief Destroys an <b>OHIPCRemoteProxy</b> object. 118 * 119 * @syscap SystemCapability.Communication.IPC.Core 120 * @param proxy Pointer to the <b>OHIPCRemoteProxy</b> object to destroy. 121 * @since 12 122 */ 123 void OH_IPCRemoteProxy_Destroy(OHIPCRemoteProxy *proxy); 124 125 /** 126 * @brief Enumerates the IPC request modes. 127 * 128 * @since 12 129 */ 130 typedef enum { 131 /** Synchronous request. */ 132 OH_IPC_REQUEST_MODE_SYNC = 0, 133 /** Asynchronous request. */ 134 OH_IPC_REQUEST_MODE_ASYNC = 1, 135 } OH_IPC_RequestMode; 136 137 /** 138 * @brief Defines the IPC message options. 139 * 140 * @since 12 141 */ 142 #pragma pack(4) 143 typedef struct { 144 /** Message request mode. */ 145 OH_IPC_RequestMode mode; 146 /** Parameter reserved for RPC, which is invalid for IPC. */ 147 uint32_t timeout; 148 /** Reserved parameter, which must be NULL. */ 149 void* reserved; 150 } OH_IPC_MessageOption; 151 #pragma pack() 152 153 /** 154 * @brief Sends an IPC message. 155 * 156 * @syscap SystemCapability.Communication.IPC.Core 157 * @param proxy Pointer to the <b>OHIPCRemoteProxy</b> object. It cannot be NULL. 158 * @param code Custom IPC command word, in the range [0x01, 0x00ffffff]. 159 * @param data Pointer to the request data object. It cannot be NULL. 160 * @param reply Pointer to the response data object. It cannot be NULL in the case of a synchronous request, 161 * and can be NULL in the case of an asynchronous request. 162 * @param option Pointer to the message options. It can be NULL, which indicates a synchronous request. 163 * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n 164 * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n 165 * Returns {@link OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT} if the <b>OHIPCRemoteStub</b> object is dead. \n 166 * Returns {@link OH_IPC_ErrorCode#OH_IPC_CODE_OUT_OF_RANGE} if the error code is out of the value range. \n 167 * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} or a custom error code in other cases. 168 * @since 12 169 */ 170 int OH_IPCRemoteProxy_SendRequest(const OHIPCRemoteProxy *proxy, uint32_t code, const OHIPCParcel *data, 171 OHIPCParcel *reply, const OH_IPC_MessageOption *option); 172 173 /** 174 * @brief Obtains the interface descriptor from the stub. 175 * 176 * @syscap SystemCapability.Communication.IPC.Core 177 * @param proxy Pointer to the <b>OHIPCRemoteProxy</b> object. It cannot be NULL. 178 * @param descriptor Double pointer to the address of the memory for holding the interface descriptor. 179 * The memory is allocated by the allocator provided by the user and needs to be released. This pointer cannot be NULL. 180 * If an error code is returned, you still need to check whether the memory is empty and release the memory. 181 * Otherwise, memory leaks may occur. 182 * @param len Pointer to the length of the data to be written to the descriptor, including the terminator. 183 * This parameter cannot be NULL. 184 * @param allocator Memory allocator specified by the user for allocating memory for <b>descriptor</b>. 185 * It cannot be NULL. 186 * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n 187 * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n 188 * Returns {@link OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT} if the <b>OHIPCRemoteStub</b> object is dead. \n 189 * Returns {@link OH_IPC_ErrorCode#OH_IPC_MEM_ALLOCATOR_ERROR} if memory allocation fails. \n 190 * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the data in the serialized object failed to be read. 191 * @since 12 192 */ 193 int OH_IPCRemoteProxy_GetInterfaceDescriptor(OHIPCRemoteProxy *proxy, char **descriptor, int32_t *len, 194 OH_IPC_MemAllocator allocator); 195 196 /** 197 * @brief Called when the <b>OHIPCRemoteStub</b> object dies unexpectedly. 198 * 199 * @syscap SystemCapability.Communication.IPC.Core 200 * @param userData Pointer to the user data. It can be NULL. 201 * @since 12 202 */ 203 typedef void (*OH_OnDeathRecipientCallback)(void *userData); 204 205 /** 206 * @brief Called when the <b>OHIPCDeathRecipient</b> object is destroyed. 207 * 208 * @syscap SystemCapability.Communication.IPC.Core 209 * @param userData Pointer to the user data. It can be NULL. 210 * @since 12 211 */ 212 typedef void (*OH_OnDeathRecipientDestroyCallback)(void *userData); 213 214 /** 215 * @brief Creates an <b>OHIPCDeathRecipient</b> object, which allows a notification to be received 216 * when the <b>OHIPCRemoteStub</b> object dies unexpectedly. 217 * 218 * @syscap SystemCapability.Communication.IPC.Core 219 * @param deathRecipientCallback Callback to be invoked when the <b>OHIPCRemoteStub</b> object is dead. 220 * It cannot be NULL. 221 * @param destroyCallback Callback to be invoked when the object is destroyed. It can be NULL. 222 * @param userData Pointer to the user data. It can be NULL. 223 * @return Returns the pointer to the <b>OHIPCDeathRecipient</b> object created if the operation is successful; 224 * returns NULL otherwise. 225 * @since 12 226 */ 227 OHIPCDeathRecipient* OH_IPCDeathRecipient_Create(OH_OnDeathRecipientCallback deathRecipientCallback, 228 OH_OnDeathRecipientDestroyCallback destroyCallback, void *userData); 229 230 /** 231 * @brief Destroys an <b>OHIPCDeathRecipient</b> object. 232 * 233 * @syscap SystemCapability.Communication.IPC.Core 234 * @param recipient Pointer to the <b>OHIPCDeathRecipient</b> object to destroy. 235 * @since 12 236 */ 237 void OH_IPCDeathRecipient_Destroy(OHIPCDeathRecipient *recipient); 238 239 /** 240 * @brief Subscribes to the death of an <b>OHIPCRemoteStub</b> object for an <b>OHIPCRemoteProxy</b> object. 241 * 242 * @syscap SystemCapability.Communication.IPC.Core 243 * @param proxy Pointer to the <b>OHIPCRemoteProxy</b> object that subscribes to the death notification. 244 * It cannot be NULL. 245 * @param recipient Pointer to the object that receives the death notification of the <b>OHIPCRemoteStub</b> object. 246 * It cannot be NULL. 247 * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n 248 * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n 249 * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. 250 * @since 12 251 */ 252 int OH_IPCRemoteProxy_AddDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient); 253 254 /** 255 * @brief Unsubscribes from the death of the <b>OHIPCRemoteStub</b> object for an <b>OHIPCRemoteProxy</b> object. 256 * 257 * @syscap SystemCapability.Communication.IPC.Core 258 * @param proxy Pointer to the <b>OHIPCRemoteProxy</b> object that unsubscribes from the death notification. 259 * It cannot be NULL. 260 * @param recipient Pointer to the object that receives the death notification of the <b>OHIPCRemoteStub</b> object. 261 * It cannot be NULL. 262 * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n 263 * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n 264 * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. 265 * @since 12 266 */ 267 int OH_IPCRemoteProxy_RemoveDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient); 268 269 /** 270 * @brief Checks whether the <b>OHIPCRemoteStub</b> object corresponding to the <b>OHIPCRemoteProxy</b> object is dead. 271 * 272 * @syscap SystemCapability.Communication.IPC.Core 273 * @param proxy Pointer to the <b>OHIPCRemoteProxy</b> object to check. It cannot be NULL. 274 * @return Returns <b>1</b> if the <b>OHIPCRemoteStub</b> object is dead; returns <b>0</b> otherwise. 275 * If an invalid parameter is found, the <b>OHIPCRemoteStub</b> object does not exist. 276 * In this case, <b>1</b> is returned. 277 * @since 12 278 */ 279 int OH_IPCRemoteProxy_IsRemoteDead(const OHIPCRemoteProxy *proxy); 280 281 #ifdef __cplusplus 282 } 283 #endif 284 285 /** @} */ 286 #endif 287