Statistics
| Branch: | Revision:

## janus-gateway / events / eventhandler.h @ 84c1291c

 1 /*! \file event.h   * \author Lorenzo Miniero   * \copyright GNU General Public License v3   * \brief Modular Janus event handlers (headers)   * \details This header contains the definition of the callbacks all   * the event handlers need to implement to interact with the Janus core.   * In fact, an event handler is basically a module that receives   * notifications from the Janus core and plugins about things happening,   * together with more or less detailed information that may be relevant.   * This may include WebRTC related events (e.g., a PeerConnection going   * up or down, media stopping or resuming, etc.), events related to media,   * or custom events plugins may originate on their own (e.g., a participant   * publishing their media in a conference, or a SIP call starting). What   * to do with these events is then up to the handler: it may choose to store   * them somewhere (e.g., a database), analyse and process them, or simply   * send them to an external tool for statistics purposes or troubleshooting.   * Whatever the aim, the structures to make the interaction between core   * and event handlers possible are defined here.   *   * An event handler plugin that wants to register at the gateway needs to   * implement the \c janus_eventhandler interface. This includes callbacks   * the Janus core can use to pass and request information, and a mask of   * the events the plugin is interested in subscribing to. Besides, as an   * event handler plugin is a shared object, and as such external to the   * gateway itself, in order to be dynamically loaded at startup it needs   * to implement the \c create_e() hook as well, that should return a   * pointer to the plugin instance. This is an example of such a step:   *  \verbatim  static janus_eventhandler myhandler = {   [..]  };    janus_eventhandler *create(void) {   JANUS_LOG(LOG_VERB, , "%s created!\n", MY_HANDLER_NAME);   return &myhandler;  }  \endverbatim   *   * This will make sure that your event handler plugin is loaded at startup   * by the gateway, if it is deployed in the proper folder.   *   * As anticipated and described in the above example, an event handler plugin   * must basically be an instance of the \c janus_eventhandler type. As such,   * it must implement the following methods and callbacks for the gateway:   *   * - \c init(): this is called by the gateway as soon as your event handler   * plugin is started; this is where you should setup your event handler plugin   * (e.g., static stuff and reading the configuration file);   * - \c destroy(): on the other hand, this is called by the gateway when it   * is shutting down, and your event handler plugin should too;   * - \c get_api_compatibility(): this method MUST return JANUS_EVENTHANDLER_API_VERSION;   * - \c get_version(): this method should return a numeric version identifier (e.g., 3);   * - \c get_version_string(): this method should return a verbose version identifier (e.g., "v1.0.1");   * - \c get_description(): this method should return a verbose description of your event handler plugin (e.g., "This is an event handler that saves some events on a database");   * - \c get_name(): this method should return a short display name for your event handler plugin (e.g., "My Amazing Event Handler");   * - \c get_package(): this method should return a unique package identifier for your event handler plugin (e.g., "janus.eventhandler.myeventhandler");   * - \c incoming_event(): this callack informs the event handler that an event is available for consumption.   *   * All the above methods and callbacks are mandatory: the Janus core will   * reject an event handler plugin that doesn't implement any of the   * mandatory callbacks.   *   * Additionally, a \c janus_eventhandler instance must also include a   * mask of the events it is interested in, a \c events_mask janus_flag   * object that must refer to the available types defined in this header.   * The core, in fact, will refer to that mask to check whether your event   * handler is interested in a specific event or not.   *   * Unlike other kind of modules (transports, plugins), the \c init() method   * here only passes the path to the configurations files folder, as event   * handlers never need to contact the gateway themselves. This path can be used to read and   * parse a configuration file for the event handler plugin: the event handler   * plugins we made available out of the box use the package name as a   * name for the file (e.g., \c janus.eventhandler.fake.cfg for the sample   * event handler plugin), but you're free to use a different one, as long   * as it doesn't collide with existing ones. Besides, the existing eventhandler   * plugins use the same INI format for configuration files the gateway   * uses (relying on the \c janus_config helpers for the purpose) but   * again, if you prefer a different format (XML, JSON, etc.) that's up to you.   *   * \ingroup eventhandlerapi   * \ref eventhandlerapi   */  #ifndef _JANUS_EVENTHANDLER_H  #define _JANUS_EVENTHANDLER_H  #include  #include  #include  #include  #include  #include  #include  #include  #include  #include "../utils.h"  /*! \brief Version of the API, to match the one event handler plugins were compiled against */  #define JANUS_EVENTHANDLER_API_VERSION 1  /*! \brief Initialization of all event handler plugin properties to NULL   *   * \note All event handler plugins MUST add this as the FIRST line when initializing   * their event handler plugin structure, e.g.:   *  \verbatim  static janus_eventhandler janus_fake_eventhandler handler plugin =   {   JANUS_EVENTHANDLER_INIT,     .init = janus_fake_init,   [..]  \endverbatim   */  /** @name Type of events Janus could notify, and the handler subscribe to   * @details This mask makes it easy to subscribe to, and unsubscribe from,   * specific events, as all you need to do is to use janus_flags_set and   * janus_flags_clear on the \c events_mask property of the handler instance,   * and the core will know whether you care about something or not.   */  ///@{  /*! \brief No event */  #define JANUS_EVENT_TYPE_NONE (0)  /*! \brief Session related events (e.g., session created/destroyed, etc.) */  #define JANUS_EVENT_TYPE_SESSION (1 << 0)  /*! \brief Handle related events (e.g., handle attached/detached, etc.) */  #define JANUS_EVENT_TYPE_HANDLE (1 << 1)  /*! \brief JSEP related events (e.g., got/sent offer/answer) */  #define JANUS_EVENT_TYPE_JSEP (1 << 3)  /*! \brief WebRTC related events (e.g., PeerConnection up/down, ICE updates, DTLS updates, etc.) */  #define JANUS_EVENT_TYPE_WEBRTC (1 << 4)  /*! \brief Media related events (e.g., media started/stopped flowing, stats on packets/bytes, etc.) */  #define JANUS_EVENT_TYPE_MEDIA (1 << 5)  /*! \brief Events originated by plugins (at the moment, all of them, no way to pick) */  #define JANUS_EVENT_TYPE_PLUGIN (1 << 6)  /*! \brief Events originated by transports (at the moment, all of them, no way to pick) */  #define JANUS_EVENT_TYPE_TRANSPORT (1 << 7)  /*! \brief Events originated by the core for its own events (e.g., Janus starting/shutting down) */  #define JANUS_EVENT_TYPE_CORE (1 << 8)   /* TODO Others? */  /*! \brief Mask with all events enabled (shortcut when you want to subscribe to everything) */  #define JANUS_EVENT_TYPE_ALL (0xffffffff)  ///@}  #define JANUS_EVENTHANDLER_INIT(...) { \   .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, \   .incoming_event = NULL, \   .events_mask = JANUS_EVENT_TYPE_NONE, \   ## __VA_ARGS__ }  /*! \brief Callbacks to contact the gateway */  typedef struct janus_eventhandler_callbacks janus_eventhandler_callbacks;  /*! \brief The event handler plugin session and callbacks interface */  typedef struct janus_eventhandler janus_eventhandler;  /*! \brief The event handler plugin session and callbacks interface */  struct janus_eventhandler {   /*! \brief Event handler plugin initialization/constructor   * @param[in] config_path Path of the folder where the configuration for this event handler plugin can be found   * @returns 0 in case of success, a negative integer in case of error */   int (* const init)(const char *config_path);   /*! \brief Event handler plugin deinitialization/destructor */   void (* const destroy)(void);   /*! \brief Informative method to request the API version this event handler plugin was compiled against   * \note All event handler plugins MUST implement this method and return JANUS_EVENTHANDLER_API_VERSION   * to make this work, or they will be rejected by the core. */   int (* const get_api_compatibility)(void);   /*! \brief Informative method to request the numeric version of the event handler plugin */   int (* const get_version)(void);   /*! \brief Informative method to request the string version of the event handler plugin */   const char *(* const get_version_string)(void);   /*! \brief Informative method to request a description of the event handler plugin */   const char *(* const get_description)(void);   /*! \brief Informative method to request the name of the event handler plugin */   const char *(* const get_name)(void);   /*! \brief Informative method to request the author of the event handler plugin */   const char *(* const get_author)(void);   /*! \brief Informative method to request the package name of the event handler plugin (what will be used in web applications to refer to it) */   const char *(* const get_package)(void);   /*! \brief Method to notify the event handler plugin that a new event is available   * \details All events are notified as a Jansson json_t object, and the syntax of   * the associated JSON document is as follows:   * \verbatim   {   "type" : ,   "timestamp" : ,   "session_id" : ,   "handle_id" : ,   "event" : {     }   }   * \endverbatim   * \note Do NOT handle the event directly in this method. Janus sends events from its   * working threads, and so you'd most likely end up slowing it down. Just take note of it   * and handle it somewhere else. It's your responsibility to \c json_decref the event   * object once you're done with it: a failure to do so will result in memory leaks.   * @param[in] event Jansson object containing the event details */   void (* const incoming_event)(json_t *event);   /*! \brief Mask of events this handler is interested in, as a janus_flags object */   janus_flags events_mask;  };  /*! \brief The hook that event handler plugins need to implement to be created from the gateway */  typedef janus_eventhandler* create_e(void);  #endif