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

SDP utilities (headers) More...

#include <inttypes.h>
#include <glib.h>
#include "refcount.h"
Include dependency graph for sdp-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_sdp
 Janus SDP internal object representation. More...
 
struct  janus_sdp_mline
 SDP m-line representation. More...
 
struct  janus_sdp_attribute
 SDP a= attribute representation. More...
 

Macros

#define JANUS_SDP_OA_AUDIO   1
 When generating an offer or answer automatically, accept/reject audio if offered (depends on value that follows) More...
 
#define JANUS_SDP_OA_VIDEO   2
 When generating an offer or answer automatically, accept/reject video if offered (depends on value that follows) More...
 
#define JANUS_SDP_OA_DATA   3
 When generating an offer or answer automatically, accept/reject datachannels if offered (depends on value that follows) More...
 
#define JANUS_SDP_OA_AUDIO_DIRECTION   4
 When generating an offer or answer automatically, use this direction for audio (depends on value that follows) More...
 
#define JANUS_SDP_OA_VIDEO_DIRECTION   5
 When generating an offer or answer automatically, use this direction for video (depends on value that follows) More...
 
#define JANUS_SDP_OA_AUDIO_CODEC   6
 When generating an offer or answer automatically, use this codec for audio (depends on value that follows) More...
 
#define JANUS_SDP_OA_VIDEO_CODEC   7
 When generating an offer or answer automatically, use this codec for video (depends on value that follows) More...
 
#define JANUS_SDP_OA_AUDIO_PT   8
 When generating an offer (this is ignored for answers), use this payload type for audio (depends on value that follows) More...
 
#define JANUS_SDP_OA_VIDEO_PT   9
 When generating an offer (this is ignored for answers), use this payload type for video (depends on value that follows) More...
 
#define JANUS_SDP_OA_AUDIO_DTMF   10
 When generating an offer or answer automatically, do or do not negotiate telephone events (FIXME telephone-event/8000 only) More...
 
#define JANUS_SDP_OA_VIDEO_RTCPFB_DEFAULTS   11
 When generating an offer or answer automatically, do or do not add the rtcpfb attributes we typically negotiate (fir, nack, pli, remb) More...
 
#define JANUS_SDP_OA_VIDEO_H264_FMTP   12
 When generating an offer or answer automatically, do or do not add the default fmtp attribute for H.264 (profile-level-id=42e01f;packetization-mode=1) More...
 
#define JANUS_SDP_OA_DATA_LEGACY   13
 When generating an offer (this is ignored for answers), use the old "DTLS/SCTP" instead of the new "UDP/DTLS/SCTP (default=TRUE for now, depends on what follows) More...
 
#define JANUS_SDP_OA_DONE   0
 MUST be used as the last argument in janus_sdp_generate_offer and janus_sdp_generate_answer. More...
 

Typedefs

typedef struct janus_sdp janus_sdp
 Janus SDP internal object representation. More...
 
typedef enum janus_sdp_mtype janus_sdp_mtype
 Helper enumeration to quickly identify m-line media types. More...
 
typedef enum janus_sdp_mdirection janus_sdp_mdirection
 Helper enumeration to quickly identify m-line directions. More...
 
typedef struct janus_sdp_mline janus_sdp_mline
 SDP m-line representation. More...
 
typedef struct janus_sdp_attribute janus_sdp_attribute
 SDP a= attribute representation. More...
 

Enumerations

enum  janus_sdp_mtype { JANUS_SDP_AUDIO, JANUS_SDP_VIDEO, JANUS_SDP_APPLICATION, JANUS_SDP_OTHER }
 Helper enumeration to quickly identify m-line media types. More...
 
enum  janus_sdp_mdirection {
  JANUS_SDP_DEFAULT, JANUS_SDP_SENDRECV, JANUS_SDP_SENDONLY, JANUS_SDP_RECVONLY,
  JANUS_SDP_INACTIVE, JANUS_SDP_INVALID
}
 Helper enumeration to quickly identify m-line directions. More...
 

Functions

janus_sdp_mtype janus_sdp_parse_mtype (const char *type)
 Helper method to get a janus_sdp_mtype from a string. More...
 
const char * janus_sdp_mtype_str (janus_sdp_mtype type)
 Helper method to get the string associated to a janus_sdp_mtype value. More...
 
janus_sdp_mdirection janus_sdp_parse_mdirection (const char *direction)
 Helper method to get a janus_sdp_mdirection from a string. More...
 
const char * janus_sdp_mdirection_str (janus_sdp_mdirection direction)
 Helper method to get the string associated to a janus_sdp_mdirection value. More...
 
