Statistics
| Branch: | Revision:

janus-gateway / sdp-utils.h @ 5de69b28

History | View | Annotate | Download (13.6 KB)

1
/*! \file    sdp-utils.h
2
 * \author   Lorenzo Miniero <lorenzo@meetecho.com>
3
 * \copyright GNU General Public License v3
4
 * \brief    SDP utilities (headers)
5
 * \details  Implementation of an internal SDP representation. Allows
6
 * to parse SDP strings to an internal janus_sdp object, the manipulation
7
 * of such object by playing with its properties, and a serialization
8
 * to an SDP string that can be passed around. Since they don't have any
9
 * core dependencies, these utilities can be used by plugins as well.
10
 * 
11
 * \ingroup core
12
 * \ref core
13
 */
14
 
15
#ifndef _JANUS_SDP_UTILS_H
16
#define _JANUS_SDP_UTILS_H
17

    
18

    
19
#include <inttypes.h>
20
#include <glib.h>
21

    
22
/*! \brief Janus SDP internal object representation */
23
typedef struct janus_sdp {
24
        /*! \brief v= */
25
        int version;
26
        /*! \brief o= name */
27
        char *o_name;
28
        /*! \brief o= session ID */
29
        guint64 o_sessid;
30
        /*! \brief o= version */
31
        guint64 o_version;
32
        /*! \brief o= protocol */
33
        gboolean o_ipv4;
34
        /*! \brief o= address */
35
        char *o_addr;
36
        /*! \brief s= */
37
        char *s_name;
38
        /*! \brief t= start */
39
        guint64 t_start;
40
        /*! \brief t= stop */
41
        guint64 t_stop;
42
        /*! \brief c= protocol (not rendered for WebRTC usage) */
43
        gboolean c_ipv4;
44
        /*! \brief c= address (not rendered for WebRTC usage) */
45
        char *c_addr;
46
        /*! \brief List of global a= attributes */
47
        GList *attributes;
48
        /*! \brief List of m= m-lines */
49
        GList *m_lines;
50
} janus_sdp;
51

    
52
/*! \brief Helper enumeration to quickly identify m-line media types */
53
typedef enum janus_sdp_mtype {
54
        /*! \brief m=audio */
55
        JANUS_SDP_AUDIO,
56
        /*! \brief m=video */
57
        JANUS_SDP_VIDEO,
58
        /*! \brief m=application */
59
        JANUS_SDP_APPLICATION,
60
        /*! \brief m=whatever (we don't care, unsupported) */
61
        JANUS_SDP_OTHER
62
} janus_sdp_mtype;
63
/*! \brief Helper method to get a janus_sdp_mtype from a string
64
 * @param[in] type The type to parse as a string (e.g., "audio")
65
 * @returns The corresponding janus_sdp_mtype value */
66
janus_sdp_mtype janus_sdp_parse_mtype(const char *type);
67
/*! \brief Helper method to get the string associated to a janus_sdp_mtype value
68
 * @param[in] type The type to stringify
69
 * @returns The type as a string, if valid, or NULL otherwise */
70
const char *janus_sdp_mtype_str(janus_sdp_mtype type);
71

    
72
/*! \brief Helper enumeration to quickly identify m-line directions */
73
typedef enum janus_sdp_mdirection {
74
        /*! \brief default=sendrecv */
75
        JANUS_SDP_DEFAULT,
76
        /*! \brief sendrecv */
77
        JANUS_SDP_SENDRECV,
78
        /*! \brief sendonly */
79
        JANUS_SDP_SENDONLY,
80
        /*! \brief recvonly */
81
        JANUS_SDP_RECVONLY,
82
        /*! \brief inactive */
83
        JANUS_SDP_INACTIVE,
84
        /*! \brief invalid direction (when parsing) */
85
        JANUS_SDP_INVALID
86
} janus_sdp_mdirection;
87
/*! \brief Helper method to get a janus_sdp_mdirection from a string
88
 * @param[in] direction The direction to parse as a string (e.g., "sendrecv")
89
 * @returns The corresponding janus_sdp_mdirection value */
90
janus_sdp_mdirection janus_sdp_parse_mdirection(const char *direction);
91
/*! \brief Helper method to get the string associated to a janus_sdp_mdirection value
92
 * @param[in] direction The direction to stringify
93
 * @returns The direction as a string, if valid, or NULL otherwise */
