1 /* 2 * Copyright (c) 2021-2023 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 /** 17 * @addtogroup HDF_IPC_ADAPTER 18 * @{ 19 * 20 * @brief Provides capabilities for the user-mode driver to use inter-process communication (IPC). 21 * 22 * The driver is implemented in C, while IPC is implemented in C++. 23 * This module implements IPC APIs in C based on the IPC over C++. 24 * It provides APIs for registering a service object, registering a function for processing 25 * the death notification of a service, and implementing the dump mechanism. 26 * 27 * @since 1.0 28 */ 29 30 /** 31 * @file hdf_remote_service.h 32 * 33 * @brief Provides IPC interface capabilities in C. 34 * 35 * @since 1.0 36 */ 37 #ifndef HDF_REMOTE_SERVICE_H 38 #define HDF_REMOTE_SERVICE_H 39 40 #include <unistd.h> 41 #include "hdf_object.h" 42 #include "hdf_sbuf.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif /* __cplusplus */ 47 48 /** 49 * @brief Defines the <b>HdfRemoteDispatcher</b> struct. 50 */ 51 struct HdfRemoteDispatcher { 52 /** Interface for synchronous message dispatching */ 53 int (*Dispatch)(struct HdfRemoteService *, int, struct HdfSBuf *, struct HdfSBuf *); 54 /** Interface for asynchronous message dispatching */ 55 int (*DispatchAsync)(struct HdfRemoteService *, int, struct HdfSBuf *, struct HdfSBuf *); 56 }; 57 58 /** 59 * @brief Defines the <b>HdfDeathRecipient</b> struct. 60 */ 61 struct HdfDeathRecipient { 62 /** Interface for listening for the death notification of a service. */ 63 void (*OnRemoteDied)(struct HdfDeathRecipient *, struct HdfRemoteService *); 64 }; 65 66 /** 67 * @brief Defines the <b>HdfRemoteService</b> struct. 68 */ 69 struct HdfRemoteService { 70 /** Remote service object */ 71 struct HdfObject object; 72 /** Target object to which the remote service object points */ 73 struct HdfObject *target; 74 /** Message dispatching interface of the remote service object */ 75 struct HdfRemoteDispatcher *dispatcher; 76 /** Address of the IPC object */ 77 uint64_t index; 78 }; 79 80 /** 81 * @brief Obtains a remote service. 82 * 83 * @param object Indicates the pointer to the service. 84 * @param dispatcher Indicates the pointer to the message dispatching interface of the service. 85 * @return Returns the remote service obtained if the operation is successful; returns a null pointer otherwise. 86 */ 87 struct HdfRemoteService *HdfRemoteServiceObtain( 88 struct HdfObject *object, struct HdfRemoteDispatcher *dispatcher); 89 90 /** 91 * @brief Recycles a remote service. 92 * 93 * @param object Indicates the pointer to the remote service to recycle. 94 */ 95 void HdfRemoteServiceRecycle(struct HdfRemoteService *service); 96 97 /** 98 * @brief Adds a function for processing the the death notification of a service. 99 * 100 * @param service Indicates the pointer to the service to be listened for. 101 * @param recipient Indicates the pointer to the callback object containing the code to be executed 102 * when the death notification is received. 103 */ 104 void HdfRemoteServiceAddDeathRecipient(struct HdfRemoteService *service, struct HdfDeathRecipient *recipient); 105 106 /** 107 * @brief Removes the function for processing the the death notification of a service. 108 * 109 * @param service Indicates the pointer to the target service. 110 * @param recipient Indicates the pointer to the callback object to remove. 111 */ 112 void HdfRemoteServiceRemoveDeathRecipient(struct HdfRemoteService *service, struct HdfDeathRecipient *recipient); 113 114 /** 115 * @brief Registers a service. 116 * 117 * @param serviceId Indicates the ID of the service to add. 118 * @param service Indicates the pointer to the service. 119 * @return Returns <b>HDF_SUCCESS</b> if the operation is successful; otherwise, the operation fails. 120 */ 121 int HdfRemoteServiceRegister(int32_t serviceId, struct HdfRemoteService *service); 122 123 /** 124 * @brief Obtains a service. 125 * 126 * @param serviceId Indicates the ID of the service to obtain. 127 * @return Returns the service object obtained if the operation is successful; returns a null pointer otherwise. 128 */ 129 struct HdfRemoteService *HdfRemoteServiceGet(int32_t serviceId); 130 131 /** 132 * @brief Sets an interface descriptor for a service. 133 * 134 * @param service Indicates the pointer to the target service. 135 * @param descriptor Indicates the interface descriptor to set. 136 * @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise. 137 */ 138 bool HdfRemoteServiceSetInterfaceDesc(struct HdfRemoteService *service, const char *descriptor); 139 140 /** 141 * @brief Sets an interface token for an <b>HdfSBuf</b> with the interface descriptor of a service. 142 * 143 * @param service Indicates the pointer to the service. 144 * @param data Indicates the pointer to the target<b>HdfSBuf</b> object to be set with an interface token. 145 * @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise. 146 */ 147 bool HdfRemoteServiceWriteInterfaceToken(struct HdfRemoteService *service, struct HdfSBuf *data); 148 149 /** 150 * @brief Checks the interface tokens of a service and an <b>HdfSBuf</b> for consistency. 151 * 152 * @param service Indicates the pointer to the service. 153 * @param data Indicates the pointer to the <b>HdfSBuf</b>. 154 * @return Returns <b>true</b> if the two interface tokens are the same; returns <b>true</b> otherwise. 155 */ 156 bool HdfRemoteServiceCheckInterfaceToken(struct HdfRemoteService *service, struct HdfSBuf *data); 157 158 /** 159 * @brief Get the caller's process ID. 160 * 161 * @return The caller's process ID. 162 */ 163 pid_t HdfRemoteGetCallingPid(void); 164 165 /** 166 * @brief Get the caller's user ID. 167 * 168 * @return The caller's user ID. 169 */ 170 pid_t HdfRemoteGetCallingUid(void); 171 172 /** 173 * @brief Default command distribution for invoking ipc. 174 * 175 * @param service Indicates the pointer to the service. 176 * @param code Indicates the command word to be distributed. 177 * @param data Indicates the pointer to the <b>HdfSBuf</b>. 178 * @param reply Indicates the pointer to the <b>HdfSBuf</b>. 179 * @return Returns <b>HDF_SUCCESS</b> if the operation is successful; otherwise, the operation fails. 180 */ 181 int HdfRemoteServiceDefaultDispatch( 182 struct HdfRemoteService *service, int code, struct HdfSBuf *data, struct HdfSBuf *reply); 183 184 #ifdef __cplusplus 185 } 186 #endif /* __cplusplus */ 187 188 #endif /* HDF_REMOTE_SERVICE_H */ 189