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_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. More...
struct stasis_message_type *	ast_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_topic *	ast_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

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

                                {
   PARKED_CALL = 0,
   PARKED_CALL_TIMEOUT,
   PARKED_CALL_GIVEUP,
   PARKED_CALL_UNPARKED,
   PARKED_CALL_FAILED,
   PARKED_CALL_SWAP,
};

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_type	What kind of parked call event is happening
parkee_snapshot	channel snapshot of the parkee
parker_dial_string	dialstring used when the call times out
retriever_snapshot	channel snapshot of the retriever (NULL allowed)
parkinglot	name of the parking lot where the parked call is parked
parkingspace	what numerical parking space the parked call is parked in
timeout	how long the parked call can remain at the point this snapshot is created before timing out
duration	how long the parked call has currently been parked

Return values

NULL	if the parked call payload can't be allocated
reference	to 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().

{
   RAII_VAR(struct ast_parked_call_payload *, payload, NULL, ao2_cleanup);

   payload = ao2_alloc(sizeof(*payload), parked_call_payload_destructor);
   if (!payload) {
      return NULL;
   }

   if (ast_string_field_init(payload, 32)) {
      return NULL;
   }

   payload->event_type = event_type;

   ao2_ref(parkee_snapshot, +1);
   payload->parkee = parkee_snapshot;

   if (retriever_snapshot) {
      ao2_ref(retriever_snapshot, +1);
      payload->retriever = retriever_snapshot;
   }

   if (parkinglot) {
      ast_string_field_set(payload, parkinglot, parkinglot);
   }

   if (parker_dial_string) {
      ast_string_field_set(payload, parker_dial_string, parker_dial_string);
   }

   payload->parkingspace = parkingspace;
   payload->timeout = timeout;
   payload->duration = duration;

   /* Bump the ref count by one since RAII_VAR is going to eat one when we leave. */
   ao2_ref(payload, +1);
   return payload;
}

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

parker	The bridge_channel object that is initiating the parking
context	The context to blind transfer to
exten	The extension to blind transfer to
exten	The extension to blind transfer to
parked_channel_cb	Execute the following function on the channel that gets parked
parked_channel_data	Data 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

0	on success
non-zero	on 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().

{
   RAII_VAR(struct ast_parking_bridge_feature_fn_table *, table,
      ao2_global_obj_ref(parking_provider), ao2_cleanup);

   if (!table || !table->parking_blind_transfer_park) {
      return -1;
   }

   if (table->module) {
      SCOPED_MODULE_USE(table->module);
      return table->parking_blind_transfer_park(parker, context, exten, parked_channel_cb, parked_channel_data);
   }

   return table->parking_blind_transfer_park(parker, context, exten, parked_channel_cb, parked_channel_data);
}

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

0	if the extension is not a parking extension
1	if 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().

{
   RAII_VAR(struct ast_parking_bridge_feature_fn_table *, table,
      ao2_global_obj_ref(parking_provider), ao2_cleanup);

   if (!table || !table->parking_is_exten_park) {
      return -1;
   }

   if (table->module) {
      SCOPED_MODULE_USE(table->module);
      return table->parking_is_exten_park(context, exten);
   }

   return table->parking_is_exten_park(context, exten);
}

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

parkee	The channel in the bridge to be parked.
parkee_uuid	The UUID of the channel being packed.
parker_uuid	The UUID of the channel performing the park.
app_data	Data 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

0	on success
non-zero	on 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().

{
   RAII_VAR(struct ast_parking_bridge_feature_fn_table *, table,
      ao2_global_obj_ref(parking_provider), ao2_cleanup);

   if (!table || !table->parking_park_bridge_channel) {
      return -1;
   }

   if (table->module) {
      SCOPED_MODULE_USE(table->module);
      return table->parking_park_bridge_channel(parkee, parkee_uuid, parker_uuid, app_data);
   }

   return table->parking_park_bridge_channel(parkee, parkee_uuid, parker_uuid, app_data);
}

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

	parker	The bridge_channel parking the bridge
[out]	exten	Optional. The parking exten to access the parking lot.
	length	Optional. 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

0	on success
non-zero	on 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().

{
   RAII_VAR(struct ast_parking_bridge_feature_fn_table *, table,
      ao2_global_obj_ref(parking_provider), ao2_cleanup);

   if (!table || !table->parking_park_call) {
      return -1;
   }

   if (table->module) {
      SCOPED_MODULE_USE(table->module);
      return table->parking_park_call(parker, exten, length);
   }

   return table->parking_park_call(parker, exten, length);
}

ast_parking_provider_registered()

int ast_parking_provider_registered

(

void

)

Check whether a parking provider is registered.

Return values

0	if there is no parking provider regsistered
1	if 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().

{
   RAII_VAR(struct ast_parking_bridge_feature_fn_table *, table,
      ao2_global_obj_ref(parking_provider), ao2_cleanup);

   return !!table;
}

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_table

The ast_parking_bridge_feature_fn_table to register

Return values

0	on success
-1	on 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().

{
   RAII_VAR(struct ast_parking_bridge_feature_fn_table *, wrapper,
      ao2_global_obj_ref(parking_provider), ao2_cleanup);

   if (fn_table->module_version != PARKING_MODULE_VERSION) {
      ast_log(AST_LOG_WARNING, "Parking module provided incorrect parking module "
         "version: %u (expected: %d)\n", fn_table->module_version, PARKING_MODULE_VERSION);
      return -1;
   }

   if (wrapper) {
      ast_log(AST_LOG_WARNING, "Parking provider already registered by %s!\n",
         wrapper->module_name);
      return -1;
   }

   wrapper = ao2_alloc(sizeof(*wrapper), NULL);
   if (!wrapper) {
      return -1;
   }
   *wrapper = *fn_table;

   ao2_global_obj_replace_unref(parking_provider, wrapper);
   return 0;
}

ast_parking_unregister_bridge_features()

int ast_parking_unregister_bridge_features

(

const char *

module_name

)

Unregister the current parking provider.

Parameters

The	module name of the provider to unregister

Return values

0	if the parking provider module_name was unregsistered
-1	on 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().

{
   RAII_VAR(struct ast_parking_bridge_feature_fn_table *, wrapper,
      ao2_global_obj_ref(parking_provider), ao2_cleanup);

   if (!wrapper) {
      return -1;
   }

   if (strcmp(wrapper->module_name, module_name)) {
      ast_log(AST_LOG_WARNING, "%s has not registered the parking provider\n", module_name);
      return -1;
   }

   ao2_global_obj_release(parking_provider);
   return 0;
}