94
const char *janus_sdp_mdirection_str(janus_sdp_mdirection direction);
95

    
96
/*! \brief SDP m-line representation */
97
typedef struct janus_sdp_mline {
98
        /*! \brief Media type as a janus_sdp_mtype enumerator */
99
        janus_sdp_mtype type;
100
        /*! \brief Media type (string) */
101
        char *type_str;
102
        /*! \brief Media port */
103
        guint16 port;
104
        /*! \brief Media protocol */
105
        char *proto;
106
        /*! \brief List of formats */
107
        GList *fmts;
108
        /*! \brief List of payload types */
109
        GList *ptypes;
110
        /*! \brief Media c= protocol */
111
        gboolean c_ipv4;
112
        /*! \brief Media c= address */
113
        char *c_addr;
114
        /*! \brief Media b= type */
115
        char *b_name;
116
        /*! \brief Media b= value */
117
        int b_value;
118
        /*! \brief Media direction */
119
        janus_sdp_mdirection direction;
120
        /*! \brief List of m-line attributes */
121
        GList *attributes;
122
} janus_sdp_mline;
123
/*! \brief Helper method to quickly create a janus_sdp_mline instance
124
 * @note The \c type_str property of the new m-line is created automatically
125
 * depending on the provided \c type attribute. If \c type is JANUS_SDP_OTHER,
126
 * though, \c type_str will NOT we allocated, and will be up to the caller.
127
 * @param[in] type Type of the media (audio/video/application) as a janus_sdp_mtype
128
 * @param[in] port Port to advertise
129
 * @param[in] proto Profile to advertise
130
 * @param[in] type Direction of the media as a janus_sdp_direction
131
 * @returns A pointer to a valid janus_sdp_mline instance, if successfull, NULL otherwise */
132
janus_sdp_mline *janus_sdp_mline_create(janus_sdp_mtype type, guint16 port, const char *proto, janus_sdp_mdirection direction);
133
/*! \brief Helper method to free a janus_sdp_mline instance
134
 * @note This method does not remove the m-line from the janus_sdp instance, that's up to the caller
135
 * @param[in] mline The janus_sdp_mline instance to free */
136
void janus_sdp_mline_destroy(janus_sdp_mline *mline);
137
/*! \brief Helper method to get the janus_sdp_mline associated to a media type
138
 * @note This currently returns the first m-line of the specified type it finds: in
139
 * general, it shouldn't be an issue as we currently only support a single stream
140
 * of the same type per session anyway... this will need to be fixed in the future.
141
 * @param[in] sdp The Janus SDP object to search
142
 * @param[in] type The type of media to search
143
 * @returns The janus_sdp_mline instance, if found, or NULL otherwise */
144
janus_sdp_mline *janus_sdp_mline_find(janus_sdp *sdp, janus_sdp_mtype type);
145

    
146
/*! \brief SDP a= attribute representation */
147
typedef struct janus_sdp_attribute {
148
        /*! \brief Attribute name */
149
        char *name;
150
        /*! \brief Attribute value */
151
        char *value;
152
        /*! \brief Attribute direction (e.g., for extmap) */
153
        janus_sdp_mdirection direction;
154
} janus_sdp_attribute;
155
/*! \brief Helper method to quickly create a janus_sdp_attribute instance
156
 * @param[in] name Name of the attribute
157
 * @param[in] value Value of the attribute, as a printf compliant string (variable arguments)
158
 * @returns A pointer to a valid janus_sdp_attribute instance, if successfull, NULL otherwise */
159
janus_sdp_attribute *janus_sdp_attribute_create(const char *name, const char *value, ...) G_GNUC_PRINTF(2, 3);
160
/*! \brief Helper method to free a janus_sdp_attribute instance
161
 * @note This method does not remove the attribute from the global or m-line attributes, that's up to the caller
162
 * @param[in] attr The janus_sdp_attribute instance to free */
163
void janus_sdp_attribute_destroy(janus_sdp_attribute *attr);
164
/*! \brief Helper method to add an attribute to a media line
165
 * @param[in] mline The m-line to add the attribute to
166
 * @param[in] attr The attribute to add
167
 * @returns 0 in case of success, -1 otherwise */