void janus_sdp_find_preferred_codecs (janus_sdp *sdp, const char **acodec, const char **vcodec)
 Helper method to return the preferred audio and video codecs in an SDP offer or answer, (where by preferred we mean the codecs we prefer ourselves, and not the m-line SDP order) as long as the m-line direction is not disabled (port=0 or direction=inactive) in the SDP. More...
 
void janus_sdp_find_first_codecs (janus_sdp *sdp, const char **acodec, const char **vcodec)
 Helper method to return the first audio and video codecs in an SDP offer or answer, (no matter whether we personally prefer them ourselves or not) as long as the m-line direction is not disabled (port=0 or direction=inactive) in the SDP. More...
 
const char * janus_sdp_match_preferred_codec (janus_sdp_mtype type, char *codec)
 Helper method to match a codec to one of the preferred codecs. More...
 
janus_sdp_mlinejanus_sdp_mline_create (janus_sdp_mtype type, guint16 port, const char *proto, janus_sdp_mdirection direction)
 Helper method to quickly create a janus_sdp_mline instance. More...
 
void janus_sdp_mline_destroy (janus_sdp_mline *mline)
 Helper method to free a janus_sdp_mline instance. More...
 
janus_sdp_mlinejanus_sdp_mline_find (janus_sdp *sdp, janus_sdp_mtype type)
 Helper method to get the janus_sdp_mline associated to a media type. More...
 
int janus_sdp_mline_remove (janus_sdp *sdp, janus_sdp_mtype type)
 Helper method to remove the janus_sdp_mline associated to a media type from the SDP. More...
 
