VLC 4.0.0-dev
Loading...
Searching...
No Matches
rtp.h
Go to the documentation of this file.
1/**
2 * @file rtp.h
3 * @brief RTP demux module shared declarations
4 */
5/*****************************************************************************
6 * Copyright © 2008 Rémi Denis-Courmont
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public License
10 * as published by the Free Software Foundation; either version 2.1
11 * of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library; if not, write to the Free Software
20 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
21 ****************************************************************************/
22
23/**
24 * \defgroup rtp RTP
25 * Real-time Transport Protocol
26 * \ingroup net
27 *
28 * @{
29 * \file
30 */
31
32typedef struct vlc_rtp_pt rtp_pt_t;
34
36struct vlc_sdp_media;
37
38/**
39 * \defgroup rtp_pt RTP payload formats
40 *
41 * RTP is a somewhat simplistic protocol to carry multiplexed and timestamped
42 * data over an unreliable network. It cannot be used as is: depending on the
43 * concrete type and subtype of data, a format must be selected which
44 * specifically defines how the data is carried as the payload of RTP packets.
45 * This format is known as an RTP payload format.
46 *
47 * A given RTP session (\ref rtp_session_t) can use up to 128 different payload
48 * types (\ref vlc_rtp_pt).
49 * Each payload type is identified by a 7-bit value and designates a
50 * payload format and an associated set of format-dependent parameters
51 * specified by a payload type mapping (\ref vlc_sdp_pt).
52 *
53 * @{
54 */
55
56/**
57 * Payload type mapping.
58 *
59 * This structure represents an RTP payload type mapping for an RTP payload
60 * format extracted from an \ref sdp description.
61 */
62struct vlc_sdp_pt {
63 const struct vlc_sdp_media *media; /**< Containant SDP media description */
64 char name[16]; /**< RTP payload format name, i.e. MIME subtype */
65 unsigned int clock_rate; /**< RTP clock rate (in Hertz) */
66 unsigned char channel_count; /**< Number of channels (0 if unspecified) */
67 const char *parameters; /**< Format parameters from the a=fmtp line */
68};
69
70/**
71 * RTP packet infos.
72 *
73 * This structure conveys infos extracted from the header of an RTP packet
74 * to payload format parsers.
75 */
77 bool m; /**< M bit from the RTP header */
78};
79
80/**
81 * RTP payload type operations.
82 *
83 * This structures contains the callbacks provided by an RTP payload type
84 * (\ref vlc_rtp_pt).
85 */
87 /**
88 * Releases the payload type.
89 *
90 * This optional callback releases any resources associated with the
91 * payload format, such as copies of the payload format parameters.
92 *
93 * \param pt RTP payload type that is being released
94 */
95 void (*release)(struct vlc_rtp_pt *pt);
96
97 /**
98 * Starts using a payload type.
99 *
100 * This required callback initialises per-source resources for the payload
101 * type, such as an elementary stream output.
102 *
103 * \note There may be multiple RTP sources using the same payload type
104 * concurrently within single given RTP session. This callback is invoked
105 * for each source.
106 *
107 * \param pt RTP payload type being taken into use
108 * \return a data pointer for decode() and destroy() callbacks
109 */
110 void *(*init)(struct vlc_rtp_pt *pt);
111
112 /**
113 * Stops using a payload type.
114 *
115 * This optional callback deinitialises per-source resources.
116 *
117 * \param pt RTP payload type to relinquish
118 * \param data data pointer returned by init()
119 */
120 void (*destroy)(struct vlc_rtp_pt *pt, void *data);
121
122 /**
123 * Processes a data payload.
124 *
125 * \param pt RTP payload type of the payload
126 * \param data data pointer returned by init()
127 * \param block payload of a received RTP packet
128 * \param info RTP packet header infos
129 */
130 void (*decode)(struct vlc_rtp_pt *pt, void *data, block_t *block,
131 const struct vlc_rtp_pktinfo *restrict info);
132};
133
134struct vlc_rtp_pt_owner;
135struct vlc_rtp_es;
136
137/**
138 * RTP payload type owner operations.
139 *
140 * This structures contains the callbacks provided by an RTP payload type owner
141 * (\ref vlc_rtp_pt_owner).
142 */
144 struct vlc_rtp_es *(*request_es)(struct vlc_rtp_pt *pt,
145 const es_format_t *restrict fmt);
146 struct vlc_rtp_es *(*request_mux)(struct vlc_rtp_pt *pt, const char *name);
147};
148
149/**
150 * RTP payload type owner.
151 *
152 * This structure embedded in \ref vlc_rtp_pt conveys the callbacks provided by
153 * the owner of a payload type.
154 */
156 const struct vlc_rtp_pt_owner_operations *ops; /**< Owner callbacks */
157 void *data; /**< Owner private data */
158};
159
160/**
161 * RTP payload type.
162 *
163 * This structures represents a payload format within an RTP session
164 * (\ref rtp_session_t).
165 */
167{
168 const struct vlc_rtp_pt_operations *ops; /**< Payload format callbacks */
169 void *opaque; /**< Private data pointer */
171 uint32_t frequency; /**< RTP clock rate (Hz) */
172 uint8_t number; /**< RTP payload type number within the session (0-127) */
173 uint8_t channel_count; /**< Channel count (zero if unspecified) */
174};
175
176/**
177 * Destroys a payload type parameter set.
178 *
179 * This function destroys a payload type.
180 * It can only be called when the payload type has no active sources.
181 */
182void vlc_rtp_pt_release(struct vlc_rtp_pt *pt);
183
184/**
185 * Binds a payload type to a source.
186 *
187 * A given SDP media can have multiple alternative payload types, each with
188 * their set of parameters. The RTP session can then have multiple concurrent
189 * RTP sources (SSRC). This function starts an association of a given payload
190 * type with an unique RTP source.
191 *
192 * @param pt RTP payload type to associate with a source
193 * @return private data for the type-source association
194 */
195static inline void *vlc_rtp_pt_begin(struct vlc_rtp_pt *pt)
196{
197 assert(pt->ops->init != NULL);
198 return pt->ops->init(pt);
199}
200
201/**
202 * Unbinds a payload type from a source.
203 *
204 * This removes an association between a payload type and a source created by
205 * vlc_rtp_pt_begin().
206 *
207 * @param pt RTP payload type to deassociate
208 * @param data private data as returned by vlc_rtp_pt_begin()
209 */
210static inline void vlc_rtp_pt_end(struct vlc_rtp_pt *pt, void *data)
211{
212 if (pt->ops->destroy != NULL)
213 pt->ops->destroy(pt, data);
214}
215
216/**
217 * Processes a payload packet.
218 *
219 * This passes a data payload from an RTP packet for processing to the payload
220 * type bound to the source of the packet. The payload type is determined from
221 * the RTP header PT field and the source from the SSRC field.
222 */
223static inline
224void vlc_rtp_pt_decode(struct vlc_rtp_pt *pt, void *data, block_t *pkt,
225 const struct vlc_rtp_pktinfo *restrict info)
226{
227 assert(pt->ops->decode != NULL);
228 pt->ops->decode(pt, data, pkt, info);
229}
230
231/**
232 * Starts an elementary stream (ES).
233 *
234 * This function is used by an active RTP payload type to create an
235 * elementary (audio, video or subtitle) stream to process encoded data
236 * extracted from an RTP source.
237 *
238 * A given payload type normally maintains one such elementary stream per
239 * active type-source association (\ref vlc_rtp_pt_begin).
240 */
241static inline
243 const es_format_t *restrict fmt)
244{
245 return pt->owner.ops->request_es(pt, fmt);
246}
247
248/**
249 * Starts a complete multiplex.
250 *
251 * This function creates a complete multiplexed multimedia stream to process
252 * data extracted from RTP packets. This should be avoided as much as possible
253 * as RTP is designed to carry raw elementary streams.
254 */
255static inline
257 const char *name)
258{
259 return pt->owner.ops->request_mux(pt, name);
260}
261
262/**
263 * RTP abstract output stream operations.
264 *
265 * This structures contains the callbacks provided by an RTP ES
266 * (\ref vlc_rtp_pt).
267 */
269 /**
270 * Destroys the corresponding \ref vlc_rtp_es.
271 *
272 * Use vlc_rtp_es_destroy() instead.
273 */
274 void (*destroy)(struct vlc_rtp_es *es);
275 /**
276 * Passes data for processing to a \ref vlc_rtp_es.
277 *
278 * Use vlc_rtp_es_send() instead.
279 */
280 void (*send)(struct vlc_rtp_es *es, block_t *block);
281};
282
283/**
284 * RTP abstract output stream.
285 *
286 * This structure represents a data sink for an active instance of a payload
287 * format, typically an output elementary stream (ES) \ref es_out_id_t.
288 */
291};
292
293/**
294 * Destroys an \ref vlc_rtp_es.
295 *
296 * \param es object to release
297 */
298static inline void vlc_rtp_es_destroy(struct vlc_rtp_es *es)
299{
300 assert(es->ops->destroy != NULL);
301 es->ops->destroy(es);
302}
303
304/**
305 * Sends coded data for output.
306 *
307 * \param es output stream to send the data to
308 * \param block data block to process
309 */
310static inline void vlc_rtp_es_send(struct vlc_rtp_es *es, block_t *block)
311{
312 assert(es->ops->send != NULL);
313 es->ops->send(es, block);
314}
315
316/**
317 * A (pointer to a) dummy output that discards data.
318 */
319extern struct vlc_rtp_es *const vlc_rtp_es_dummy;
320
321/**
322 * Callback prototype for RTP parser module.
323 *
324 * This is the callback prototype for any RTP payload format parser module.
325 *
326 * \param obj VLC object for logging and configuration
327 * \param pt RTP payload type
328 * \param[in] desc SDP payload format description and type mapping
329 *
330 * \return VLC_SUCCESS on success, an error code on failure.
331 */
332typedef int (*vlc_rtp_parser_cb)(vlc_object_t *obj, struct vlc_rtp_pt *pt,
333 const struct vlc_sdp_pt *desc);
334
335/**
336 * Helper to set the RTP payload format parser module capability and callback.
337 */
338#define set_rtp_parser_callback(cb) \
339 { \
340 vlc_rtp_parser_cb cb__ = (cb); (void) cb__; \
341 set_callback(cb) \
342 set_capability("rtp parser", 0) \
343 }
344
345int vlc_rtp_pt_instantiate(vlc_object_t *obj, struct vlc_rtp_pt *restrict pt,
346 const struct vlc_sdp_pt *restrict desc);
347
349 const struct vlc_rtp_pt_owner *restrict);
350
351static inline uint8_t rtp_ptype (const block_t *block)
352{
353 return block->p_buffer[1] & 0x7F;
354}
355
356/** @} */
357
358/**
359 * \defgroup rtp_session RTP session
360 * @{
361 */
362#define RTP_MAX_SRC_DEFAULT 1
363#define RTP_MAX_DROPOUT_DEFAULT 3000
364#define RTP_MAX_TIMEOUT_DEFAULT 5
365#define RTP_MAX_MISORDER_DEFAULT 100
366
368rtp_session_t *rtp_session_create_custom (uint16_t max_dropout, uint16_t max_misorder,
369 uint8_t max_src, vlc_tick_t timeout);
371void rtp_queue (struct vlc_logger *, rtp_session_t *, block_t *);
373int rtp_add_type(rtp_session_t *ses, rtp_pt_t *pt);
375 const struct vlc_sdp_media *media,
376 const struct vlc_rtp_pt_owner *restrict owner);
377
378void *rtp_dgram_thread (void *data);
379
380/** @} */
381/** @} */
void rtp_autodetect(vlc_object_t *, rtp_session_t *, const struct vlc_rtp_pt_owner *restrict)
static void * vlc_rtp_pt_begin(struct vlc_rtp_pt *pt)
Binds a payload type to a source.
Definition rtp.h:195
static void vlc_rtp_es_destroy(struct vlc_rtp_es *es)
Destroys an vlc_rtp_es.
Definition rtp.h:298
static uint8_t rtp_ptype(const block_t *block)
Definition rtp.h:351
static struct vlc_rtp_es * vlc_rtp_pt_request_mux(struct vlc_rtp_pt *pt, const char *name)
Starts a complete multiplex.
Definition rtp.h:256
static void vlc_rtp_pt_end(struct vlc_rtp_pt *pt, void *data)
Unbinds a payload type from a source.
Definition rtp.h:210
void vlc_rtp_pt_release(struct vlc_rtp_pt *pt)
Destroys a payload type parameter set.
Definition rtpfmt.c:154
int(* vlc_rtp_parser_cb)(vlc_object_t *obj, struct vlc_rtp_pt *pt, const struct vlc_sdp_pt *desc)
Callback prototype for RTP parser module.
Definition rtp.h:332
static void vlc_rtp_es_send(struct vlc_rtp_es *es, block_t *block)
Sends coded data for output.
Definition rtp.h:310
int vlc_rtp_pt_instantiate(vlc_object_t *obj, struct vlc_rtp_pt *restrict pt, const struct vlc_sdp_pt *restrict desc)
Definition rtp.c:158
static void vlc_rtp_pt_decode(struct vlc_rtp_pt *pt, void *data, block_t *pkt, const struct vlc_rtp_pktinfo *restrict info)
Processes a payload packet.
Definition rtp.h:224
struct vlc_rtp_es *const vlc_rtp_es_dummy
A (pointer to a) dummy output that discards data.
Definition rtpfmt.c:332
static struct vlc_rtp_es * vlc_rtp_pt_request_es(struct vlc_rtp_pt *pt, const es_format_t *restrict fmt)
Starts an elementary stream (ES).
Definition rtp.h:242
int rtp_add_type(rtp_session_t *ses, rtp_pt_t *pt)
Adds a payload type to an RTP session.
Definition session.c:112
void rtp_queue(struct vlc_logger *, rtp_session_t *, block_t *)
Receives an RTP packet and queues it.
Definition session.c:223
void * rtp_dgram_thread(void *data)
RTP/RTCP session thread for datagram sockets.
Definition input.c:103
void rtp_session_destroy(struct vlc_logger *, rtp_session_t *)
Destroys an RTP session.
Definition session.c:96
rtp_session_t * rtp_session_create(void)
Definition session.c:85
rtp_session_t * rtp_session_create_custom(uint16_t max_dropout, uint16_t max_misorder, uint8_t max_src, vlc_tick_t timeout)
Creates a new RTP session.
Definition session.c:62
int vlc_rtp_add_media_types(vlc_object_t *obj, rtp_session_t *ses, const struct vlc_sdp_media *media, const struct vlc_rtp_pt_owner *restrict owner)
Registers all payload types declared in an SDP media.
Definition rtpfmt.c:229
bool rtp_dequeue(struct vlc_logger *, const rtp_session_t *, vlc_tick_t, vlc_tick_t *)
const char name[16]
Definition httpd.c:1298
Definition vlc_es.h:633
State for a RTP session:
Definition session.c:40
Definition demux_chained.c:36
Definition vlc_frame.h:123
uint8_t * p_buffer
Payload start.
Definition vlc_frame.h:126
Definition messages.c:85
VLC object common members.
Definition vlc_objects.h:53
RTP abstract output stream operations.
Definition rtp.h:268
void(* destroy)(struct vlc_rtp_es *es)
Destroys the corresponding vlc_rtp_es.
Definition rtp.h:274
void(* send)(struct vlc_rtp_es *es, block_t *block)
Passes data for processing to a vlc_rtp_es.
Definition rtp.h:280
RTP abstract output stream.
Definition rtp.h:289
const struct vlc_rtp_es_operations * ops
Definition rtp.h:290
RTP packet infos.
Definition rtp.h:76
bool m
M bit from the RTP header.
Definition rtp.h:77
RTP payload type operations.
Definition rtp.h:86
void *(* init)(struct vlc_rtp_pt *pt)
Starts using a payload type.
Definition rtp.h:110
void(* release)(struct vlc_rtp_pt *pt)
Releases the payload type.
Definition rtp.h:95
void(* decode)(struct vlc_rtp_pt *pt, void *data, block_t *block, const struct vlc_rtp_pktinfo *restrict info)
Processes a data payload.
Definition rtp.h:130
void(* destroy)(struct vlc_rtp_pt *pt, void *data)
Stops using a payload type.
Definition rtp.h:120
RTP payload type owner operations.
Definition rtp.h:143
struct vlc_rtp_es *(* request_mux)(struct vlc_rtp_pt *pt, const char *name)
Definition rtp.h:146
struct vlc_rtp_es *(* request_es)(struct vlc_rtp_pt *pt, const es_format_t *restrict fmt)
Definition rtp.h:144
RTP payload type owner.
Definition rtp.h:155
void * data
Owner private data.
Definition rtp.h:157
const struct vlc_rtp_pt_owner_operations * ops
Owner callbacks.
Definition rtp.h:156
RTP payload type.
Definition rtp.h:167
void * opaque
Private data pointer.
Definition rtp.h:169
uint32_t frequency
RTP clock rate (Hz)
Definition rtp.h:171
uint8_t number
RTP payload type number within the session (0-127)
Definition rtp.h:172
struct vlc_rtp_pt_owner owner
Definition rtp.h:170
const struct vlc_rtp_pt_operations * ops
Payload format callbacks.
Definition rtp.h:168
uint8_t channel_count
Channel count (zero if unspecified)
Definition rtp.h:173
SDP media.
Definition sdp.h:77
Payload type mapping.
Definition rtp.h:62
char name[16]
RTP payload format name, i.e.
Definition rtp.h:64
unsigned char channel_count
Number of channels (0 if unspecified)
Definition rtp.h:66
const struct vlc_sdp_media * media
Containant SDP media description.
Definition rtp.h:63
const char * parameters
Format parameters from the a=fmtp line.
Definition rtp.h:67
unsigned int clock_rate
RTP clock rate (in Hertz)
Definition rtp.h:65
int64_t vlc_tick_t
High precision date or time interval.
Definition vlc_tick.h:48