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

TURN REST API client. More...

#include <stdint.h>
#include <glib.h>
#include <jansson.h>
Include dependency graph for utils.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  janus_json_parameter
 
struct  janus_vp8_simulcast_context
 VP8 simulcasting context, in order to make sure SSRC changes result in coherent picid/temporal level increases. More...
 

Macros

#define JANUS_JSON_STRING   JSON_STRING
 
#define JANUS_JSON_INTEGER   JSON_INTEGER
 
#define JANUS_JSON_OBJECT   JSON_OBJECT
 
#define JANUS_JSON_BOOL   JSON_TRUE
 
#define JANUS_JSON_PARAM_REQUIRED   1
 
#define JANUS_JSON_PARAM_POSITIVE   2
 
#define JANUS_JSON_PARAM_NONEMPTY   4
 
#define JANUS_VALIDATE_JSON_OBJECT_FORMAT(missing_format, invalid_format, obj, params, error_code, error_cause, log_error, missing_code, invalid_code)
 Validates the JSON object against the description of its parameters. More...
 
#define JANUS_VALIDATE_JSON_OBJECT(obj, params, error_code, error_cause, log_error, missing_code, invalid_code)   JANUS_VALIDATE_JSON_OBJECT_FORMAT("Missing mandatory element (%s)", "Invalid element type (%s should be %s)", obj, params, error_code, error_cause, log_error, missing_code, invalid_code)
 Validates the JSON object against the description of its parameters. More...
 
#define JANUS_CHECK_SECRET(secret, obj, member, error_code, error_cause, missing_code, invalid_code, unauthorized_code)
 If the secret isn't NULL, check the secret after validating the specified member of the JSON object. More...
 

Typedefs

typedef struct janus_vp8_simulcast_context janus_vp8_simulcast_context
 VP8 simulcasting context, in order to make sure SSRC changes result in coherent picid/temporal level increases. More...
 

Functions

gint64 janus_get_monotonic_time (void)
 Helper to retrieve the system monotonic time, as Glib's g_get_monotonic_time may not be available (only since 2.28) More...
 
gint64 janus_get_real_time (void)
 Helper to retrieve the system real time, as Glib's g_get_real_time may not be available (only since 2.28) More...
 
char * janus_string_replace (char *message, const char *old_string, const char *new_string) G_GNUC_WARN_UNUSED_RESULT
 Helper to replace strings. More...
 
gboolean janus_is_true (const char *value)
 Helper to parse yes/no|true/false configuration values. More...
 
gboolean janus_strcmp_const_time (const void *str1, const void *str2)
 Helper to compare strings in constant time. More...
 
guint32 janus_random_uint32 (void)
 Helper to generate random 32-bit unsigned integers (useful for SSRCs, etc.) More...
 
guint64 janus_random_uint64 (void)
 Helper to generate random 64-bit unsigned integers (useful for Janus IDs) More...
 
guint64 * janus_uint64_dup (guint64 num)
 Helper to generate an allocated copy of a guint64 number. More...
 
int janus_mkdir (const char *dir, mode_t mode)
 Helper to create a new directory, and recursively create parent directories if needed. More...
 
int janus_get_codec_pt (const char *sdp, const char *codec)
 Ugly and dirty helper to quickly get the payload type associated with a codec in an SDP. More...
 
const char * janus_get_codec_from_pt (const char *sdp, int pt)
 Ugly and dirty helper to quickly get the codec associated with a payload type in an SDP. More...
 
int janus_pidfile_create (const char *file)
 Create and lock a PID file. More...
 
int janus_pidfile_remove (void)
 Unlock and remove a previously created PID file. More...
 
void janus_get_json_type_name (int jtype, unsigned int flags, char *type_name)
 Creates a string describing the JSON type and constraint. More...
 
gboolean janus_json_is_valid (json_t *val, json_type jtype, unsigned int flags)
 Checks whether the JSON value matches the type and constraint. More...
 
gboolean janus_vp8_is_keyframe (char *buffer, int len)
 Helper method to check if a VP8 frame is a keyframe or not. More...
 
gboolean janus_vp9_is_keyframe (char *buffer, int len)
 Helper method to check if a VP9 frame is a keyframe or not. More...
 
gboolean janus_h264_is_keyframe (char *buffer, int len)
 Helper method to check if an H.264 frame is a keyframe or not. More...
 
void janus_vp8_simulcast_context_reset (janus_vp8_simulcast_context *context)
 Set (or reset) the context fields to their default values. More...
 