janus_sdp_attributejanus_sdp_attribute_create (const char *name, const char *value,...) G_GNUC_PRINTF(2
 Helper method to quickly create a janus_sdp_attribute instance. More...
 
janus_sdp_attribute void janus_sdp_attribute_destroy (janus_sdp_attribute *attr)
 Helper method to free a janus_sdp_attribute instance. More...
 
int janus_sdp_attribute_add_to_mline (janus_sdp_mline *mline, janus_sdp_attribute *attr)
 Helper method to add an attribute to a media line. More...
 
janus_sdpjanus_sdp_parse (const char *sdp, char *error, size_t errlen)
 Method to parse an SDP string to a janus_sdp object. More...
 
int janus_sdp_remove_payload_type (janus_sdp *sdp, int pt)
 Helper method to quickly remove all traces (m-line, rtpmap, fmtp, etc.) of a payload type. More...
 
char * janus_sdp_write (janus_sdp *sdp)
 Method to serialize a janus_sdp object to an SDP string. More...
 
janus_sdpjanus_sdp_new (const char *name, const char *address)
 Method to quickly generate a janus_sdp instance from a few selected fields. More...
 
void janus_sdp_destroy (janus_sdp *sdp)
 Method to destroy a Janus SDP object. More...
 
janus_sdpjanus_sdp_generate_offer (const char *name, const char *address,...)
 Method to generate a janus_sdp offer, using variable arguments to dictate what to negotiate (e.g., in terms of media to offer, directions, etc.). Variable arguments are in the form of a sequence of name-value terminated by a JANUS_SDP_OA_DONE, e.g.: More...
 
janus_sdpjanus_sdp_generate_answer (janus_sdp *offer,...)
 Method to generate a janus_sdp answer to a provided janus_sdp offer, using variable arguments to dictate how to responde (e.g., in terms of media to accept, reject, directions, etc.). Variable arguments are in the form of a sequence of name-value terminated by a JANUS_SDP_OA_DONE, e.g.: More...
 
int janus_sdp_get_codec_pt (janus_sdp *sdp, const char *codec)
 Helper to get the payload type associated to a specific codec. More...
 
const char * janus_sdp_get_codec_name (janus_sdp *sdp, int pt)
 Helper to get the codec name associated to a specific payload type. More...
 
const char * janus_sdp_get_codec_rtpmap (const char *codec)
 Helper to get the rtpmap associated to a specific codec. More...
 

Detailed Description

SDP utilities (headers)

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

Implementation of an internal SDP representation. Allows to parse SDP strings to an internal janus_sdp object, the manipulation of such object by playing with its properties, and a serialization to an SDP string that can be passed around. Since they don't have any core dependencies, these utilities can be used by plugins as well.

Core

Macro Definition Documentation

#define JANUS_SDP_OA_AUDIO   1

When generating an offer or answer automatically, accept/reject audio if offered (depends on value that follows)

#define JANUS_SDP_OA_AUDIO_CODEC   6

When generating an offer or answer automatically, use this codec for audio (depends on value that follows)

#define JANUS_SDP_OA_AUDIO_DIRECTION   4

When generating an offer or answer automatically, use this direction for audio (depends on value that follows)

#define JANUS_SDP_OA_AUDIO_DTMF   10

When generating an offer or answer automatically, do or do not negotiate telephone events (FIXME telephone-event/8000 only)

#define JANUS_SDP_OA_AUDIO_PT   8

When generating an offer (this is ignored for answers), use this payload type for audio (depends on value that follows)

#define JANUS_SDP_OA_DATA   3

When generating an offer or answer automatically, accept/reject datachannels if offered (depends on value that follows)

#define JANUS_SDP_OA_DATA_LEGACY   13

When generating an offer (this is ignored for answers), use the old "DTLS/SCTP" instead of the new "UDP/DTLS/SCTP (default=TRUE for now, depends on what follows)

#define JANUS_SDP_OA_DONE   0

MUST be used as the last argument in janus_sdp_generate_offer and janus_sdp_generate_answer.

#define JANUS_SDP_OA_VIDEO   2

When generating an offer or answer automatically, accept/reject video if offered (depends on value that follows)

#define JANUS_SDP_OA_VIDEO_CODEC   7

When generating an offer or answer automatically, use this codec for video (depends on value that follows)

#define JANUS_SDP_OA_VIDEO_DIRECTION   5

When generating an offer or answer automatically, use this direction for video (depends on value that follows)

#define JANUS_SDP_OA_VIDEO_H264_FMTP   12

When generating an offer or answer automatically, do or do not add the default fmtp attribute for H.264 (profile-level-id=42e01f;packetization-mode=1)

#define JANUS_SDP_OA_VIDEO_PT   9

When generating an offer (this is ignored for answers), use this payload type for video (depends on value that follows)

#define JANUS_SDP_OA_VIDEO_RTCPFB_DEFAULTS   11

When generating an offer or answer automatically, do or do not add the rtcpfb attributes we typically negotiate (fir, nack, pli, remb)

Typedef Documentation

typedef struct janus_sdp janus_sdp

Janus SDP internal object representation.

SDP a= attribute representation.

Helper enumeration to quickly identify m-line directions.

SDP m-line representation.

Helper enumeration to quickly identify m-line media types.

Enumeration Type Documentation

Helper enumeration to quickly identify m-line directions.

Enumerator
JANUS_SDP_DEFAULT 

default=sendrecv

JANUS_SDP_SENDRECV 

sendrecv

JANUS_SDP_SENDONLY 

sendonly

JANUS_SDP_RECVONLY 

recvonly

JANUS_SDP_INACTIVE 

inactive

JANUS_SDP_INVALID 

invalid direction (when parsing)

Helper enumeration to quickly identify m-line media types.

Enumerator
JANUS_SDP_AUDIO 

m=audio

JANUS_SDP_VIDEO 

m=video

JANUS_SDP_APPLICATION 

m=application

JANUS_SDP_OTHER 

m=whatever (we don't care, unsupported)

Function Documentation

int janus_sdp_attribute_add_to_mline ( janus_sdp_mline mline,
janus_sdp_attribute attr 
)

Helper method to add an attribute to a media line.

Parameters
[in]mlineThe m-line to add the attribute to
[in]attrThe attribute to add
Returns
0 in case of success, -1 otherwise
janus_sdp_attribute* janus_sdp_attribute_create ( const char *  name,
const char *  value,
  ... 
)

Helper method to quickly create a janus_sdp_attribute instance.

Parameters
[in]nameName of the attribute
[in]valueValue of the attribute, as a printf compliant string (variable arguments)
Returns
A pointer to a valid janus_sdp_attribute instance, if successfull, NULL otherwise
janus_sdp_attribute void janus_sdp_attribute_destroy ( janus_sdp_attribute attr)

Helper method to free a janus_sdp_attribute instance.

Note
This method does not remove the attribute from the global or m-line attributes, that's up to the caller
Parameters
[in]attrThe janus_sdp_attribute instance to free
void janus_sdp_destroy ( janus_sdp sdp)

Method to destroy a Janus SDP object.

Parameters
[in]sdpThe Janus SDP object to free
void janus_sdp_find_first_codecs ( janus_sdp sdp,
const char **  acodec,
const char **  vcodec 
)

Helper method to return the first audio and video codecs in an SDP offer or answer, (no matter whether we personally prefer them ourselves or not) as long as the m-line direction is not disabled (port=0 or direction=inactive) in the SDP.

Note
The acodec and vcodec arguments are input/output, and they'll be set to a static value in janus_preferred_audio_codecs and janus_preferred_video_codecs, so don't free them.
Parameters
[in]sdpThe Janus SDP object to parse
[out]acodecThe audio codec that was found
[out]vcodecThe video codec that was found
void janus_sdp_find_preferred_codecs ( janus_sdp sdp,
const char **  acodec,
const char **  vcodec 
)

Helper method to return the preferred audio and video codecs in an SDP offer or answer, (where by preferred we mean the codecs we prefer ourselves, and not the m-line SDP order) as long as the m-line direction is not disabled (port=0 or direction=inactive) in the SDP.

Note
The acodec and vcodec arguments are input/output, and they'll be set to a static value in janus_preferred_audio_codecs and janus_preferred_video_codecs, so don't free them.
Parameters
[in]sdpThe Janus SDP object to parse
[out]acodecThe audio codec that was found
[out]vcodecThe video codec that was found
janus_sdp* janus_sdp_generate_answer ( janus_sdp offer,
  ... 
)

Method to generate a janus_sdp answer to a provided janus_sdp offer, using variable arguments to dictate how to responde (e.g., in terms of media to accept, reject, directions, etc.). Variable arguments are in the form of a sequence of name-value terminated by a JANUS_SDP_OA_DONE, e.g.:

       janus_sdp *answer = janus_sdp_generate_answer(offer,
        JANUS_SDP_OA_AUDIO, TRUE,
        JANUS_SDP_OA_AUDIO_DIRECTION, JANUS_SDP_RECVONLY,
        JANUS_SDP_OA_AUDIO_CODEC, "opus",
        JANUS_SDP_OA_VIDEO, FALSE,
        JANUS_SDP_OA_DATA, FALSE,
        JANUS_SDP_OA_DONE);

to only accept the audio stream being offered, but as recvonly, use Opus and reject both video and datachannels. Refer to the property names in the header file for a complete list of how you can drive the answer. The default, if not specified, is to accept everything as sendrecv.

Parameters
[in]offerThe Janus SDP offer to respond to
Returns
A pointer to a janus_sdp object, if successful, NULL otherwise
janus_sdp* janus_sdp_generate_offer ( const char *  name,
const char *  address,
  ... 
)

Method to generate a janus_sdp offer, using variable arguments to dictate what to negotiate (e.g., in terms of media to offer, directions, etc.). Variable arguments are in the form of a sequence of name-value terminated by a JANUS_SDP_OA_DONE, e.g.:

       janus_sdp *offer = janus_sdp_generate_offer("My session", "127.0.0.1",
        JANUS_SDP_OA_AUDIO, TRUE,
        JANUS_SDP_OA_AUDIO_PT, 100,
        JANUS_SDP_OA_AUDIO_DIRECTION, JANUS_SDP_SENDONLY,
        JANUS_SDP_OA_AUDIO_CODEC, "opus",
        JANUS_SDP_OA_VIDEO, FALSE,
        JANUS_SDP_OA_DATA, FALSE,
        JANUS_SDP_OA_DONE);

to only offer a sendonly Opus audio stream being offered with 100 as payload type, and avoid video and datachannels. Refer to the property names in the header file for a complete list of how you can drive the offer. The default, if not specified, is to offer everything, using Opus with pt=111 for audio, VP8 with pt=96 as video, and data channels, all as sendrecv.

Parameters
[in]nameThe session name (if NULL, a default value will be set)
[in]addressThe IP to set in o= and c= fields (if NULL, a default value will be set)
Returns
A pointer to a janus_sdp object, if successful, NULL otherwise
const char* janus_sdp_get_codec_name ( janus_sdp sdp,
int  pt 
)

Helper to get the codec name associated to a specific payload type.

Parameters
sdpThe Janus SDP instance to process
ptThe payload type to find
Returns
The codec name, if found, or NULL otherwise
int janus_sdp_get_codec_pt ( janus_sdp sdp,
const char *  codec 
)

Helper to get the payload type associated to a specific codec.

Parameters
sdpThe Janus SDP instance to process
codecThe codec to find, as a string
Returns
The payload type, if found, or -1 otherwise
const char* janus_sdp_get_codec_rtpmap ( const char *  codec)

Helper to get the rtpmap associated to a specific codec.

Parameters
codecThe codec name, as a string (e.g., "opus")
Returns
The rtpmap value, if found (e.g., "opus/48000/2"), or -1 otherwise
const char* janus_sdp_match_preferred_codec ( janus_sdp_mtype  type,
char *  codec 
)

Helper method to match a codec to one of the preferred codecs.

Note
Don't free the returned value, as it's a constant value
Parameters
[in]typeThe type of media to match
[in]codecThe codec to match
Returns
The codec, if found, or NULL otherwise
const char* janus_sdp_mdirection_str ( janus_sdp_mdirection  direction)

Helper method to get the string associated to a janus_sdp_mdirection value.

Parameters
[in]directionThe direction to stringify
Returns
The direction as a string, if valid, or NULL otherwise
janus_sdp_mline* janus_sdp_mline_create ( janus_sdp_mtype  type,
guint16  port,
const char *  proto,
janus_sdp_mdirection  direction 
)

Helper method to quickly create a janus_sdp_mline instance.

Note
The type_str property of the new m-line is created automatically depending on the provided type attribute. If type is JANUS_SDP_OTHER, though, type_str will NOT we allocated, and will be up to the caller.
Parameters
[in]typeType of the media (audio/video/application) as a janus_sdp_mtype
[in]portPort to advertise
[in]protoProfile to advertise
[in]directionDirection of the media as a janus_sdp_direction
Returns
A pointer to a valid janus_sdp_mline instance, if successfull, NULL otherwise
void janus_sdp_mline_destroy ( janus_sdp_mline mline)

Helper method to free a janus_sdp_mline instance.

Note
This method does not remove the m-line from the janus_sdp instance, that's up to the caller
Parameters
[in]mlineThe janus_sdp_mline instance to free
janus_sdp_mline* janus_sdp_mline_find ( janus_sdp sdp,
janus_sdp_mtype  type 
)

Helper method to get the janus_sdp_mline associated to a media type.

Note
This currently returns the first m-line of the specified type it finds: in general, it shouldn't be an issue as we currently only support a single stream of the same type per session anyway... this will need to be fixed in the future.
Parameters
[in]sdpThe Janus SDP object to search
[in]typeThe type of media to search
Returns
The janus_sdp_mline instance, if found, or NULL otherwise
int janus_sdp_mline_remove ( janus_sdp sdp,
janus_sdp_mtype  type 
)

Helper method to remove the janus_sdp_mline associated to a media type from the SDP.

Note
This currently removes the first m-line of the specified type it finds: in general, it shouldn't be an issue as we currently only support a single stream of the same type per session anyway... this will need to be fixed in the future.
Parameters
[in]sdpThe Janus SDP object to modify
[in]typeThe type of media to remove
Returns
0 if successful, a negative integer otherwise
const char* janus_sdp_mtype_str ( janus_sdp_mtype  type)

Helper method to get the string associated to a janus_sdp_mtype value.

Parameters
[in]typeThe type to stringify
Returns
The type as a string, if valid, or NULL otherwise
janus_sdp* janus_sdp_new ( const char *  name,
const char *  address 
)

Method to quickly generate a janus_sdp instance from a few selected fields.

Note
This allocates the o_addr, s_name and c_addr properties: if you want to replace them, don't remember to g_free the original pointers first.
Parameters
[in]nameThe session name (if NULL, a default value will be set)
[in]addressThe IP to set in o= and c= fields (if NULL, a default value will be set)
Returns
A pointer to a janus_sdp object, if successful, NULL otherwise
janus_sdp* janus_sdp_parse ( const char *  sdp,
char *  error,
size_t  errlen 
)

Method to parse an SDP string to a janus_sdp object.

Parameters
[in]sdpThe SDP string to parse
[in,out]errorBuffer to receive a reason for an error, if any
[in]errlenThe length of the error buffer
Returns
A pointer to a janus_sdp object, if successful, NULL otherwise; in case of errors, if provided the error string is filled with a reason
janus_sdp_mdirection janus_sdp_parse_mdirection ( const char *  direction)

Helper method to get a janus_sdp_mdirection from a string.

Parameters
[in]directionThe direction to parse as a string (e.g., "sendrecv")
Returns
The corresponding janus_sdp_mdirection value
janus_sdp_mtype janus_sdp_parse_mtype ( const char *  type)

Helper method to get a janus_sdp_mtype from a string.

Parameters
[in]typeThe type to parse as a string (e.g., "audio")
Returns
The corresponding janus_sdp_mtype value
int janus_sdp_remove_payload_type ( janus_sdp sdp,
int  pt 
)

Helper method to quickly remove all traces (m-line, rtpmap, fmtp, etc.) of a payload type.

Parameters
[in]sdpThe janus_sdp object to remove the payload type from
[in]ptThe payload type to remove
Returns
0 in case of success, a negative integer otherwise
char* janus_sdp_write ( janus_sdp sdp)

Method to serialize a janus_sdp object to an SDP string.

Parameters
[in]sdpThe janus_sdp object to serialize
Returns
A pointer to a string with the serialized SDP, if successful, NULL otherwise