Asterisk - The Open Source Telephony Project GIT-master-67613d1
Data Structures | Macros | Enumerations | Functions
parking.h File Reference

Call Parking API. More...

#include "asterisk/stringfields.h"
#include "asterisk/bridge.h"
Include dependency graph for parking.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ast_parked_call_payload
 A parked call message payload. More...
 
struct  ast_parking_bridge_feature_fn_table
 A function table providing parking functionality to the Bridging API Bridging API and other consumers. More...
 

Macros

#define DEFAULT_PARKINGLOT   "default"
 The default parking lot. More...
 
#define PARK_APPLICATION   "Park"
 The default parking application that Asterisk expects. More...
 
#define PARKING_MODULE_VERSION   1
 

Enumerations

enum  ast_parked_call_event_type {
  PARKED_CALL = 0 , PARKED_CALL_TIMEOUT , PARKED_CALL_GIVEUP , PARKED_CALL_UNPARKED ,
  PARKED_CALL_FAILED , PARKED_CALL_SWAP
}
 Defines the type of parked call message being published. More...
 

Functions

struct ast_parked_call_payloadast_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. More...
 
struct stasis_message_typeast_parked_call_type (void)
 accessor for the parked call stasis message type More...
 
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. More...
 
int ast_parking_is_exten_park (const char *context, const char *exten)
 Determine if the context/exten is a "parking" extension. More...
 
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. More...
 
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. More...
 
int ast_parking_provider_registered (void)
 Check whether a parking provider is registered. More...
 
int ast_parking_register_bridge_features (struct ast_parking_bridge_feature_fn_table *fn_table)
 Register a parking provider. More...
 
struct stasis_topicast_parking_topic (void)
 accessor for the parking stasis topic More...
 
int ast_parking_unregister_bridge_features (const char *module_name)
 Unregister the current parking provider. More...
 

Detailed Description

Call Parking API.

Author
Jonathan Rose jrose.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Definition in file parking.h.

Macro Definition Documentation

◆ DEFAULT_PARKINGLOT

#define DEFAULT_PARKINGLOT   "default"

The default parking lot.

Definition at line 40 of file parking.h.

◆ PARK_APPLICATION

#define PARK_APPLICATION   "Park"

The default parking application that Asterisk expects.

Definition at line 35 of file parking.h.

◆ PARKING_MODULE_VERSION

#define PARKING_MODULE_VERSION   1

Definition at line 119 of file parking.h.

Enumeration Type Documentation

◆ ast_parked_call_event_type

Defines the type of parked call message being published.

Since
12
Enumerator
PARKED_CALL 
PARKED_CALL_TIMEOUT 
PARKED_CALL_GIVEUP 
PARKED_CALL_UNPARKED 
PARKED_CALL_FAILED 
PARKED_CALL_SWAP 

Definition at line 46 of file parking.h.

46 {
47 PARKED_CALL = 0,
53};
@ 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

Function Documentation

◆ ast_parked_call_payload_create()

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.

Since
12
Parameters
event_typeWhat kind of parked call event is happening
parkee_snapshotchannel snapshot of the parkee
parker_dial_stringdialstring used when the call times out
retriever_snapshotchannel snapshot of the retriever (NULL allowed)
parkinglotname of the parking lot where the parked call is parked
parkingspacewhat numerical parking space the parked call is parked in
timeouthow long the parked call can remain at the point this snapshot is created before timing out
durationhow long the parked call has currently been parked
Return values
NULLif the parked call payload can't be allocated
Returns
reference to a newly created parked call payload

Definition at line 82 of file parking.c.

87{
89
90 payload = ao2_alloc(sizeof(*payload), parked_call_payload_destructor);
91 if (!payload) {
92 return NULL;
93 }
94
95 if (ast_string_field_init(payload, 32)) {
96 return NULL;
97 }
98
99 payload->event_type = event_type;
100
101 ao2_ref(parkee_snapshot, +1);
102 payload->parkee = parkee_snapshot;
103
104 if (retriever_snapshot) {
105 ao2_ref(retriever_snapshot, +1);
106 payload->retriever = retriever_snapshot;
107 }
108
109 if (parkinglot) {
110 ast_string_field_set(payload, parkinglot, parkinglot);
111 }
112
113 if (parker_dial_string) {
114 ast_string_field_set(payload, parker_dial_string, parker_dial_string);
115 }
116
117 payload->parkingspace = parkingspace;
118 payload->timeout = timeout;
119 payload->duration = duration;
120
121 /* Bump the ref count by one since RAII_VAR is going to eat one when we leave. */
122 ao2_ref(payload, +1);
123 return payload;
124}
#define ao2_cleanup(obj)
Definition: astobj2.h:1934
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
#define ao2_alloc(data_size, destructor_fn)
Definition: astobj2.h:409
static void parked_call_payload_destructor(void *obj)
Destructor for parked_call_payload objects.
Definition: parking.c:73
#define NULL
Definition: resample.c:96
#define ast_string_field_set(x, field, data)
Set a field to a simple string value.
Definition: stringfields.h:521
#define ast_string_field_init(x, size)
Initialize a field pool and fields.
Definition: stringfields.h:359
A parked call message payload.
Definition: parking.h:59
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941

