some updates to the Linux build system - obtained a core binary and all required...
[xonotic/netradiant.git] / libs / synapse.h
1 /*\r
2 Copyright (C) 1999-2007 id Software, Inc. and contributors.\r
3 For a list of contributors, see the accompanying CONTRIBUTORS file.\r
4 \r
5 This file is part of GtkRadiant.\r
6 \r
7 GtkRadiant is free software; you can redistribute it and/or modify\r
8 it under the terms of the GNU General Public License as published by\r
9 the Free Software Foundation; either version 2 of the License, or\r
10 (at your option) any later version.\r
11 \r
12 GtkRadiant is distributed in the hope that it will be useful,\r
13 but WITHOUT ANY WARRANTY; without even the implied warranty of\r
15 GNU General Public License for more details.\r
16 \r
17 You should have received a copy of the GNU General Public License\r
18 along with GtkRadiant; if not, write to the Free Software\r
19 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA\r
20 */\r
21 \r
22 #ifndef __SYNAPSE_H__\r
23 #define __SYNAPSE_H__\r
24 \r
25 /*!\r
26 synapse library\r
27 code and utilities to deal with dynamic components programming\r
28 \r
29 "the point at which a nervous impulse passes from one neuron to another"\r
30 \r
31 dependencies:\r
32   libxml for parsing\r
33   STL for some algorithms and data structures\r
34   glib for Str.h (Str class)\r
35   \r
36 this is a utility library, it provides typical synapse client and server\r
37 could be split into two independant libraries actually, the server part and the client part\r
38 (that's just a matter of reducing binary size)  \r
39 */\r
40 \r
41 // compile time settings\r
42 #ifdef _DEBUG\r
43   #define SYNAPSE_VERBOSE // be verbosive about the loading process\r
44 #endif\r
45 \r
46 // ydnar: required for os x\r
47 #if defined (__APPLE__)\r
48   #include <sys/types.h>\r
49 #endif\r
50 \r
51 #if defined (__linux__) || defined (__APPLE__)\r
52   #include <dlfcn.h>\r
53   #include <dirent.h>  \r
54 #endif\r
55 \r
56 #if defined(_WIN32)\r
57   #include <windows.h>\r
58 #endif\r
59 \r
60 #if defined(_WIN32)\r
62 #elif defined(__linux__) || defined(__APPLE__)  /* ydnar */\r
63 //  #define SYNAPSE_DLL_EXPORT __attribute__ ((visibility ("protected")))\r
64   #define SYNAPSE_DLL_EXPORT\r
65 #else\r
66   #error unknown architecture\r
67 #endif\r
68 \r
69 // NOTE TTimo: VC6 crap, gets confused when some variable names in function declarations\r
70 //   are 'allocator' or 'list'\r
71 //   if you #include glib *after* STL, you get those errors .. better be safe then\r
72 #include <glib.h>\r
73 \r
74 #include "libxml/parser.h"\r
75 \r
76 #include "irefcount.h"\r
77 #include "gtkr_list.h"\r
78 #include "gtkr_vector.h"\r
79 \r
80 #include "str.h"\r
81 \r
82 /*!\r
83 use when API change make things incompatible at synapse level\r
84 i.e. entry point and classes API changes\r
85 */\r
86 #define SYNAPSE_VERSION "3"\r
87 \r
88 /*!\r
89 =======================================================================\r
90 diagnostic printing facility\r
91 independently from any API negociation stuff,\r
92 we need a diagnostic facility that's available at all times\r
93 =======================================================================\r
94 */\r
95 extern "C"\r
96 {\r
97 /*!\r
98 prototype to provide to synapse to redirect the output appropriately  \r
99 */  \r
100 typedef void (* PFN_SYN_PRINTF_VA) (const char *text, va_list args);\r
101 void Set_Syn_Printf(PFN_SYN_PRINTF_VA pf); ///< change the handler, set back to NULL for default\r
102 /*!\r
103 use this for synapse code diagnostics, it will be piped through the handler if necessary\r
104 */\r
105 void Syn_Printf (const char *text, ...);\r
106 };\r
107   \r
108 /*\r
109 =======================================================================\r
110 client\r
111 =======================================================================\r
112 */\r
113 \r
114 /*!\r
115 description of an API:\r
116 a module requires and provides several APIs\r
117 the basic rule is that we will avoid asking an API from a module if the APIs it requires are not filled in yet\r
118 the exception being the 'resolve' operation of a given client, which we 'activate'\r
119 (that is we make the interfaces it provides available, leave the ones it requires unsolved, and try to get back to a stable situation)\r
120 */\r
121 \r
123 \r
124 #define MAX_APINAME 128\r
125 typedef struct APIDescriptor_s\r
126 {\r
127   /*!\r
128   major version, this must be UNIQUE for each API\r
129   NOTE: we used to rely on GUID for this, that was a good solution to make sure we never get conflicts\r
130   but it was a bit overkill, so we dropped and use a string now\r
131   */\r
132   char major_name[MAX_APINAME];\r
133   /*!\r
134   what kind of interface\r
135   for instance for "image" API, "tga" "jpg" etc.\r
136   */\r
137   char minor_name[MAX_APINAME];\r
138   EAPIType mType; ///< is this an API we provide or an API we require\r
139   /*!\r
140   pointer to the table to be filled in\r
141   this is valid for SYN_REQUIRE APIs only\r
142   */\r
143   void *mpTable;\r
144   bool mbTableInitDone; ///< turned to true by the server after the function table has been filled in\r
145   /*!\r
146   gives the size of the expected function table  \r
147   */\r
148   int mSize;\r
149   /*!\r
150   refcounts how many times this API is being used through the app\r
151   this is valid for SYN_PROVIDE APIs only\r
152   */\r
153   int mRefCount;\r
154 } APIDescriptor_t;\r
155 \r
156 typedef struct XMLConfigEntry_s {\r
157   const char *api;\r
158   EAPIType type;\r
159   int size;\r
160   void *pTable;\r
161 } XMLConfigEntry_t;\r
162 \r
163 /*!\r
164 \class CSynapseAPIManager\r
165 derive from this class if you want to manage several APIs through the same object\r
166 (typically, loading plugins, or an unknown number of APIs that match some criterions)\r
167 this class has some pure virtual members that need to be implemented by the childs\r
168 \r
169 we deal with two types of API managers:\r
170 - the 'loose' ones have a matching pattern and load everything that matches criterions\r
171   typically used for plugins\r
172 - the 'list' ones have a fixed list of things they require. They are used to provide\r
173   easy access to multiple interfaces\r
174 \r
175 those two types of managers are not stored in the same structs, and not handled the\r
176 same way. For instance the 'list' manager will require ALL it's APIs to be loaded, or\r
177 the init will fail. They also play a role in the client activation.\r
178 \r
179 apart from the multiple API management facility, the main difference with static tables\r
180 and individual calls to CSynapseClient::AddAPI is the fact that the APIDescriptor_t are\r
181 allocated on demand\r
182 */\r
183 \r
184 /* we do some matching, or store minors list, the strings need to be bigger */\r
185 #define MAX_PATTERN_STRING 512\r
186 \r
187 /*! \enum EAPIManagerType\r
188   \brief type of this manager, loosely matching with "*", or a fixed list of required interfaces\r
189 */\r
190 typedef enum { API_MATCH = 0,  API_LIST } EAPIManagerType;\r
191 \r
192 class CSynapseAPIManager : public IRefCounted\r
193 {\r
194   EAPIManagerType mType;\r
195   \r
196   // the list of APIs we have obtained (SYN_REQUIRE_ANY)\r
197   vector< APIDescriptor_t * > mAPIs;\r
198   /*!\r
199   pattern for matching the major version\r
200   NOTE: only supported for now: exact match\r
201   */\r
202   char major_pattern[MAX_PATTERN_STRING];\r
203   /*!\r
204   pattern for matching the minor\r
205   */\r
206   char minor_pattern[MAX_PATTERN_STRING];  \r
207   \r
208 public:\r
209   CSynapseAPIManager() { mType = API_MATCH; }\r
210   virtual ~CSynapseAPIManager();\r
211 \r
212   EAPIManagerType GetType() { return mType; }\r
213   void SetType(EAPIManagerType type) { mType = type; }\r
214   \r
215   /*!\r
216   set the API matching pattern\r
217   supported syntax:\r
218   any minor for a given major, for instance: PLUGIN_MAJOR, "*"\r
219   a space seperated list of minors for a given major: IMAGE_MAJOR, "tga jpg"\r
220   */\r
221   void SetMatchAPI(const char *major, const char *minor);\r
222   \r
223   /*!\r
224   utility function\r
225   start building a SYN_REQUIRE_ANY descriptor from a SYN_PROVIDE interface that we found matching\r
226   */\r
227   static APIDescriptor_t* PrepareRequireAPI(APIDescriptor_t *pAPI);  \r
228   \r
229   /*!\r
230   for managers that require a fixed list of things, we are not active until everything has been loaded up\r
231   managers that work on a loose pattern like "*" are always active (since they don't know what they want for sure)\r
232   */\r
233   bool CheckSetActive();\r
234   \r
235   /*!\r
236   the manager answers wether it wants to load this or not\r
237   we provide a default implementation, but this can be completely overriden if needed\r
238   see SetMatchAPI for the documentation of the default implementation\r
239   NOTE: this should only be called on API_MATCH type of managers\r
240   */\r
241   virtual bool MatchAPI(const char *major, const char *minor);\r
242   \r
243   /*!\r
244   build an APIDescriptor_t configured as SYN_REQUIRE_ANY from the SYN_PROVIDE API we found\r
245   used when we scan the available interfaces for a match that would be interesting to this manager\r
246   NOTE: only for API_MATCH managers\r
247   */\r
248   virtual APIDescriptor_t *BuildRequireAPI(APIDescriptor_t *pAPI) { return NULL; }\r
249   \r
250   /*!\r
251   below is relevant to API_LIST only ---------------------------------------------------------------------\r
252   */\r
253 \r
254   /*!\r
255   fill in the table info to this descriptor, store it as a new slot\r
256   NOTE: only for API_LIST\r
257   */\r
258   virtual void FillAPITable(APIDescriptor_t *pAPI) { }\r
259   \r
260   /*!\r
261   initialize the list of APIDescriptor_t* with all the stuff we expect\r
262   */\r
263   void InitializeAPIList();\r
264   \r
265   /*!\r
266   access the API descriptors\r
267   */\r
268   int GetAPICount();\r
269   APIDescriptor_t *GetAPI(int);\r
270 };\r
271 \r
272 /*!\r
273 \class CSynapseClient\r
274 */\r
275 class CSynapseServer; // forward declare\r
276 class CSynapseClient : public IRefCounted\r
277 {\r
278   /*!\r
279   this flag indicates wether this client is active\r
280   i.e. wether you can ask it for interfaces\r
281   this is either a client for which all required interfaces have been filled in\r
282   or a client we are trying to resolve (i.e. load with all it's stuff)\r
283   */\r
284   bool mbActive;\r
285   \r
286   /*!\r
287   we store APIDescriptor_t*, the module fills that in at startup\r
288   */\r
289   vector<APIDescriptor_t *> mAPIDescriptors;\r
290   \r
291   /*!\r
292   managers for multiple APIs management\r
293   mManagersMatch are managers with loose matching / undefined number of APIs\r
294   mManagersList are managers with a fixed list of required interfaces\r
295   */\r
296   vector<CSynapseAPIManager *> mManagersMatch;\r
297   vector<CSynapseAPIManager *> mManagersList;\r
298   \r
299 protected:\r
300   friend class CSynapseServer;\r
301   /*!\r
302   use of this is restricted to the server, expecting it knows what it is doing\r
303   will make the client we are trying to resolve able to provide interfaces even though all interfaces it requires have not been filled in yet.\r
304   */\r
305   void ForceSetActive() { mbActive = true; }\r
306   \r
307 public:\r
308   CSynapseClient();\r
309   virtual ~CSynapseClient();\r
310 \r
311   int GetAPICount(); ///< returns the number of APIs that this module provides\r
312   APIDescriptor_t* GetAPIDescriptor(int); ///< retrieve specific information about on of the APIs\r
313 \r
314   /*!\r
315   Add the API to the CSynapseClient information\r
316   \r
317   \param minor\r
318   minor can be NULL, some APIs don't need to have a 'minor' description  \r
319   \r
320   \param type\r
321   SYN_PROVIDE: means this is an API we provide if anyone needs it\r
322   SYN_REQUIRE: means this is an API we will require for operation\r
323   SYN_REQUIRE_ANY: means this is an API we want to load *any* minor found\r
324      (for instance a list of image fornats, or the plugins)\r
325      \r
326   \param pTable \r
327   the function table\r
328   only valid for SYN_REQUIRE APIs\r
329   \r
330   \param size\r
331   the size of the function table\r
332   if SYN_REQUIRE, you should set the size in pTable and AddAPI will work it out\r
333   if SYN_PROVIDE, you need to provide this parameter\r
334   \r
335   returns a bool:\r
336   operation may fail, since we have a few safe checks  \r
337   */\r
338   bool AddAPI(const char *major, const char *minor = NULL, int size = 0, EAPIType type = SYN_PROVIDE, void *pTable = NULL);\r
339   \r
340   /*!\r
341   Add an API manager to the client\r
342   this class is designed to handle multiple APIs\r
343   is not memory managed by CSynapseClient (should it? or ref counted maybe?)\r
344   writing it with support for multiple managers, that may be a bit overkill right now\r
345   */\r
346   void AddManager(CSynapseAPIManager *pManager);\r
347   \r
348   int GetManagerMatchCount(); ///< how many API managers\r
349   CSynapseAPIManager* GetManagerMatch(int); ///< get corresponding API manager\r
350 \r
351   int GetManagerListCount(); ///< how many API managers\r
352   CSynapseAPIManager* GetManagerList(int); ///< get corresponding API manager\r
353   \r
354   /*!\r
355   each client has to implement this function itself\r
356   it will fill in the function table\r
357   and increment the ref counting in it's own SYN_PROVIDE descriptor\r
358   returns a bool, false if you ask for an API that's not available\r
359   */\r
360   virtual bool RequestAPI(APIDescriptor_t *pAPI) = 0;\r
361   \r
362   /*!\r
363   return the build date, can be overriden by client module\r
364   */\r
365   virtual const char* GetInfo();\r
366   \r
367   /*!\r
368   \brief a shirt name to identify the client\r
369   we use this string to identify individual clients, for instance when some XML configuration nodes are required\r
370   should be unique, the synapse server should't accept multiple occurences?  \r
371   */\r
372   virtual const char* GetName() { return ""; }\r
373   \r
374   bool IsActive() { return mbActive; }\r
375   /*!\r
376   check wether all interfaces have been filled in\r
377   in which case we will switch to 'activated' state, that is this client can provide interfaces to others now\r
378   */\r
379   bool CheckSetActive();\r
380   \r
381   /*!\r
382   \brief called when the client is being shutdown, before the dlclose happens\r
383   this is the last call before the dlclose, there's no turning back\r
384   just do what you have to do before you die.. decref and stuff\r
385   */\r
386   void Shutdown();\r
387   \r
388   /*!\r
389   override this one in clients that need to proceed through some init steps when activated\r
390   if returning false, the init will abort\r
391   */\r
392   virtual bool OnActivate() { return true; }\r
393   \r
394   /*!\r
395   \brief walk the XML config and initialize from structures\r
396   when you use this function, OnActivate will also make sure all the interfaces listed were properly initialized\r
397   two tables, one for the regular single interface, one for the listings\r
398   need to store for later and check in OnActivate\r
399   \r
400   \param pServer, pass the server to talk to\r
401   NOTE: might want to store it in the class if that's needed too often\r
402   \r
403   \param client_name, the name of the client node to look for. If NULL, use GetName()\r
404   \r
405   \return wether all APIs given were successfully found in the config\r
406   */\r
407   bool ConfigXML( CSynapseServer *pServer, const char *client_name, const XMLConfigEntry_t entries[] );\r
408 };\r
409 \r
410 /*!\r
411 prototype for the only exported function needed in a synapse client\r
412 */\r
413 #define NAME_SYNAPSE_ENUMERATEINTERFACES "Synapse_EnumerateInterfaces"\r
414 \r
415 class CSynapseServer; // forward declare\r
416 typedef CSynapseClient* (SYNAPSE_DLL_EXPORT *PFN_SYNAPSE_ENUMERATEINTERFACES)(const char *version, CSynapseServer *server);\r
417 \r
418 /*!\r
419 a derived version of CSynapseClient that can be used to provide builtin module without having to go through DLLs\r
420 this is useful for things we want to isolate behind an abstract API, but that we feel better about having present at all times (such as .def class loader)\r
421 */\r
422 class CSynapseBuiltinClient : public CSynapseClient\r
423 {\r
424   public:\r
425   CSynapseBuiltinClient() {}\r
426   virtual ~CSynapseBuiltinClient() {}\r
427   \r
428   virtual void EnumerateInterfaces(CSynapseServer *server) = 0;\r
429   \r
430 };\r
431 \r
432 /*\r
433 =======================================================================\r
434 server\r
435 =======================================================================\r
436 */\r
437 \r
438 /*!\r
439   \enum EClientType\r
440   \brief we can have clients that are builtin to a server\r
441 */\r
442 typedef enum { SYN_SO, SYN_BUILTIN } EClientType;\r
443 \r
444 /*!\r
445 server side slot for a synapse client\r
446 is OS dependant, except for the ISynapseClient part\r
447 */\r
448 class CSynapseClientSlot\r
449 {\r
450 public:\r
451   /*!\r
452   \todo cleanup, make that private with accessors\r
453   */\r
454 #if defined(__linux__) || defined(__APPLE__)\r
455   void *mpDLL; ///< handle to the shared object (invalid if SYN_BUILTIN)\r
456 #elif defined(_WIN32)\r
457   HMODULE mpDLL; ///< handle to the shared object (invalid if SYN_BUILTIN)\r
458 #endif\r
459   PFN_SYNAPSE_ENUMERATEINTERFACES mpEnumerate; ///< function pointer to the enumeration entry point (invalid if SYN_BUILTIN)\r
460 \r
461   CSynapseClient *mpClient; ///< the full client API\r
462   Str mFileName; ///< path to the file\r
463   \r
464   EClientType mType;\r
465 \r
466   /*!\r
467   \brief release the shared object. NOTE: OS dependent  \r
468   */\r
469   void ReleaseSO();\r
470   \r
471   CSynapseClientSlot() { mpDLL = NULL; mpEnumerate = NULL; mpClient = NULL; mType = SYN_SO; }\r
472   /*!\r
473   NOTE: the slot is stored as static object, and copy constructors used  \r
474   */\r
475   virtual ~CSynapseClientSlot() { }\r
476 \r
477 };\r
478 \r
479 /*!\r
480 \class CSynapseServer\r
481 dynamic modules manager class\r
482 this class provides the server functionality:\r
483 initialize, get a list of modules, load them, link them together..\r
484 */\r
485 class CSynapseServer : public IRefCounted\r
486 {\r
487   list<char *> mSearchPaths;\r
488   list<CSynapseClientSlot> mClients;\r
489           \r
490   /*!\r
491   used for resolve operations\r
492   */\r
493   list<APIDescriptor_t*> mStack;\r
494   /*!\r
495   set this when mStack is modified with new stuff to resolve\r
496   NOTE: if this hack becomes too tricky to use we could just encapsulate mStack\r
497   */\r
498   bool mbStackChanged;\r
499   \r
500   xmlDocPtr mpDoc;\r
501   xmlNodePtr mpFocusedNode; ///< currently focused node while we are scanning the config (strictly for GetNextConfig usage)\r
502   xmlNodePtr mpCurrentClientConfig;\r
503   /*!\r
504   stores the allocated strings for each call to GetNextConfig\r
505   need to be freed if != NULL\r
506   */\r
507   xmlChar *m_api_name;\r
508   gchar *m_content;\r
509     \r
510   /*!\r
511   push required interfaces for this client into the stack of things to be resolved\r
512   it is possible that several mathing interfaces be in the stack at the same time\r
513   (for instance several modules that want to get the VFS)\r
514   but we should never have the same APIDescriptor_t twice\r
515   NOTE: as this function is called repeatedly during the resolve (because the list of required things is refining),\r
516     we often have to drop APIDescriptor_t requests that are already there.\r
517   NOTE CSynapseAPIManager: if there are CSynapseAPIManager objects in the CSynapseClient,\r
518     we will scan and push all the matching APIs too\r
519   */\r
520   void PushRequired(CSynapseClient *pClient);\r
521   \r
522   /*!\r
523   work on resolving this particular APIDescriptor_t\r
524   returns true if we were able to resolve the interface\r
525   returns false otherwise\r
526   if the API was found, but not requested because of more required APIs, we push them in mStack\r
527   */\r
528   bool ResolveAPI(APIDescriptor_t* pAPI);\r
529   \r
530   /*!\r
531   push an APIDescriptor_t* into the stack of things to be resolved\r
532   will check that this is not already present first\r
533   will update the mbStackChanged flag\r
534   */\r
535   void TryPushStack(APIDescriptor_t *);\r
536         \r
537   /*!\r
538   \brief 'client shutdown' (see libs/synapse/docs/unload.txt)\r
539   performs a 'client shutdown'\r
540   will free the DLL module\r
541   before calling here, the client must be in a 'non active' state\r
542   (i.e. it was not used at all during startup, or we have properly done a 'release' already)\r
543   we scan the mStack for the SYN_REQUIRE that this client owns, and remove them\r
544   \param iSlot is an mClients iterator, invalid when the function returns as the item will have been removed from the list\r
545   \return the iterator afer erase call so that the caller iteration can continue\r
546   */\r
547   list<CSynapseClientSlot>::iterator ShutdownClient(list<CSynapseClientSlot>::iterator iSlot);\r
548   \r
549   /*!\r
550   \brief actual implementation of the Resolve function\r
551   */\r
552   bool DoResolve(CSynapseClient *pClient);  \r
553     \r
554 public:\r
555   CSynapseServer();\r
556   virtual ~CSynapseServer();\r
557 \r
558   void AddSearchPath(char*); ///< add a new directory to the module search path\r
559   /*!\r
560   do the big thing, scan for modules, scan their APIs, load up everything\r
561   providing pf is optional, will set the diagnostics printing\r
562   \param conf_file is the XML configuration file for the intialization (see docs/runtime.txt)\r
563   \return false if the init failed (for instance not found/invalid conf file\r
564   */\r
565   bool Initialize(const char* conf_file = NULL, PFN_SYN_PRINTF_VA pf = NULL);\r
566 \r
567   /*!\r
568   enumerate the interfaces for a given module\r
569   this will load it, query it's entry point, and request the APIs\r
570   */\r
571   void EnumerateInterfaces(Str &);\r
572   \r
573   /*!\r
574   enumerate the interfaces for a module that is builtin to the server\r
575   */\r
576   void EnumerateBuiltinModule(CSynapseBuiltinClient *);\r
577   \r
578   /*!\r
579   \brief resolve the function table loading for this client\r
580   if the client is not listed in the known slots yet, it will be added\r
581   wraps around internal DoResolve implementation to unload the unused modules\r
582   \return wether the resolution has been successful  \r
583   */\r
584   bool Resolve(CSynapseClient *pClient);\r
585   \r
586   /*!\r
587   \brief shutdown all the clients. Should only be called when the core is about to exit\r
588   this will force all clients to shutdown. it may destroy refcounted APIs and stuff\r
589   \todo hafta use the release/refresh code before doing actual shutdown\r
590   (i.e. when that code is written later on)\r
591   we need to 'broadcast' to all the clients .. that all the modules are going to be reloaded sorta\r
592   should clear up as many interfaces as possible to avoid unexpected crashes in the final stages of app exit\r
593   */\r
594   void Shutdown();\r
595   \r
596   /*!\r
597   diagnostic print function\r
598   NOTE:\r
599     it is essential that those functions should be virtual,\r
600     otherwise when accessing the g_pPrintf global we could mismatch\r
601     (happens because the same library is linked into server and client)\r
602   */\r
603   virtual PFN_SYN_PRINTF_VA Get_Syn_Printf();\r
604   \r
605   /*!\r
606   \return true if those APIs are matching\r
607   we provide two APIs for convenience, actual implementation is MatchAPI\r
608   the minors have to be both NULL, or equal, or one the minors be '*'\r
609   NOTE: the '*' minor should ONLY be used on an API that will be unique. It is hackish and kinda dangerous\r
610   */\r
611   static bool MatchAPI( APIDescriptor_t *p1, APIDescriptor_t *p2 );\r
612   static bool MatchAPI( const char* major1, const char* minor1, const char* major2, const char* minor2 );\r
613   \r
614 #if defined(_WIN32)\r
615   /*!\r
616   utility function to retrieve formatted GetLastError message\r
617   ANSI text, static string\r
618   */\r
619   static const char* FormatGetLastError();\r
620 #endif\r
621 \r
622   /*!\r
623   dump the stack of interfaces to be solved\r
624   this is used when synapse initialization failed to quickly identify the missing/broken pieces\r
625   */\r
626   void DumpStack();\r
627   \r
628   /*!\r
629   general purpose information, list what modules are loaded up\r
630   */\r
631   void DumpActiveClients();\r
632   \r
633   /*!\r
634   \brief select the config node that has this name\r
635   call this to locate the right node in XML config\r
636   this will focus and get ready to walk through the api nodes\r
637   \return wether the config node was correctly selected\r
638   */\r
639   bool SelectClientConfig(const char *client_name);\r
640   \r
641   /*!\r
642   \brief walk through the apis\r
643   the pointers don't need to be freed\r
644   you need to copy them over as they are invalidated between each call to GetNextConfig\r
645   \return false when all apis have been parsed\r
646   */\r
647   bool GetNextConfig(char **api_name, char **minor);\r
648   \r
649   /*!\r
650   \brief read the minor for a given api in the current config\r
651   \return false if this node doesn't exist\r
652   */\r
653   bool GetConfigForAPI( const char *api, char **minor );\r
654 \r
655   /*!\r
656   returns the filename of the module that the passed on client exists in\r
657   */\r
658   const char *GetModuleFilename(CSynapseClient *pClient);\r
659 };\r
660 \r
661 #endif\r