Statistics
| Branch: | Revision:

janus-gateway / janus.h @ 5e9e29e0

History | View | Annotate | Download (6.96 KB)

1 be35facb meetecho
/*! \file   janus.h
2
 * \author Lorenzo Miniero <lorenzo@meetecho.com>
3
 * \copyright GNU Affero General Public License v3
4
 * \brief  Janus core (headers)
5
 * \details Implementation of the gateway core. This code takes care of
6
 * the gateway initialization (command line/configuration) and setup,
7
 * and implements the web server (based on libmicrohttpd) and Janus protocol
8
 * (a JSON protocol implemented with Jansson) to interact with the web
9
 * applications. The core also takes care of bridging peers and plugins
10
 * accordingly. 
11
 * 
12
 * \ingroup core
13
 * \ref core
14
 */
15
 
16
#ifndef _JANUS_GATEWAY_H
17
#define _JANUS_GATEWAY_H
18
19
#include <inttypes.h>
20
#include <stdlib.h>
21
#include <stdint.h>
22
#include <stdio.h>
23
#include <string.h>
24
#include <ctype.h>
25
#include <unistd.h>
26
27
#include <jansson.h>
28
#include <microhttpd.h>
29
30
#include "mutex.h"
31
#include "dtls.h"
32
#include "ice.h"
33
#include "plugins/plugin.h"
34
35
36
#define BUFSIZE        4096
37
38
39
/* Messaging */
40
typedef struct janus_http_msg {
41
        gchar *acrh, *acrm;
42
        gchar *contenttype;
43
        gchar *payload;
44
        size_t len;
45
        gint64 session_id;
46
} janus_http_msg;
47
48
typedef struct janus_http_event {
49
        gint code;
50
        gchar *payload;
51
        gint allocated:1;
52
} janus_http_event;
53
54
55
/* Gateway-Client session */
56
typedef struct janus_session {
57
        guint64 session_id;
58
        GHashTable *ice_handles;
59
        /* HTTP */
60
        GQueue *messages;
61
        gint destroy:1;
62
        janus_mutex mutex;
63
} janus_session;
64
65
66
/* Gateway Sessions */
67
janus_session *janus_session_create(void);
68
janus_session *janus_session_find(guint64 session_id);
69
gint janus_session_destroy(guint64 session_id);
70
71
72
/** @name Janus web server
73
 * \details Browsers make use of HTTP to make requests to the gateway.
74
 * Since the gateway may be deployed on a different domain than the web
75
 * server hosting the web applications using it, the gateway automatically
76
 * handles OPTIONS request to comply with the CORS specification.
77
 * POST requests can be used to ask for the management of a session with
78
 * the gateway, to attach to a plugin, to send messages to the plugin
79
 * itself and so on. GET requests instead are used for getting events
80
 * associated to a gateway session (and as such to all its plugin handles
81
 * and the events plugins push in the session itself), using a long poll
82
 * approach. A JavaScript library (janus.js) implements all of this on
83
 * the client side automatically.
84
 */
85
///@{
86
/*! \brief Callback (libmicrohttpd) invoked when an HTTP message (GET, POST, OPTIONS, etc.) is available */
87
int janus_ws_handler(void *cls, struct MHD_Connection *connection, const char *url, const char *method, const char *version, const char *upload_data, size_t *upload_data_size, void **ptr);
88
/*! \brief Callback (libmicrohttpd) invoked when headers of an incoming HTTP message have been parsed */
89
int janus_ws_headers(void *cls, enum MHD_ValueKind kind, const char *key, const char *value);
90
/*! \brief Callback (libmicrohttpd) invoked when a request has been processed and can be freed */
91
void janus_ws_request_completed (void *cls, struct MHD_Connection *connection, void **con_cls, enum MHD_RequestTerminationCode toe);
92
/*! \brief Method to return a successful Janus response message (JSON) to the browser
93
 * @param[in] connection The libmicrohttpd MHD_Connection connection instance that is handling the request
94
 * @param[in] msg The original request
95
 * @param[in] transaction The Janus transaction identifier
96
 * @param[in] payload The stringified version of the Janus response (JSON) 
97
 * @returns MHD_YES on success, MHD_NO otherwise */
