Fork me on GitHub
Data Structures | 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...
 

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...
 
typedef enum janus_sdp_oa_type janus_sdp_oa_type
 

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...
 
enum  janus_sdp_oa_type {
  JANUS_SDP_OA_AUDIO = 1, JANUS_SDP_OA_VIDEO, JANUS_SDP_OA_DATA, JANUS_SDP_OA_AUDIO_DIRECTION,
  JANUS_SDP_OA_VIDEO_DIRECTION, JANUS_SDP_OA_AUDIO_CODEC, JANUS_SDP_OA_VIDEO_CODEC, JANUS_SDP_OA_AUDIO_PT,
  JANUS_SDP_OA_VIDEO_PT, JANUS_SDP_OA_AUDIO_DTMF, JANUS_SDP_OA_VIDEO_RTCPFB_DEFAULTS, JANUS_SDP_OA_VIDEO_H264_FMTP,
  JANUS_SDP_OA_DATA_LEGACY, JANUS_SDP_OA_DONE = 0
}
 

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 respond (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

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)

Enumerator
JANUS_SDP_OA_AUDIO 

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

JANUS_SDP_OA_VIDEO 

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

JANUS_SDP_OA_DATA 

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

JANUS_SDP_OA_AUDIO_DIRECTION 

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

JANUS_SDP_OA_VIDEO_DIRECTION 

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

JANUS_SDP_OA_AUDIO_CODEC 

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

JANUS_SDP_OA_VIDEO_CODEC 

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

JANUS_SDP_OA_AUDIO_PT 

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

JANUS_SDP_OA_VIDEO_PT 

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

JANUS_SDP_OA_AUDIO_DTMF 

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

JANUS_SDP_OA_VIDEO_RTCPFB_DEFAULTS 

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

JANUS_SDP_OA_VIDEO_H264_FMTP 

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)

JANUS_SDP_OA_DATA_LEGACY 

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)

JANUS_SDP_OA_DONE 

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

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 respond (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 forget 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