1 /* 2 * Copyright (c) 2021 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 PLUGIN_MODULE_API_H 17 #define PLUGIN_MODULE_API_H 18 19 #include <stdbool.h> 20 #include <stddef.h> 21 #include <stdint.h> 22 #include <climits> 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 /** 29 * @brief interface type of plugin session starting 30 * 31 * It will be called when the plugin session starts, and the binary data pointed 32 * by the parameter is the protobuffer binary data filled by the IDE side; 33 * 34 * The implementation part —— need to call the deserialization code generated by 35 * protobuffer to restore it to the data type generated by proto; 36 * 37 * For the third-party developers, you can also not use the protobuffer as a 38 * serialization tool, only need to adapt to the Java code. 39 * 40 * @param ConfigData configure the starting address of information memory block 41 * @param ConfigSize configure the byte counts of information memory block 42 * @return Return 0 for success and -1 for failure 43 */ 44 typedef int (*PluginSessionStartCallback)(const uint8_t* configData, uint32_t configSize); 45 46 /** 47 * @brief interface type of Plugin result reporting interface type 48 * The incoming memory block is a large memory pre allocated by the plugin management module, 49 * The implementation part —— need to define the specific result type object of proto and serialize it to this memory, 50 * The framework will transfer the original data to the PC as it is. 51 * @param bufferData: the starting address of the memory buffer where the result is stored 52 * @param bufferSize: The byte counts in the memory buffer where the result is stored 53 * @return The return value greater than 0 indicates the number of bytes filled in memory, 54 * and 0 indicates that nothing is filled, 55 * return value less than 0 indicates failure, and -1 is a general error 56 * If the absolute value of the return value is greater than buffersize, the number of bytes in the buffer 57 * is insufficient to store the result. The framework will try to get the result again with a larger cache. 58 */ 59 typedef int (*PluginReportResultCallback)(uint8_t* bufferData, uint32_t bufferSize); 60 61 /** 62 * @brief interface type of plugin session stop, 63 * Called when stopping plugin sessions 64 * @return Return 0 for success and -1 for failure. 65 */ 66 typedef int (*PluginSessionStopCallback)(void); 67 68 /** 69 * @brief interface type of plugin session stop, 70 * Called when stopping plugin sessions 71 * @return Return 0 for success and -1 for failure. 72 */ 73 typedef int (*PluginReportBasicDataCallback)(void); 74 75 /** 76 * WriterStruct type forward declaration 77 */ 78 typedef struct WriterStruct WriterStruct; 79 80 /** 81 * @brief write : interface type 82 * @param writer : pointer 83 * @param data : the first byte pointer of data buffer 84 * @param size : The byte counts in the data buffer 85 * @return : Return the number of bytes written for success, and returns -1 for failure 86 */ 87 typedef long (*WriteFuncPtr)(WriterStruct* writer, const void* data, size_t size); 88 89 /** 90 * @brief flush : interface type 91 * @return Return true for success and false for failure； 92 */ 93 typedef bool (*FlushFuncPtr)(WriterStruct* writer); 94 95 /** 96 * WriterStruct : type definition, containing two function pointers. 97 */ 98 struct WriterStruct { 99 /** 100 * write : function pointer,point to the actual write function. 101 */ 102 WriteFuncPtr write; 103 104 /** 105 * flush function pointer,point to the actual flush function. 106 */ 107 FlushFuncPtr flush; 108 }; 109 110 /** 111 * @brief : register writer interface type 112 * @param : writer, writer pointer 113 * @return : Return 0 for success and -1 for failure 114 */ 115 typedef int (*RegisterWriterStructCallback)(const WriterStruct* writer); 116 117 /** 118 * PluginModuleCallbacks : type forward declaration 119 */ 120 typedef struct PluginModuleCallbacks PluginModuleCallbacks; 121 122 /** 123 * @brief Plugin callback function table 124 */ 125 struct PluginModuleCallbacks { 126 /** 127 * Session start callback 128 */ 129 PluginSessionStartCallback onPluginSessionStart; 130 131 /** 132 * Data reporting callback and it is used to connect the 133 * polling reporting results of plugin management framework. 134 */ 135 PluginReportResultCallback onPluginReportResult; 136 137 /** 138 * Session stop callback 139 */ 140 PluginSessionStopCallback onPluginSessionStop; 141 142 /** 143 * Register the writer callback, which is used to connect the 144 * flow reporting results of plugin management framework 145 */ 146 RegisterWriterStructCallback onRegisterWriterStruct; 147 148 /** 149 * report plugin basic data 150 */ 151 PluginReportBasicDataCallback onReportBasicDataCallback = 0; 152 }; 153 154 /** 155 * @brief The maximum length of the plugin name and it does not contain the ending character(\0) 156 */ 157 #define PLUGIN_MODULE_NAME_MAX 127 158 159 /** 160 * @brief The maximum length of the plugin version and it does not contain the ending character(\0) 161 */ 162 #define PLUGIN_MODULE_VERSION_MAX 7 163 164 /** 165 * PluginModuleStruct type forward declaration 166 */ 167 typedef struct PluginModuleStruct PluginModuleStruct; 168 169 struct PluginModuleStruct { 170 /** 171 * Callback function table 172 */ 173 PluginModuleCallbacks* callbacks; 174 175 /** 176 * Plugin name 177 */ 178 char name[PLUGIN_MODULE_NAME_MAX + 1]; 179 180 /** 181 * Plugin version 182 */ 183 char version[PLUGIN_MODULE_VERSION_MAX + 1]; 184 185 /** 186 * (polling type needed)result buffer byte number prompt, used to prompt the plugin management 187 * module to call the data reporting interface to use the memory buffer byte number 188 */ 189 uint32_t resultBufferSizeHint; 190 191 bool isStandaloneFileData = false; 192 193 char outFileName[PATH_MAX + 1]; 194 }; 195 196 /** 197 * Plugin module registration information； 198 199 * The plugin management module will search the symbol from the dynamic object file according to the name, 200 * and then retrieve the basic information and callback function table. 201 * 202 * If Callback function table of onPluginReportResult is filled with non null values, 203 * the plugin will be regarded as a "polling" plugin by the plugin management framework, 204 * and the management framework will call this interface in the module regularly. 205 206 * If Callback function table of onRegisterWriterStruct is filled with non null values, 207 * The plugin will be regarded as a "streaming" plugin by the plugin management framework, 208 * and the management framework will not call this interface in the module regularly. 209 210 * The plugin module needs to save the writer pointer when the onregisterwriterstruct interface is called, 211 * and create a thread when the onpluginsessionstart interface is called; 212 213 * At the right time, the thread calls the writer's write() interface to write data to 214 * the shared memory area, and calls the writer's flush (); 215 216 * The interface notifies the service process to take the data from the shared memory area. 217 */ 218 extern PluginModuleStruct g_pluginModule; 219 220 #ifdef __cplusplus 221 } 222 #endif 223 224 #endif // PLUGIN_MODULE_API_H 225