Loading...
Searching...
No Matches
transport.h File Reference
Transports » Transport API

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_transport * | create_t(void)
| The hook that transport plugins need to implement to be created from the Janus core.

## Functions

janus_transport_session * | janus_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

Copyright
  GNU General Public License v3

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

Copyright
  GNU General Public License v3

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(*)(void *) | p_free
| ) |  |

Helper to create a janus_transport_session instance.

Note
  This helper automatically initializes the reference counter

Parameters

  transport_p | Pointer to the transport-side session instance (won't be touched by the core)
  p_free | Pointer 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

  session | Pointer to the janus_transport_session instance