Asterisk - The Open Source Telephony Project  GIT-master-a24979a
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 {
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) {
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 char parkinglot[AST_MAX_CONTEXT]
Definition: chan_mgcp.c:166
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:936

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, 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
static char exten[AST_MAX_EXTENSION]
Definition: chan_alsa.c:122
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:120
#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, context, exten, parking_provider, RAII_VAR, SCOPED_MODULE_USE, and table.

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

◆ 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, context, exten, parking_provider, RAII_VAR, SCOPED_MODULE_USE, and table.

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

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

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.

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, exten, parking_provider, RAII_VAR, SCOPED_MODULE_USE, and table.

Referenced by handle_soft_key_event_message(), and handle_stimulus_message().

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

242 {
245 
246  return !!table;
247 }

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(), and mgcp_ss().

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