Asterisk - The Open Source Telephony Project GIT-master-85241bd
parking.h
Go to the documentation of this file.
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#ifndef ASTERISK_PARKING_H
27#define ASTERISK_PARKING_H
28
30#include "asterisk/bridge.h"
31
32/*!
33 * \brief The default parking application that Asterisk expects.
34 */
35#define PARK_APPLICATION "Park"
36
37/*!
38 * \brief The default parking lot
39 */
40#define DEFAULT_PARKINGLOT "default"
41
42/*!
43 * \brief Defines the type of parked call message being published
44 * \since 12
45 */
53};
54
55/*!
56 * \brief A parked call message payload
57 * \since 12
58 */
60 struct ast_channel_snapshot *parkee; /*!< Snapshot of the channel that is parked */
61 struct ast_channel_snapshot *retriever; /*!< Snapshot of the channel that retrieved the call (may be NULL) */
62 enum ast_parked_call_event_type event_type; /*!< Reason for issuing the parked call message */
63 long unsigned int timeout; /*!< Time remaining before the call times out (seconds ) */
64 long unsigned int duration; /*!< How long the parkee has been parked (seconds) */
65 unsigned int parkingspace; /*!< Which Parking Space the parkee occupies */
67 AST_STRING_FIELD(parkinglot); /*!< Name of the parking lot used to park the parkee */
68 AST_STRING_FIELD(parker_dial_string); /*!< The device string used for call control on parking timeout */
69 );
70};
71
72struct ast_exten;
73
74/*!
75 * \brief Constructor for parked_call_payload objects
76 * \since 12
77 *
78 * \param event_type What kind of parked call event is happening
79 * \param parkee_snapshot channel snapshot of the parkee
80 * \param parker_dial_string dialstring used when the call times out
81 * \param retriever_snapshot channel snapshot of the retriever (NULL allowed)
82 * \param parkinglot name of the parking lot where the parked call is parked
83 * \param parkingspace what numerical parking space the parked call is parked in
84 * \param timeout how long the parked call can remain at the point this snapshot is created before timing out
85 * \param duration how long the parked call has currently been parked
86 *
87 * \retval NULL if the parked call payload can't be allocated
88 * \return reference to a newly created parked call payload
89 */
91 struct ast_channel_snapshot *parkee_snapshot, const char *parker_dial_string,
92 struct ast_channel_snapshot *retriever_snapshot, const char *parkinglot,
93 unsigned int parkingspace, unsigned long int timeout, unsigned long int duration);
94
95/*! \addtogroup StasisTopicsAndMessages
96 * @{
97 */
98
99/*!
100 * \brief accessor for the parking stasis topic
101 * \since 12
102 *
103 * \retval NULL if the parking topic hasn't been created or has been disabled
104 * \return a pointer to the parking topic
105 */
106struct stasis_topic *ast_parking_topic(void);
107
108/*!
109 * \brief accessor for the parked call stasis message type
110 * \since 12
111 *
112 * \retval NULL if the parking topic hasn't been created or has been canceled
113 * \return a pointer to the parked call message type
114 */
116
117/*! @} */
118
119#define PARKING_MODULE_VERSION 1
120
121struct ast_module_info;
122
123/*!
124 * \brief A function table providing parking functionality to the \ref AstBridging
125 * Bridging API and other consumers
126 */
128
129 /*!
130 * \brief The version of this function table. If the ABI for this table
131 * changes, the module version (/ref PARKING_MODULE_VERSION) should be
132 * incremented.
133 */
134 unsigned int module_version;
135
136 /*!
137 * \brief The name of the module that provides this parking functionality
138 */
139 const char *module_name;
140
141 /*!
142 * \brief Determine if the context/exten is a "parking" extension
143 *
144 * \retval 0 if the extension is not a parking extension
145 * \retval 1 if the extension is a parking extension
146 */
147 int (* parking_is_exten_park)(const char *context, const char *exten);
148
149 /*!
150 * \brief Park the bridge and/or callers that this channel is in
151 *
152 * \param parker The \p bridge_channel parking the bridge
153 * \param exten Optional. The extension the channel or bridge was parked at if the
154 * call succeeds.
155 * \param length Optional. If \c exten is specified, the size of the buffer.
156 *
157 * \note This is safe to be called outside of the \ref AstBridging Bridging API.
158 *
159 * \retval 0 on success
160 * \retval non-zero on error
161 */
162 int (* parking_park_call)(struct ast_bridge_channel *parker, char *exten, size_t length);
163
164 /*!
165 * \brief Perform a blind transfer to a parking extension.
166 *
167 * \param parker The \p bridge_channel object that is initiating the parking
168 * \param context The context to blind transfer to
169 * \param exten The extension to blind transfer to
170 * \param parked_channel_cb Execute the following function on the channel that gets parked
171 * \param parked_channel_data Data for the parked_channel_cb
172 *
173 * \note If the bridge \p parker is in has more than one other occupant, the entire
174 * bridge will be parked using a Local channel
175 *
176 * \note This is safe to be called outside of the \ref AstBridging Bridging API.
177 *
178 * \retval 0 on success
179 * \retval non-zero on error
180 */
181 int (* parking_blind_transfer_park)(struct ast_bridge_channel *parker, const char *context,
182 const char *exten, transfer_channel_cb parked_channel_cb, struct transfer_channel_data *parked_channel_data);
183
184 /*!
185 * \brief Perform a direct park on a channel in a bridge.
186 *
187 * \param parkee The channel in the bridge to be parked.
188 * \param parkee_uuid The UUID of the channel being packed.
189 * \param parker_uuid The UUID of the channel performing the park.
190 * \param app_data Data to pass to the Park application
191 *
192 * \note This must be called within the context of the \ref AstBridging Bridging API.
193 * External entities should not call this method directly, but should instead use
194 * the direct call parking method or the blind transfer method.
195 *
196 * \retval 0 on success
197 * \retval non-zero on error
198 */
199 int (* parking_park_bridge_channel)(struct ast_bridge_channel *parkee, const char *parkee_uuid, const char *parker_uuid, const char *app_data);
200
201 /*! \brief The module info for the module registering this parking provider */
203};
204
205/*!
206 * \brief Determine if the context/exten is a "parking" extension
207 *
208 * \retval 0 if the extension is not a parking extension
209 * \retval 1 if the extension is a parking extension
210 */
211int ast_parking_is_exten_park(const char *context, const char *exten);
212
213/*!
214 * \brief Park the bridge and/or callers that this channel is in
215 *
216 * \param parker The bridge_channel parking the bridge
217 * \param[out] exten Optional. The parking exten to access the parking lot.
218 * \param length Optional. If \c exten is specified, the size of the buffer.
219 *
220 * \note This is safe to be called outside of the \ref AstBridging Bridging API.
221 *
222 * \note The exten parameter was intended to return the extension the channel or
223 * bridge was parked at if the call succeeds. However, accessing that information
224 * is very difficult to do with the new asynchronous design. That information may
225 * not be available anywhere by the time this function currently returns.
226 *
227 * \retval 0 on success
228 * \retval non-zero on error
229 */
230int ast_parking_park_call(struct ast_bridge_channel *parker, char *exten, size_t length);
231
232/*!
233 * \brief Perform a blind transfer to a parking extension.
234 *
235 * \param parker The ast_bridge_channel object that is initiating the parking
236 * \param context The context to blind transfer to
237 * \param exten The extension to blind transfer to
238 * \param parked_channel_cb Execute the following function on the channel that gets parked
239 * \param parked_channel_data Data for the parked_channel_cb
240 *
241 * \note If the bridge \p parker is in has more than one other occupant, the entire
242 * bridge will be parked using a Local channel
243 *
244 * \note This is safe to be called outside of the \ref AstBridging Bridging API.
245 *
246 * \retval 0 on success
247 * \retval non-zero on error
248 */
249int ast_parking_blind_transfer_park(struct ast_bridge_channel *parker, const char *context,
250 const char *exten, transfer_channel_cb parked_channel_cb, struct transfer_channel_data *parked_channel_data);
251
252/*!
253 * \brief Perform a direct park on a channel in a bridge.
254 *
255 * \param parkee The channel in the bridge to be parked.
256 * \param parkee_uuid The UUID of the channel being packed.
257 * \param parker_uuid The UUID of the channel performing the park.
258 * \param app_data Data to pass to the Park application
259 *
260 * \note This must be called within the context of the \ref AstBridging Bridging API.
261 * External entities should not call this method directly, but should instead use
262 * the direct call parking method or the blind transfer method.
263 *
264 * \retval 0 on success
265 * \retval non-zero on error
266 */
267int ast_parking_park_bridge_channel(struct ast_bridge_channel *parkee, const char *parkee_uuid, const char *parker_uuid, const char *app_data);
268
269/*!
270 * \brief Register a parking provider
271 *
272 * \param fn_table The \ref ast_parking_bridge_feature_fn_table to register
273 *
274 * \retval 0 on success
275 * \retval -1 on error
276 */
278
279/*!
280 * \brief Unregister the current parking provider
281 *
282 * \param module_name The module name of the provider to unregister
283 *
284 * \retval 0 if the parking provider \c module_name was unregsistered
285 * \retval -1 on error
286 */
287int ast_parking_unregister_bridge_features(const char *module_name);
288
289/*!
290 * \brief Check whether a parking provider is registered
291 *
292 * \retval 0 if there is no parking provider regsistered
293 * \retval 1 if there is a parking provider regsistered
294 */
296
297#endif /* ASTERISK_PARKING_H */
Bridging API.
void(* transfer_channel_cb)(struct ast_channel *chan, struct transfer_channel_data *user_data, enum ast_transfer_type transfer_type)
Callback function type called during blind transfers.
Definition: bridge.h:1143
struct stasis_topic * ast_parking_topic(void)
accessor for the parking stasis topic
Definition: parking.c:67
struct stasis_message_type * ast_parked_call_type(void)
accessor for the parked call stasis message type
int ast_parking_park_call(struct ast_bridge_channel *parker, char *exten, size_t length)
Park the bridge and/or callers that this channel is in.
Definition: parking.c:162
int ast_parking_blind_transfer_park(struct ast_bridge_channel *parker, const char *context, const char *exten, transfer_channel_cb parked_channel_cb, struct transfer_channel_data *parked_channel_data)
Perform a blind transfer to a parking extension.
Definition: parking.c:143
int ast_parking_unregister_bridge_features(const char *module_name)
Unregister the current parking provider.
Definition: parking.c:223
int ast_parking_is_exten_park(const char *context, const char *exten)
Determine if the context/exten is a "parking" extension.
Definition: parking.c:179
int ast_parking_park_bridge_channel(struct ast_bridge_channel *parkee, const char *parkee_uuid, const char *parker_uuid, const char *app_data)
Perform a direct park on a channel in a bridge.
Definition: parking.c:126
struct ast_parked_call_payload * ast_parked_call_payload_create(enum ast_parked_call_event_type event_type, struct ast_channel_snapshot *parkee_snapshot, const char *parker_dial_string, struct ast_channel_snapshot *retriever_snapshot, const char *parkinglot, unsigned int parkingspace, unsigned long int timeout, unsigned long int duration)
Constructor for parked_call_payload objects.
Definition: parking.c:82
int ast_parking_register_bridge_features(struct ast_parking_bridge_feature_fn_table *fn_table)
Register a parking provider.
Definition: parking.c:196
ast_parked_call_event_type
Defines the type of parked call message being published.
Definition: parking.h:46
@ PARKED_CALL
Definition: parking.h:47
@ PARKED_CALL_TIMEOUT
Definition: parking.h:48
@ PARKED_CALL_UNPARKED
Definition: parking.h:50
@ PARKED_CALL_FAILED
Definition: parking.h:51
@ PARKED_CALL_GIVEUP
Definition: parking.h:49
@ PARKED_CALL_SWAP
Definition: parking.h:52
int ast_parking_provider_registered(void)
Check whether a parking provider is registered.
Definition: parking.c:241
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:341
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
Structure that contains information regarding a channel in a bridge.
Structure representing a snapshot of channel state.
ast_exten: An extension The dialplan is saved as a linked list with each context having it's own link...
Definition: pbx.c:237
A parked call message payload.
Definition: parking.h:59
unsigned int parkingspace
Definition: parking.h:65
long unsigned int duration
Definition: parking.h:64
const ast_string_field parkinglot
Definition: parking.h:69
struct ast_channel_snapshot * retriever
Definition: parking.h:61
long unsigned int timeout
Definition: parking.h:63
struct ast_channel_snapshot * parkee
Definition: parking.h:60
enum ast_parked_call_event_type event_type
Definition: parking.h:62
const ast_string_field parker_dial_string
Definition: parking.h:69
A function table providing parking functionality to the Bridging API Bridging API and other consumers...
Definition: parking.h:127
int(* parking_blind_transfer_park)(struct ast_bridge_channel *parker, const char *context, const char *exten, transfer_channel_cb parked_channel_cb, struct transfer_channel_data *parked_channel_data)
Perform a blind transfer to a parking extension.
Definition: parking.h:181
unsigned int module_version
The version of this function table. If the ABI for this table changes, the module version (/ref PARKI...
Definition: parking.h:134
const char * module_name
The name of the module that provides this parking functionality.
Definition: parking.h:139
int(* parking_park_bridge_channel)(struct ast_bridge_channel *parkee, const char *parkee_uuid, const char *parker_uuid, const char *app_data)
Perform a direct park on a channel in a bridge.
Definition: parking.h:199
struct ast_module * module
The module info for the module registering this parking provider.
Definition: parking.h:202
int(* parking_park_call)(struct ast_bridge_channel *parker, char *exten, size_t length)
Park the bridge and/or callers that this channel is in.
Definition: parking.h:162
int(* parking_is_exten_park)(const char *context, const char *exten)
Determine if the context/exten is a "parking" extension.
Definition: parking.h:147
AO2 object that wraps data for transfer_channel_cb.
Definition: bridge.h:1119