168
int janus_sdp_attribute_add_to_mline(janus_sdp_mline *mline, janus_sdp_attribute *attr);
169

    
170
/*! \brief Method to parse an SDP string to a janus_sdp object
171
 * @param[in] sdp The SDP string to parse
172
 * @param[in,out] error Buffer to receive a reason for an error, if any
173
 * @param[in] errlen The length of the error buffer
174
 * @returns A pointer to a janus_sdp object, if successful, NULL otherwise; in case
175
 * of errors, if provided the error string is filled with a reason  */
176
janus_sdp *janus_sdp_parse(const char *sdp, char *error, size_t errlen);
177

    
178
/*! \brief Helper method to quickly remove all traces (m-line, rtpmap, fmtp, etc.) of a payload type
179
 * @param[in] sdp The janus_sdp object to remove the payload type from
180
 * @param[in] pt The payload type to remove
181
 * @returns 0 in case of success, a negative integer otherwise */
182
int janus_sdp_remove_payload_type(janus_sdp *sdp, int pt);
183

    
184
/*! \brief Method to serialize a janus_sdp object to an SDP string
185
 * @param[in] sdp The janus_sdp object to serialize
186
 * @returns A pointer to a string with the serialized SDP, if successful, NULL otherwise */
187
char *janus_sdp_write(janus_sdp *sdp);
188

    
189
/*! \brief Method to quickly generate a janus_sdp instance from a few selected fields
190
 * @note This allocates the \c o_addr, \c s_name and \c c_addr properties: if you
191
 * want to replace them, don't remember to \c g_free the original pointers first.
192
 * @param[in] name The session name (if NULL, a default value will be set)
193
 * @param[in] address The IP to set in o= and c= fields (if NULL, a default value will be set)
194
 * @returns A pointer to a janus_sdp object, if successful, NULL otherwise */
195
janus_sdp *janus_sdp_new(const char *name, const char *address);
196

    
197
/*! \brief Method to free a Janus SDP object
198
 * @param[in] sdp The Janus SDP object to free */
199
void janus_sdp_free(janus_sdp *sdp);
200

    
201
/*! \brief When generating an offer or answer automatically, accept/reject audio if offered (depends on value that follows) */
202
#define JANUS_SDP_OA_AUDIO                                        1
203
/*! \brief When generating an offer or answer automatically, accept/reject video if offered (depends on value that follows) */
204
#define JANUS_SDP_OA_VIDEO                                        2
205
/*! \brief When generating an offer or answer automatically, accept/reject datachannels if offered (depends on value that follows) */
206
#define JANUS_SDP_OA_DATA                                        3
207
/*! \brief When generating an offer or answer automatically, use this direction for audio (depends on value that follows) */
208
#define JANUS_SDP_OA_AUDIO_DIRECTION                4
209
/*! \brief When generating an offer or answer automatically, use this direction for video (depends on value that follows) */
210
#define JANUS_SDP_OA_VIDEO_DIRECTION                5
211
/*! \brief When generating an offer or answer automatically, use this codec for audio (depends on value that follows) */
212
#define JANUS_SDP_OA_AUDIO_CODEC                        6
213
/*! \brief When generating an offer or answer automatically, use this codec for video (depends on value that follows) */
214
#define JANUS_SDP_OA_VIDEO_CODEC                        7
215
/*! \brief When generating an offer (this is ignored for answers), use this payload type for audio (depends on value that follows) */
216
#define JANUS_SDP_OA_AUDIO_PT                                8
217
/*! \brief When generating an offer (this is ignored for answers), use this payload type for video (depends on value that follows) */
218
#define JANUS_SDP_OA_VIDEO_PT                        9
219
/*! \brief When generating an offer or answer automatically, do or do not negotiate telephone events (FIXME telephone-event/8000 only) */
220
#define JANUS_SDP_OA_AUDIO_DTMF                                10
221
/*! \brief When generating an offer or answer automatically, do or do not add the rtcpfb attributes we typically negotiate (fir, nack, pli, remb) */
222
#define JANUS_SDP_OA_VIDEO_RTCPFB_DEFAULTS        11
223
/*! \brief 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) */
224
#define JANUS_SDP_OA_VIDEO_H264_FMTP                12
225
/*! \brief MUST be used as the last argument in janus_sdp_generate_answer */
226
#define JANUS_SDP_OA_DONE                                        0
227

    
228
/*! \brief Method to generate a janus_sdp offer, using variable arguments to dictate
229
 * what to negotiate (e.g., in terms of media to offer, directions, etc.). Variable
230
 * arguments are in the form of a sequence of name-value terminated by a JANUS_SDP_OA_DONE, e.g.:
231
 \verbatim
232
        janus_sdp *offer = janus_sdp_generate_offer("My session", "127.0.0.1",
233
                JANUS_SDP_OA_AUDIO, TRUE,
234
                JANUS_SDP_OA_AUDIO_PT, 100,
235
                JANUS_SDP_OA_AUDIO_DIRECTION, JANUS_SDP_SENDONLY,
236
                JANUS_SDP_OA_AUDIO_CODEC, "opus",
237
                JANUS_SDP_OA_VIDEO, FALSE,
238
                JANUS_SDP_OA_DATA, FALSE,
239
                JANUS_SDP_OA_DONE);
240
 \endverbatim
241
 * to only offer a \c sendonly Opus audio stream being offered with 100 as
242
 * payload type, and avoid video and datachannels. Refer to the property names in
243
 * the header file for a complete list of how you can drive the offer.
244
 * The default, if not specified, is to offer everything, using Opus with pt=111
245
 * for audio, VP8 with pt=96 as video, and data channels, all as \c sendrecv.
246
 * @param[in] name The session name (if NULL, a default value will be set)
247
 * @param[in] address The IP to set in o= and c= fields (if NULL, a default value will be set)
248
 * @returns A pointer to a janus_sdp object, if successful, NULL otherwise */