98
int janus_ws_success(struct MHD_Connection *connection, janus_http_msg *msg, const char *transaction, char *payload);
99
/*! \brief Method to return an error Janus response message (JSON) to the browser
100
 * @param[in] connection The libmicrohttpd MHD_Connection connection instance that is handling the request
101
 * @param[in] msg The original request
102
 * @param[in] transaction The Janus transaction identifier
103
 * @param[in] error The error code as defined in apierror.h
104
 * @param[in] format The printf format of the reason string, followed by a variable
105
 * number of arguments, if needed; if format is NULL, a pre-configured string
106
 * associated with the error code is used
107
 * @returns MHD_YES on success, MHD_NO otherwise */
108
int janus_ws_error(struct MHD_Connection *connection, janus_http_msg *msg, const char *transaction, gint error, const char *format, ...);
109
/*! \brief Worker to handle requests that are actually long polls
110
 * \details As this method handles a long poll, it doesn't return until an
111
 * event (e.g., pushed by a plugin) is available, or a timeout (30 seconds)
112
 * has been fired. In case of a timeout, a keep-alive Janus response (JSON)
113
 * is sent to tell the browser that the session is still valid.
114
 * @param[in] connection The libmicrohttpd MHD_Connection connection instance that is handling the request
115
 * @param[in] msg The original request, which also manages the request state
116
 * @returns MHD_YES on success, MHD_NO otherwise */
117
int janus_ws_notifier(struct MHD_Connection *connection, janus_http_msg *msg);
118
///@}
119
120
121
/** @name Janus plugin management
122
 * As anticipated, the gateway doesn't provide any specific feature: it takes
123
 * care of WebRTC-related stuff, and of sending and receiving JSON-based
124
 * messages. To implement applications based on these foundations, plugins
125
 * can be used. These plugins are shared objects that need to implement
126
 * the interfaces defined in plugin.h and as such are dynamically loaded
127
 * by the gateway at startup, and unloaded when the gateway closes.
128
 */
129
///@{
130
/*! \brief Callback (g_hash_table_foreach) invoked when it's time to destroy a plugin instance
131
 * @param[in] key Key of the plugins hash table (package name)
132
 * @param[in] value The janus_plugin plugin instance to destroy
133
 * @param[in] user_data User provided data (unused) */
134
void janus_plugin_close(void *key, void *value, void *user_data);
135
/*! \brief Callback (g_hash_table_foreach) invoked when it's time to close a plugin
136
 * @param[in] key Key of the plugins hash table (package name)
137
 * @param[in] value The janus_plugin plugin instance to close
138
 * @param[in] user_data User provided data (unused) */
139
void janus_pluginso_close(void *key, void *value, void *user_data);
140
/*! \brief Method to return a registered plugin instance out of its package name
141
 * @param[in] package The unique package name of the plugin
142
 * @returns The plugin instance */
143
janus_plugin *janus_plugin_find(const gchar *package);
144
///@}
145
146
/*! \brief Helper method to return the path to the provided server certificate */
147
gchar *janus_get_server_pem(void);
148
/*! \brief Helper method to return the path to the provided server certificate key */
149
gchar *janus_get_server_key(void);
150
151
152 5e9e29e0 meetecho
/*! \brief Helper method to return the local IP address (autodetected by default) */
153 be35facb meetecho
gchar *janus_get_local_ip(void);
154 5e9e29e0 meetecho
/*! \brief Helper method to return the IP address to use in the SDP (autodetected by default) */
155
gchar *janus_get_public_ip(void);
156
/*! \brief Helper method to overwrite the IP address to use in the SDP */
157
void janus_set_public_ip(const char *ip);
158 be35facb meetecho
/*! \brief Helper method to check whether the gateway is being shut down */
159
gint janus_is_stopping(void);
160
161
162
#endif