1 /** 2 * yatepbx.h 3 * This file is part of the YATE Project http://YATE.null.ro 4 * 5 * Common C++ base classes for PBX related plugins 6 * 7 * Yet Another Telephony Engine - a fully featured software PBX and IVR 8 * Copyright (C) 2004-2014 Null Team 9 * 10 * This software is distributed under multiple licenses; 11 * see the COPYING file in the main directory for licensing 12 * information for this specific distribution. 13 * 14 * This use of this software may be subject to additional restrictions. 15 * See the LEGAL file in the main directory for details. 16 * 17 * This program is distributed in the hope that it will be useful, 18 * but WITHOUT ANY WARRANTY; without even the implied warranty of 19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 20 */ 21 22 #include <yatephone.h> 23 24 #ifdef _WINDOWS 25 26 #ifdef LIBYPBX_EXPORTS 27 #define YPBX_API __declspec(dllexport) 28 #else 29 #ifndef LIBYPBX_STATIC 30 #define YPBX_API __declspec(dllimport) 31 #endif 32 #endif 33 34 #endif /* _WINDOWS */ 35 36 #ifndef YPBX_API 37 #define YPBX_API 38 #endif 39 40 namespace TelEngine { 41 42 /** 43 * Hold extra informations about an active CallEndpoint 44 */ 45 class YPBX_API CallInfo : public NamedList 46 { 47 public: 48 inline CallInfo(const char* name, CallEndpoint* call = 0) NamedList(name)49 : NamedList(name), m_call(call) 50 { } 51 ~CallInfo()52 virtual ~CallInfo() 53 { m_call = 0; } 54 call()55 inline CallEndpoint* call() const 56 { return m_call; } 57 setCall(CallEndpoint * call)58 inline void setCall(CallEndpoint* call) 59 { m_call = call; } 60 clearCall()61 inline void clearCall() 62 { m_call = 0; } 63 64 /** 65 * Copy one parameter from a NamedList - typically a Message 66 */ 67 bool copyParam(const NamedList& original, const String& name, bool clear = false); 68 69 /** 70 * Copy many parameters from a NamedList, end the list with a NULL or 0 71 */ 72 void copyParams(const NamedList& original, bool clear, ...); 73 void fillParam(NamedList& target, const String& name, bool clear = false); 74 void fillParams(NamedList& target); 75 76 protected: 77 CallEndpoint* m_call; 78 int m_route; 79 }; 80 81 /** 82 * Hold a list of call informations 83 */ 84 class YPBX_API CallList 85 { 86 public: append(CallInfo * call)87 inline void append(CallInfo* call) 88 { m_calls.append(call); } remove(CallInfo * call)89 inline void remove(CallInfo* call) 90 { m_calls.remove(call,false); } 91 CallInfo* find(const String& id); 92 CallInfo* find(const CallEndpoint* call); 93 protected: 94 ObjList m_calls; 95 }; 96 97 class YPBX_API MultiRouter : public MessageReceiver, public Mutex 98 { 99 public: 100 enum { 101 Route, 102 Execute, 103 Hangup, 104 Disconnected 105 }; 106 MultiRouter(const char* trackName = 0); 107 virtual ~MultiRouter(); 108 void setup(int priority = 0); 109 virtual bool received(Message& msg, int id); 110 virtual bool msgRoute(Message& msg, CallInfo& info, bool first); 111 virtual bool msgExecute(Message& msg, CallInfo& info, bool first); 112 virtual bool msgDisconnected(Message& msg, CallInfo& info); 113 virtual void msgHangup(Message& msg, CallInfo& info); 114 virtual Message* buildExecute(CallInfo& info, bool reroute) = 0; 115 Message* defaultExecute(CallInfo& info, const char* route = 0); 116 protected: 117 CallList m_list; 118 private: 119 String m_trackName; 120 MessageRelay* m_relRoute; 121 MessageRelay* m_relExecute; 122 MessageRelay* m_relHangup; 123 MessageRelay* m_relDisconnected; 124 }; 125 126 class ChanAssistList; 127 128 /** 129 * Object that assists a channel 130 */ 131 class YPBX_API ChanAssist : public RefObject 132 { 133 public: 134 /** 135 * Destructor 136 */ 137 virtual ~ChanAssist(); 138 139 /** 140 * Get the String value of this object 141 * @return ID of the assisted channel 142 */ toString()143 virtual const String& toString() const 144 { return m_chanId; } 145 146 /** 147 * Process the chan.startup message 148 * @param msg First channel message, may be received after call.execute 149 */ 150 virtual void msgStartup(Message& msg); 151 152 /** 153 * Process the chan.hangup message 154 * @param msg Last channel message 155 */ 156 virtual void msgHangup(Message& msg); 157 158 /** 159 * Process the call.execute message, copy any parameters needed later 160 * @param msg Call execute message, may be received before chan.startup 161 */ 162 virtual void msgExecute(Message& msg); 163 164 /** 165 * Process the channel disconnect message, may connect to something else 166 * @param msg The chan.disconnected message 167 * @param reason The disconnection reason 168 */ 169 virtual bool msgDisconnect(Message& msg, const String& reason); 170 171 /** 172 * Retrieve the list that owns this object 173 * @return Pointer to the owner list 174 */ list()175 inline ChanAssistList* list() const 176 { return m_list; } 177 178 /** 179 * Get the name of the assisted channel 180 * @return Identifier of the channel 181 */ id()182 inline const String& id() const 183 { return m_chanId; } 184 185 /** 186 * Retrieve a smart pointer to an arbitrary channel 187 * @param id Identifier of the channel to locate 188 * @return Smart pointer to the channel or NULL if not found or dead 189 */ 190 static RefPointer<CallEndpoint> locate(const String& id); 191 192 /** 193 * Retrieve a smart pointer to the assisted channel 194 * @return Smart pointer to the channel or NULL if not found or dead 195 */ locate()196 inline RefPointer<CallEndpoint> locate() const 197 { return locate(m_chanId); } 198 199 protected: 200 /** 201 * Constructor of base class 202 * @param list ChanAssistList that owns this object 203 * @param id Identifier of the assisted channel 204 */ ChanAssist(ChanAssistList * list,const String & id)205 inline ChanAssist(ChanAssistList* list, const String& id) 206 : m_list(list), m_chanId(id) 207 { } 208 private: 209 ChanAssist(); // no default constructor please 210 ChanAssistList* m_list; 211 String m_chanId; 212 }; 213 214 /** 215 * Class keeping a list of ChanAssist objects. It also serves as base to 216 * implement channel assisting plugins. 217 */ 218 class YPBX_API ChanAssistList : public Module 219 { 220 friend class ChanAssist; 221 public: 222 /** 223 * Message realy IDs 224 */ 225 enum { 226 Startup = Private, 227 Hangup, 228 Disconnected, 229 AssistPrivate 230 }; 231 232 /** 233 * Destructor 234 */ ~ChanAssistList()235 virtual ~ChanAssistList() 236 { } 237 238 /** 239 * Message handler called internally 240 * @param msg Received nessage 241 * @param id Numeric identifier of the message type 242 * @return True if the message was handled and further processing should stop 243 */ 244 virtual bool received(Message& msg, int id); 245 246 /** 247 * Message handler for an assistant object 248 * @param msg Received nessage 249 * @param id Numeric identifier of the message type 250 * @param assist Pointer to the matching assistant object 251 * @return True if the message was handled and further processing should stop 252 */ 253 virtual bool received(Message& msg, int id, ChanAssist* assist); 254 255 /** 256 * Method to (re)initialize the plugin 257 */ 258 virtual void initialize(); 259 260 /** 261 * Create a new channel assistant 262 * @param msg Message that triggered the creation 263 * @param id Channel's identifier 264 * @return Pointer to new assistant object, NULL if unacceptable 265 */ 266 virtual ChanAssist* create(Message& msg, const String& id) = 0; 267 268 /** 269 * Initialize the plugin for the first time 270 * @param priority Priority used to install message handlers 271 */ 272 virtual void init(int priority = 15); 273 274 /** 275 * Find a channel assistant by channel ID 276 * @param id Identifier of the assisted channel 277 * @return Pointer to the assistant object 278 */ find(const String & id)279 inline ChanAssist* find(const String& id) const 280 { return static_cast<ChanAssist*>(m_calls[id]); } 281 282 protected: 283 /** 284 * Constructor 285 * @param name Name of the module 286 * @param earlyInit True to attempt to initialize module before others 287 */ 288 inline ChanAssistList(const char* name, bool earlyInit = false) 289 : Module(name, "misc", earlyInit), m_first(true) 290 { } 291 292 /** 293 * Removes an assistant object from list 294 * @param assist Object to remove from list 295 */ 296 void removeAssist(ChanAssist* assist); 297 298 /** 299 * Access to the assisted calls list 300 * @return The HashList holding the calls 301 */ calls()302 inline HashList& calls() 303 { return m_calls; } 304 305 /** 306 * Access to the assisted calls list 307 * @return The HashList holding the calls 308 */ calls()309 inline const HashList& calls() const 310 { return m_calls; } 311 312 private: 313 ChanAssistList(); // no default constructor please 314 HashList m_calls; 315 bool m_first; 316 }; 317 318 } 319 320 /* vi: set ts=8 sw=4 sts=4 noet: */ 321