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