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 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 *parker;      /*!< Snapshot of the channel that parked the call at the time of parking */
 104         struct ast_channel_snapshot *retriever;   /*!< Snapshot of the channel that retrieves a parked call */
 105         struct timeval start;                     /*!< When the call was parked */
 106         int parking_space;                        /*!< Which parking space is used */
 107         char comeback[AST_MAX_CONTEXT];           /*!< Where to go on parking timeout */
 108         char blindtransfer[AST_CHANNEL_NAME];     /*!< What the BLINDTRANSFER variable was at the time of entry */
 109         unsigned int time_limit;                  /*!< How long this specific channel may remain in the parking lot before timing out */
 110         struct parking_lot *lot;                  /*!< Which parking lot the user is parked to */
 111         enum park_call_resolution resolution;     /*!< How did the parking session end? If the call is in a bridge, lock parked_user before checking/setting */
 112 };
 113
 114 /*!
 115  * \since 12.0.0
 116  * \brief If a parking lot exists in the parking lot list already, update its status to match the provided
 117  *        configuration and return a reference return a reference to it. Otherwise, create a parking lot
 118  *        struct based on a parking lot configuration and return a reference to the new one.
 119  *
 120  * \param cfg The configuration being used as a reference to build the parking lot from.
 121  * \param dynamic non-zero if creating a dynamic parking lot with this. Don't replace existing parking lots. Ever.
 122  *
 123  * \retval A reference to the new parking lot
 124  * \retval NULL if it was not found and could not be be allocated
 125  *
 126  * \note The parking lot will need to be unreffed if it ever falls out of scope
 127  * \note The parking lot will automatically be added to the parking lot container if needed as part of this process
 128  */
 129 struct parking_lot *parking_lot_build_or_update(struct parking_lot_cfg *cfg, int dynamic);
 130
 131 /*!
 132  * \since 12.0.0
 133  * \brief Remove a parking lot from the usable lists if it is no longer involved in any calls and no configuration currently claims it
 134  *
 135  * \param lot Which parking lot is being checked for elimination
 136  *
 137  * \retval 0 if the parking lot was removed
 138  * \retval -1 if the parking lot wasn't removed.
 139  *
 140  * \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
 141  *       a parking lot no longer existing in configurations.
 142  */
 143 int parking_lot_remove_if_unused(struct parking_lot *lot);
 144
 145 /*!
 146  * \since 12.0.0
 147  * \brief Create a new parking bridge
 148  *
 149  * \param bridge_lot Parking lot which the new bridge should be based on
 150  *
 151  * \retval NULL if the bridge can not be created
 152  * \retval Newly created parking bridge
 153  */
 154 struct ast_bridge *bridge_parking_new(struct parking_lot *bridge_lot);
 155
 156 /*!
 157  * \since 12.0.0
 158  * \brief Get a reference to a parking lot's bridge. If it doesn't exist, create it and get a reference.
 159  *
 160  * \param lot Which parking lot we need the bridge from. This parking lot must be locked before calling this function.
 161  *
 162  * \retval A reference to the ast_bridge associated with the parking lot
 163  * \retval NULL if it didn't already have a bridge and one couldn't be created
 164  *
 165  * \note This bridge will need to be unreffed if it ever falls out of scope.
 166  */
 167 struct ast_bridge *parking_lot_get_bridge(struct parking_lot *lot);
 168
 169 /*!
 170  * \since 12.0.0
 171  * \brief Get an available parking space within a parking lot.
 172  *
 173  * \param lot Which parking lot we are getting a space from
 174  * \param target_override If there is a specific slot we want, provide it here and we'll start from that position
 175  *
 176  * \retval -1 if No slot can be found
 177  * \retval integer value of parking space selected
 178  *
 179  * \note lot should be locked before this is called and unlocked only after a parked_user with the space
 180  *       returned has been added to the parking lot.
 181  */
 182 int parking_lot_get_space(struct parking_lot *lot, int target_override);
 183
 184 /*!
 185  * \since 12.0.0
 186  * \brief Determine if there is a parked user in a parking space and pull it from the parking lot if there is.
 187  *
 188  * \param lot Parking lot being pulled from
 189  * \param target If < 0   search for the first occupied space in the parking lot
 190  *               If >= 0  Only pull from the indicated target
 191  *
 192  * \retval NULL if no parked user could be pulled from the requested parking lot at the requested parking space
 193  * \retval reference to the requested parked user
 194  *
 195  * \note The parked user will be removed from parking lot as part of this process
 196  * \note Remove this reference with ao2_cleanup once it falls out of scope.
 197  */
 198 struct parked_user *parking_lot_retrieve_parked_user(struct parking_lot *lot, int target);
 199
 200 /*!
 201  * \since 12.0.0
 202  * \brief Apply features based on the parking lot feature options
 203  *
 204  * \param chan Which channel's feature set is being modified
 205  * \param lot parking lot which establishes the features used
 206  * \param recipient_mode AST_FEATURE_FLAG_BYCALLER if the user is the retriever
 207  *                       AST_FEATURE_FLAG_BYCALLEE if the user is the parkee
 208  */
 209 void parked_call_retrieve_enable_features(struct ast_channel *chan, struct parking_lot *lot, int recipient_mode);
 210
 211 /*!
 212  * \since 12.0.0
 213  * \brief Set necessary bridge roles on a channel that is about to enter a parking lot
 214  *
 215  * \param chan Entering channel
 216  * \param lot The parking lot the channel will be entering
 217  * \param force_ringing Use ringing instead of music on hold
 218  */
 219 void parking_channel_set_roles(struct ast_channel *chan, struct parking_lot *lot, int force_ringing);
 220
 221 /*!
 222  * \since 12.0.0
 223  * \brief custom callback function for ast_bridge_channel_queue_playfile which plays a parking space
 224  *        and optionally hangs up the call afterwards based on the payload in playfile.
 225  */
 226 void say_parking_space(struct ast_bridge_channel *bridge_channel, const char *payload);
 227
 228 /*!
 229  * \since 12.0.0
 230  * \brief Setup timeout interval feature on an ast_bridge_features for parking
 231  *
 232  * \param features The ast_bridge_features we are establishing the interval hook on
 233  * \param user The parked_user receiving the timeout duration limits
 234  */
 235 void parking_set_duration(struct ast_bridge_features *features, struct parked_user *user);
 236
 237 /*!
 238  * \since 12.0.0
 239  * \brief Get a pointer to the parking lot container for purposes such as iteration
 240  *
 241  * \retval pointer to the parking lot container.
 242  */
 243 struct ao2_container *get_parking_lot_container(void);
 244
 245 /*!
 246  * \since 12.0.0
 247  * \brief Find a parking lot based on its name
 248  *
 249  * \param lot_name Name of the parking lot sought
 250  *
 251  * \retval The parking lot if found
 252  * \retval NULL if no parking lot with the name specified exists
 253  *
 254  * \note ao2_cleanup this reference when you are done using it or you'll cause leaks.
 255  */
 256 struct parking_lot *parking_lot_find_by_name(const char *lot_name);
 257
 258 /*!
 259  * \since 12.0.0
 260  * \brief Create a dynamic parking lot
 261  *
 262  * \param name Dynamic parking lot name to create
 263  * \param chan Channel parkee to get dynamic parking lot parameters from
 264  *
 265  * \retval dynamically created parking lot on success
 266  * \retval NULL on error
 267  *
 268  * \note This should be called only after verifying that the named parking lot doesn't already exist in a non-dynamic way.
 269  *       The parking lots container should be locked before verifying and remain locked until after this function is called.
 270  */
 271 struct parking_lot *parking_create_dynamic_lot(const char *name, struct ast_channel *chan);
 272
 273 /*!
 274  * \since 12.0.0
 275  * \brief Find parking lot name from channel
 276  *
 277  * \param chan The channel we want the parking lot name for
 278  *
 279  * \retval name of the channel's assigned parking lot if it is defined by the channel in some way
 280  * \retval name of the default parking lot if it is not
 281  *
 282  * \note Channel needs to be locked while the returned string is in use.
 283  */
 284 const char *find_channel_parking_lot_name(struct ast_channel *chan);
 285
 286 /*!
 287  * \since 12.0.0
 288  * \brief Flattens a peer name so that it can be written to/found from PBX extensions
 289  *
 290  * \param peername unflattened peer name. This will be flattened in place, so expect it to change.
 291  */
 292 void flatten_peername(char *peername);
 293
 294 /*!
 295  * \since 12.0.0
 296  * \brief Set a channel's position in the PBX after timeout using the parking lot settings
 297  *
 298  * \param pu Parked user who is entering/reentering the PBX
 299  * \param lot Parking lot the user was removed from.
 300  *
 301  * \retval 0 Position set successfully
 302  * \retval -1 Failed to set the position
 303  */
 304 int comeback_goto(struct parked_user *pu, struct parking_lot *lot);
 305
 306 /*!
 307  * \since 12.0.0
 308  * \brief Add extensions for a parking lot configuration
 309  *
 310  * \param lot_cfg parking lot configuration to generate extensions for
 311  *
 312  * \retval 0 on success
 313  * \retval non-zero on failure
 314  */
 315 int parking_lot_cfg_create_extensions(struct parking_lot_cfg *lot_cfg);
 316
 317 /*!
 318  * \since 12.0.0
 319  * \brief Remove extensions belonging to a parking lot configuration
 320  *
 321  * \param lot_cfg parking lot configuratin to remove extensions from
 322  *
 323  * \note This will not remove extensions registered non-exclusively even
 324  *       if those extensions were registered by lot_cfg. Those are only
 325  *       purged on a res_parking module reload.
 326  */
 327 void parking_lot_cfg_remove_extensions(struct parking_lot_cfg *lot_cfg);
 328
 329 /*!
 330  * \since 12.0.0
 331  * \brief Pull a parked user out of its parking lot. Use this when you don't want to use the parked user afterwards.
 332  * \param user The parked user being pulled.
 333  *
 334  * \retval 0 on success
 335  * \retval -1 if the user didn't have its parking lot set
 336  */
 337 int unpark_parked_user(struct parked_user *user);
 338
 339 /*!
 340  * \since 12.0.0
 341  * \brief Publish a stasis parked call message for the channel indicating failure to park.
 342  *
 343  * \param parkee channel belonging to the failed parkee
 344  */
 345 void publish_parked_call_failure(struct ast_channel *parkee);
 346
 347 /*!
 348  * \since 12.0.0
 349  * \brief Publish a stasis parked call message for a given parked user
 350  *
 351  * \param pu pointer to a parked_user that we are generating the message for
 352  * \param event_type What parked call event type is provoking this message
 353  */
 354 void publish_parked_call(struct parked_user *pu, enum ast_parked_call_event_type event_type);
 355
 356 /*!
 357  * \since 12.0.0
 358  * \brief Setup a parked call on a parking bridge without needing to parse appdata
 359  *
 360  */
 361 struct ast_bridge *park_common_setup(struct ast_channel *parkee, struct ast_channel *parker,
 362                 const char *lot_name, const char *comeback_override,
 363                 int use_ringing, int randomize, int time_limit, int silence_announcements);
 364
 365 /*!
 366  * \since 12.0.0
 367  * \brief Function to prepare a channel for parking by determining which parking bridge should
 368  *        be used, setting up a park common datastore so that the parking bridge will have access
 369  *        to necessary parking information when joining, and applying various bridge roles to the
 370  *        channel.
 371  *
 372  * \param parkee The channel being preparred for parking
 373  * \param parker The channel initiating the park; may be the parkee as well
 374  * \param app_data arguments supplied to the Park application. May be NULL.
 375  * \param silence_announcements optional pointer to an integer where we want to store the silence option flag
 376  *        this value should be initialized to 0 prior to calling park_common_setup.
 377  *
 378  * \retval reference to a parking bridge if successful
 379  * \retval NULL on failure
 380  *
 381  * \note ao2_cleanup this reference when you are done using it or you'll cause leaks.
 382  */
 383 struct ast_bridge *park_application_setup(struct ast_channel *parkee, struct ast_channel *parker,
 384         const char *app_data, int *silence_announcements);
 385
 386 struct park_common_datastore {
 387         char *parker_uuid;           /*!< Unique ID of the channel parking the call. */
 388         char *comeback_override;     /*!< Optional goto string for where to send the call after we are done */
 389         int randomize;               /*!< Pick a parking space to enter on at random */
 390         int time_limit;              /*!< time limit override. -1 values don't override, 0 for unlimited time, >0 for custom time limit in seconds */
 391         int silence_announce;        /*!< Used when a call parks itself to keep it from hearing the parked call announcement */
 392 };
 393
 394 /*!
 395  * \since 12.0.0
 396  * \brief Function that pulls data from the park common datastore on a channel in order to apply it to
 397  *        the parked user struct upon bridging.
 398  *
 399  * \param parkee The channel entering parking with the datastore we are checking
 400  * \param parker_uuid pointer to a string pointer for placing the name of the channel that parked parkee
 401  * \param comeback_override pointer to a string pointer for placing the comeback_override option
 402  * \param randomize integer pointer to an integer for placing the randomize option
 403  * \param time_limit integer pointer to an integer for placing the time limit option
 404  * \param silence_announce pointer to an integer for placing the silence_announcements option
 405  */
 406 void get_park_common_datastore_data(struct ast_channel *parkee,
 407                 char **parker_uuid, char **comeback_override,
 408                 int *randomize, int *time_limit, int *silence_announce);
 409
 410 /*!
 411  * \since 12.0.0
 412  * \brief Notify metermaids that we've changed an extension
 413  *
 414  * \param exten Extension of the call parked/unparked
 415  * \param context Context of the call parked/unparked
 416  * \param state new device state
 417  */
 418 void parking_notify_metermaids(int exten, const char *context, enum ast_device_state state);
 419
 420 /*!
 421  * \since 12.0.0
 422  * \brief Check global configuration to see if dynamic parking is enabled
 423  *
 424  * \retval 1 if dynamic parking is enabled
 425  * \retval 0 if dynamic parking is disabled
 426  */
 427 int parking_dynamic_lots_enabled(void);
 428
 429 /*!
 430  * \since 12.0.0
 431  * \brief Execution function for the parking application
 432  *
 433  * \param chan ast_channel entering the application
 434  * \param data arguments to the application
 435  *
 436  * \retval 0 the application executed in such a way that the channel should proceed in the dial plan
 437  * \retval -1 the channel should no longer proceed through the dial plan
 438  *
 439  * \note this function should only be used to register the parking application and not generally to park calls.
 440  */
 441 int park_app_exec(struct ast_channel *chan, const char *data);
 442
 443 /*!
 444  * \since 12.0.0
 445  * \brief Execution function for the parked call application
 446  *
 447  * \param chan ast_channel entering the application
 448  * \param data arguments to the application
 449  *
 450  * \retval 0 the application executed in such a way that the channel should proceed in the dial plan
 451  * \retval -1 the channel should no longer proceed through the dial plan
 452  */
 453 int parked_call_app_exec(struct ast_channel *chan, const char *data);
 454
 455 /*!
 456  * \since 12.0.0
 457  * \brief Execution function for the park and retrieve application
 458  *
 459  * \param chan ast_channel entering the application
 460  * \param data arguments to the application
 461  *
 462  * \retval 0 the application executed in such a way that the channel should proceed in the dial plan
 463  * \retval -1 the channel should no longer proceed through the dial plan
 464  *
 465  * \note this function should only be used to register the park and announce application and not generally to park and announce.
 466  */
 467 int park_and_announce_app_exec(struct ast_channel *chan, const char *data);
 468
 469 /*!
 470  * \since 12.0.0
 471  * \brief Register CLI commands
 472  *
 473  * \retval 0 if successful
 474  * \retval -1 on failure
 475  */
 476 int load_parking_ui(void);
 477
 478 /*!
 479  * \since 12.0.0
 480  * \brief Unregister CLI commands
 481  */
 482 void unload_parking_ui(void);
 483
 484 /*!
 485  * \since 12.0.0
 486  * \brief Register manager actions and setup subscriptions for stasis events
 487  */
 488 int load_parking_manager(void);
 489
 490 /*!
 491  * \since 12.0.0
 492  * \brief Unregister manager actions and remove subscriptions for stasis events
 493  */
 494 void unload_parking_manager(void);
 495
 496 /*!
 497  * \since 12.0.0
 498  * \brief Register bridge features for parking
 499  *
 500  * \retval 0 on success
 501  * \retval -1 on failure
 502  */
 503 int load_parking_bridge_features(void);
 504
 505 /*!
 506  * \since 12.0.0
 507  * \brief Unregister features registered by load_parking_bridge_features
 508  */
 509 void unload_parking_bridge_features(void);
 510
 511 /*!
 512  * \since 12.0.0
 513  * \brief Register Parking devstate handler
 514  */
 515 int load_parking_devstate(void);
 516
 517 /*!
 518  * \since 12.0.0
 519  * \brief Unregister Parking devstate handler
 520  */
 521 void unload_parking_devstate(void);