KiCad PCB EDA Suite
pluginldr.cpp
Go to the documentation of this file.
1/*
2 * This program source code file is part of KiCad, a free EDA CAD application.
3 *
4 * Copyright (C) 2015-2016 Cirilo Bernardo <[email protected]>
5 * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors.
6 *
7 * This program is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU General Public License
9 * as published by the Free Software Foundation; either version 2
10 * of the License, or (at your option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, you may find one here:
19 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
20 * or you may search the http://www.gnu.org website for the version 2 license,
21 * or you may write to the Free Software Foundation, Inc.,
22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
23 */
24
25#include <iostream>
26#include <sstream>
27#include <wx/dynload.h>
28#include <wx/log.h>
29#include <wx/string.h>
30#include <wx/translation.h>
31
32#include "pluginldr.h"
33
34
40const wxChar* const tracePluginLoader = wxT( "KICAD_PLUGIN_LOADER" );
41
42
44{
45 ok = false;
46 m_getPluginClass = nullptr;
47 m_getClassVersion = nullptr;
48 m_checkClassVersion = nullptr;
49 m_getPluginName = nullptr;
50 m_getVersion = nullptr;
51
52 return;
53}
54
55
57{
58 close();
59 return;
60}
61
62
63bool KICAD_PLUGIN_LDR::open( const wxString& aFullFileName, const char* aPluginClass )
64{
65 m_error.clear();
66
67 if( ok )
68 Close();
69
70 if( aFullFileName.empty() )
71 return false;
72
73 m_fileName.clear();
74
75 m_PluginLoader.Load( aFullFileName, wxDL_LAZY );
76
77 if( !m_PluginLoader.IsLoaded() )
78 {
79 wxLogTrace( tracePluginLoader, wxT( " * could not open file: '%s'" ),
80 aFullFileName.ToUTF8() );
81
82 return false;
83 }
84
85 LINK_ITEM( m_getPluginClass, GET_PLUGIN_CLASS, "GetKicadPluginClass" );
86 LINK_ITEM( m_getClassVersion, GET_CLASS_VERSION, "GetClassVersion" );
87 LINK_ITEM( m_checkClassVersion, CHECK_CLASS_VERSION , "CheckClassVersion" );
88 LINK_ITEM( m_getPluginName, GET_PLUGIN_NAME, "GetKicadPluginName" );
89 LINK_ITEM( m_getVersion, GET_VERSION, "GetPluginVersion" );
90
91#ifdef DEBUG
92 bool fail = false;
93
94 if( !m_getPluginClass )
95 {
96 wxLogTrace( tracePluginLoader,
97 wxT( "%s:%s:%d\n"
98 "incompatible plugin (missing function 'GetKicadPluginClass')" ),
99 __FILE__, __FUNCTION__, __LINE__ );
100
101 fail = true;
102 }
103
104 if( !m_getClassVersion )
105 {
106 if( !fail )
107 {
108 wxLogTrace( tracePluginLoader,
109 wxT( "%s:%s:%d\n"
110 "incompatible plugin (missing function 'GetClassVersion')" ),
111 __FILE__, __FUNCTION__, __LINE__ );
112 fail = true;
113 }
114 else
115 {
116 wxLogTrace( tracePluginLoader, wxT( "missing function 'GetClassVersion'" ) );
117 }
118 }
119
121 {
122 if( !fail )
123 {
124 wxLogTrace( tracePluginLoader,
125 wxT( "%s:%s:%d\n"
126 "incompatible plugin (missing function 'CheckClassVersion')" ),
127 __FILE__, __FUNCTION__, __LINE__ );
128
129 fail = true;
130 }
131 else
132 {
133 wxLogTrace( tracePluginLoader, wxT( "missing function 'CheckClassVersion'" ) );
134 }
135 }
136
137 if( !m_getPluginName )
138 {
139 if( !fail )
140 {
141 wxLogTrace( tracePluginLoader,
142 wxT( "%s:%s:%d\n"
143 "incompatible plugin (missing function 'GetKicadPluginName')" ),
144 __FILE__, __FUNCTION__, __LINE__ );
145
146 fail = true;
147 }
148 else
149 {
150 wxLogTrace( tracePluginLoader, wxT( "missing function 'GetKicadPluginName'" ) );
151 }
152 }
153
154 if( !m_getVersion )
155 {
156 if( !fail )
157 {
158 wxLogTrace( tracePluginLoader,
159 wxT( "%s:%s:%d\n"
160 "incompatible plugin (missing function 'GetVersion')" ),
161 __FILE__, __FUNCTION__, __LINE__ );
162 }
163 else
164 {
165 wxLogTrace( tracePluginLoader, wxT( "missing function 'GetVersion'" ) );
166 }
167 }
168
169#endif
170
173 {
174 m_error = "incompatible plugin interface (missing functions)";
175 close();
176 return false;
177 }
178
179 // note: since 'ok' is not yet set at this point we must use the function
180 // pointers directly rather than invoking the functions exposed by this class
181
182 // check that the Plugin Class matches
183 char const* pclassName = m_getPluginClass();
184
185 if( !pclassName || strcmp( aPluginClass, pclassName ) )
186 {
187 m_error = "Loader type (";
188 m_error.append( aPluginClass );
189 m_error.append( ") does not match Plugin type (" );
190
191 if( pclassName )
192 m_error.append( pclassName );
193 else
194 m_error.append( "nullptr" );
195
196 m_error.append( ")" );
197
198 close();
199 return false;
200 }
201
202 // perform a universally enforced version check (major number must match)
203 unsigned char lMajor;
204 unsigned char lMinor;
205 unsigned char lPatch;
206 unsigned char lRevno;
207 unsigned char pMajor;
208 unsigned char pMinor;
209 unsigned char pPatch;
210 unsigned char pRevno;
211
212 m_getClassVersion( &pMajor, &pMinor, &pPatch, &pRevno );
213 GetLoaderVersion( &lMajor, &lMinor, &lPatch, &lRevno );
214
215 // major version changes by definition are incompatible and that is enforced here.
216 if( pMajor != lMajor )
217 {
218 std::ostringstream ostr;
219 ostr << "Loader Major version (" << lMajor;
220 ostr << ") does not match Plugin Major version (" << pMajor << ")";
221
222 m_error = ostr.str();
223 close();
224 return false;
225 }
226
227 if( !m_checkClassVersion( lMajor, lMinor, lPatch, lRevno ) )
228 {
229 std::ostringstream ostr;
230 ostr << "Plugin Version (" << pMajor << "." << pMinor << "." << pPatch << "." << pRevno;
231 ostr << ") does not support Loader Version (" << pMajor << "." << pMinor;
232 ostr << "." << pPatch << "." << pRevno << ")";
233
234 m_error = ostr.str();
235 close();
236 return false;
237 }
238
239 m_fileName = aFullFileName;
240
241 wxLogTrace( tracePluginLoader,
242 wxT( "%s:%s:%d\n"
243 " * [INFO] opened plugin '%s'" ),
244 __FILE__, __FUNCTION__, __LINE__, m_fileName );
245
246 ok = true;
247
248 // set the plugin info string
250 std::ostringstream ostr;
251 unsigned char r0, r1, r2, r3;
252 GetVersion( &r0, &r1, &r2, &r3 );
253 ostr << ":" << (unsigned int)r0 << "." << (unsigned int)r1;
254 ostr << "." << (unsigned int)r2 << "." << (unsigned int)r3;
255 m_pluginInfo.append( ostr.str() );
256
257 return true;
258}
259
260
262{
263 ok = false;
264 m_getPluginClass = nullptr;
265 m_getClassVersion = nullptr;
266 m_checkClassVersion = nullptr;
267 m_getPluginName = nullptr;
268 m_getVersion = nullptr;
269 m_PluginLoader.Unload();
270
271 return;
272}
273
274
276{
277 m_error.clear();
278
279 if( m_fileName.empty() )
280 return false;
281
282 wxString fname = m_fileName;
283
284 return Open( fname );
285}
286
287
288std::string KICAD_PLUGIN_LDR::GetLastError( void ) const
289{
290 return m_error;
291}
292
293
295{
296 m_error.clear();
297
298 if( !ok && !reopen() )
299 {
300 if( m_error.empty() )
301 m_error = "[INFO] no open plugin / plugin could not be opened";
302
303 return nullptr;
304 }
305
306 if( nullptr == m_getPluginClass )
307 {
308 m_error = "[BUG] GetPluginClass is not linked";
309
310 wxLogTrace( tracePluginLoader, wxT( "%s:%s:%d\n"
311 "%s" ),
312 __FILE__, __FUNCTION__, __LINE__, m_error );;
313
314 return nullptr;
315 }
316
317 return m_getPluginClass();
318}
319
320
321bool KICAD_PLUGIN_LDR::GetClassVersion( unsigned char* Major, unsigned char* Minor,
322 unsigned char* Patch, unsigned char* Revision )
323{
324 m_error.clear();
325
326 if( Major )
327 *Major = 0;
328
329 if( Minor )
330 *Minor = 0;
331
332 if( Patch )
333 *Patch = 0;
334
335 if( Revision )
336 *Revision = 0;
337
338 unsigned char major;
339 unsigned char minor;
340 unsigned char patch;
341 unsigned char revno;
342
343 if( !ok && !reopen() )
344 {
345 if( m_error.empty() )
346 m_error = "[INFO] no open plugin / plugin could not be opened";
347
348 return false;
349 }
350
351 if( nullptr == m_checkClassVersion )
352 {
353 m_error = "[BUG] CheckClassVersion is not linked";
354
355 wxLogTrace( tracePluginLoader, wxT( "%s:%s:%d\n"
356 "%s" ),
357 __FILE__, __FUNCTION__, __LINE__, m_error );;
358
359 return false;
360 }
361
362 m_getClassVersion( &major, &minor, &patch, &revno );
363
364 if( Major )
365 *Major = major;
366
367 if( Minor )
368 *Minor = minor;
369
370 if( Patch )
371 *Patch = patch;
372
373 if( Revision )
374 *Revision = revno;
375
376 return true;
377}
378
379
380bool KICAD_PLUGIN_LDR::CheckClassVersion( unsigned char Major, unsigned char Minor,
381 unsigned char Patch, unsigned char Revision )
382{
383 m_error.clear();
384
385 if( !ok && !reopen() )
386 {
387 if( m_error.empty() )
388 m_error = "[INFO] no open plugin / plugin could not be opened";
389
390 return false;
391 }
392
393 if( nullptr == m_checkClassVersion )
394 {
395 m_error = "[BUG] CheckClassVersion is not linked";
396
397 wxLogTrace( tracePluginLoader, wxT( "%s:%s:%d\n"
398 "%s" ),
399 __FILE__, __FUNCTION__, __LINE__, m_error );;
400
401 return false;
402 }
403
404 return m_checkClassVersion( Major, Minor, Patch, Revision );
405}
406
407
409{
410 m_error.clear();
411
412 if( !ok && !reopen() )
413 {
414 if( m_error.empty() )
415 m_error = "[INFO] no open plugin / plugin could not be opened";
416
417 return nullptr;
418 }
419
420 if( nullptr == m_getPluginName )
421 {
422 m_error = "[BUG] GetKicadPluginName is not linked";
423
424 wxLogTrace( tracePluginLoader, wxT( "%s:%s:%d\n"
425 "%s" ),
426 __FILE__, __FUNCTION__, __LINE__, m_error );;
427
428 return nullptr;
429 }
430
431 return m_getPluginName();
432}
433
434
435bool KICAD_PLUGIN_LDR::GetVersion( unsigned char* Major, unsigned char* Minor,
436 unsigned char* Patch, unsigned char* Revision )
437{
438 m_error.clear();
439
440 if( !ok && !reopen() )
441 {
442 if( m_error.empty() )
443 m_error = "[INFO] no open plugin / plugin could not be opened";
444
445 return false;
446 }
447
448 if( nullptr == m_getVersion )
449 {
450 m_error = "[BUG] GetKicadPluginName is not linked";
451
452 wxLogTrace( tracePluginLoader, wxT( "%s:%s:%d\n"
453 "%s" ),
454 __FILE__, __FUNCTION__, __LINE__, m_error );;
455
456 return false;
457 }
458
459 m_getVersion( Major, Minor, Patch, Revision );
460
461 return true;
462}
463
464
465void KICAD_PLUGIN_LDR::GetPluginInfo( std::string& aPluginInfo )
466{
467 aPluginInfo = m_pluginInfo;
468}
virtual void GetLoaderVersion(unsigned char *Major, unsigned char *Minor, unsigned char *Patch, unsigned char *Revision) const =0
Return the version information of the Plugin Loader for plugin compatibility checking.
CHECK_CLASS_VERSION m_checkClassVersion
Definition: pluginldr.h:143
std::string GetLastError(void) const
Return the value of the internal error string.
Definition: pluginldr.cpp:288
char const * GetKicadPluginClass(void)
Definition: pluginldr.cpp:294
GET_PLUGIN_CLASS m_getPluginClass
Definition: pluginldr.h:141
GET_CLASS_VERSION m_getClassVersion
Definition: pluginldr.h:142
GET_VERSION m_getVersion
Definition: pluginldr.h:145
std::string m_pluginInfo
Definition: pluginldr.h:147
virtual void Close(void)=0
Clean up and closes/unloads the plugin.
virtual bool Open(const wxString &aFullFileName)=0
Open a plugin of the given class, performs version compatibility checks, and links all required funct...
bool CheckClassVersion(unsigned char Major, unsigned char Minor, unsigned char Patch, unsigned char Revision)
Definition: pluginldr.cpp:380
GET_PLUGIN_NAME m_getPluginName
Definition: pluginldr.h:144
void GetPluginInfo(std::string &aPluginInfo)
Definition: pluginldr.cpp:465
bool open(const wxString &aFullFileName, const char *aPluginClass)
Open a plugin of the specified class and links the extensions required by kicad_plugin.
Definition: pluginldr.cpp:63
bool GetClassVersion(unsigned char *Major, unsigned char *Minor, unsigned char *Patch, unsigned char *Revision)
Definition: pluginldr.cpp:321
wxDynamicLibrary m_PluginLoader
Definition: pluginldr.h:137
bool GetVersion(unsigned char *Major, unsigned char *Minor, unsigned char *Patch, unsigned char *Revision)
Definition: pluginldr.cpp:435
const char * GetKicadPluginName(void)
Definition: pluginldr.cpp:408
std::string m_error
Definition: pluginldr.h:134
virtual ~KICAD_PLUGIN_LDR()
Definition: pluginldr.cpp:56
void close(void)
Nullify internal pointers in preparation for closing the plugin.
Definition: pluginldr.cpp:261
wxString m_fileName
Definition: pluginldr.h:146
bool reopen(void)
Reopen a plugin.
Definition: pluginldr.cpp:275
const wxChar *const tracePluginLoader
Flag to enable plugin loader trace output.
Definition: pluginldr.cpp:40
defines the most basic functions which all kicad plugin loaders require.
void(* GET_VERSION)(unsigned char *, unsigned char *, unsigned char *, unsigned char *)
Definition: pluginldr.h:59
void(* GET_CLASS_VERSION)(unsigned char *, unsigned char *, unsigned char *, unsigned char *)
Definition: pluginldr.h:51
bool(* CHECK_CLASS_VERSION)(unsigned char, unsigned char, unsigned char, unsigned char)
Definition: pluginldr.h:54
char const *(* GET_PLUGIN_CLASS)(void)
Definition: pluginldr.h:49
const char *(* GET_PLUGIN_NAME)(void)
Definition: pluginldr.h:57
#define LINK_ITEM(funcPtr, funcType, funcName)
Definition: pluginldr.h:45