dd8a67bf28789a044c58134510bd4d92675ec770
[asterisk/asterisk.git] / include / asterisk / 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 API
22  *
23  * \author Jonathan Rose <jrose@digium.com>
24  */
25
26 #include "asterisk/stringfields.h"
27
28 #define PARK_APPLICATION "Park"
29
30 /*!
31  * \brief Defines the type of parked call message being published
32  * \since 12
33  */
34 enum ast_parked_call_event_type {
35         PARKED_CALL = 0,
36         PARKED_CALL_TIMEOUT,
37         PARKED_CALL_GIVEUP,
38         PARKED_CALL_UNPARKED,
39         PARKED_CALL_FAILED,
40 };
41
42 /*!
43  * \brief A parked call message payload
44  * \since 12
45  */
46 struct ast_parked_call_payload {
47         struct ast_channel_snapshot *parkee;             /*!< Snapshot of the channel that is parked */
48         struct ast_channel_snapshot *retriever;          /*!< Snapshot of the channel that retrieved the call (may be NULL) */
49         enum ast_parked_call_event_type event_type;      /*!< Reason for issuing the parked call message */
50         long unsigned int timeout;                       /*!< Time remaining before the call times out (seconds ) */
51         long unsigned int duration;                      /*!< How long the parkee has been parked (seconds) */
52         unsigned int parkingspace;                       /*!< Which Parking Space the parkee occupies */
53         AST_DECLARE_STRING_FIELDS(
54                 AST_STRING_FIELD(parkinglot);                /*!< Name of the parking lot used to park the parkee */
55                 AST_STRING_FIELD(parker_dial_string);          /*!< The device string used for call control on parking timeout */
56         );
57 };
58
59 struct ast_exten;
60
61 /*!
62  * \brief Constructor for parked_call_payload objects
63  * \since 12
64  *
65  * \param event_type What kind of parked call event is happening
66  * \param parkee_snapshot channel snapshot of the parkee
67  * \param parker_dial_string dialstring used when the call times out
68  * \param retriever_snapshot channel snapshot of the retriever (NULL allowed)
69  * \param parkinglot name of the parking lot where the parked call is parked
70  * \param parkingspace what numerical parking space the parked call is parked in
71  * \param timeout how long the parked call can remain at the point this snapshot is created before timing out
72  * \param duration how long the parked call has currently been parked
73  *
74  * \retval NULL if the parked call payload can't be allocated
75  * \retval reference to a newly created parked call payload
76  */
77 struct ast_parked_call_payload *ast_parked_call_payload_create(enum ast_parked_call_event_type event_type,
78                 struct ast_channel_snapshot *parkee_snapshot, const char *parker_dial_string,
79                 struct ast_channel_snapshot *retriever_snapshot, const char *parkinglot,
80                 unsigned int parkingspace, unsigned long int timeout, unsigned long int duration);
81
82 /*!
83  * \brief accessor for the parking stasis topic
84  * \since 12
85  *
86  * \retval NULL if the parking topic hasn't been created or has been disabled
87  * \retval a pointer to the parking topic
88  */
89 struct stasis_topic *ast_parking_topic(void);
90
91 /*!
92  * \brief accessor for the parked call stasis message type
93  * \since 12
94  *
95  * \retval NULL if the parking topic hasn't been created or has been canceled
96  * \retval a pointer to the parked call message type
97  */
98 struct stasis_message_type *ast_parked_call_type(void);
99
100 /*!
101  * \brief invoke an installable park callback to asynchronously park a bridge_channel in a bridge
102  * \since 12
103  *
104  * \param bridge_channel the bridge channel that initiated parking
105  * \parkee_uuid channel id of the channel being parked
106  * \parker_uuid channel id of the channel that initiated parking
107  * \param app_data string of application data that might be applied to parking
108  */
109 void ast_bridge_channel_park(struct ast_bridge_channel *bridge_channel,
110         const char *parkee_uuid,
111         const char *parker_uuid,
112         const char *app_data);
113
114 typedef int (*ast_park_blind_xfer_fn)(struct ast_bridge *bridge, struct ast_bridge_channel *parker,
115         struct ast_exten *park_exten);
116
117 /*!
118  * \brief install a callback for handling blind transfers to a parking extension
119  * \since 12
120  *
121  * \param parking_func Function to use for transfers to 'Park' applications
122  */
123 void ast_install_park_blind_xfer_func(ast_park_blind_xfer_fn park_blind_xfer_func);
124
125 /*!
126  * \brief uninstall a callback for handling blind transfers to a parking extension
127  * \since 12
128  */
129 void ast_uninstall_park_blind_xfer_func(void);
130
131 /*!
132  * \brief use the installed park blind xfer func
133  * \since 12
134  *
135  * \param bridge Bridge being transferred from
136  * \param bridge_channel Bridge channel initiating the transfer
137  * \param app_data arguments to the park application
138  *
139  * \retval 0 on success
140  * \retval -1 on failure
141  */
142 int ast_park_blind_xfer(struct ast_bridge *bridge, struct ast_bridge_channel *parker,
143                 struct ast_exten *park_exten);
144
145 typedef void (*ast_bridge_channel_park_fn)(struct ast_bridge_channel *parkee, const char *parkee_uuid,
146         const char *parker_uuid, const char *app_data);
147
148 /*!
149  * \brief Install a function for ast_bridge_channel_park
150  * \since 12
151  *
152  * \param bridge_channel_park_func function callback to use for ast_bridge_channel_park
153  */
154 void ast_install_bridge_channel_park_func(ast_bridge_channel_park_fn bridge_channel_park_func);
155
156 /*!
157  * \brief Uninstall the ast_bridge_channel_park function callback
158  * \since 12
159  */
160 void ast_uninstall_bridge_channel_park_func(void);
161
162
163 /*!
164  * \brief Determines whether a certain extension is a park application extension or not.
165  * \since 12
166  *
167  * \param exten_str string representation of the extension sought
168  * \param chan channel the extension is sought for
169  * \param context context the extension is sought from
170  *
171  * \retval pointer to the extension if the extension is a park extension
172  * \retval NULL if the extension was not a park extension
173  */
174 struct ast_exten *ast_get_parking_exten(const char *exten_str, struct ast_channel *chan, const char *context);