int janus_vp8_parse_descriptor (char *buffer, int len, uint16_t *picid, uint8_t *tl0picidx, uint8_t *tid, uint8_t *y, uint8_t *keyidx)
 Helper method to parse a VP8 payload descriptor for useful info (e.g., when simulcasting) More...
 
void janus_vp8_simulcast_descriptor_update (char *buffer, int len, janus_vp8_simulcast_context *context, gboolean switched)
 Use the context info to update the RTP header of a packet, if needed. More...
 
int janus_vp9_parse_svc (char *buffer, int len, int *found, int *spatial_layer, int *temporal_layer, uint8_t *p, uint8_t *d, uint8_t *u, uint8_t *b, uint8_t *e)
 Helper method to parse a VP9 payload descriptor for SVC-related info (e.g., when SVC is enabled) More...
 
guint32 janus_push_bits (guint32 word, size_t num, guint32 val)
 Helper method to push individual bits at the end of a word. More...
 
void janus_set1 (guint8 *data, size_t i, guint8 val)
 Helper method to set one byte at a memory position. More...
 
void janus_set2 (guint8 *data, size_t i, guint32 val)
 Helper method to set two bytes at a memory position. More...
 
void janus_set3 (guint8 *data, size_t i, guint32 val)
 Helper method to set three bytes at a memory position. More...
 
void janus_set4 (guint8 *data, size_t i, guint32 val)
 Helper method to set four bytes at a memory position. More...
 

Flags helper methods

typedef gsize janus_flags
 Janus flags container. More...
 
void janus_flags_reset (janus_flags *flags)
 Janus flags reset method. More...
 
void janus_flags_set (janus_flags *flags, gsize flag)
 Janus flags set method. More...
 
void janus_flags_clear (janus_flags *flags, gsize flag)
 Janus flags clear method. More...
 
gboolean janus_flags_is_set (janus_flags *flags, gsize flag)
 Janus flags check method. More...
 

Detailed Description

TURN REST API client.

Utilities and helpers (headers)

TURN REST API client (headers)

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

Implementation of the draft-uberti-rtcweb-turn-rest-00 draft, that is a REST API that can be used to access TURN services, more specifically credentials to use. Currently implemented in both rfc5766-turn-server and coturn, and so should be generic enough to be usable here.

Note
This implementation depends on libcurl and is optional.

Core

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

Implementations of a few methods that may be of use here and there in the code.

Core

Macro Definition Documentation

#define JANUS_CHECK_SECRET (   secret,
  obj,
  member,
  error_code,
  error_cause,
  missing_code,
  invalid_code,
  unauthorized_code 
)
Value:
do { \
if (secret) { \
static struct janus_json_parameter secret_parameters[] = { \
{member, JSON_STRING, JANUS_JSON_PARAM_REQUIRED} \
}; \
JANUS_VALIDATE_JSON_OBJECT(obj, secret_parameters, error_code, error_cause, TRUE, missing_code, invalid_code); \
if(error_code == 0 && !janus_strcmp_const_time((secret), json_string_value(json_object_get(obj, member)))) { \
error_code = (unauthorized_code); \
JANUS_LOG(LOG_ERR, "Unauthorized (wrong %s)\n", member); \
if(error_cause != NULL) \
g_snprintf(error_cause, sizeof(error_cause), "Unauthorized (wrong %s)", member); \
} \
} \
} while(0)
#define JANUS_LOG(level, format,...)
Logger based on different levels, which can either be displayed or not according to the configuration...
Definition: debug.h:88
#define JANUS_JSON_PARAM_REQUIRED
Definition: utils.h:24
#define JANUS_VALIDATE_JSON_OBJECT(obj, params, error_code, error_cause, log_error, missing_code, invalid_code)
Validates the JSON object against the description of its parameters.
Definition: utils.h:198
Definition: utils.h:28
#define LOG_ERR
Non-fatal error.
Definition: debug.h:43
gboolean janus_strcmp_const_time(const void *str1, const void *str2)
Helper to compare strings in constant time.
Definition: utils.c:46

If the secret isn't NULL, check the secret after validating the specified member of the JSON object.

