app_meetme: Refactor manager events to use stasis
[asterisk/asterisk.git] / res / parking / res_parking.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * Jonathan Rose <jrose@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  *
21  * \brief Call Parking Resource Internal API
22  *
23  * \author Jonathan Rose <jrose@digium.com>
24  */
25
26 #include "asterisk/pbx.h"
27 #include "asterisk/bridging.h"
28 #include "asterisk/parking.h"
29 #include "asterisk/stasis_channels.h"
30
31 #define DEFAULT_PARKING_LOT "default"
32 #define DEFAULT_PARKING_EXTEN "700"
33 #define PARK_DIAL_CONTEXT "park-dial"
34
35 enum park_call_resolution {
36         PARK_UNSET = 0,         /*! Nothing set a resolution. This should never be observed in practice. */
37         PARK_ABANDON,           /*! The channel for the parked call hung up */
38         PARK_TIMEOUT,           /*! The parked call stayed parked until the parking lot timeout was reached and was removed */
39         PARK_FORCED,            /*! The parked call was forcibly terminated by an unusual means in Asterisk */
40         PARK_ANSWERED,          /*! The parked call was retrieved successfully */
41 };
42
43 enum parked_call_feature_options {
44         OPT_PARKEDPLAY = 0,
45         OPT_PARKEDTRANSFERS,
46         OPT_PARKEDREPARKING,
47         OPT_PARKEDHANGUP,
48         OPT_PARKEDRECORDING,
49 };
50
51 enum parking_lot_modes {
52         PARKINGLOT_NORMAL = 0,          /*! The parking lot is configured normally and can accept new calls. Disable on reload if the config isn't replaced.
53                                          *  valid transitions: PARKINGLOT_DISABLED */
54         PARKINGLOT_DYNAMIC,             /*! The parking lot is a dynamically created parking lot. It can be parked to at any time. Disabled on last parked call leaving.
55                                          *  valid transitions: PARKINGLOT_DISABLED */
56         PARKINGLOT_DISABLED,            /*! The parking lot is no longer linked to a parking lot in configuration. It can no longer be parked to.
57                                          *  and it can not be parked to. This mode has no transitions. */
58 };
59
60 struct parking_lot_cfg {
61         int parking_start;                        /*!< First space in the parking lot */
62         int parking_stop;                         /*!< Last space in the parking lot */
63
64         unsigned int parkingtime;                 /*!< Analogous to parkingtime config option */
65         unsigned int comebackdialtime;            /*!< Analogous to comebackdialtime config option */
66         unsigned int parkfindnext;                /*!< Analogous to parkfindnext config option */
67         unsigned int parkext_exclusive;           /*!< Analogous to parkext_exclusive config option */
68         unsigned int parkaddhints;                /*!< Analogous to parkaddhints config option */
69         unsigned int comebacktoorigin;            /*!< Analogous to comebacktoorigin config option */
70         int parkedplay;                           /*!< Analogous to parkedplay config option */
71         int parkedcalltransfers;                  /*!< Analogous to parkedcalltransfers config option */
72         int parkedcallreparking;                  /*!< Analogous to parkedcallreparking config option */
73         int parkedcallhangup;                     /*!< Analogous to parkedcallhangup config option */
74         int parkedcallrecording;                  /*!< Analogous to parkedcallrecording config option */
75
76         AST_DECLARE_STRING_FIELDS(
77                 AST_STRING_FIELD(name);               /*!< Name of the parking lot configuration object */
78                 AST_STRING_FIELD(mohclass);           /*!< Analogous to mohclass config option */
79                 AST_STRING_FIELD(parkext);            /*!< Analogous to parkext config option */
80                 AST_STRING_FIELD(parking_con);        /*!< Analogous to context config option */
81                 AST_STRING_FIELD(comebackcontext);    /*!< Analogous to comebackcontext config option */
82                 AST_STRING_FIELD(courtesytone);       /*!< Analogous to courtesytone config option */
83         );
84 };
85
86 struct parking_lot {
87         int next_space;                           /*!< When using parkfindnext, which space we should start searching from next time we park */
88         struct ast_bridge *parking_bridge;        /*!< Bridged where parked calls will rest until they are answered or otherwise leave */
89         struct ao2_container *parked_users;       /*!< List of parked users rigidly ordered by their parking space */
90         struct parking_lot_cfg *cfg;              /*!< Reference to configuration object for the parking lot */
91         enum parking_lot_modes mode;              /*!< Whether a parking lot is operational, being reconfigured, primed for deletion, or dynamically created. */
92         int disable_mark;                         /*!< On reload, disable this parking lot if it doesn't receive a new configuration. */
93
94         AST_DECLARE_STRING_FIELDS(
95                 AST_STRING_FIELD(name);               /*!< Name of the parking lot object */
96         );
97 };
98
99 struct parked_user {
100         struct ast_channel *chan;                 /*!< Parked channel */
101         struct ast_channel_snapshot *parker;      /*!< Snapshot of the channel that parked the call at the time of parking */
102         struct ast_channel_snapshot *retriever;   /*!< Snapshot of the channel that retrieves a parked call */
103         struct timeval start;                     /*!< When the call was parked */
104         int parking_space;                        /*!< Which parking space is used */
105         char comeback[AST_MAX_CONTEXT];           /*!< Where to go on parking timeout */
106         unsigned int time_limit;                  /*!< How long this specific channel may remain in the parking lot before timing out */
107         struct parking_lot *lot;      /*!< Which parking lot the user is parked to */
108         enum park_call_resolution resolution;     /*!< How did the parking session end? If the call is in a bridge, lock parked_user before checking/setting */
109 };
110
111 /*!
112  * \since 12
113  * \brief If a parking lot exists in the parking lot list already, update its status to match the provided
114  *        configuration and return a reference return a reference to it. Otherwise, create a parking lot
115  *        struct based on a parking lot configuration and return a reference to the new one.
116  *
117  * \param cfg The configuration being used as a reference to build the parking lot from.
118  *
119  * \retval A reference to the new parking lot
120  * \retval NULL if it was not found and could not be be allocated
121  *
122  * \note The parking lot will need to be unreffed if it ever falls out of scope
123  * \note The parking lot will automatically be added to the parking lot container if needed as part of this process
124  */
125 struct parking_lot *parking_lot_build_or_update(struct parking_lot_cfg *cfg);
126
127 /*!
128  * \since 12
129  * \brief Remove a parking lot from the usable lists if it is no longer involved in any calls and no configuration currently claims it
130  *
131  * \param lot Which parking lot is being checked for elimination
132  *
133  * \note This should generally be called when something is happening that could cause a parking lot to die such as a call being unparked or
134  *       a parking lot no longer existing in configurations.
135  */
136 void parking_lot_remove_if_unused(struct parking_lot *lot);
137
138 /*!
139  * \since 12
140  * \brief Create a new parking bridge
141  *
142  * \param bridge_lot Parking lot which the new bridge should be based on
143  *
144  * \retval NULL if the bridge can not be created
145  * \retval Newly created parking bridge
146  */
147 struct ast_bridge *bridge_parking_new(struct parking_lot *bridge_lot);
148
149 /*!
150  * \since 12
151  * \brief Get a reference to a parking lot's bridge. If it doesn't exist, create it and get a reference.
152  *
153  * \param lot Which parking lot we need the bridge from. This parking lot must be locked before calling this function.
154  *
155  * \retval A reference to the ast_bridge associated with the parking lot
156  * \retval NULL if it didn't already have a bridge and one couldn't be created
157  *
158  * \note This bridge will need to be unreffed if it ever falls out of scope.
159  */
160 struct ast_bridge *parking_lot_get_bridge(struct parking_lot *lot);
161
162 /*!
163  * \since 12
164  * \brief Get an available parking space within a parking lot.
165  *
166  * \param lot Which parking lot we are getting a space from
167  * \param target_override If there is a specific slot we want, provide it here and we'll start from that position
168  *
169  * \retval -1 if No slot can be found
170  * \retval integer value of parking space selected
171  *
172  * \note lot should be locked before this is called and unlocked only after a parked_user with the space
173  *       returned has been added to the parking lot.
174  */
175 int parking_lot_get_space(struct parking_lot *lot, int target_override);
176
177 /*!
178  * \since 12
179  * \brief Determine if there is a parked user in a parking space and pull it from the parking lot if there is.
180  *
181  * \param lot Parking lot being pulled from
182  * \param target If < 0   search for the first occupied space in the parking lot
183  *               If >= 0  Only pull from the indicated target
184  *
185  * \retval NULL if no parked user could be pulled from the requested parking lot at the requested parking space
186  * \retval reference to the requested parked user
187  *
188  * \note The parked user will be removed from parking lot as part of this process
189  * \note Remove this reference with ao2_cleanup once it falls out of scope.
190  */
191 struct parked_user *parking_lot_retrieve_parked_user(struct parking_lot *lot, int target);
192
193 /*!
194  * \since 12
195  * \brief Apply features based on the parking lot feature options
196  *
197  * \param chan Which channel's feature set is being modified
198  * \param lot parking lot which establishes the features used
199  * \param recipient_mode AST_FEATURE_FLAG_BYCALLER if the user is the retriever
200  *                       AST_FEATURE_FLAG_BYCALLEE if the user is the parkee
201  */
202 void parked_call_retrieve_enable_features(struct ast_channel *chan, struct parking_lot *lot, int recipient_mode);
203
204 /*!
205  * \since 12
206  * \brief Set necessary bridge roles on a channel that is about to enter a parking lot
207  *
208  * \param chan Entering channel
209  * \param lot The parking lot the channel will be entering
210  * \param force_ringing Use ringing instead of music on hold
211  */
212 void parking_channel_set_roles(struct ast_channel *chan, struct parking_lot *lot, int force_ringing);
213
214 /*!
215  * \since 12
216  * \brief custom callback function for ast_bridge_channel_queue_playfile which plays a parking space
217  *        and optionally hangs up the call afterwards based on the payload in playfile.
218  */
219 void say_parking_space(struct ast_bridge_channel *bridge_channel, const char *payload);
220
221 /*!
222  * \since 12
223  * \brief Setup timeout interval feature on an ast_bridge_features for parking
224  *
225  * \param features The ast_bridge_features we are establishing the interval hook on
226  * \param user The parked_user receiving the timeout duration limits
227  */
228 void parking_set_duration(struct ast_bridge_features *features, struct parked_user *user);
229
230 /*!
231  * \since 12
232  * \brief Get a pointer to the parking lot container for purposes such as iteration
233  *
234  * \retval pointer to the parking lot container.
235  */
236 struct ao2_container *get_parking_lot_container(void);
237
238 /*!
239  * \since 12
240  * \brief Find a parking lot based on its name
241  *
242  * \param lot_name Name of the parking lot sought
243  *
244  * \retval The parking lot if found
245  * \retval NULL if no parking lot with the name specified exists
246  *
247  * \note ao2_cleanup this reference when you are done using it or you'll cause leaks.
248  */
249 struct parking_lot *parking_lot_find_by_name(const char *lot_name);
250
251 /*!
252  * \since 12
253  * \brief Find parking lot name from channel
254  *
255  * \param chan The channel we want the parking lot name for
256  *
257  * \retval name of the channel's assigned parking lot if it is defined by the channel in some way
258  * \retval name of the default parking lot if it is not
259  *
260  * \note Channel needs to be locked while the returned string is in use.
261  */
262 const char *find_channel_parking_lot_name(struct ast_channel *chan);
263
264 /*!
265  * \since 12
266  * \brief Flattens a peer name so that it can be written to/found from PBX extensions
267  *
268  * \param peername unflattened peer name. This will be flattened in place, so expect it to change.
269  */
270 void flatten_peername(char *peername);
271
272 /*!
273  * \since 12
274  * \brief Set a channel's position in the PBX after timeout using the parking lot settings
275  *
276  * \param pu Parked user who is entering/reentering the PBX
277  * \param lot Parking lot the user was removed from.
278  *
279  * \retval 0 Position set successfully
280  * \retval -1 Failed to set the position
281  */
282 int comeback_goto(struct parked_user *pu, struct parking_lot *lot);
283
284 /*!
285  * \since 12
286  * \brief Pull a parked user out of its parking lot. Use this when you don't want to use the parked user afterwards.
287  * \param user The parked user being pulled.
288  *
289  * \retval 0 on success
290  * \retval -1 if the user didn't have its parking lot set
291  */
292 int unpark_parked_user(struct parked_user *user);
293
294 /*!
295  * \since 12
296  * \brief Publish a stasis parked call message for the channel indicating failure to park.
297  *
298  * \param parkee channel belonging to the failed parkee
299  */
300 void publish_parked_call_failure(struct ast_channel *parkee);
301
302 /*!
303  * \since 12
304  * \brief Publish a stasis parked call message for a given parked user
305  *
306  * \param pu pointer to a parked_user that we are generating the message for
307  * \param event_type What parked call event type is provoking this message
308  */
309 void publish_parked_call(struct parked_user *pu, enum ast_parked_call_event_type event_type);
310
311 /*!
312  * \since 12
313  * \brief Function to prepare a channel for parking by determining which parking bridge should
314  *        be used, setting up a park common datastore so that the parking bridge will have access
315  *        to necessary parking information when joining, and applying various bridge roles to the
316  *        channel.
317  *
318  * \param parkee The channel being preparred for parking
319  * \param parker The channel initiating the park; may be the parkee as well
320  * \param app_data arguments supplied to the Park application. May be NULL.
321  * \param silence_announcements optional pointer to an integer where we want to store the silence option flag
322  *        this value should be initialized to 0 prior to calling park_common_setup.
323  *
324  * \retval reference to a parking bridge if successful
325  * \retval NULL on failure
326  *
327  * \note ao2_cleanup this reference when you are done using it or you'll cause leaks.
328  */
329 struct ast_bridge *park_common_setup(struct ast_channel *parkee, struct ast_channel *parker,
330         const char *app_data, int *silence_announcements);
331
332 struct park_common_datastore {
333         char *parker_uuid;           /*!< Unique ID of the channel parking the call. */
334         char *comeback_override;     /*!< Optional goto string for where to send the call after we are done */
335         int randomize;               /*!< Pick a parking space to enter on at random */
336         int time_limit;              /*!< time limit override. -1 values don't override, 0 for unlimited time, >0 for custom time limit in seconds */
337         int silence_announce;        /*!< Used when a call parks itself to keep it from hearing the parked call announcement */
338 };
339
340 /*!
341  * \since 12
342  * \brief Function that pulls data from the park common datastore on a channel in order to apply it to
343  *        the parked user struct upon bridging.
344  *
345  * \param parkee The channel entering parking with the datastore we are checking
346  * \param parker_uuid pointer to a string pointer for placing the name of the channel that parked parkee
347  * \param comeback_override pointer to a string pointer for placing the comeback_override option
348  * \param randomize integer pointer to an integer for placing the randomize option
349  * \param time_limit integer pointer to an integer for placing the time limit option
350  * \param silence_announce pointer to an integer for placing the silence_announcements option
351  */
352 void get_park_common_datastore_data(struct ast_channel *parkee,
353                 char **parker_uuid, char **comeback_override,
354                 int *randomize, int *time_limit, int *silence_announce);
355
356 /*!
357  * \since 12
358  * \brief Execution function for the parking application
359  *
360  * \param chan ast_channel entering the application
361  * \param data arguments to the application
362  *
363  * \retval 0 the application executed in such a way that the channel should proceed in the dial plan
364  * \retval -1 the channel should no longer proceed through the dial plan
365  *
366  * \note this function should only be used to register the parking application and not generally to park calls.
367  */
368 int park_app_exec(struct ast_channel *chan, const char *data);
369
370 /*!
371  * \since 12
372  * \brief Execution function for the parked call application
373  *
374  * \param chan ast_channel entering the application
375  * \param data arguments to the application
376  *
377  * \retval 0 the application executed in such a way that the channel should proceed in the dial plan
378  * \retval -1 the channel should no longer proceed through the dial plan
379  */
380 int parked_call_app_exec(struct ast_channel *chan, const char *data);
381
382 /*!
383  * \since 12
384  * \brief Execution function for the park and retrieve application
385  *
386  * \param chan ast_channel entering the application
387  * \param data arguments to the application
388  *
389  * \retval 0 the application executed in such a way that the channel should proceed in the dial plan
390  * \retval -1 the channel should no longer proceed through the dial plan
391  *
392  * \note this function should only be used to register the park and announce application and not generally to park and announce.
393  */
394 int park_and_announce_app_exec(struct ast_channel *chan, const char *data);
395
396 /*!
397  * \since 12
398  * \brief Register CLI commands
399  *
400  * \retval 0 if successful
401  * \retval -1 on failure
402  */
403 int load_parking_ui(void);
404
405 /*!
406  * \since 12
407  * \brief Unregister CLI commands
408  */
409 void unload_parking_ui(void);
410
411 /*!
412  * \since 12
413  * \brief Register manager actions and setup subscriptions for stasis events
414  */
415 int load_parking_manager(void);
416
417 /*!
418  * \since 12
419  * \brief Unregister manager actions and remove subscriptions for stasis events
420  */
421 void unload_parking_manager(void);
422
423 /*!
424  * \since 12
425  * \brief Register bridge features for parking
426  *
427  * \retval 0 on success
428  * \retval -1 on failure
429  */
430 int load_parking_bridge_features(void);
431
432 /*!
433  * \since 12
434  * \brief Unregister features registered by load_parking_bridge_features
435  */
436 void unload_parking_bridge_features(void);