Asterisk - The Open Source Telephony Project  18.5.0
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.

Referenced by reload_config().

◆ PARK_APPLICATION

#define PARK_APPLICATION   "Park"

The default parking application that Asterisk expects.

Definition at line 35 of file parking.h.

Referenced by load_parking_applications(), parking_is_exten_park(), parking_lot_cfg_create_extensions(), and unload_parking_applications().

◆ PARKING_MODULE_VERSION

#define PARKING_MODULE_VERSION   1

Definition at line 119 of file parking.h.

Referenced by ast_parking_register_bridge_features().

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.

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
referenceto a newly created parked call payload

Definition at line 82 of file parking.c.

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::parkingspace, RAII_VAR, and timeout.

Referenced by parked_call_payload_from_failure(), and parked_call_payload_from_parked_user().

87 {
88  RAII_VAR(struct ast_parked_call_payload *, payload, NULL, ao2_cleanup);
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) {
111  }
112 
113  if (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 }
static char parkinglot[AST_MAX_CONTEXT]
Definition: chan_mgcp.c:163
static int timeout
Definition: cdr_mysql.c:86
A parked call message payload.
Definition: parking.h:59
#define NULL
Definition: resample.c:96
enum ast_parked_call_event_type event_type
Definition: parking.h:62
long unsigned int duration
Definition: parking.h:64
#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:911
#define ast_string_field_init(x, size)
Initialize a field pool and fields.
Definition: stringfields.h:353
#define ao2_ref(o, delta)
Definition: astobj2.h:464
unsigned int parkingspace
Definition: parking.h:65
#define ao2_alloc(data_size, destructor_fn)
Definition: astobj2.h:411
#define ao2_cleanup(obj)
Definition: astobj2.h:1958
const ast_string_field parker_dial_string
Definition: parking.h:69
static void parked_call_payload_destructor(void *obj)
Destructor for parked_call_payload objects.
Definition: parking.c:73
#define ast_string_field_set(x, field, data)
Set a field to a simple string value.
Definition: stringfields.h:514

◆ 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 bridge_channel object that is initiating the parking
contextThe context to blind transfer to
extenThe extension 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.

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

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

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 }
static char exten[AST_MAX_EXTENSION]
Definition: chan_alsa.c:118
#define ao2_global_obj_ref(holder)
Definition: astobj2.h:925
static char * table
Definition: cdr_odbc.c:58
A function table providing parking functionality to the Bridging API Bridging API and other consumers...
Definition: parking.h:127
#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:911
struct ast_parking_bridge_feature_fn_table parking_provider
#define SCOPED_MODULE_USE(module)
Definition: module.h:665
#define ao2_cleanup(obj)
Definition: astobj2.h:1958
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:116

◆ 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.

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

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

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 }
static char exten[AST_MAX_EXTENSION]
Definition: chan_alsa.c:118
#define ao2_global_obj_ref(holder)
Definition: astobj2.h:925
static char * table
Definition: cdr_odbc.c:58
A function table providing parking functionality to the Bridging API Bridging API and other consumers...
Definition: parking.h:127
#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:911
struct ast_parking_bridge_feature_fn_table parking_provider
#define SCOPED_MODULE_USE(module)
Definition: module.h:665
#define ao2_cleanup(obj)
Definition: astobj2.h:1958
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:116

◆ 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.

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

Referenced by bridge_channel_park().

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 }
#define ao2_global_obj_ref(holder)
Definition: astobj2.h:925
static char * table
Definition: cdr_odbc.c:58
A function table providing parking functionality to the Bridging API Bridging API and other consumers...
Definition: parking.h:127
#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:911
struct ast_parking_bridge_feature_fn_table parking_provider
#define SCOPED_MODULE_USE(module)
Definition: module.h:665
#define ao2_cleanup(obj)
Definition: astobj2.h:1958

◆ 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.

Only, chan_skinny is known to call this function and use the exten parameter for the phone display.

Return values
0on success
non-zeroon error

Definition at line 162 of file parking.c.

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

Referenced by handle_soft_key_event_message(), and handle_stimulus_message().

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 }
static char exten[AST_MAX_EXTENSION]
Definition: chan_alsa.c:118
#define ao2_global_obj_ref(holder)
Definition: astobj2.h:925
static char * table
Definition: cdr_odbc.c:58
A function table providing parking functionality to the Bridging API Bridging API and other consumers...
Definition: parking.h:127
#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:911
struct ast_parking_bridge_feature_fn_table parking_provider
#define SCOPED_MODULE_USE(module)
Definition: module.h:665
#define ao2_cleanup(obj)
Definition: astobj2.h:1958

◆ 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(), handle_soft_key_event_message(), handle_stimulus_message(), mgcp_ss(), and try_parking().

242 {
245 
246  return !!table;
247 }
#define ao2_global_obj_ref(holder)
Definition: astobj2.h:925
static char * table
Definition: cdr_odbc.c:58
A function table providing parking functionality to the Bridging API Bridging API and other consumers...
Definition: parking.h:127
#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:911
struct ast_parking_bridge_feature_fn_table parking_provider
#define ao2_cleanup(obj)
Definition: astobj2.h:1958

◆ 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.

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().

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_WARNING
Definition: logger.h:279
#define ao2_global_obj_ref(holder)
Definition: astobj2.h:925
#define NULL
Definition: resample.c:96
A function table providing parking functionality to the Bridging API Bridging API and other consumers...
Definition: parking.h:127
#define ast_log
Definition: astobj2.c:42
#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:911
#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
struct ast_parking_bridge_feature_fn_table parking_provider
#define ao2_alloc(data_size, destructor_fn)
Definition: astobj2.h:411
#define ao2_global_obj_replace_unref(holder, obj)
Definition: astobj2.h:908
#define ao2_cleanup(obj)
Definition: astobj2.h:1958

◆ ast_parking_unregister_bridge_features()

int ast_parking_unregister_bridge_features ( const char *  module_name)

Unregister the current parking provider.

Parameters
Themodule 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.

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().

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 AST_LOG_WARNING
Definition: logger.h:279
#define ao2_global_obj_ref(holder)
Definition: astobj2.h:925
A function table providing parking functionality to the Bridging API Bridging API and other consumers...
Definition: parking.h:127
#define ast_log
Definition: astobj2.c:42
#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:911
#define ao2_global_obj_release(holder)
Definition: astobj2.h:865
struct ast_parking_bridge_feature_fn_table parking_provider
#define ao2_cleanup(obj)
Definition: astobj2.h:1958