Fork me on GitHub
Loading...
Searching...
No Matches
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   8
 Version of the API, to match the one transport plugins were compiled against.
 
#define JANUS_TRANSPORT_INIT(...)
 Initialization of all transport plugin properties to NULL.
 

Typedefs

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

Functions

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

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:

  • incoming_request(): to notify an incoming JSON message/event from one of the transport clients.

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:

  • init(): this is called by the Janus core as soon as your transport plugin is started; this is where you should setup your transport plugin (e.g., static stuff and reading the configuration file);
  • destroy(): on the other hand, this is called by the core when it is shutting down, and your transport plugin should too;
  • get_api_compatibility(): this method MUST return JANUS_TRANSPORT_API_VERSION;
  • get_version(): this method should return a numeric version identifier (e.g., 3);
  • get_version_string(): this method should return a verbose version identifier (e.g., "v1.0.1");
  • get_description(): this method should return a verbose description of your transport plugin (e.g., "This is my avian carrier transport plugin for the Janus API");
  • get_name(): this method should return a short display name for your transport plugin (e.g., "My Amazing Transport");
  • get_package(): this method should return a unique package identifier for your transport plugin (e.g., "janus.transport.mytransport");
  • is_janus_api_enabled(): this method should return TRUE if Janus API can be used with this transport, and support has been enabled by the user;
  • is_admin_api_enabled(): this method should return TRUE if Admin API can be used with this transport, and support has been enabled by the user;
  • send_message(): this method asks the transport to send a message (be it a response or an event) to a client on the specified transport;
  • session_created(): this method notifies the transport that a Janus session has been created by one of its requests;
  • session_over(): this method notifies the transport that one of its Janus sessionss is now over, whether because of a timeout or not.
  • session_claimed(): this method notifies the transport that it has claimed a session.

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

◆ JANUS_TRANSPORT_API_VERSION

#define JANUS_TRANSPORT_API_VERSION   8

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

◆ JANUS_TRANSPORT_INIT

#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, \
.query_transport = 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

◆ create_t

typedef janus_transport * create_t(void)

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

◆ janus_transport

typedef struct janus_transport janus_transport

The transport plugin session and callbacks interface.

◆ janus_transport_callbacks

typedef struct janus_transport_callbacks janus_transport_callbacks

Callbacks to contact the Janus core.

◆ janus_transport_session

typedef struct janus_transport_session janus_transport_session

Transport-Gateway session mapping.

Function Documentation

◆ janus_transport_session_create()

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

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

◆ janus_transport_session_destroy()

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