KVIrc 5.2.4
Developer APIs
KviModule.h
Go to the documentation of this file.
1#ifndef _KVI_MODULE_H_
2#define _KVI_MODULE_H_
3//=============================================================================
4//
5// File : KviModule.h
6// Creation date : Sat Aug 12 2000 18:34:22 by Szymon Stefanek
7//
8// This file is part of the KVIrc IRC client distribution
9// Copyright (C) 2000-2010 Szymon Stefanek (pragma at kvirc dot net)
10//
11// This program is FREE software. You can redistribute it and/or
12// modify it under the terms of the GNU General Public License
13// as published by the Free Software Foundation; either version 2
14// of the License, or (at your option) any later version.
15//
16// This program is distributed in the HOPE that it will be USEFUL,
17// but WITHOUT ANY WARRANTY; without even the implied warranty of
18// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
19// See the GNU General Public License for more details.
20//
21// You should have received a copy of the GNU General Public License
22// along with this program. If not, write to the Free Software Foundation,
23// Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
24//
25//=============================================================================
26
27#include "kvi_settings.h"
28
29#include "KviModuleExtension.h"
31
32template <typename Key, typename T>
34
35#ifdef COMPILE_CRYPT_SUPPORT
36class KviCryptEngine;
37class KviCryptEngineDescription;
38class KviCryptEngineManager;
39#endif
40
41#if defined(COMPILE_ON_WINDOWS) || defined(COMPILE_ON_MINGW)
42#if defined(COMPILE_ON_MINGW)
43#define KVIMODULEEXPORT extern "C" __declspec(dllexport) __attribute__((visibility("default")))
44#else
45#define KVIMODULEEXPORT extern "C" __declspec(dllexport)
46#endif
47#define KVIMODULEEXPORTDATA KVIMODULEEXPORT
48#define KVIMODULEEXPORTFUNC KVIMODULEEXPORT
49#else
50#define KVIMODULEEXPORT extern "C" __attribute__((visibility("default")))
51#define KVIMODULEEXPORTDATA __attribute__((visibility("default")))
52#define KVIMODULEEXPORTFUNC KVIMODULEEXPORT
53#endif
54
55class KviModule;
56class KviCString;
57class QLibrary;
58
60typedef bool (*KviModuleCtrlRoutine)(KviModule *, const char *, void *);
61
63{
64 const char * szKVIrcVersion; // must match KVI_VERSION if module version checking is in force
65 const char * szModuleName; // module name
66 const char * szModuleContext; // name of the translation catalogue (if any)
67 const char * szVersion;
68 const char * szCopyright;
69 const char * szDescription;
70 /*
71 * This routine is called when the module is loaded
72 */
74 /*
75 * This should return true if the module is actually
76 * not providing any service and can be unloaded from memory.
77 * Please note that this is not a mandatory lock: KVIrc may still unload
78 * the module even when this function returns false.
79 * The only assumption you can make is that KVIrc will not try
80 * to unload the module spontaneously: it will do it only if forced to
81 * (actually only by the user, but maybe later also by constrained resources).
82 * If this pointer is zero, KVIrc will assume that the module
83 * does not provide any service and will unload the module at the
84 * first spontaneous cleanup.
85 * There is a yet stronger locking method in KviModule::lock()
86 */
88 /*
89 * This is a generic control routine with prototype
90 * bool <name>(KviModule * m,const char * operation,void * param)
91 * KVIrc uses it to comunicate with bundled modules
92 * in most user-build modules this will be 0
93 */
95 /*
96 * This routine is called when the module is being unloaded
97 * Note that the module can be unloaded even if can_unload returns false:
98 * that's the user choice, KVIrc can only forcibly unload the module,
99 * so better cleanup everything here :)
100 */
101 KviModuleSystemRoutine cleanup_routine; // WARNING : g_pApp may be in the destructor and may have no frames open!
102};
103
104// NOTE: The init and cleanup routines should NEVER rely on g_pApp existing!
105// so only "initialization and cleanup INTERNAL to the module" goes there!
106
107// A module should be prepared to be unloaded at ANY time, even if it is locked
108// or if can_unload returns false; locking is only a "suggestion" to the KVIrc core.
109
110// When unloaded, a module must ensure the destruction of all the resources that depend
111// on the module core code
112
113#define KVIRC_MODULE_STRUCTURE_SYMBOL "KVIrc_module_info"
114
115#define KVIRC_MODULE(_szModuleName, _szVersion, _szCopyright, _szDescription, _init_routine, _can_unload, _ctrl_routine, _cleanup_routine, _szModuleContext) \
116 \
117 KVIMODULEEXPORTDATA KviModuleInfo KVIrc_module_info = { \
118 KVI_VERSION, \
119 _szModuleName, \
120 _szModuleContext, \
121 _szVersion, \
122 _szCopyright, \
123 _szDescription, \
124 _init_routine, \
125 _can_unload, \
126 _ctrl_routine, \
127 _cleanup_routine \
128 };
129
131{
132 friend class KviPointerHashTable<const char *, KviModule>;
133 friend class KviModuleManager;
134 friend class KviUserParser;
135
136protected:
137 KviModule(QLibrary * handle, KviModuleInfo * info, const QString & name, const QString & filename);
138
139public:
140 ~KviModule(); // must be public for KviPointerList
141private:
142 QString m_szName;
145 QLibrary * m_pLibrary;
146 unsigned int m_uLock;
148
149protected:
150 void updateAccessTime();
151 unsigned int secondsSinceLastAccess();
152
153public:
154 // name of this module: always low case, single word
155 const QString & name() { return m_szName; };
156 // filename of this module (with NO path): formatted as "libkvi%s.so",name()
157 const QString & filename() { return m_szFileName; };
158 QLibrary * handle() { return m_pLibrary; };
159 KviModuleInfo * moduleInfo() { return m_pModuleInfo; };
160
161 //
162 // This is a locking method a bit stronger than the can_unload routine
163 // in the descriptor. It will behave in the same way plus
164 // the user will be unable to unload the module unless he will specify
165 // the -f switch to the <module>.unload command. Without the -f switch
166 // he will be just warned that the module is locked in memory and
167 // don't want to be unloaded.
168 // The usage of this method is encouraged
169 // only when you have blocking dialogs inside the module code, like the
170 // QMessageBox or QFileDialog static methods.
171 // In this case you're entering a modal event loop that you can't control
172 // and if some script will attempt to forcibly unload the module
173 // it will surely lead to a crash when the static method returns (jumping into no mans land).
174 // <module>.unload -f is in fact undocumented so people will substantially
175 // not use it (unless they are developers and they are reading this comment).
176 //
177 void lock() { m_uLock++; };
178 void unlock()
179 {
180 if(m_uLock > 0)
181 m_uLock--;
182 };
183 bool isLocked() { return (m_uLock > 0); };
184
185 void * getSymbol(const char * symname);
186 bool ctrl(const char * operation, void * param);
187
188 void getDefaultConfigFileName(QString & szBuffer);
189
190 static void unregisterMetaObject(const char * metaObjName);
191
192#ifdef COMPILE_CRYPT_SUPPORT
193 void registerCryptEngine(KviCryptEngineDescription * d);
194 void unregisterCryptEngine(const char * szName);
195 void unregisterCryptEngines();
196#endif
197
198 KviModuleExtensionDescriptor * registerExtension(const KviCString & szType, const KviCString & szName, const QString & szVisibleName, KviModuleExtensionAllocRoutine r);
199 KviModuleExtensionDescriptor * registerExtension(const KviCString & szType, const KviCString & szName, const QString & szVisibleName, KviModuleExtensionAllocRoutine r, const QPixmap & icon);
200 KviModuleExtensionDescriptor * findExtensionDescriptor(const KviCString & szType, const KviCString & szName);
201 void unregisterAllExtensions();
202};
203
204#endif //_KVI_MODULE_H_
KviModuleExtension *(* KviModuleExtensionAllocRoutine)(KviModuleExtensionAllocStruct *)
Definition KviModuleExtension.h:49
bool(* KviModuleSystemRoutine)(KviModule *)
Definition KviModule.h:59
bool(* KviModuleCtrlRoutine)(KviModule *, const char *, void *)
Definition KviModule.h:60
Definition KviCString.h:102
Definition KviCryptEngine.h:54
Definition KviKvsModuleInterface.h:136
Definition KviModuleExtension.h:52
Definition KviModuleManager.h:36
Definition KviModule.h:131
void lock()
Definition KviModule.h:177
long int m_lastAccessTime
Definition KviModule.h:147
void unlock()
Definition KviModule.h:178
QString m_szName
Definition KviModule.h:142
static void unregisterMetaObject(const char *metaObjName)
QLibrary * handle()
Definition KviModule.h:158
KviModuleInfo * m_pModuleInfo
Definition KviModule.h:144
bool isLocked()
Definition KviModule.h:183
QString m_szFileName
Definition KviModule.h:143
const QString & filename()
Definition KviModule.h:157
unsigned int m_uLock
Definition KviModule.h:146
const QString & name()
Definition KviModule.h:155
KviModuleInfo * moduleInfo()
Definition KviModule.h:159
QLibrary * m_pLibrary
Definition KviModule.h:145
A fast pointer hash table implementation.
Definition KviPointerHashTable.h:450
#define d
Definition detector.cpp:69
#define r
Definition detector.cpp:83
This file contains compile time settings.
#define KVIRC_API
Definition kvi_settings.h:127
Definition KviModule.h:63
KviModuleSystemRoutine can_unload
Definition KviModule.h:87
const char * szModuleContext
Definition KviModule.h:66
KviModuleSystemRoutine cleanup_routine
Definition KviModule.h:101
const char * szCopyright
Definition KviModule.h:68
KviModuleCtrlRoutine ctrl_routine
Definition KviModule.h:94
const char * szDescription
Definition KviModule.h:69
const char * szVersion
Definition KviModule.h:67
KviModuleSystemRoutine init_routine
Definition KviModule.h:73
const char * szModuleName
Definition KviModule.h:65
const char * szKVIrcVersion
Definition KviModule.h:64
char szBuffer[4096]
Definition winamp.cpp:77