1 /* 2 * Copyright (C) 2002-2003 Fhg Fokus 3 * Copyright (C) 2006 iptego GmbH 4 * 5 * This file is part of SEMS, a free SIP media server. 6 * 7 * SEMS is free software; you can redistribute it and/or modify 8 * it under the terms of the GNU General Public License as published by 9 * the Free Software Foundation; either version 2 of the License, or 10 * (at your option) any later version. This program is released under 11 * the GPL with the additional exemption that compiling, linking, 12 * and/or using OpenSSL is allowed. 13 * 14 * For a license to use the SEMS software under conditions 15 * other than those described here, or to purchase support for this 16 * software, please contact iptel.org by e-mail at the following addresses: 17 * info@iptel.org 18 * 19 * SEMS is distributed in the hope that it will be useful, 20 * but WITHOUT ANY WARRANTY; without even the implied warranty of 21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 22 * GNU General Public License for more details. 23 * 24 * You should have received a copy of the GNU General Public License 25 * along with this program; if not, write to the Free Software 26 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 27 */ 28 /** @file AmApi.h */ 29 #ifndef _AmApi_h_ 30 #define _AmApi_h_ 31 32 #include "AmThread.h" 33 #include "AmSipMsg.h" 34 #include "AmConfig.h" 35 #include "AmConfigReader.h" 36 #include "AmArg.h" 37 #include "AmEventQueue.h" 38 #include "atomic_types.h" 39 40 #include <stdarg.h> 41 42 #include <string> 43 using std::string; 44 45 /** 46 * \brief interface of the DynInvoke API 47 */ 48 class AmDynInvoke 49 { 50 public: 51 /** \brief NotImplemented result for DI API calls */ 52 struct NotImplemented { 53 string what; NotImplementedNotImplemented54 NotImplemented(const string& w) 55 : what(w) {} 56 }; 57 58 AmDynInvoke(); 59 virtual ~AmDynInvoke(); 60 virtual void invoke(const string& method, const AmArg& args, AmArg& ret); 61 }; 62 63 /** 64 * \brief Base interface for plugin factories 65 */ 66 class AmPluginFactory 67 : public virtual atomic_ref_cnt 68 { 69 string plugin_name; 70 71 public: AmPluginFactory(const string & name)72 AmPluginFactory(const string& name) 73 : plugin_name(name) {} 74 ~AmPluginFactory()75 virtual ~AmPluginFactory() {} 76 getName()77 const string& getName() { return plugin_name; } 78 79 /** 80 * Enables the plug-in to initialize whatever it needs. 81 * Ex. load the configuration. 82 * @return 0 everything was ok. 83 * @return 1 on error. 84 */ 85 virtual int onLoad()=0; 86 }; 87 88 /** 89 * \brief Interface of factory for plugins that provide a DI API 90 * 91 * Factory for multi-purpose plugin classes, 92 * classes that provide a DynInvoke (DI) API 93 */ 94 class AmDynInvokeFactory: public AmPluginFactory 95 { 96 public: 97 AmDynInvokeFactory(const string& name); 98 virtual AmDynInvoke* getInstance()=0; 99 }; 100 101 102 class AmSession; 103 class AmSessionEventHandler; 104 /** 105 * \brief Interface for PluginFactories that can handle events in sessions 106 */ 107 class AmSessionEventHandlerFactory: public AmPluginFactory 108 { 109 public: 110 AmSessionEventHandlerFactory(const string& name); 111 112 virtual AmSessionEventHandler* getHandler(AmSession*)=0; 113 114 /** 115 * @return false if session creation should be stopped 116 */ 117 virtual bool onInvite(const AmSipRequest& req, AmConfigReader& cfg)=0; 118 virtual bool onInvite(const AmSipRequest& req, AmArg& session_params, AmConfigReader& cfg); 119 }; 120 121 /** \brief Interface for plugins to create sessions */ 122 class AmSessionFactory: public AmPluginFactory 123 { 124 125 protected: 126 /** 127 * This reads the module configuration from 128 * cfg into the modules mod_conf. 129 */ 130 int configureModule(AmConfigReader& cfg); 131 132 public: 133 134 static void replyOptions(const AmSipRequest& req); 135 136 /** 137 * This function applys the module configuration 138 */ 139 void configureSession(AmSession* sess); 140 141 AmSessionFactory(const string& name); 142 143 /** 144 * Creates a dialog state on new UAS request. 145 * @return 0 if the request is not acceptable. 146 * 147 * Warning: 148 * This method should not make any expensive 149 * processing as it would block the server. 150 */ 151 virtual AmSession* onInvite(const AmSipRequest& req, const string& app_name, 152 const map<string,string>& app_params)=0; 153 154 /** 155 * Creates a dialog state on new UAC request. 156 * @param session_params parameters passed to the new session by the caller. 157 * 158 * @return 0 if the request is not acceptable. 159 * 160 * Warning: 161 * This method should not make any expensive 162 * processing as it would block the server. 163 */ 164 virtual AmSession* onInvite(const AmSipRequest& req, const string& app_name, 165 AmArg& session_params); 166 167 /** 168 * Creates a dialog state on new REFER with local-tag. 169 * @return 0 if the request is not acceptable. 170 * 171 * Warning: 172 * This method should not make any expensive 173 * processing as it would block the server. 174 */ 175 virtual AmSession* onRefer(const AmSipRequest& req, const string& app_name, 176 const map<string,string>& app_params); 177 178 /** 179 * Creates a dialog state on new REFER with local-tag. 180 * Passes session_params to the new session. 181 * @return 0 if the request is not acceptable. 182 * 183 * Warning: 184 * This method should not make any expensive 185 * processing as it would block the server. 186 */ 187 virtual AmSession* onRefer(const AmSipRequest& req, const string& app_name, 188 AmArg& session_params); 189 190 /** 191 * Method to receive any out-of-dialog request 192 * other than INVITE and REFER 193 * 194 * Warning: 195 * This method should not make any expensive 196 * processing as it would block the thread 197 * posting the event! 198 */ 199 virtual void onOoDRequest(const AmSipRequest& req); 200 }; 201 202 /** \brief Interface for plugins that implement a 203 * logging facility 204 */ 205 class AmLoggingFacility : public AmPluginFactory 206 { 207 208 public: 209 AmLoggingFacility(const string& name); ~AmLoggingFacility()210 virtual ~AmLoggingFacility() { } 211 212 /** 213 * This method is called when logging a message if the instance 214 * is registered as a logging hook. 215 * 216 * @param level log level 217 * @param pid process ID 218 * @param tid thread ID 219 * @param func function name 220 * @param file file name 221 * @param line line number 222 * @param msg message 223 */ 224 virtual void log(int level, pid_t pid, pthread_t tid, const char* func, const char* file, int line, char* msg) = 0; 225 }; 226 227 #if __GNUC__ < 3 228 #define EXPORT_FACTORY(fctname,class_name,args...) \ 229 extern "C" void* fctname()\ 230 {\ 231 return new class_name(##args);\ 232 } 233 #else 234 #define EXPORT_FACTORY(fctname,class_name,...) \ 235 extern "C" void* fctname()\ 236 {\ 237 return new class_name(__VA_ARGS__);\ 238 } 239 #endif 240 241 typedef void* (*FactoryCreate)(); 242 243 #define STR(x) #x 244 #define XSTR(x) STR(x) 245 246 #define FACTORY_SESSION_EXPORT session_factory_create 247 #define FACTORY_SESSION_EXPORT_STR XSTR(FACTORY_SESSION_EXPORT) 248 249 #define EXPORT_SESSION_FACTORY(class_name,app_name) \ 250 EXPORT_FACTORY(FACTORY_SESSION_EXPORT,class_name,app_name) 251 252 #define FACTORY_SESSION_EVENT_HANDLER_EXPORT sess_evh_factory_create 253 #define FACTORY_SESSION_EVENT_HANDLER_EXPORT_STR XSTR(FACTORY_SESSION_EVENT_HANDLER_EXPORT) 254 255 #define EXPORT_SESSION_EVENT_HANDLER_FACTORY(class_name,app_name) \ 256 EXPORT_FACTORY(FACTORY_SESSION_EVENT_HANDLER_EXPORT,class_name,app_name) 257 258 #define FACTORY_PLUGIN_EXPORT base_plugin_create 259 #define FACTORY_PLUGIN_EXPORT_STR XSTR(FACTORY_PLUGIN_EXPORT) 260 261 #define EXPORT_PLUGIN_FACTORY(class_name,app_name) \ 262 EXPORT_FACTORY(FACTORY_PLUGIN_EXPORT,class_name,app_name) 263 264 #define FACTORY_PLUGIN_CLASS_EXPORT plugin_class_create 265 #define FACTORY_PLUGIN_CLASS_EXPORT_STR XSTR(FACTORY_PLUGIN_CLASS_EXPORT) 266 267 #define EXPORT_PLUGIN_CLASS_FACTORY(class_name,app_name) \ 268 EXPORT_FACTORY(FACTORY_PLUGIN_CLASS_EXPORT,class_name,app_name) 269 270 #define FACTORY_SIP_EVENT_HANDLER_EXPORT sip_evh_factory_create 271 #define FACTORY_SIP_EVENT_HANDLER_EXPORT_STR XSTR(FACTORY_SIP_EVENT_HANDLER_EXPORT) 272 273 #define EXPORT_SIP_EVENT_HANDLER_FACTORY(class_name,app_name) \ 274 EXPORT_FACTORY(FACTORY_SIP_EVENT_HANDLER_EXPORT,class_name,app_name) 275 276 #define FACTORY_LOG_FACILITY_EXPORT log_facilty_factory_create 277 #define FACTORY_LOG_FACILITY_EXPORT_STR XSTR(FACTORY_LOG_FACILITY_EXPORT) 278 279 #define EXPORT_LOG_FACILITY_FACTORY(class_name,app_name) \ 280 EXPORT_FACTORY(FACTORY_LOG_FACILITY_EXPORT,class_name,app_name) 281 282 // ---------------- simplified SEMS plug-in interface -------------------------- 283 // - export module as basic SEMS plugin with EXPORT_MODULE_FUNC 284 // - in onLoad, register the capabilities you provide, 285 // e.g. AmPlugIn::registerApplication(...), AmPlugIn::registerDIInterface(...) etc 286 287 #define EXPORT_MODULE_FUNC(class_name) \ 288 extern "C" void* base_plugin_create() \ 289 { \ 290 return class_name::instance(); \ 291 } 292 293 #define EXPORT_MODULE_FACTORY(class_name) \ 294 EXPORT_MODULE_FUNC(class_name) 295 296 297 // - use DECLARE_MODULE_INSTANCE/DEFINE_MODULE_INSTANCE to save some typing when 298 // creating plugins with DI Interface 299 300 #define DEFINE_MODULE_INSTANCE(class_name, mod_name) \ 301 \ 302 class_name* class_name::_instance=0; \ 303 \ 304 class_name* class_name::instance() \ 305 { \ 306 if(_instance == NULL) \ 307 _instance = new class_name(mod_name); \ 308 return _instance; \ 309 } 310 311 #define DECLARE_MODULE_INSTANCE(class_name) \ 312 static class_name* _instance; \ 313 static class_name* instance(); 314 315 316 #endif // _AmApi_h_ 317