Minor parking cleanup.
[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/bridge.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 BASE_REGISTRAR "res_parking"
34 #define PARK_DIAL_CONTEXT "park-dial"
35
36 enum park_call_resolution {
37         PARK_UNSET = 0,         /*! Nothing set a resolution. This should never be observed in practice. */
38         PARK_ABANDON,           /*! The channel for the parked call hung up */
39         PARK_TIMEOUT,           /*! The parked call stayed parked until the parking lot timeout was reached and was removed */
40         PARK_FORCED,            /*! The parked call was forcibly terminated by an unusual means in Asterisk */
41         PARK_ANSWERED,          /*! The parked call was retrieved successfully */
42 };
43
44 enum parked_call_feature_options {
45         OPT_PARKEDPLAY = 0,
46         OPT_PARKEDTRANSFERS,
47         OPT_PARKEDREPARKING,
48         OPT_PARKEDHANGUP,
49         OPT_PARKEDRECORDING,
50 };
51
52 enum parking_lot_modes {
53         PARKINGLOT_NORMAL = 0,          /*! The parking lot is configured normally and can accept new calls. Disable on reload if the config isn't replaced.
54                                          *  valid transitions: PARKINGLOT_DISABLED */
55         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.
56                                          *  valid transitions: PARKINGLOT_DISABLED */
57         PARKINGLOT_DISABLED,            /*! The parking lot is no longer linked to a parking lot in configuration. It can no longer be parked to.
58                                          *  and it can not be parked to. This mode has no transitions. */
59 };
60
61 struct parking_lot_cfg {
62         int parking_start;                        /*!< First space in the parking lot */
63         int parking_stop;                         /*!< Last space in the parking lot */
64
65         unsigned int parkingtime;                 /*!< Analogous to parkingtime config option */
66         unsigned int comebackdialtime;            /*!< Analogous to comebackdialtime config option */
67         unsigned int parkfindnext;                /*!< Analogous to parkfindnext config option */
68         unsigned int parkext_exclusive;           /*!< Analogous to parkext_exclusive config option */
69         unsigned int parkaddhints;                /*!< Analogous to parkaddhints config option */
70         unsigned int comebacktoorigin;            /*!< Analogous to comebacktoorigin config option */
71         int parkedplay;                           /*!< Analogous to parkedplay config option */
72         int parkedcalltransfers;                  /*!< Analogous to parkedcalltransfers config option */
73         int parkedcallreparking;                  /*!< Analogous to parkedcallreparking config option */
74         int parkedcallhangup;                     /*!< Analogous to parkedcallhangup config option */
75         int parkedcallrecording;                  /*!< Analogous to parkedcallrecording config option */
76
77         AST_DECLARE_STRING_FIELDS(
78                 AST_STRING_FIELD(name);               /*!< Name of the parking lot configuration object */
79                 AST_STRING_FIELD(registrar);          /*!< Which registrar the lot uses if it isn't the default registrar */
80                 AST_STRING_FIELD(mohclass);           /*!< Analogous to mohclass config option */
81                 AST_STRING_FIELD(parkext);            /*!< Analogous to parkext config option */
82                 AST_STRING_FIELD(parking_con);        /*!< Analogous to context config option */
83                 AST_STRING_FIELD(comebackcontext);    /*!< Analogous to comebackcontext config option */
84                 AST_STRING_FIELD(courtesytone);       /*!< Analogous to courtesytone config option */
85         );
86 };
87
88 struct parking_lot {
89         int next_space;                           /*!< When using parkfindnext, which space we should start searching from next time we park */
90         struct ast_bridge *parking_bridge;        /*!< Bridged where parked calls will rest until they are answered or otherwise leave */
91         struct ao2_container *parked_users;       /*!< List of parked users rigidly ordered by their parking space */
92         struct parking_lot_cfg *cfg;              /*!< Reference to configuration object for the parking lot */
93         enum parking_lot_modes mode;              /*!< Whether a parking lot is operational, being reconfigured, primed for deletion, or dynamically created. */
94         int disable_mark;                         /*!< On reload, disable this parking lot if it doesn't receive a new configuration. */
95
96         AST_DECLARE_STRING_FIELDS(
97                 AST_STRING_FIELD(name);               /*!< Name of the parking lot object */
98         );
99 };
100
101 struct parked_user {
102         struct ast_channel *chan;                 /*!< Parked channel */
103         struct ast_channel_snapshot *retriever;   /*!< Snapshot of the channel that retrieves a parked call */
104         struct timeval start;                     /*!< When the call was parked */
105         int parking_space;                        /*!< Which parking space is used */
106         char comeback[AST_MAX_CONTEXT];           /*!< Where to go on parking timeout */
107         char *parker_dial_string;                 /*!< dialstring to call back with comebacktoorigin. Used timeout extension generation and call control */
108         unsigned int time_limit;                  /*!< How long this specific channel may remain in the parking lot before timing out */
109         struct parking_lot *lot;                  /*!< Which parking lot the user is parked to */
110         enum park_call_resolution resolution;     /*!< How did the parking session end? If the call is in a bridge, lock parked_user before checking/setting */
111 };
112
113 #if defined(TEST_FRAMEWORK)
114 /*!
115  * \since 12.0.0
116  * \brief Create an empty parking lot configuration structure
117  *        useful for unit tests.
118  *
119  * \param cat name given to the parking lot
120  *
121  * \retval NULL failure
122  * \retval non-NULL successfully allocated parking lot
123  */
124 struct parking_lot_cfg *parking_lot_cfg_create(const char *cat);
125 #endif
126
127 /*!
128  * \since 12.0.0
129  * \brief If a parking lot exists in the parking lot list already, update its status to match the provided
130  *        configuration and return a reference return a reference to it. Otherwise, create a parking lot
131  *        struct based on a parking lot configuration and return a reference to the new one.
132  *
133  * \param cfg The configuration being used as a reference to build the parking lot from.
134  * \param dynamic non-zero if creating a dynamic parking lot with this. Don't replace existing parking lots. Ever.
135  *
136  * \retval A reference to the new parking lot
137  * \retval NULL if it was not found and could not be be allocated
138  *
139  * \note The parking lot will need to be unreffed if it ever falls out of scope
140  * \note The parking lot will automatically be added to the parking lot container if needed as part of this process
141  */
142 struct parking_lot *parking_lot_build_or_update(struct parking_lot_cfg *cfg, int dynamic);
143
144 /*!
145  * \since 12.0.0
146  * \brief Remove a parking lot from the usable lists if it is no longer involved in any calls and no configuration currently claims it
147  *
148  * \param lot Which parking lot is being checked for elimination
149  *
150  * \retval 0 if the parking lot was removed
151  * \retval -1 if the parking lot wasn't removed.
152  *
153  * \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
154  *       a parking lot no longer existing in configurations.
155  */
156 int parking_lot_remove_if_unused(struct parking_lot *lot);
157
158 /*!
159  * \since 12.0.0
160  * \brief Create a new parking bridge
161  *
162  * \param bridge_lot Parking lot which the new bridge should be based on
163  *
164  * \retval NULL if the bridge can not be created
165  * \retval Newly created parking bridge
166  */
167 struct ast_bridge *bridge_parking_new(struct parking_lot *bridge_lot);
168
169 /*!
170  * \since 12.0.0
171  * \brief Get a reference to a parking lot's bridge. If it doesn't exist, create it and get a reference.
172  *
173  * \param lot Which parking lot we need the bridge from. This parking lot must be locked before calling this function.
174  *
175  * \retval A reference to the ast_bridge associated with the parking lot
176  * \retval NULL if it didn't already have a bridge and one couldn't be created
177  *
178  * \note This bridge will need to be unreffed if it ever falls out of scope.
179  */
180 struct ast_bridge *parking_lot_get_bridge(struct parking_lot *lot);
181
182 /*!
183  * \since 12.0.0
184  * \brief Get an available parking space within a parking lot.
185  *
186  * \param lot Which parking lot we are getting a space from
187  * \param target_override If there is a specific slot we want, provide it here and we'll start from that position
188  *
189  * \retval -1 if No slot can be found
190  * \retval integer value of parking space selected
191  *
192  * \note lot should be locked before this is called and unlocked only after a parked_user with the space
193  *       returned has been added to the parking lot.
194  */
195 int parking_lot_get_space(struct parking_lot *lot, int target_override);
196
197 /*!
198  * \since 12.0.0
199  * \brief Determine if there is a parked user in a parking space and pull it from the parking lot if there is.
200  *
201  * \param lot Parking lot being pulled from
202  * \param target If < 0   search for the first occupied space in the parking lot
203  *               If >= 0  Only pull from the indicated target
204  *
205  * \retval NULL if no parked user could be pulled from the requested parking lot at the requested parking space
206  * \retval reference to the requested parked user
207  *
208  * \note The parked user will be removed from parking lot as part of this process
209  * \note Remove this reference with ao2_cleanup once it falls out of scope.
210  */
211 struct parked_user *parking_lot_retrieve_parked_user(struct parking_lot *lot, int target);
212
213 /*!
214  * \since 12.0.0
215  * \brief Apply features based on the parking lot feature options
216  *
217  * \param chan Which channel's feature set is being modified
218  * \param lot parking lot which establishes the features used
219  * \param recipient_mode AST_FEATURE_FLAG_BYCALLER if the user is the retriever
220  *                       AST_FEATURE_FLAG_BYCALLEE if the user is the parkee
221  */
222 void parked_call_retrieve_enable_features(struct ast_channel *chan, struct parking_lot *lot, int recipient_mode);
223
224 /*!
225  * \since 12.0.0
226  * \brief Set necessary bridge roles on a channel that is about to enter a parking lot
227  *
228  * \param chan Entering channel
229  * \param lot The parking lot the channel will be entering
230  * \param force_ringing Use ringing instead of music on hold
231  *
232  * \retval 0 on success
233  * \retval non-zero on failure
234  */
235 int parking_channel_set_roles(struct ast_channel *chan, struct parking_lot *lot, int force_ringing);
236
237 /*!
238  * \since 12.0.0
239  * \brief custom callback function for ast_bridge_channel_queue_playfile which plays a parking space
240  *        and optionally hangs up the call afterwards based on the payload in playfile.
241  */
242 void say_parking_space(struct ast_bridge_channel *bridge_channel, const char *payload);
243
244 /*!
245  * \since 12.0.0
246  * \brief Setup timeout interval feature on an ast_bridge_features for parking
247  *
248  * \param features The ast_bridge_features we are establishing the interval hook on
249  * \param user The parked_user receiving the timeout duration limits
250  */
251 void parking_set_duration(struct ast_bridge_features *features, struct parked_user *user);
252
253 /*!
254  * \since 12.0.0
255  * \brief Get a pointer to the parking lot container for purposes such as iteration
256  *
257  * \retval pointer to the parking lot container.
258  */
259 struct ao2_container *get_parking_lot_container(void);
260
261 /*!
262  * \since 12.0.0
263  * \brief Find a parking lot based on its name
264  *
265  * \param lot_name Name of the parking lot sought
266  *
267  * \retval The parking lot if found
268  * \retval NULL if no parking lot with the name specified exists
269  *
270  * \note ao2_cleanup this reference when you are done using it or you'll cause leaks.
271  */
272 struct parking_lot *parking_lot_find_by_name(const char *lot_name);
273
274 /*!
275  * \since 12.0.0
276  * \brief Create a dynamic parking lot
277  *
278  * \param name Dynamic parking lot name to create
279  * \param chan Channel parkee to get dynamic parking lot parameters from
280  *
281  * \retval dynamically created parking lot on success
282  * \retval NULL on error
283  *
284  * \note This should be called only after verifying that the named parking lot doesn't already exist in a non-dynamic way.
285  */
286 struct parking_lot *parking_create_dynamic_lot(const char *name, struct ast_channel *chan);
287
288 #if defined(TEST_FRAMEWORK)
289 /*!
290  * \since 12.0.0
291  * \brief Create a dynamic parking lot without respect to whether they are enabled by configuration
292  *
293  * \param name Dynamic parking lot name to create
294  * \param chan Channel parkee to get the dynamic parking lot parameters from
295  *
296  * \retval dynamically created parking lot on success
297  * \retval NULL on error
298  *
299  * \note This should be called only after verifying that the named parking lot doesn't already exist in a non-dynamic way.
300  */
301 struct parking_lot *parking_create_dynamic_lot_forced(const char *name, struct ast_channel *chan);
302 #endif
303
304 /*!
305  * \since 12.0.0
306  * \brief Find parking lot name from channel
307  *
308  * \param chan The channel we want the parking lot name for
309  *
310  * \retval name of the channel's assigned parking lot if it is defined by the channel in some way
311  * \retval name of the default parking lot if it is not
312  *
313  * \note Channel needs to be locked while the returned string is in use.
314  */
315 const char *find_channel_parking_lot_name(struct ast_channel *chan);
316
317 /*!
318  * \since 12.0.0
319  * \brief Flattens a dial string so that it can be written to/found from PBX extensions
320  *
321  * \param peername unflattened dial string. This will be flattened in place.
322  */
323 void flatten_dial_string(char *dialstring);
324
325 /*!
326  * \since 12.0.0
327  * \brief Set a channel's position in the PBX after timeout using the parking lot settings
328  *
329  * \param pu Parked user who is entering/reentering the PBX
330  * \param lot Parking lot the user was removed from.
331  *
332  * \retval 0 Position set successfully
333  * \retval -1 Failed to set the position
334  */
335 int comeback_goto(struct parked_user *pu, struct parking_lot *lot);
336
337 /*!
338  * \since 12.0.0
339  * \brief Add extensions for a parking lot configuration
340  *
341  * \param lot_cfg parking lot configuration to generate extensions for
342  *
343  * \retval 0 on success
344  * \retval non-zero on failure
345  */
346 int parking_lot_cfg_create_extensions(struct parking_lot_cfg *lot_cfg);
347
348 /*!
349  * \since 12.0.0
350  * \brief Remove extensions belonging to a parking lot configuration
351  *
352  * \param lot_cfg parking lot configuratin to remove extensions from
353  *
354  * \note This will not remove extensions registered non-exclusively even
355  *       if those extensions were registered by lot_cfg. Those are only
356  *       purged on a res_parking module reload.
357  */
358 void parking_lot_cfg_remove_extensions(struct parking_lot_cfg *lot_cfg);
359
360 /*!
361  * \since 12.0.0
362  * \brief Pull a parked user out of its parking lot. Use this when you don't want to use the parked user afterwards.
363  * \param user The parked user being pulled.
364  *
365  * \retval 0 on success
366  * \retval -1 if the user didn't have its parking lot set
367  */
368 int unpark_parked_user(struct parked_user *user);
369
370 /*!
371  * \since 12.0.0
372  * \brief Publish a stasis parked call message for the channel indicating failure to park.
373  *
374  * \param parkee channel belonging to the failed parkee
375  */
376 void publish_parked_call_failure(struct ast_channel *parkee);
377
378 /*!
379  * \since 12.0.0
380  * \brief Publish a stasis parked call message for a given parked user
381  *
382  * \param pu pointer to a parked_user that we are generating the message for
383  * \param event_type What parked call event type is provoking this message
384  */
385 void publish_parked_call(struct parked_user *pu, enum ast_parked_call_event_type event_type);
386
387 /*!
388  * \since 12.0.0
389  * \brief Setup a parked call on a parking bridge without needing to parse appdata
390  *
391  */
392 struct ast_bridge *park_common_setup(struct ast_channel *parkee, struct ast_channel *parker,
393                 const char *lot_name, const char *comeback_override,
394                 int use_ringing, int randomize, int time_limit, int silence_announcements);
395
396 /*!
397  * \since 12.0.0
398  * \brief Function to prepare a channel for parking by determining which parking bridge should
399  *        be used, setting up a park common datastore so that the parking bridge will have access
400  *        to necessary parking information when joining, and applying various bridge roles to the
401  *        channel.
402  *
403  * \param parkee The channel being preparred for parking
404  * \param parker The channel initiating the park; may be the parkee as well. May be NULL.
405  * \param app_data arguments supplied to the Park application. May be NULL.
406  * \param silence_announcements optional pointer to an integer where we want to store the silence option flag
407  *        this value should be initialized to 0 prior to calling park_common_setup.
408  *
409  * \retval reference to a parking bridge if successful
410  * \retval NULL on failure
411  *
412  * \note ao2_cleanup this reference when you are done using it or you'll cause leaks.
413  */
414 struct ast_bridge *park_application_setup(struct ast_channel *parkee, struct ast_channel *parker,
415         const char *app_data, int *silence_announcements);
416
417 struct park_common_datastore {
418         char *parker_uuid;           /*!< Unique ID of the channel parking the call. */
419         char *parker_dial_string;    /*!< Dial string that we would attempt to call when timing out when comebacktoorigin=yes */
420         char *comeback_override;     /*!< Optional goto string for where to send the call after we are done */
421         int randomize;               /*!< Pick a parking space to enter on at random */
422         int time_limit;              /*!< time limit override. -1 values don't override, 0 for unlimited time, >0 for custom time limit in seconds */
423         int silence_announce;        /*!< Used when a call parks itself to keep it from hearing the parked call announcement */
424 };
425
426 /*!
427  * \since 12.0.0
428  * \brief Get a copy of the park_common_datastore from a channel that is being parked
429  *
430  * \param parkee The channel entering parking with the datastore we are checking
431  *
432  * \retval Pointer to a copy of the park common datastore for parkee if it could be cloned. This needs to be free'd with park_common_datastore free.
433  * \retval NULL if the park_common_datastore could not be copied off of the channel.
434  */
435 struct park_common_datastore *get_park_common_datastore_copy(struct ast_channel *parkee);
436
437 /*!
438  * \since 12.0.0
439  * \brief Free a park common datastore struct
440  *
441  * \param datastore The park_common_datastore being free'd. (NULL tolerant)
442  */
443 void park_common_datastore_free(struct park_common_datastore *datastore);
444
445 /*!
446  * \since 12.0.0
447  * \brief Notify metermaids that we've changed an extension
448  *
449  * \param exten Extension of the call parked/unparked
450  * \param context Context of the call parked/unparked
451  * \param state new device state
452  */
453 void parking_notify_metermaids(int exten, const char *context, enum ast_device_state state);
454
455 /*!
456  * \since 12.0.0
457  * \brief Check global configuration to see if dynamic parking is enabled
458  *
459  * \retval 1 if dynamic parking is enabled
460  * \retval 0 if dynamic parking is disabled
461  */
462 int parking_dynamic_lots_enabled(void);
463
464 /*!
465  * \since 12.0.0
466  * \brief Execution function for the parking application
467  *
468  * \param chan ast_channel entering the application
469  * \param data arguments to the application
470  *
471  * \retval 0 the application executed in such a way that the channel should proceed in the dial plan
472  * \retval -1 the channel should no longer proceed through the dial plan
473  *
474  * \note this function should only be used to register the parking application and not generally to park calls.
475  */
476 int park_app_exec(struct ast_channel *chan, const char *data);
477
478 /*!
479  * \since 12.0.0
480  * \brief Execution function for the parked call application
481  *
482  * \param chan ast_channel entering the application
483  * \param data arguments to the application
484  *
485  * \retval 0 the application executed in such a way that the channel should proceed in the dial plan
486  * \retval -1 the channel should no longer proceed through the dial plan
487  */
488 int parked_call_app_exec(struct ast_channel *chan, const char *data);
489
490 /*!
491  * \since 12.0.0
492  * \brief Execution function for the park and retrieve application
493  *
494  * \param chan ast_channel entering the application
495  * \param data arguments to the application
496  *
497  * \retval 0 the application executed in such a way that the channel should proceed in the dial plan
498  * \retval -1 the channel should no longer proceed through the dial plan
499  *
500  * \note this function should only be used to register the park and announce application and not generally to park and announce.
501  */
502 int park_and_announce_app_exec(struct ast_channel *chan, const char *data);
503
504 /*!
505  * \since 12.0.0
506  * \brief Register CLI commands
507  *
508  * \retval 0 if successful
509  * \retval -1 on failure
510  */
511 int load_parking_ui(void);
512
513 /*!
514  * \since 12.0.0
515  * \brief Unregister CLI commands
516  */
517 void unload_parking_ui(void);
518
519 /*!
520  * \since 12.0.0
521  * \brief Register manager actions and setup subscriptions for stasis events
522  */
523 int load_parking_manager(void);
524
525 /*!
526  * \since 12.0.0
527  * \brief Unregister manager actions and remove subscriptions for stasis events
528  */
529 void unload_parking_manager(void);
530
531 /*!
532  * \since 12.0.0
533  * \brief Register bridge features for parking
534  *
535  * \retval 0 on success
536  * \retval -1 on failure
537  */
538 int load_parking_bridge_features(void);
539
540 /*!
541  * \since 12.0.0
542  * \brief Unregister features registered by load_parking_bridge_features
543  */
544 void unload_parking_bridge_features(void);
545
546 /*!
547  * \since 12.0.0
548  * \brief Register Parking devstate handler
549  */
550 int load_parking_devstate(void);
551
552 /*!
553  * \since 12.0.0
554  * \brief Unregister Parking devstate handler
555  */
556 void unload_parking_devstate(void);
557
558 /*!
559  * \since 12.0.0
560  * \brief Register parking unit tests
561  *
562  * \retval 0 on success
563  * \retval nonzero on failure
564  */
565 int load_parking_tests(void);
566
567 /*!
568  * \since 12.0.0
569  * \brief Unregister parking unit tests
570  *
571  * \return Nothing
572  */
573 void unload_parking_tests(void);