transport.h File Reference

#include <stdint.h>
#include "asterisk/res_aeap.h"

Include dependency graph for transport.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	aeap_transport
	Asterisk external application transport structure to be "derived" by specific transport implementation types. More...
struct	aeap_transport_vtable
	Asterisk external application transport virtual table. More...

Functions
int	aeap_transport_connect (struct aeap_transport *transport, const char *url, const char *protocol, int timeout)
	Connect a transport. More...
struct aeap_transport *	aeap_transport_create (const char *type)
	Create an Asterisk external application transport. More...
struct aeap_transport *	aeap_transport_create_and_connect (const char *type, const char *url, const char *protocol, int timeout)
	Create an Asterisk external application transport, and connect it. More...
void	aeap_transport_destroy (struct aeap_transport *transport)
	Destroy a transport. More...
int	aeap_transport_disconnect (struct aeap_transport *transport)
	Disconnect a transport. More...
int	aeap_transport_is_connected (struct aeap_transport *transport)
	Whether or not the transport is in a connected state. More...
intmax_t	aeap_transport_read (struct aeap_transport *transport, void *buf, intmax_t size, enum AST_AEAP_DATA_TYPE *rtype)
	Read data from the transport. More...
intmax_t	aeap_transport_write (struct aeap_transport *transport, const void *buf, intmax_t size, enum AST_AEAP_DATA_TYPE wtype)
	Write data to the transport. More...

Function Documentation

aeap_transport_connect()

int aeap_transport_connect	(	struct aeap_transport *	transport,
		const char *	url,
		const char *	protocol,
		int	timeout
	)

Connect a transport.

Parameters

transport	The transport to connect
url	The URL to connect to
protocol	The connection protocol to use if applicable
timeout	How long (in milliseconds) to attempt to connect (-1 equals infinite)

Returns

0 on success, or -1 on error

Definition at line 48 of file transport.c.

{
    int res;
 
    SCOPED_MUTEX(rlock, &transport->read_lock);
    SCOPED_MUTEX(wlock, &transport->write_lock);
 
    if (aeap_transport_is_connected(transport)) {
        return 0;
    }
 
    res = transport->vtable->connect(transport, url, protocol, timeout);
    if (!res) {
        transport->connected = 1;
    }
 
    return res;
}

References aeap_transport_is_connected(), aeap_transport_vtable::connect, aeap_transport::connected, aeap_transport::read_lock, SCOPED_MUTEX, url, aeap_transport::vtable, and aeap_transport::write_lock.

Referenced by aeap_transport_create_and_connect(), ast_aeap_connect(), and AST_TEST_DEFINE().

aeap_transport_create()

struct aeap_transport * aeap_transport_create

(

const char *

type

)

Create an Asterisk external application transport.

Parameters

type	The type of transport to create

Returns

An Asterisk external application transport, or NULL on error

Definition at line 27 of file transport.c.

{
    struct aeap_transport *transport = NULL;
 
    if (!strncasecmp(type, "ws", 2)) {
        transport = (struct aeap_transport *)aeap_transport_websocket_create();
    }
 
    if (!transport) {
        ast_log(LOG_ERROR, "AEAP transport: failed to create for type '%s'\n", type);
        return NULL;
    }
 
    ast_mutex_init(&transport->read_lock);
    ast_mutex_init(&transport->write_lock);
 
    transport->connected = 0;
 
    return transport;
}

References aeap_transport_websocket_create(), ast_log, ast_mutex_init, aeap_transport::connected, LOG_ERROR, NULL, aeap_transport::read_lock, type, and aeap_transport::write_lock.

Referenced by aeap_transport_create_and_connect(), ast_aeap_create(), and AST_TEST_DEFINE().

aeap_transport_create_and_connect()

struct aeap_transport * aeap_transport_create_and_connect	(	const char *	type,
		const char *	url,
		const char *	protocol,
		int	timeout
	)

Create an Asterisk external application transport, and connect it.

Parameters

type	The type of transport to create
url	The URL to connect to
protocol	The connection protocol to use if applicable
timeout	How long (in milliseconds) to attempt to connect (-1 equals infinite)

Returns

An Asterisk external application transport, or NULL on error

Definition at line 68 of file transport.c.

{
    struct aeap_transport *transport = aeap_transport_create(type);
 
    if (!transport) {
        return NULL;
    }
 
    if (aeap_transport_connect(transport, url, protocol, timeout)) {
        aeap_transport_destroy(transport);
        return NULL;
    }
 
    return transport;
}

References aeap_transport_connect(), aeap_transport_create(), aeap_transport_destroy(), NULL, type, and url.

Referenced by AST_TEST_DEFINE().

aeap_transport_destroy()

void aeap_transport_destroy

(

struct aeap_transport *

transport

)

Destroy a transport.

Parameters

transport

The transport to destroy

Definition at line 117 of file transport.c.

