Fork me on GitHub
Data Structures | Macros | Typedefs | Functions
transport.h File Reference

Modular Janus API transports. More...

#include <stdlib.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include <unistd.h>
#include <inttypes.h>
#include <glib.h>
#include <jansson.h>
#include "refcount.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  janus_transport_session
 Transport-Gateway session mapping. More...
 
struct  janus_transport
 The transport plugin session and callbacks interface. More...
 
struct  janus_transport_callbacks
 Callbacks to contact the Janus core. More...
 

Macros

#define JANUS_TRANSPORT_API_VERSION   7
 Version of the API, to match the one transport plugins were compiled against. More...
 
#define JANUS_TRANSPORT_INIT(...)
 Initialization of all transport plugin properties to NULL. More...
 

Typedefs

typedef struct janus_transport_callbacks janus_transport_callbacks
 Callbacks to contact the Janus core. More...
 
typedef struct janus_transport janus_transport
 The transport plugin session and callbacks interface. More...
 
typedef struct janus_transport_session janus_transport_session
 Transport-Gateway session mapping. More...
 
typedef janus_transportcreate_t(void)
 The hook that transport plugins need to implement to be created from the Janus core. More...
 

Functions

janus_transport_sessionjanus_transport_session_create (void *transport_p, void(*p_free)(void *))
 Helper to create a janus_transport_session instance. More...
 
void janus_transport_session_destroy (janus_transport_session *session)
 Helper to mark a janus_transport_session instance as destroyed. More...
 

Detailed Description

Modular Janus API transports.

Modular Janus API transports (headers)

Author
Lorenzo Miniero loren.nosp@m.zo@m.nosp@m.eetec.nosp@m.ho.c.nosp@m.om

This header contains the definition of the callbacks both the gateway and all the transports need too implement to interact with each other. The structures to make the communication possible are defined here as well.

Transport API

Author
Lorenzo Miniero loren.nosp@m.zo@m.nosp@m.eetec.nosp@m.ho.c.nosp@m.om

This header contains the definition of the callbacks both the Janus core and all the transports need to implement to interact with each other. The structures to make the communication possible are defined here as well.

In particular, the Janus core implements the janus_transport_callbacks interface. This means that, as a transport plugin, you can use the methods it exposes to contact the core, e.g., in order to notify an incoming message. In particular, the methods the core exposes to transport plugins are:

On the other hand, a transport plugin that wants to register at the Janus core needs to implement the janus_transport interface. Besides, as a transport plugin is a shared object, and as such external to the core itself, in order to be dynamically loaded at startup it needs to implement the create_t() hook as well, that should return a pointer to the plugin instance. This is an example of such a step:

static janus_transport mytransport = {
        [..]
};

janus_transport *create(void) {
        JANUS_LOG(LOG_VERB, , "%s created!\n", MY_TRANSPORT_NAME);
        return &mytransport;
}

This will make sure that your transport plugin is loaded at startup by the Janus core, if it is deployed in the proper folder.

As anticipated and described in the above example, a transport plugin must basically be an instance of the janus_transport type. As such, it must implement the following methods and callbacks for the core:

All the above methods and callbacks are mandatory: the Janus core will reject a transport plugin that doesn't implement any of the mandatory callbacks.

The Janus core janus_transport_callbacks interface is provided to a transport plugin, together with the path to the configurations files folder, in the init() method. This path can be used to read and parse a configuration file for the transport plugin: the transport plugins we made available out of the box use the package name as a name for the file (e.g., janus.transport.http.cfg for the HTTP/HTTPS transport plugin), but you're free to use a different one, as long as it doesn't collide with existing ones. Besides, the existing transport plugins use the same INI format for configuration files the core uses (relying on the janus_config helpers for the purpose) but again, if you prefer a different format (XML, JSON, etc.) that's up to you.

Transport API

Macro Definition Documentation

#define JANUS_TRANSPORT_API_VERSION   7

Version of the API, to match the one transport plugins were compiled against.

#define JANUS_TRANSPORT_INIT (   ...)
Value:
{ \
.init = NULL, \
.destroy = NULL, \
.get_api_compatibility = NULL, \
.get_version = NULL, \
.get_version_string = NULL, \
.get_description = NULL, \
.get_name = NULL, \
.get_author = NULL, \
.get_package = NULL, \
.is_janus_api_enabled = NULL, \
.is_admin_api_enabled = NULL, \
.send_message = NULL, \
.session_created = NULL, \
.session_over = NULL, \
.session_claimed = NULL, \
## __VA_ARGS__ }

Initialization of all transport plugin properties to NULL.

Note
All transport plugins MUST add this as the FIRST line when initializing their transport plugin structure, e.g.:
static janus_transport janus_http_transport plugin =
        {
                JANUS_TRANSPORT_INIT,

                .init = janus_http_init,
                [..]

Typedef Documentation

typedef janus_transport* create_t(void)

The hook that transport plugins need to implement to be created from the Janus core.

The transport plugin session and callbacks interface.

Callbacks to contact the Janus core.

Transport-Gateway session mapping.

Function Documentation

janus_transport_session* janus_transport_session_create ( void *  transport_p,
void(*)(void *)  p_free 
)

Helper to create a janus_transport_session instance.

Note
This helper automatically initializes the reference counter
Parameters
transport_pPointer to the transport-side session instance (won't be touched by the core)
p_freePointer to the transport-provided function, if needed, that will be used to free the opaque transport-side session instance (won't be touched by the core)
Returns
Pointer to a valid janus_transport_session, if successful, NULL otherwise
void janus_transport_session_destroy ( janus_transport_session session)

Helper to mark a janus_transport_session instance as destroyed.

Note
Only use this helper when that specific transport session must not be used by the core anymore: e.g., a WebSocket connection was closed, an HTTP connection associated with a pending request was lost, etc. Remember to decrease the counter in case you increased it in other methods (this method does this automatically as far as the create was concerned).
Parameters
sessionPointer to the janus_transport_session instance