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 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /** 28 * @brief interface type of plug-in session starting 29 * 30 * It will be called when the plug-in 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 Plug-in result reporting interface type 47 * The incoming memory block is a large memory pre allocated by the plug-in 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 /** 61 * @brief interface type of plug-in session stop, 62 * Called when stopping plug-in sessions 63 * @return Return 0 for success and - 1 for failure； 64 */ 65 typedef int (*PluginSessionStopCallback)(); 66 67 /** 68 * WriterStruct type forward declaration 69 */ 70 typedef struct WriterStruct WriterStruct; 71 72 /** 73 * @brief write : interface type 74 * @param writer : pointer 75 * @param data : the first byte pointer of data buffer 76 * @param size : The byte counts in the data buffer 77 * @return : Return the number of bytes written for success, and returns - 1 for failure 78 */ 79 typedef long (*WriteFuncPtr)(WriterStruct* writer, const void* data, size_t size); 80 81 /** 82 * @brief flush : interface type 83 * @return Return true for success and false for failure； 84 */ 85 typedef bool (*FlushFuncPtr)(WriterStruct* writer); 86 87 /** 88 * WriterStruct : type definition, containing two function pointers； 89 */ 90 struct WriterStruct { 91 /** 92 * write : function pointer,point to the actual write function; 93 */ 94 WriteFuncPtr write; 95 96 /** 97 * flush function pointer,point to the actual flush function; 98 */ 99 FlushFuncPtr flush; 100 }; 101 102 /** 103 * @brief : register writer interface type 104 * @param : writer, writer pointer 105 * @return : Return 0 for success and - 1 for failure 106 */ 107 typedef int (*RegisterWriterStructCallback)(const WriterStruct* writer); 108 109 /** 110 * PluginModuleCallbacks : type forward declaration 111 */ 112 typedef struct PluginModuleCallbacks PluginModuleCallbacks; 113 114 /** 115 * @brief Plug-in callback function table 116 */ 117 struct PluginModuleCallbacks { 118 /** 119 * Session start callback 120 */ 121 PluginSessionStartCallback onPluginSessionStart; 122 123 /** 124 * Data reporting callback and it is used to connect the 125 * polling reporting results of plug-in management framework， 126 */ 127 PluginReportResultCallback onPluginReportResult; 128 129 /** 130 * Session stop callback 131 */ 132 PluginSessionStopCallback onPluginSessionStop; 133 134 /** 135 * Register the writer callback, which is used to connect the 136 * flow reporting results of plug-in management framework 137 */ 138 RegisterWriterStructCallback onRegisterWriterStruct; 139 }; 140 141 /** 142 * @brief The maximum length of the plug-in name and it does not contain the ending character(\0) 143 */ 144 #define PLUGIN_MODULE_NAME_MAX 127 145 146 /** 147 * PluginModuleStruct type forward declaration 148 */ 149 typedef struct PluginModuleStruct PluginModuleStruct; 150 151 struct PluginModuleStruct { 152 /** 153 * Callback function table 154 */ 155 PluginModuleCallbacks* callbacks; 156 157 /** 158 * Plug-in name 159 */ 160 char name[PLUGIN_MODULE_NAME_MAX + 1]; 161 162 /** 163 * (polling type needed)result buffer byte number prompt, used to prompt the plug-in management 164 * module to call the data reporting interface to use the memory buffer byte number 165 */ 166 uint32_t resultBufferSizeHint; 167 }; 168 169 /** 170 * Plug-in module registration information； 171 172 * The plug-in management module will search the symbol from the dynamic object file according to the name, 173 * and then retrieve the basic information and callback function table； 174 * 175 * If Callback function table of onPluginReportResult is filled with non null values, 176 * the plug-in will be regarded as a "polling" plug-in by the plug-in management framework, 177 * and the management framework will call this interface in the module regularly。 178 179 * If Callback function table of onRegisterWriterStruct is filled with non null values, 180 * The plug-in will be regarded as a "streaming" plug-in by the plug-in management framework, 181 * and the management framework will not call this interface in the module regularly。 182 183 * The plug-in module needs to save the writer pointer when the onregisterwriterstruct interface is called, 184 * and create a thread when the onpluginsessionstart interface is called; 185 186 * At the right time, the thread calls the writer's write() interface to write data to 187 * the shared memory area, and calls the writer's flush (); 188 189 * The interface notifies the service process to take the data from the shared memory area; 190 */ 191 extern PluginModuleStruct g_pluginModule; 192 193 #ifdef __cplusplus 194 } 195 #endif 196 197 #endif // PLUGIN_MODULE_API_H 198