1 /* 2 * Copyright (c) Huawei Technologies Co., Ltd. 2021-2023. All rights reserved. 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 PLUGIN_MODULE_API_H 17 #define PLUGIN_MODULE_API_H 18 19 #include <stddef.h> 20 #include <stdint.h> 21 #include <climits> 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /** 28 * @brief interface type of plugin session starting 29 * 30 * It will be called when the plugin session starts, and the binary data pointed 31 * by the parameter is the protobuffer binary data filled by the IDE side; 32 * 33 * The implementation part —— need to call the deserialization code generated by 34 * protobuffer to restore it to the data type generated by proto; 35 * 36 * For the third-party developers, you can also not use the protobuffer as a 37 * serialization tool, only need to adapt to the Java code. 38 * 39 * @param ConfigData configure the starting address of information memory block 40 * @param ConfigSize configure the byte counts of information memory block 41 * @return Return 0 for success and -1 for failure 42 */ 43 typedef int (*PluginSessionStartCallback)(const uint8_t* configData, uint32_t configSize); 44 45 /** 46 * @brief interface type of Plugin result reporting interface type 47 * The incoming memory block is a large memory pre allocated by the plugin management module, 48 * The implementation part —— need to define the specific result type object of proto and serialize it to this memory, 49 * The framework will transfer the original data to the PC as it is. 50 * @param bufferData: the starting address of the memory buffer where the result is stored 51 * @param bufferSize: The byte counts in the memory buffer where the result is stored 52 * @return The return value greater than 0 indicates the number of bytes filled in memory, 53 * and 0 indicates that nothing is filled, 54 * return value less than 0 indicates failure, and -1 is a general error 55 * If the absolute value of the return value is greater than buffersize, the number of bytes in the buffer 56 * is insufficient to store the result. The framework will try to get the result again with a larger cache. 57 */ 58 typedef int (*PluginReportResultCallback)(uint8_t* bufferData, uint32_t bufferSize); 59 60 struct RandomWriteCtx; 61 62 /** 63 * @brief get memory of the specified length 64 * @param ctx : writing context 65 * @param size : The byte counts to be used 66 * @param memory : output current target memory pointer 67 * @param offset : output current offset relative to the head of writing 68 * @return : Return true for success and false for failure 69 */ 70 typedef bool (*GetMemoryFunc)(RandomWriteCtx* ctx, uint32_t size, uint8_t** memory, uint32_t* offset); 71 72 /** 73 * @brief seek to the specified offset for writing 74 * @param ctx : writing context 75 * @param offset : offset relative to the head of writing 76 * @return : Return true for success and false for failure 77 */ 78 typedef bool (*SeekFunc)(RandomWriteCtx* ctx, uint32_t offset); 79 80 /** 81 * RandomWriteCtx : type definition, random write context. 82 */ 83 struct RandomWriteCtx { 84 /** 85 * get the memory and current offset. 86 */ 87 GetMemoryFunc getMemory; 88 89 /** 90 * seek for writing. 91 */ 92 SeekFunc seek; 93 }; 94 95 /** 96 * @brief interface type of Plugin result reporting interface type 97 * The plugin reports the bytes data by randomWrite() directly, 98 * or constructor proto_encoder message by randomWrite(), 99 * the message class code is generated by protoc using proto file. 100 * @param randomWrite: random write context 101 * @return size that has been reproted, -1 when reprot faild. 102 */ 103 typedef int32_t (*PluginReportResultOptimizeCallback)(RandomWriteCtx* randomWrite); 104 105 /** 106 * @brief interface type of plugin session stop, 107 * Called when stopping plugin sessions 108 * @return Return 0 for success and -1 for failure. 109 */ 110 typedef int (*PluginSessionStopCallback)(void); 111 112 /** 113 * @brief interface type of plugin session stop, 114 * Called when stopping plugin sessions 115 * @return Return 0 for success and -1 for failure. 116 */ 117 typedef int (*PluginReportBasicDataCallback)(void); 118 119 /** 120 * WriterStruct type forward declaration 121 */ 122 typedef struct WriterStruct WriterStruct; 123 124 /** 125 * @brief write : interface type 126 * @param writer : pointer 127 * @param data : the first byte pointer of data buffer 128 * @param size : The byte counts in the data buffer 129 * @return : Return the number of bytes written for success, and returns -1 for failure 130 */ 131 typedef long (*WriteFuncPtr)(WriterStruct* writer, const void* data, size_t size); 132 133 /** 134 * @brief flush : interface type 135 * @return Return true for success and false for failure； 136 */ 137 typedef bool (*FlushFuncPtr)(WriterStruct* writer); 138 139 /** 140 * @brief StartReport interface type 141 * @return : Return RandomWriteCtx for success, null for failure 142 * The plugin reports the bytes data by RandomWriteCtx directly, 143 * or constructor proto_encoder message by RandomWriteCtx, 144 * the message class code is generated by protoc using proto file. 145 */ 146 typedef RandomWriteCtx* (*StartReportFuncPtr)(WriterStruct* writer); 147 148 /** 149 * @brief FinishReport interface type 150 * @param size : The byte counts of data reported 151 * @return 152 */ 153 typedef void (*FinishReportFuncPtr)(WriterStruct* writer, int32_t size); 154 155 /** 156 * WriterStruct : type definition. 157 */ 158 struct WriterStruct { 159 /** 160 * write : function pointer,point to the actual write function. 161 */ 162 WriteFuncPtr write = nullptr; 163 164 /** 165 * flush function pointer,point to the actual flush function. 166 */ 167 FlushFuncPtr flush = nullptr; 168 169 /** 170 * startMessage function pointer, point to the actual startMessage function. 171 */ 172 StartReportFuncPtr startReport = nullptr; 173 174 /** 175 * finishMessage function pointer, point to the actual finishMessage function. 176 */ 177 FinishReportFuncPtr finishReport = nullptr; 178 179 /** 180 * data encoding method, true is protobuf, false is protoencoder, default is true for UT. 181 */ 182 bool isProtobufSerialize = true; 183 }; 184 185 /** 186 * @brief : register writer interface type 187 * @param : writer, writer pointer 188 * @return : Return 0 for success and -1 for failure 189 */ 190 typedef int (*RegisterWriterStructCallback)(const WriterStruct* writer); 191 192 /** 193 * PluginModuleCallbacks : type forward declaration 194 */ 195 typedef struct PluginModuleCallbacks PluginModuleCallbacks; 196 197 /** 198 * @brief Plugin callback function table 199 */ 200 struct PluginModuleCallbacks { 201 /** 202 * Session start callback 203 */ 204 PluginSessionStartCallback onPluginSessionStart; 205 206 /** 207 * Data reporting callback and it is used to connect the 208 * polling reporting results of plugin management framework. 209 */ 210 PluginReportResultCallback onPluginReportResult; 211 212 /** 213 * Session stop callback 214 */ 215 PluginSessionStopCallback onPluginSessionStop; 216 217 /** 218 * Register the writer callback, which is used to connect the 219 * flow reporting results of plugin management framework 220 */ 221 RegisterWriterStructCallback onRegisterWriterStruct; 222 223 /** 224 * report plugin basic data 225 */ 226 PluginReportBasicDataCallback onReportBasicDataCallback = 0; 227 228 /** 229 * Data reporting callback optimized and it is used to connect the 230 * polling reporting results of plugin management framework. 231 */ 232 PluginReportResultOptimizeCallback onPluginReportResultOptimize; 233 }; 234 235 /** 236 * @brief The maximum length of the plugin name and it does not contain the ending character(\0) 237 */ 238 #define PLUGIN_MODULE_NAME_MAX 127 239 240 /** 241 * @brief The maximum length of the plugin version and it does not contain the ending character(\0) 242 */ 243 #define PLUGIN_MODULE_VERSION_MAX 7 244 245 /** 246 * PluginModuleStruct type forward declaration 247 */ 248 typedef struct PluginModuleStruct PluginModuleStruct; 249 250 struct PluginModuleStruct { 251 /** 252 * Callback function table 253 */ 254 PluginModuleCallbacks* callbacks; 255 256 /** 257 * Plugin name 258 */ 259 char name[PLUGIN_MODULE_NAME_MAX + 1]; 260 261 /** 262 * Plugin version 263 */ 264 char version[PLUGIN_MODULE_VERSION_MAX + 1]; 265 266 /** 267 * (polling type needed)result buffer byte number prompt, used to prompt the plugin management 268 * module to call the data reporting interface to use the memory buffer byte number 269 */ 270 uint32_t resultBufferSizeHint; 271 272 bool isStandaloneFileData = false; 273 274 char outFileName[PATH_MAX + 1]; 275 }; 276 277 /** 278 * Plugin module registration information； 279 280 * The plugin management module will search the symbol from the dynamic object file according to the name, 281 * and then retrieve the basic information and callback function table. 282 * 283 * If Callback function table of onPluginReportResult is filled with non null values, 284 * the plugin will be regarded as a "polling" plugin by the plugin management framework, 285 * and the management framework will call this interface in the module regularly. 286 287 * If Callback function table of onRegisterWriterStruct is filled with non null values, 288 * The plugin will be regarded as a "streaming" plugin by the plugin management framework, 289 * and the management framework will not call this interface in the module regularly. 290 291 * The plugin module needs to save the writer pointer when the onregisterwriterstruct interface is called, 292 * and create a thread when the onpluginsessionstart interface is called; 293 294 * At the right time, the thread calls the writer's write() interface to write data to 295 * the shared memory area, and calls the writer's flush (); 296 297 * The interface notifies the service process to take the data from the shared memory area. 298 */ 299 extern PluginModuleStruct g_pluginModule; 300 301 #ifdef __cplusplus 302 } 303 #endif 304 305 #endif // PLUGIN_MODULE_API_H 306