astxx::manager::connection Class Reference

#include <astxx/manager/connection.h>

Collaboration diagram for astxx::manager::connection:

Detailed Description

An Asterisk Manager connection.

This class is the main point of access to the manager API. Once connected you can send commands to and read events from Asterisk.

Commands can be sent using the connection::send_action() or connection::send_action_async() function. The connection::send_action() function blocks and waits for asterisk to send a response before returning. The '()' operator is overloaded to behave as both of these functions depending on which arguments are passed to it.

 action::logoff logoff;
 message::response r = logoff(connection); // action::logoff will throw
                                           // exceptions for 'Error'
                                           // responses from Asterisk

 message::response r = connection(action::logoff()); // no processing
                                                     // of the response
                                                     // will be done

 async_response_handler handler();
 action::logoff logoff;
 connection(logoff, handler);

To recieve events you must register an event handler (via connection::register_event()) then trigger the handler by calling connection::process_events() (optionally after connection::wait_event() which will wait for an event and put it in the event queue if the queue is empty). The handler can be a function, functor, or member function that takes message::event object as a parameter. To unregister an event use the boost::signals::connection::disconnect() method from the boost::signals::connection object returned by connection::register_event().

Your main application loop could look something like this:

 connection.wait_event();
 connection.pump_messages();
 connection.process_events();

 connection.process_responses(); // if you are sending actions asychronously.

Warning:: This library is not thread safe. Only one thread of execution should call functions in the library at a time.

Definition at line 99 of file connection.h.


Public Types
typedef boost::function< void(message::event)>	event_handler_t
typedef std::map< std::string, boost::shared_ptr < boost::signal< void(message::event)> > >	event_handlers_t
typedef std::queue < message::event >	events_t
typedef boost::function< void(message::response)>	response_handler_t
typedef std::queue < response_handler_t >	response_handlers_t
typedef std::queue < message::response >	responses_t
Public Member Functions
void	connect (const std::string &host="", unsigned short port=0)
	Connect to the given host on the given port.
	connection (const std::string &host, unsigned short port=5038)
	Initilize a connection to the given host on the given port.
void	disconnect ()
	Close our connection to Asterisk.
bool	is_connected () const
	Check if we are connected.
std::string	name () const
	Get the name of the manager we are connected to.
void	operator() (const manager::basic_action &command, response_handler_t handler)
	Send a command to Asterisk and recieve the response asynchronously.
message::response	operator() (const manager::basic_action &command)
	Send a command to Asterisk.
void	process_events ()
	Process all the events in the queue.
void	process_responses ()
	Process asynchronous responses.
void	pump_messages ()
	Read messages from the network until there is no more data waiting.
boost::signals::connection	register_event (const std::string &e, boost::function< void(message::event)> f)
	Register an event handler.
message::response	send_action (const manager::basic_action &command)
	Send a command to Asterisk.
void	send_action_async (const manager::basic_action &command, response_handler_t handler)
	Send a command to Asterisk and recieve the response asynchronously.
std::string	version () const
	Get the version string for the manager we are connected to.
void	wait_event ()
	Wait for an event and put it in the queue.
void	wait_response ()
	Wait for a response and puts it in the queue.

Constructor & Destructor Documentation

astxx::manager::connection::connection	(	const std::string &	host,
		unsigned short	port = `5038`
	)

Initilize a connection to the given host on the given port.

Parameters:

	host	the host to connect to
	port	the port to connect on

Exceptions:

boost::system::system_error

if there is a problem connecting to or resolving a host

Definition at line 81 of file connection.cc.

References connect().

Member Function Documentation

void astxx::manager::connection::connect	(	const std::string &	host = `""`,
		unsigned short	port = `0`
	)

Connect to the given host on the given port.

Parameters:

	host	the host to connect to
	port	the port to connect on

Note:: If host is not given, the host and port given on construction will be used. If port is not given, the port given on construction wll be used. In order for the given port to be used, host must be specified.

Calling this function will disconnect any existing connections.

Exceptions:

boost::system::system_error

if there is a problem connecting to or resolving a host

Definition at line 99 of file connection.cc.

Referenced by connection().

void astxx::manager::connection::disconnect ( )

Close our connection to Asterisk.

Note:: Upon destruction the connection to the manager should be properly closed automatically.

Definition at line 142 of file connection.cc.

bool astxx::manager::connection::is_connected ( ) const

Check if we are connected.

Returns:: whether we are connected or not