Parameters
secretThe secret to be checked; no check if the secret is NULL
objThe JSON object to be validated
memberThe JSON member with the secret, usually "secret" or "pin"
[out]error_codeint to return error code
[out]error_causeArray of char or NULL to return the error descriptions; the array has to be a global or stack variable to make sizeof work; the required size is 60
missing_codeThe code to be returned in error_code if a parameter is missing
invalid_codeThe code to be returned in error_code if a parameter is invalid
unauthorized_codeThe code to be returned in error_code if the secret doesn't match
#define JANUS_JSON_BOOL   JSON_TRUE
#define JANUS_JSON_INTEGER   JSON_INTEGER
#define JANUS_JSON_OBJECT   JSON_OBJECT
#define JANUS_JSON_PARAM_NONEMPTY   4
#define JANUS_JSON_PARAM_POSITIVE   2
#define JANUS_JSON_PARAM_REQUIRED   1
#define JANUS_JSON_STRING   JSON_STRING
#define JANUS_VALIDATE_JSON_OBJECT (   obj,
  params,
  error_code,
  error_cause,
  log_error,
  missing_code,
  invalid_code 
)    JANUS_VALIDATE_JSON_OBJECT_FORMAT("Missing mandatory element (%s)", "Invalid element type (%s should be %s)", obj, params, error_code, error_cause, log_error, missing_code, invalid_code)

Validates the JSON object against the description of its parameters.

Parameters
objThe JSON object to be validated
paramsArray of struct janus_json_parameter to describe the parameters; the array has to be a global or stack variable to make sizeof work
[out]error_codeint to return error code
[out]error_causeArray of char or NULL to return the error descriptions; the array has to be a global or stack variable to make sizeof work; the required size is the length of the longest parameter name plus 54 for the format string and type description
log_errorIf TRUE, log any error with JANUS_LOG(LOG_ERR)
missing_codeThe code to be returned in error_code if a parameter is missing
invalid_codeThe code to be returned in error_code if a parameter is invalid
#define JANUS_VALIDATE_JSON_OBJECT_FORMAT (   missing_format,
  invalid_format,
  obj,
  params,
  error_code,
  error_cause,
  log_error,
  missing_code,
  invalid_code 
)
Value:
do { \
error_code = 0; \
unsigned int i; \
for(i = 0; i < sizeof(params) / sizeof(struct janus_json_parameter); i++) { \
json_t *val = json_object_get(obj, params[i].name); \
if(!val) { \
if((params[i].flags & JANUS_JSON_PARAM_REQUIRED) != 0) { \
error_code = (missing_code); \
if(log_error) \
JANUS_LOG(LOG_ERR, missing_format "\n", params[i].name); \
if(error_cause != NULL) \
g_snprintf(error_cause, sizeof(error_cause), missing_format, params[i].name); \
break; \
} \
continue; \
} \
if(!janus_json_is_valid(val, params[i].jtype, params[i].flags)) { \
error_code = (invalid_code); \
char type_name[20]; \
janus_get_json_type_name(params[i].jtype, params[i].flags, type_name); \
if(log_error) \
JANUS_LOG(LOG_ERR, invalid_format "\n", params[i].name, type_name); \
if(error_cause != NULL) \
g_snprintf(error_cause, sizeof(error_cause), invalid_format, params[i].name, type_name); \
break; \
} \
} \
} while(0)
unsigned int flags
Definition: utils.h:31
struct json_t json_t
Definition: plugin.h:223
void janus_get_json_type_name(int jtype, unsigned int flags, char *type_name)
Creates a string describing the JSON type and constraint.
Definition: utils.c:419
#define JANUS_LOG(level, format,...)
Logger based on different levels, which can either be displayed or not according to the configuration...
Definition: debug.h:88
#define JANUS_JSON_PARAM_REQUIRED
Definition: utils.h:24
const gchar * name
Definition: utils.h:29
json_type jtype
Definition: utils.h:30
Definition: utils.h:28
#define LOG_ERR
Non-fatal error.
Definition: debug.h:43
gboolean janus_json_is_valid(json_t *val, json_type jtype, unsigned int flags)
Checks whether the JSON value matches the type and constraint.
Definition: utils.c:459

Validates the JSON object against the description of its parameters.

Parameters
missing_formatprintf format to indicate a missing required parameter; needs one s for the parameter name
invalid_formatprintf format to indicate an invalid parameter; needs two s for parameter name and type description from janus_get_json_type_name
objThe JSON object to be validated
paramsArray of struct janus_json_parameter to describe the parameters; the array has to be a global or stack variable to make sizeof work
[out]error_codeint to return error code
[out]error_causeArray of char or NULL to return the error descriptions; the array has to be a global or stack variable to make sizeof work; the required size is the length of the format string plus the length of the longest parameter name plus 19 for the type description
log_errorIf TRUE, log any error with JANUS_LOG(LOG_ERR)
missing_codeThe code to be returned in error_code if a parameter is missing
invalid_codeThe code to be returned in error_code if a parameter is invalid

