1 /* 2 * Copyright (c) 2020 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 Registry 18 * @{ 19 * 20 * @brief Provides APIs for registering and discovering inter-process communication (IPC) 21 * capabilities. 22 * 23 * Based on the Samgr development framework, this module helps you to develop system capabilities 24 * and implement cross-process calls. \n 25 * This module is used when system capabilities need to be provided across processes. \n 26 * 27 * @since 1.0 28 * @version 1.0 29 */ 30 31 /** 32 * @file iproxy_client.h 33 * 34 * @brief Provides the client proxy class. 35 * 36 * When you need to call system capabilities of other processes, obtain the class from Samgr. \n 37 * 38 * @since 1.0 39 * @version 1.0 40 */ 41 42 #ifndef LITE_IPROXY_CLIENT_H 43 #define LITE_IPROXY_CLIENT_H 44 45 #include "iunknown.h" 46 #include "message.h" 47 #include "serializer.h" 48 49 #ifdef __cplusplus 50 #if __cplusplus 51 extern "C" { 52 #endif 53 #endif 54 55 #define CLIENT_PROXY_VER (0x40 | (uint16)DEFAULT_VERSION) 56 57 /** 58 * @brief Indicates the inherited macro of the client proxy. 59 * 60 * This constant is used when a client proxy needs to be customized or generated by a tool. \n 61 * 62 */ 63 #define INHERIT_CLIENT_IPROXY \ 64 INHERIT_IUNKNOWN; \ 65 int (*Invoke)(IClientProxy *proxy, int funcId, IpcIo *request, IOwner owner, INotify notify) 66 67 typedef void *IOwner; 68 69 /** 70 * @brief Called when a client request is responded. 71 * 72 * The client implements this <b>INotify</b> callback to receive response data from the server. \n 73 * <b>owner</b> indicates the client proxy that receives the response data; <b>code</b> indicates 74 * the error code of the response data from the server; <b>reply</b> indicates the response data. \n 75 * 76 */ 77 typedef int (*INotify)(IOwner owner, int code, IpcIo *reply); 78 79 typedef struct IClientProxy IClientProxy; 80 81 /** 82 * @brief Defines the client proxy object. 83 * 84 * This object is used for the IPC with the server. \n 85 * If you want to use the same invocation mode as that on the server, create an object inherited 86 * from {@code IClientProxy} and implement serialization. 87 * 88 * @since 1.0 89 * @version 1.0 90 */ 91 struct IClientProxy { 92 /** Inherites the <b>IUnknown</b> base class. */ 93 INHERIT_IUNKNOWN; 94 95 /** 96 * @brief Sends an IPC message from the client to the <b>IServerProxy</b>. 97 * 98 * This function is used for IPC. \n 99 * The passed <b>proxy</b> is used to obtain the server information. Then, <b>request</b> 100 * carries the request message to be sent to the server and processed by the function specified 101 * by <b>funcId</b>. <b>notify</b> is a callback function used to process the response message. \n 102 * 103 * @param proxy Indicates the pointer of the client proxy object. 104 * @param funcId Indicates the ID of the function implemented on the server. 105 * @param request Indicates the pointer to the serialized request message. 106 * @param owner Indicates the receiver (generics type) of the response message. 107 * @param notify Indicates the callback function that notifies the client of the response 108 * message. 109 * @return Returns <b>EC_SUCCESS</b> if the IPC message is sent successfully; returns other 110 * error codes if the message fails to be sent. 111 * @since 1.0 112 * @version 1.0 113 */ 114 int (*Invoke)(IClientProxy *proxy, int funcId, IpcIo *request, IOwner owner, INotify notify); 115 }; 116 117 #define INHERIT_IPROXY_ENTRY(T) INHERIT_IUNKNOWNENTRY(T) 118 119 #define CLIENT_IPROXY_BEGIN IUNKNOWN_ENTRY_BEGIN(CLIENT_PROXY_VER) 120 121 #define IPROXY_END IUNKNOWN_ENTRY_END 122 123 /** 124 * @brief Obtains the IPC address of a remote service and feature based on the service name 125 * and feature name. 126 * 127 * This function is used when {@link IClientProxy} cannot meet your requirements for calling IPCs. \n 128 * For example, if you need to receive the death notification of a remote service or feature, 129 * you can call this function to obtain the address of the remote service or feature 130 * and subscribe to the death notification from the IPC. \n 131 * 132 * @param service Indicates the pointer to the name of the remote service. 133 * @param feature Indicates the pointer to the name of the remote feature. 134 * @return Returns the IPC address of the remote service or feature. When the handle of the 135 * obtained address structure {@link SvcIdentity} is <b>0xFFFFFFFF</b>, the address is invalid. 136 * @attention This function can be called only after <b>GetFeatureApi</b> in {@link SamgrLite} 137 * is successfully called. Otherwise, an invalid address is returned. When the service or feature 138 * does not support IPC communication, an invalid address will be returned. 139 * @since 1.0 140 * @version 1.0 141 */ 142 SvcIdentity SAMGR_GetRemoteIdentity(const char *service, const char *feature); 143 144 #ifdef __cplusplus 145 #if __cplusplus 146 } 147 #endif 148 #endif 149 #endif // LITE_IPROXY_CLIENT_H 150 /** @} */ 151