{
    if (!transport) {
        return;
    }
 
    /* Ensure an orderly disconnect occurs before final destruction */
    aeap_transport_disconnect(transport);
 
    transport->vtable->destroy(transport);
 
    ast_mutex_destroy(&transport->read_lock);
    ast_mutex_destroy(&transport->write_lock);
 
    ast_free(transport);
}

References aeap_transport_disconnect(), ast_free, ast_mutex_destroy, aeap_transport_vtable::destroy, aeap_transport::read_lock, aeap_transport::vtable, and aeap_transport::write_lock.

Referenced by aeap_destructor(), aeap_transport_create_and_connect(), and AST_TEST_DEFINE().

aeap_transport_disconnect()

int aeap_transport_disconnect

(

struct aeap_transport *

transport

)

Disconnect a transport.

Note

Locks both the transport's read and write locks before calling transport instance's disconnect, and unlocks both before returning.

Parameters

transport

The transport to disconnect

Returns

0 on success, or -1 on error

Definition at line 94 of file transport.c.

{
    int res;
 
    SCOPED_MUTEX(rlock, &transport->read_lock);
    SCOPED_MUTEX(wlock, &transport->write_lock);
 
    if (!aeap_transport_is_connected(transport)) {
        return 0;
    }
 
    res = transport->vtable->disconnect(transport);
 
    /*
     * Even though the transport is locked here use atomics to set the value of
     * 'connected' since it's possible the variable is being 'read' by another
     * thread via the 'is_connected' call.
     */
    ast_atomic_fetch_sub(&transport->connected, 1, __ATOMIC_RELAXED);
 
    return res;
}

References aeap_transport_is_connected(), ast_atomic_fetch_sub, aeap_transport::connected, aeap_transport_vtable::disconnect, aeap_transport::read_lock, SCOPED_MUTEX, aeap_transport::vtable, and aeap_transport::write_lock.

Referenced by aeap_transport_destroy(), ast_aeap_disconnect(), AST_TEST_DEFINE(), websocket_read(), and websocket_write().

aeap_transport_is_connected()

int aeap_transport_is_connected

(

struct aeap_transport *

transport

)

Whether or not the transport is in a connected state.

Parameters

transport

The transport object

Returns

True if connected, false otherwise

Definition at line 85 of file transport.c.

{
    /*
     * Avoid using a lock to 'read' the 'connected' variable in order to
     * keep things slightly more efficient.
     */
    return ast_atomic_fetch_add(&transport->connected, 0, __ATOMIC_RELAXED);
}

References ast_atomic_fetch_add, and aeap_transport::connected.

Referenced by aeap_receive(), aeap_transport_connect(), aeap_transport_disconnect(), aeap_transport_read(), aeap_transport_write(), ast_aeap_connect(), and AST_TEST_DEFINE().

aeap_transport_read()

intmax_t aeap_transport_read	(	struct aeap_transport *	transport,
		void *	buf,
		intmax_t	size,
		enum AST_AEAP_DATA_TYPE *	rtype
	)

Read data from the transport.

This is a blocking read, and will not return until the transport implementation returns.

Note

Locks transport's read lock before calling transport instance's read, and unlocks it before returning.

Parameters

transport	The transport to read from
buf	The buffer data is read into
size	The size of data given data buffer
rtype	[out] The type of data read

Returns

Total number of bytes read, or less than zero on error

Definition at line 134 of file transport.c.

{
    SCOPED_MUTEX(lock, &transport->read_lock);
 
    if (!aeap_transport_is_connected(transport)) {
        return 0;
    }
 
    return transport->vtable->read(transport, buf, size, rtype);
}

References aeap_transport_is_connected(), buf, lock, aeap_transport_vtable::read, aeap_transport::read_lock, SCOPED_MUTEX, and aeap_transport::vtable.

Referenced by aeap_receive(), and AST_TEST_DEFINE().

aeap_transport_write()

intmax_t aeap_transport_write	(	struct aeap_transport *	transport,
		const void *	buf,
		intmax_t	size,
		enum AST_AEAP_DATA_TYPE	wtype
	)

Write data to the transport.

Note

Locks transport's write lock before calling transport instance's write, and unlocks it before returning.

Parameters

transport	The transport to write to
buf	The data to write
size	The size of data to write
wtype	The type of data to write

Returns

Total number of bytes written, or less than zero on error

Definition at line 146 of file transport.c.

{
    SCOPED_MUTEX(lock, &transport->write_lock);
 
    if (!aeap_transport_is_connected(transport)) {
        return 0;
    }
 
    return transport->vtable->write(transport, buf, size, wtype);
}

References aeap_transport_is_connected(), buf, lock, SCOPED_MUTEX, aeap_transport::vtable, aeap_transport_vtable::write, and aeap_transport::write_lock.

Referenced by aeap_send(), and AST_TEST_DEFINE().