References ao2_alloc, ao2_cleanup, ao2_ref, ast_string_field_init, ast_string_field_set, ast_parked_call_payload::duration, ast_parked_call_payload::event_type, NULL, parked_call_payload_destructor(), ast_parked_call_payload::parker_dial_string, ast_parked_call_payload::parkinglot, ast_parked_call_payload::parkingspace, RAII_VAR, and ast_parked_call_payload::timeout.

Referenced by parked_call_payload_from_failure(), and parked_call_payload_from_parked_user().

◆ ast_parking_blind_transfer_park()

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.

Parameters
parkerThe ast_bridge_channel object that is initiating the parking
contextThe context to blind transfer to
extenThe extension to blind transfer to
parked_channel_cbExecute the following function on the channel that gets parked
parked_channel_dataData for the parked_channel_cb
Note
If the bridge parker is in has more than one other occupant, the entire bridge will be parked using a Local channel
This is safe to be called outside of the Bridging API Bridging API.
Return values
0on success
non-zeroon error

Definition at line 143 of file parking.c.

146{
149
150 if (!table || !table->parking_blind_transfer_park) {
151 return -1;
152 }
153
154 if (table->module) {
155 SCOPED_MODULE_USE(table->module);
156 return table->parking_blind_transfer_park(parker, context, exten, parked_channel_cb, parked_channel_data);
157 }
158
159 return table->parking_blind_transfer_park(parker, context, exten, parked_channel_cb, parked_channel_data);
160}
#define ao2_global_obj_ref(holder)
Get a reference to the object stored in the global holder.
Definition: astobj2.h:918
static char * table
Definition: cdr_odbc.c:55
#define SCOPED_MODULE_USE(module)
Definition: module.h:665
struct ast_parking_bridge_feature_fn_table parking_provider
A function table providing parking functionality to the Bridging API Bridging API and other consumers...
Definition: parking.h:127

References ao2_cleanup, ao2_global_obj_ref, voicemailpwcheck::context, parking_provider, RAII_VAR, SCOPED_MODULE_USE, and table.

Referenced by __analog_ss_thread(), analog_ss_thread(), and try_parking().

◆ ast_parking_is_exten_park()

int ast_parking_is_exten_park ( const char *  context,
const char *  exten 
)

Determine if the context/exten is a "parking" extension.

Return values
0if the extension is not a parking extension
1if the extension is a parking extension

Definition at line 179 of file parking.c.

180{
183
184 if (!table || !table->parking_is_exten_park) {
185 return -1;
186 }
187
188 if (table->module) {
189 SCOPED_MODULE_USE(table->module);
190 return table->parking_is_exten_park(context, exten);
191 }
192
193 return table->parking_is_exten_park(context, exten);
194}

References ao2_cleanup, ao2_global_obj_ref, voicemailpwcheck::context, parking_provider, RAII_VAR, SCOPED_MODULE_USE, and table.

Referenced by __analog_ss_thread(), and analog_ss_thread().

◆ ast_parking_park_bridge_channel()

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.

Parameters
parkeeThe channel in the bridge to be parked.
parkee_uuidThe UUID of the channel being packed.
parker_uuidThe UUID of the channel performing the park.
app_dataData to pass to the Park application
Note
This must be called within the context of the Bridging API Bridging API. External entities should not call this method directly, but should instead use the direct call parking method or the blind transfer method.
Return values
0on success
non-zeroon error

Definition at line 126 of file parking.c.

127{
130
131 if (!table || !table->parking_park_bridge_channel) {
132 return -1;
133 }
134
135 if (table->module) {
136 SCOPED_MODULE_USE(table->module);
137 return table->parking_park_bridge_channel(parkee, parkee_uuid, parker_uuid, app_data);
138 }
139
140 return table->parking_park_bridge_channel(parkee, parkee_uuid, parker_uuid, app_data);
141}