249
janus_sdp *janus_sdp_generate_offer(const char *name, const char *address, ...);
250
/*! \brief Method to generate a janus_sdp answer to a provided janus_sdp offer, using variable arguments
251
 * to dictate how to responde (e.g., in terms of media to accept, reject, directions, etc.). Variable
252
 * arguments are in the form of a sequence of name-value terminated by a JANUS_SDP_OA_DONE, e.g.:
253
 \verbatim
254
        janus_sdp *answer = janus_sdp_generate_answer(offer,
255
                JANUS_SDP_OA_AUDIO, TRUE,
256
                JANUS_SDP_OA_AUDIO_DIRECTION, JANUS_SDP_RECVONLY,
257
                JANUS_SDP_OA_AUDIO_CODEC, "opus",
258
                JANUS_SDP_OA_VIDEO, FALSE,
259
                JANUS_SDP_OA_DATA, FALSE,
260
                JANUS_SDP_OA_DONE);
261
 \endverbatim
262
 * to only accept the audio stream being offered, but as \c recvonly, use Opus
263
 * and reject both video and datachannels. Refer to the property names in
264
 * the header file for a complete list of how you can drive the answer.
265
 * The default, if not specified, is to accept everything as \c sendrecv.
266
 * @param[in] offer The Janus SDP offer to respond to
267
 * @returns A pointer to a janus_sdp object, if successful, NULL otherwise */
268
janus_sdp *janus_sdp_generate_answer(janus_sdp *offer, ...);
269

    
270
/*! \brief Helper to get the payload type associated to a specific codec
271
 * @param sdp The Janus SDP instance to process
272
 * @param codec The codec to find, as a string
273
 * @returns The payload type, if found, or -1 otherwise */
274
int janus_sdp_get_codec_pt(janus_sdp *sdp, const char *codec);
275

    
276
/*! \brief Helper to get the codec name associated to a specific payload type
277
 * @param sdp The Janus SDP instance to process
278
 * @param pt The payload type to find
279
 * @returns The codec name, if found, or NULL otherwise */
280
const char *janus_sdp_get_codec_name(janus_sdp *sdp, int pt);
281

    
282
/*! \brief Helper to get the rtpmap associated to a specific codec
283
 * @param codec The codec name, as a string (e.g., "opus")
284
 * @returns The rtpmap value, if found (e.g., "opus/48000/2"), or -1 otherwise */
285
const char *janus_sdp_get_codec_rtpmap(const char *codec);
286

    
287
#endif