Definition at line 150 of file connection.cc.

void astxx::manager::connection::operator()	(	const manager::basic_action &	command,
		response_handler_t	handler
	)

Send a command to Asterisk and recieve the response asynchronously.

Parameters:

	command	the command to send
	handler	the handler function/functor

This function executes connection::send_action_async().

Definition at line 238 of file connection.cc.

References send_action_async().

message::response astxx::manager::connection::operator() ( const manager::basic_action & command )

Send a command to Asterisk.

Parameters:

command

the command to send

This function executes connection::send_action().

Definition at line 228 of file connection.cc.

References send_action().

void astxx::manager::connection::process_events ( )

Process all the events in the queue.

This function executes all the registered event handlers that match events in the queue.

Definition at line 386 of file connection.cc.

References astxx::manager::message::basic_message< message_traits >::main_header().

void astxx::manager::connection::process_responses ( )

Process asynchronous responses.

This function executes handlers for responses waiting.

This function is called by connection::send_action() while waiting for a response.

Definition at line 427 of file connection.cc.

void astxx::manager::connection::pump_messages ( )

Read messages from the network until there is no more data waiting.

This function does not block. It reads messages from the network until there are no more waiting and places them in the proper queues. If there are no messages waiting it will simply return.

Definition at line 457 of file connection.cc.

boost::signals::connection astxx::manager::connection::register_event	(	const std::string &	e,
		boost::function< void(message::event)>	f
	)

Register an event handler.

Parameters:

	e	the name of the event (case sensitive, use a blank string to match all events)
	f	the callback function pointer or functor

This function is used to register an event handler. The name of the event passed here is case sensitive and must match exactly what Asterisk will return. Pass a blank string to match all events.

The event handler can be unregistered using the boost::signals::connection object that is returned.

The signature of the handler should be:

 void event_handler(message::event e); // e is the event

See also:

connection::process_events()

connection::wait_event()

connection::pump_messages()

Returns:: a boost::signals::connection object that can be used to manager this event handler

Definition at line 487 of file connection.cc.

message::response astxx::manager::connection::send_action ( const manager::basic_action & command )

Send a command to Asterisk.

Parameters:

command

the command to send

This function sends a command to Asterisk and also waits for a response which is then returned.

If error handling is desired, pass the result of this function to basic_action::handle_response() which will throw exceptions for most errors the manager returns. The basic_action::operator()() function does this automatically.

 action::example example;
 message::response r = example(connection); // send this action over
                                            // "connection" and handle
                                            // errors before returning
                                            // the response

Note:: This function blocks while waiting for a response.

See also:: connection::operator()(const basic_action&, response_handler_t)
connection::operator()(const basic_action&)

Returns:: the response from asterisk

Definition at line 180 of file connection.cc.

References send_action_async(), and astxx::manager::response_waiter::wait().

Referenced by operator()().

void astxx::manager::connection::send_action_async	(	const manager::basic_action &	command,
		response_handler_t	handler
	)

Send a command to Asterisk and recieve the response asynchronously.

Parameters:

	command	the command to send
	handler	the handler function/functor

This function sends a command to Asterisk and then returns. The given handler will be called with the response to this action when it is recieved.

The handler function pointer/functor will be copied unless you use boost::ref to prevent it. You can use boost::bind to pass member functions as response handlers.

The signature of the handler should be:

 void response_handler(message::response r); // r is the response

The connection::process_responses() function triggers response handler execution. See its documentation for circumstances when it will be called.

See also:

connection::send_action()

connection::operator()(const basic_action&, response_handler_t)

connection::process_responses()

Returns:: the response from asterisk

Definition at line 212 of file connection.cc.

References astxx::manager::basic_action::action(), astxx::manager::basic_action::action_id(), and astxx::manager::message::basic_message< message_traits >::format().

Referenced by operator()(), and send_action().

void astxx::manager::connection::wait_event ( )

Wait for an event and put it in the queue.

This function waits for an event.

Note:: If there is alreay an event waiting, this function will not block.

Definition at line 415 of file connection.cc.

void astxx::manager::connection::wait_response ( )

Wait for a response and puts it in the queue.

This function waits for a response.

Note:: If there is alreay a response waiting, this function will not block.

Definition at line 446 of file connection.cc.

The documentation for this class was generated from the following files:

include/astxx/manager/connection.h
src/manager/connection.cc

astxx::manager::connection Class Reference

Detailed Description

Public Types

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation