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