SRTP events and callbacks

libSRTP can use a user-provided callback function to handle events. More...

Classes
struct	srtp_event_data_t
	srtp_event_data_t is the structure passed as a callback to the event handler function More...

Typedefs
typedef struct srtp_event_data_t	srtp_event_data_t
	srtp_event_data_t is the structure passed as a callback to the event handler function More...
typedef void()	srtp_event_handler_func_t(srtp_event_data_t *data)
	srtp_event_handler_func_t is the function prototype for the event handler. More...

Enumerations
enum	srtp_event_t { event_ssrc_collision, event_key_soft_limit, event_key_hard_limit, event_packet_index_limit }
	srtp_event_t defines events that need to be handled More...

Functions
srtp_err_status_t	srtp_install_event_handler (srtp_event_handler_func_t func)
	sets the event handler to the function supplied by the caller. More...
const char *	srtp_get_version_string (void)
	Returns the version string of the library. More...
unsigned int	srtp_get_version (void)
	Returns the numeric representation of the library version. More...
srtp_err_status_t	srtp_set_debug_module (char *mod_name, int v)
	srtp_set_debug_module(mod_name, v) More...
srtp_err_status_t	srtp_list_debug_modules (void)
	srtp_list_debug_modules() outputs a list of debugging modules More...

Detailed Description

libSRTP can use a user-provided callback function to handle events.

libSRTP allows a user to provide a callback function to handle events that need to be dealt with outside of the data plane (see the enum srtp_event_t for a description of these events). Dealing with these events is not a strict necessity; they are not security-critical, but the application may suffer if they are not handled. The function srtp_set_event_handler() is used to provide the callback function.

A default event handler that merely reports on the events as they happen is included. It is also possible to set the event handler function to NULL, in which case all events will just be silently ignored.

Typedef Documentation

srtp_event_data_t

typedef struct srtp_event_data_t srtp_event_data_t

srtp_event_data_t is the structure passed as a callback to the event handler function

The struct srtp_event_data_t holds the data passed to the event handler function.

srtp_event_handler_func_t

typedef void() srtp_event_handler_func_t(srtp_event_data_t *data)

srtp_event_handler_func_t is the function prototype for the event handler.

The typedef srtp_event_handler_func_t is the prototype for the event handler function. It has as its only argument an srtp_event_data_t which describes the event that needs to be handled. There can only be a single, global handler for all events in libSRTP.

Enumeration Type Documentation

srtp_event_t

enum srtp_event_t

srtp_event_t defines events that need to be handled

The enum srtp_event_t defines events that need to be handled outside the `data plane', such as SSRC collisions and key expirations.

When a key expires or the maximum number of packets has been reached, an SRTP stream will enter an `expired' state in which no more packets can be protected or unprotected. When this happens, it is likely that you will want to either deallocate the stream (using srtp_remove_stream()), and possibly allocate a new one.

When an SRTP stream expires, the other streams in the same session are unaffected, unless key sharing is used by that stream. In the latter case, all of the streams in the session will expire.

Enumerator
event_ssrc_collision	An SSRC collision occured.
event_key_soft_limit	An SRTP stream reached the soft key usage limit and will expire soon.
event_key_hard_limit	An SRTP stream reached the hard key usage limit and has expired.
event_packet_index_limit	An SRTP stream reached the hard packet limit (2^48 packets).

Function Documentation

srtp_get_version()

unsigned int srtp_get_version

(

void

)

Returns the numeric representation of the library version.

srtp_get_version_string()

const char* srtp_get_version_string

(

void

)

Returns the version string of the library.

srtp_install_event_handler()

srtp_err_status_t srtp_install_event_handler

(

srtp_event_handler_func_t

func

)

sets the event handler to the function supplied by the caller.

The function call srtp_install_event_handler(func) sets the event handler function to the value func. The value NULL is acceptable as an argument; in this case, events will be ignored rather than handled.

Parameters

func	is a pointer to a fuction that takes an srtp_event_data_t pointer as an argument and returns void. This function will be used by libSRTP to handle events.

srtp_list_debug_modules()

srtp_err_status_t srtp_list_debug_modules

(

void

)

srtp_list_debug_modules() outputs a list of debugging modules

srtp_set_debug_module()

srtp_err_status_t srtp_set_debug_module	(	char *	mod_name,
		int	v
	)

srtp_set_debug_module(mod_name, v)

sets dynamic debugging to the value v (0 for off, 1 for on) for the debug module with the name mod_name

returns err_status_ok on success, err_status_fail otherwise