References ao2_cleanup, ao2_global_obj_ref, ast_parked_call_payload::parkee, parking_provider, RAII_VAR, SCOPED_MODULE_USE, and table.

Referenced by bridge_channel_park().

◆ ast_parking_park_call()

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.

Parameters
parkerThe bridge_channel parking the bridge
[out]extenOptional. The parking exten to access the parking lot.
lengthOptional. If exten is specified, the size of the buffer.
Note
This is safe to be called outside of the Bridging API Bridging API.
The exten parameter was intended to return the extension the channel or bridge was parked at if the call succeeds. However, accessing that information is very difficult to do with the new asynchronous design. That information may not be available anywhere by the time this function currently returns.
Return values
0on success
non-zeroon error

Definition at line 162 of file parking.c.

163{
166
167 if (!table || !table->parking_park_call) {
168 return -1;
169 }
170
171 if (table->module) {
172 SCOPED_MODULE_USE(table->module);
173 return table->parking_park_call(parker, exten, length);
174 }
175
176 return table->parking_park_call(parker, exten, length);
177}

References ao2_cleanup, ao2_global_obj_ref, parking_provider, RAII_VAR, SCOPED_MODULE_USE, and table.

◆ ast_parking_provider_registered()

int ast_parking_provider_registered ( void  )

Check whether a parking provider is registered.

Return values
0if there is no parking provider regsistered
1if there is a parking provider regsistered

Definition at line 241 of file parking.c.

References ao2_cleanup, ao2_global_obj_ref, parking_provider, RAII_VAR, and table.

Referenced by __analog_ss_thread(), analog_ss_thread(), bridge_channel_park(), and try_parking().

◆ ast_parking_register_bridge_features()

int ast_parking_register_bridge_features ( struct ast_parking_bridge_feature_fn_table fn_table)

Register a parking provider.

Parameters
fn_tableThe ast_parking_bridge_feature_fn_table to register
Return values
0on success
-1on error

Definition at line 196 of file parking.c.

197{
200
201 if (fn_table->module_version != PARKING_MODULE_VERSION) {
202 ast_log(AST_LOG_WARNING, "Parking module provided incorrect parking module "
203 "version: %u (expected: %d)\n", fn_table->module_version, PARKING_MODULE_VERSION);
204 return -1;
205 }
206
207 if (wrapper) {
208 ast_log(AST_LOG_WARNING, "Parking provider already registered by %s!\n",
209 wrapper->module_name);
210 return -1;
211 }
212
213 wrapper = ao2_alloc(sizeof(*wrapper), NULL);
214 if (!wrapper) {
215 return -1;
216 }
217 *wrapper = *fn_table;
218
220 return 0;
221}
#define ast_log
Definition: astobj2.c:42
#define ao2_global_obj_replace_unref(holder, obj)
Replace an ao2 object in the global holder, throwing away any old object.
Definition: astobj2.h:901
#define AST_LOG_WARNING
#define PARKING_MODULE_VERSION
Definition: parking.h:119
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

References ao2_alloc, ao2_cleanup, ao2_global_obj_ref, ao2_global_obj_replace_unref, ast_log, AST_LOG_WARNING, ast_parking_bridge_feature_fn_table::module_version, NULL, PARKING_MODULE_VERSION, parking_provider, and RAII_VAR.

Referenced by load_parking_bridge_features().

◆ ast_parking_unregister_bridge_features()

int ast_parking_unregister_bridge_features ( const char *  module_name)

Unregister the current parking provider.

Parameters
module_nameThe module name of the provider to unregister
Return values
0if the parking provider module_name was unregsistered
-1on error

Definition at line 223 of file parking.c.

224{
227
228 if (!wrapper) {
229 return -1;
230 }
231
232 if (strcmp(wrapper->module_name, module_name)) {
233 ast_log(AST_LOG_WARNING, "%s has not registered the parking provider\n", module_name);
234 return -1;
235 }
236
238 return 0;
239}
#define ao2_global_obj_release(holder)
Release the ao2 object held in the global holder.
Definition: astobj2.h:859

References ao2_cleanup, ao2_global_obj_ref, ao2_global_obj_release, ast_log, AST_LOG_WARNING, parking_provider, and RAII_VAR.

Referenced by unload_parking_bridge_features().