Typedef Documentation

typedef gsize janus_flags

Janus flags container.

VP8 simulcasting context, in order to make sure SSRC changes result in coherent picid/temporal level increases.

Function Documentation

void janus_flags_clear ( janus_flags flags,
gsize  flag 
)

Janus flags clear method.

Parameters
[in]flagsThe janus_flags instance to update
[in]flagThe flag to clear
gboolean janus_flags_is_set ( janus_flags flags,
gsize  flag 
)

Janus flags check method.

Parameters
[in]flagsThe janus_flags instance to check
[in]flagThe flag to check
Returns
true if the flag is set, false otherwise
void janus_flags_reset ( janus_flags flags)

Janus flags reset method.

Parameters
[in]flagsThe janus_flags instance to reset
void janus_flags_set ( janus_flags flags,
gsize  flag 
)

Janus flags set method.

Parameters
[in]flagsThe janus_flags instance to update
[in]flagThe flag to set
const char* janus_get_codec_from_pt ( const char *  sdp,
int  pt 
)

Ugly and dirty helper to quickly get the codec associated with a payload type in an SDP.

Parameters
sdpThe SDP to parse
ptThe payload type to look for
Returns
The codec name, if found, NULL otherwise
int janus_get_codec_pt ( const char *  sdp,
const char *  codec 
)

Ugly and dirty helper to quickly get the payload type associated with a codec in an SDP.

Parameters
sdpThe SDP to parse
codecThe codec to look for
Returns
The payload type, if found, -1 otherwise
void janus_get_json_type_name ( int  jtype,
unsigned int  flags,
char *  type_name 
)

Creates a string describing the JSON type and constraint.

Parameters
jtypeThe JSON type, e.g., JSON_STRING
flagsIndicates constraints for the described type
[out]type_nameThe type description, e.g., "a positive integer"; required size is 19 characters
Returns
0 if successful, a negative integer otherwise
gint64 janus_get_monotonic_time ( void  )

Helper to retrieve the system monotonic time, as Glib's g_get_monotonic_time may not be available (only since 2.28)

Returns
The system monotonic time
gint64 janus_get_real_time ( void  )

Helper to retrieve the system real time, as Glib's g_get_real_time may not be available (only since 2.28)

Returns
The system real time
gboolean janus_h264_is_keyframe ( char *  buffer,
int  len 
)

Helper method to check if an H.264 frame is a keyframe or not.

Parameters
[in]bufferThe RTP payload to process
[in]lenThe length of the RTP payload
Returns
TRUE if it's a keyframe, FALSE otherwise
gboolean janus_is_true ( const char *  value)

Helper to parse yes/no|true/false configuration values.

Parameters
valueThe configuration value to parse
Returns
true if the value contains a "yes", "YES", "true", TRUE", "1", false otherwise
gboolean janus_json_is_valid ( json_t val,
json_type  jtype,
unsigned int  flags 
)

Checks whether the JSON value matches the type and constraint.

Parameters
valThe JSON value to be checked
jtypeThe JSON type, e.g., JSON_STRING
flagsIndicates constraints for the described type
Returns
TRUE if the value is valid
int janus_mkdir ( const char *  dir,
mode_t  mode 
)

Helper to create a new directory, and recursively create parent directories if needed.

Parameters
dirPath to the new folder to create
modeFile permissions for the new directory file
Returns
An integer like the regular mkdir does
Note
A failure may indicate that creating any of the subdirectories failed: some may still have been created
int janus_pidfile_create ( const char *  file)

Create and lock a PID file.

Parameters
filePath to the PID file to use
Returns
0 if successful, a negative integer otherwise
int janus_pidfile_remove ( void  )

Unlock and remove a previously created PID file.

Returns
0 if successful, a negative integer otherwise
guint32 janus_push_bits ( guint32  word,
size_t  num,
guint32  val 
)
inline

Helper method to push individual bits at the end of a word.

Parameters
[in]wordInitial value of word
[in]numNumber of bits to push
[in]valValue of bits to push
Returns
0 New word value
guint32 janus_random_uint32 ( void  )

Helper to generate random 32-bit unsigned integers (useful for SSRCs, etc.)

Note
Currently just wraps g_random_int()
Returns
A random 32-bit unsigned integer
guint64 janus_random_uint64 ( void  )

Helper to generate random 64-bit unsigned integers (useful for Janus IDs)

Returns
A random 64-bit unsigned integer
void janus_set1 ( guint8 *  data,
size_t  i,
guint8  val 
)
inline

Helper method to set one byte at a memory position.

Parameters
[in]datamemory data pointer
[in]iposition in memory to change
[in]valvalue to write
void janus_set2 ( guint8 *  data,
size_t  i,
guint32  val 
)
inline

Helper method to set two bytes at a memory position.

Parameters
[in]datamemory data pointer
[in]iposition in memory to change
[in]valvalue to write
void janus_set3 ( guint8 *  data,
size_t  i,
guint32  val 
)
inline

Helper method to set three bytes at a memory position.

Parameters
[in]datamemory data pointer
[in]iposition in memory to change
[in]valvalue to write
void janus_set4 ( guint8 *  data,
size_t  i,
guint32  val 
)
inline

Helper method to set four bytes at a memory position.

Parameters
[in]datamemory data pointer
[in]iposition in memory to change
[in]valvalue to write
gboolean janus_strcmp_const_time ( const void *  str1,
const void *  str2 
)

Helper to compare strings in constant time.

Parameters
str1The first string to compare
str2The second string to compare
Returns
true if the strings are the same, false otherwise
char* janus_string_replace ( char *  message,
const char *  old_string,
const char *  new_string 
)

Helper to replace strings.

Parameters
messageThe string that contains the text to replace, which may be freed if it is too short
old_stringThe old text to replace
new_stringThe new text
Returns
A pointer to the updated text string (re-allocated or just updated)
guint64* janus_uint64_dup ( guint64  num)

Helper to generate an allocated copy of a guint64 number.

Note
While apparently silly, this is needed in order to make sure guint64 values used as keys in GHashTable operations are not lost: using temporary guint64 numbers in a g_hash_table_insert, for instance, will cause the key to contain garbage as soon as the temporary variable is lost, and all opererations on the key to fail
Parameters
numThe guint64 number to duplicate
Returns
A pointer to a guint64 number, if successful, NULL otherwise
gboolean janus_vp8_is_keyframe ( char *  buffer,
int  len 
)

Helper method to check if a VP8 frame is a keyframe or not.

Parameters
[in]bufferThe RTP payload to process
[in]lenThe length of the RTP payload
Returns
TRUE if it's a keyframe, FALSE otherwise
int janus_vp8_parse_descriptor ( char *  buffer,
int  len,
uint16_t *  picid,
uint8_t *  tl0picidx,
uint8_t *  tid,
uint8_t *  y,
uint8_t *  keyidx 
)

Helper method to parse a VP8 payload descriptor for useful info (e.g., when simulcasting)

Parameters
[in]bufferThe RTP payload to process
[in]lenThe length of the RTP payload
[out]picidThe Picture ID
[out]tl0picidxTemporal level zero index
[out]tidTemporal-layer index
[out]yLayer sync bit
[out]keyidxTemporal key frame index
Returns
0 in case of success, a negative integer otherwise
void janus_vp8_simulcast_context_reset ( janus_vp8_simulcast_context context)

Set (or reset) the context fields to their default values.

Parameters
[in]contextThe context to (re)set
void janus_vp8_simulcast_descriptor_update ( char *  buffer,
int  len,
janus_vp8_simulcast_context context,
gboolean  switched 
)

Use the context info to update the RTP header of a packet, if needed.

Parameters
[in]bufferThe RTP payload to process
[in]lenThe length of the RTP payload
[in]contextThe context to use as a reference
[in]switchedWhether there has been a source switch or not (important to compute offsets)
gboolean janus_vp9_is_keyframe ( char *  buffer,
int  len 
)

Helper method to check if a VP9 frame is a keyframe or not.

Parameters
[in]bufferThe RTP payload to process
[in]lenThe length of the RTP payload
Returns
TRUE if it's a keyframe, FALSE otherwise
int janus_vp9_parse_svc ( char *  buffer,
int  len,
int *  found,
int *  spatial_layer,
int *  temporal_layer,
uint8_t *  p,
uint8_t *  d,
uint8_t *  u,
uint8_t *  b,
uint8_t *  e 
)

Helper method to parse a VP9 payload descriptor for SVC-related info (e.g., when SVC is enabled)

Parameters
[in]bufferThe RTP payload to process
[in]lenThe length of the RTP payload
[out]foundWhether any SVC related info has been found or not
[out]spatial_layerSpatial layer of the packet
[out]temporal_layerTemporal layer of the packet
[out]pInter-picture predicted picture bit
[out]dInter-layer dependency used bit
[out]uSwitching up point bit
[out]bStart of a frame bit
[out]eEnd of a frame bit
Returns
0 in case of success, a negative integer otherwise