mlp: missing initializer (fixes #20494)
[vlc.git] / include / vlc_demux.h
blob3888ac57ce347071cdeca883fdc03d3651ad555f
1 /*****************************************************************************
2 * vlc_demux.h: Demuxer descriptor, queries and methods
3 *****************************************************************************
4 * Copyright (C) 1999-2005 VLC authors and VideoLAN
5 * $Id$
7 * Authors: Laurent Aimar <fenrir@via.ecp.fr>
9 * This program is free software; you can redistribute it and/or modify it
10 * under the terms of the GNU Lesser General Public License as published by
11 * the Free Software Foundation; either version 2.1 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU Lesser General Public License for more details.
19 * You should have received a copy of the GNU Lesser General Public License
20 * along with this program; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22 *****************************************************************************/
24 #ifndef VLC_DEMUX_H
25 #define VLC_DEMUX_H 1
27 #include <stdlib.h>
28 #include <string.h>
30 #include <vlc_es.h>
31 #include <vlc_stream.h>
32 #include <vlc_es_out.h>
34 /**
35 * \defgroup demux Demultiplexer
36 * \ingroup input
37 * Demultiplexers (file format parsers)
38 * @{
39 * \file
40 * Demultiplexer modules interface
43 /* pf_demux return values */
44 #define VLC_DEMUXER_EOF 0
45 #define VLC_DEMUXER_EGENERIC -1
46 #define VLC_DEMUXER_SUCCESS 1
48 /* DEMUX_TEST_AND_CLEAR flags */
49 #define INPUT_UPDATE_TITLE 0x0010
50 #define INPUT_UPDATE_SEEKPOINT 0x0020
51 #define INPUT_UPDATE_META 0x0040
52 #define INPUT_UPDATE_TITLE_LIST 0x0100
54 /* demux_meta_t is returned by "meta reader" module to the demuxer */
55 typedef struct demux_meta_t
57 struct vlc_common_members obj;
58 input_item_t *p_item; /***< the input item that is being read */
60 vlc_meta_t *p_meta; /**< meta data */
62 int i_attachments; /**< number of attachments */
63 input_attachment_t **attachments; /**< array of attachments */
64 } demux_meta_t;
66 /**
67 * Control query identifiers for use with demux_t.pf_control
69 * In the individual identifier description, the input stream refers to
70 * demux_t.s if non-NULL, and the output refers to demux_t.out.
72 * A demuxer is synchronous if it only accesses its input stream and the
73 * output from within its demux_t callbacks, i.e. demux.pf_demux and
74 * demux_t.pf_control.
76 * A demuxer is threaded if it accesses either or both input and output
77 * asynchronously.
79 * An access-demuxer is a demuxer without input, i.e. demux_t.s == NULL).
81 enum demux_query_e
83 /** Checks whether the stream supports seeking.
84 * Can fail if seeking is not supported (same as returning false).
85 * \bug Failing should not be allowed.
87 * arg1 = bool * */
88 DEMUX_CAN_SEEK,
90 /** Checks whether (long) pause then stream resumption is supported.
91 * Can fail only if synchronous and <b>not</b> an access-demuxer. The
92 * underlying input stream then determines if pause is supported.
93 * \bug Failing should not be allowed.
95 * arg1= bool * */
96 DEMUX_CAN_PAUSE = 0x002,
98 /** Whether the stream can be read at an arbitrary pace.
99 * Cannot fail.
101 * arg1= bool * */
102 DEMUX_CAN_CONTROL_PACE,
104 /** Retrieves the PTS delay (roughly the default buffer duration).
105 * Can fail only if synchronous and <b>not</b> an access-demuxer. The
106 * underlying input stream then determines the PTS delay.
108 * arg1= int64_t * */
109 DEMUX_GET_PTS_DELAY = 0x101,
111 /** Retrieves stream meta-data.
112 * Should fail if no meta-data were retrieved.
114 * arg1= vlc_meta_t * */
115 DEMUX_GET_META = 0x105,
117 /** Retrieves an estimate of signal quality and strength.
118 * Can fail.
120 * arg1=double *quality, arg2=double *strength */
121 DEMUX_GET_SIGNAL = 0x107,
123 /** Sets the paused or playing/resumed state.
125 * Streams are initially in playing state. The control always specifies a
126 * change from paused to playing (false) or from playing to paused (true)
127 * and streams are initially playing; a no-op cannot be requested.
129 * The control is never used if DEMUX_CAN_PAUSE fails.
130 * Can fail.
132 * arg1= bool */
133 DEMUX_SET_PAUSE_STATE = 0x200,
135 /** Seeks to the beginning of a title.
137 * The control is never used if DEMUX_GET_TITLE_INFO fails.
138 * Can fail.
140 * arg1= int */
141 DEMUX_SET_TITLE,
143 /** Seeks to the beginning of a chapter of the current title.
145 * The control is never used if DEMUX_GET_TITLE_INFO fails.
146 * Can fail.
148 * arg1= int */
149 DEMUX_SET_SEEKPOINT, /* arg1= int can fail */
151 /** Check which INPUT_UPDATE_XXX flag is set and reset the ones set.
153 * The unsigned* argument is set with the flags needed to be checked,
154 * on return it contains the values that were reset during the call
156 * arg1= unsigned * */
157 DEMUX_TEST_AND_CLEAR_FLAGS, /* arg1= unsigned* can fail */
159 /** Read the title number currently playing
161 * Can fail.
163 * arg1= int * */
164 DEMUX_GET_TITLE, /* arg1= int* can fail */
166 /* Read the seekpoint/chapter currently playing
168 * Can fail.
170 * arg1= int * */
171 DEMUX_GET_SEEKPOINT, /* arg1= int* can fail */
173 /* I. Common queries to access_demux and demux */
174 /* POSITION double between 0.0 and 1.0 */
175 DEMUX_GET_POSITION = 0x300, /* arg1= double * res= */
176 DEMUX_SET_POSITION, /* arg1= double arg2= bool b_precise res=can fail */
178 /* LENGTH/TIME in microsecond, 0 if unknown */
179 DEMUX_GET_LENGTH, /* arg1= int64_t * res= */
180 DEMUX_GET_TIME, /* arg1= int64_t * res= */
181 DEMUX_SET_TIME, /* arg1= int64_t arg2= bool b_precise res=can fail */
184 * \todo Document
186 * \warning The prototype is different from STREAM_GET_TITLE_INFO
188 * Can fail, meaning there is only one title and one chapter.
190 * arg1= input_title_t ***, arg2=int *, arg3=int *pi_title_offset(0),
191 * arg4= int *pi_seekpoint_offset(0) */
192 DEMUX_GET_TITLE_INFO,
194 /* DEMUX_SET_GROUP/SET_ES only a hint for demuxer (mainly DVB) to allow not
195 * reading everything (you should not use this to call es_out_Control)
196 * if you don't know what to do with it, just IGNORE it, it is safe(r)
197 * -1 means all group, 0 default group (first es added) */
198 DEMUX_SET_GROUP, /* arg1= int, arg2=const vlc_list_t * can fail */
199 DEMUX_SET_ES, /* arg1= int can fail */
201 /* Ask the demux to demux until the given date at the next pf_demux call
202 * but not more (and not less, at the precision available of course).
203 * XXX: not mandatory (except for subtitle demux) but will help a lot
204 * for multi-input
206 DEMUX_SET_NEXT_DEMUX_TIME, /* arg1= mtime_t can fail */
207 /* FPS for correct subtitles handling */
208 DEMUX_GET_FPS, /* arg1= double * res=can fail */
210 /* Meta data */
211 DEMUX_HAS_UNSUPPORTED_META, /* arg1= bool * res can fail */
213 /* Attachments */
214 DEMUX_GET_ATTACHMENTS, /* arg1=input_attachment_t***, int* res=can fail */
216 /* RECORD you are ensured that it is never called twice with the same state
217 * you should accept it only if the stream can be recorded without
218 * any modification or header addition. */
219 DEMUX_CAN_RECORD, /* arg1=bool* res=can fail(assume false) */
221 * \todo Document
223 * \warning The prototype is different from STREAM_SET_RECORD_STATE
225 * The control is never used if DEMUX_CAN_RECORD fails or returns false.
226 * Can fail.
228 * arg1= bool */
229 DEMUX_SET_RECORD_STATE,
231 /* II. Specific access_demux queries */
233 /* DEMUX_CAN_CONTROL_RATE is called only if DEMUX_CAN_CONTROL_PACE has
234 * returned false. *pb_rate should be true when the rate can be changed
235 * (using DEMUX_SET_RATE). */
236 DEMUX_CAN_CONTROL_RATE, /* arg1= bool*pb_rate */
237 /* DEMUX_SET_RATE is called only if DEMUX_CAN_CONTROL_RATE has returned true.
238 * It should return the value really used in *pi_rate */
239 DEMUX_SET_RATE, /* arg1= int*pi_rate can fail */
241 /** Checks whether the stream is actually a playlist, rather than a real
242 * stream.
244 * Can fail if the stream is not a playlist (same as returning false).
246 * arg1= bool * */
247 DEMUX_IS_PLAYLIST,
249 /* Menu (VCD/DVD/BD) Navigation */
250 /** Activate the navigation item selected. Can fail */
251 DEMUX_NAV_ACTIVATE,
252 /** Use the up arrow to select a navigation item above. Can fail */
253 DEMUX_NAV_UP,
254 /** Use the down arrow to select a navigation item under. Can fail */
255 DEMUX_NAV_DOWN,
256 /** Use the left arrow to select a navigation item on the left. Can fail */
257 DEMUX_NAV_LEFT,
258 /** Use the right arrow to select a navigation item on the right. Can fail */
259 DEMUX_NAV_RIGHT,
260 /** Activate the popup Menu (for BD). Can fail */
261 DEMUX_NAV_POPUP,
262 /** Activate disc Root Menu. Can fail */
263 DEMUX_NAV_MENU, /* res=can fail */
264 /** Enable/Disable a demux filter
265 * \warning This has limited support, and is likely to break if more than
266 * a single demux_filter is present in the chain. This is not guaranteed to
267 * work in future VLC versions, nor with all demux filters
269 DEMUX_FILTER_ENABLE,
270 DEMUX_FILTER_DISABLE
273 /*************************************************************************
274 * Main Demux
275 *************************************************************************/
277 VLC_API demux_t *demux_New( vlc_object_t *p_obj, const char *psz_name,
278 stream_t *s, es_out_t *out );
280 static inline void demux_Delete(demux_t *demux)
282 vlc_stream_Delete(demux);
285 VLC_API int demux_vaControlHelper( stream_t *, int64_t i_start, int64_t i_end,
286 int64_t i_bitrate, int i_align, int i_query, va_list args );
288 VLC_USED static inline int demux_Demux( demux_t *p_demux )
290 if( !p_demux->pf_demux )
291 return VLC_DEMUXER_SUCCESS;
293 return p_demux->pf_demux( p_demux );
296 VLC_API int demux_vaControl( demux_t *p_demux, int i_query, va_list args );
298 static inline int demux_Control( demux_t *p_demux, int i_query, ... )
300 va_list args;
301 int i_result;
303 va_start( args, i_query );
304 i_result = demux_vaControl( p_demux, i_query, args );
305 va_end( args );
306 return i_result;
309 /*************************************************************************
310 * Miscellaneous helpers for demuxers
311 *************************************************************************/
313 #ifndef __cplusplus
314 static inline void demux_UpdateTitleFromStream( demux_t *demux,
315 int *restrict titlep, int *restrict seekpointp,
316 unsigned *restrict updatep )
318 stream_t *s = demux->s;
319 unsigned title, seekpoint;
321 if( vlc_stream_Control( s, STREAM_GET_TITLE, &title ) == VLC_SUCCESS
322 && title != (unsigned)*titlep )
324 *titlep = title;
325 *updatep |= INPUT_UPDATE_TITLE;
328 if( vlc_stream_Control( s, STREAM_GET_SEEKPOINT,
329 &seekpoint ) == VLC_SUCCESS
330 && seekpoint != (unsigned)*seekpointp )
332 *seekpointp = seekpoint;
333 *updatep |= INPUT_UPDATE_SEEKPOINT;
336 # define demux_UpdateTitleFromStream(demux) \
337 demux_UpdateTitleFromStream(demux, \
338 &((demux_sys_t *)((demux)->p_sys))->current_title, \
339 &((demux_sys_t *)((demux)->p_sys))->current_seekpoint, \
340 &((demux_sys_t *)((demux)->p_sys))->updates)
341 #endif
343 VLC_USED
344 static inline bool demux_IsPathExtension( demux_t *p_demux, const char *psz_extension )
346 const char *name = (p_demux->psz_filepath != NULL) ? p_demux->psz_filepath
347 : p_demux->psz_location;
348 const char *psz_ext = strrchr ( name, '.' );
349 if( !psz_ext || strcasecmp( psz_ext, psz_extension ) )
350 return false;
351 return true;
354 VLC_USED
355 static inline bool demux_IsContentType(demux_t *demux, const char *type)
357 return stream_IsMimeType(demux->s, type);
360 VLC_USED
361 static inline bool demux_IsForced( demux_t *p_demux, const char *psz_name )
363 if( p_demux->psz_name == NULL || strcmp( p_demux->psz_name, psz_name ) )
364 return false;
365 return true;
369 * This function will create a packetizer suitable for a demuxer that parses
370 * elementary stream.
372 * The provided es_format_t will be cleaned on error or by
373 * demux_PacketizerDestroy.
375 VLC_API decoder_t * demux_PacketizerNew( demux_t *p_demux, es_format_t *p_fmt, const char *psz_msg ) VLC_USED;
378 * This function will destroy a packetizer create by demux_PacketizerNew.
380 VLC_API void demux_PacketizerDestroy( decoder_t *p_packetizer );
382 /* */
383 #define DEMUX_INIT_COMMON() do { \
384 p_demux->pf_control = Control; \
385 p_demux->pf_demux = Demux; \
386 p_demux->p_sys = calloc( 1, sizeof( demux_sys_t ) ); \
387 if( !p_demux->p_sys ) return VLC_ENOMEM;\
388 } while(0)
391 * \defgroup chained_demux Chained demultiplexer
392 * Demultiplexers wrapped by another demultiplexer
393 * @{
396 typedef struct vlc_demux_chained_t vlc_demux_chained_t;
399 * Creates a chained demuxer.
401 * This creates a thread running a demuxer whose input stream is generated
402 * directly by the caller. This typically handles some sort of stream within a
403 * stream, e.g. MPEG-TS within something else.
405 * \note There are a number of limitations to this approach. The chained
406 * demuxer is run asynchronously in a separate thread. Most demuxer controls
407 * are synchronous and therefore unavailable in this case. Also the input
408 * stream is a simple FIFO, so the chained demuxer cannot perform seeks.
409 * Lastly, most errors cannot be detected.
411 * \param parent parent VLC object
412 * \param name chained demux module name (e.g. "ts")
413 * \param out elementary stream output for the chained demux
414 * \return a non-NULL pointer on success, NULL on failure.
416 VLC_API vlc_demux_chained_t *vlc_demux_chained_New(vlc_object_t *parent,
417 const char *name,
418 es_out_t *out);
421 * Destroys a chained demuxer.
423 * Sends an end-of-stream to the chained demuxer, and releases all underlying
424 * allocated resources.
426 VLC_API void vlc_demux_chained_Delete(vlc_demux_chained_t *);
429 * Sends data to a chained demuxer.
431 * This queues data for a chained demuxer to consume.
433 * \param block data block to queue
435 VLC_API void vlc_demux_chained_Send(vlc_demux_chained_t *, block_t *block);
438 * Controls a chained demuxer.
440 * This performs a <b>demux</b> (i.e. DEMUX_...) control request on a chained
441 * demux.
443 * \note In most cases, vlc_demux_chained_Control() should be used instead.
444 * \warning As per vlc_demux_chained_New(), most demux controls are not, and
445 * cannot be, supported; VLC_EGENERIC is returned.
447 * \param query demux control (see \ref demux_query_e)
448 * \param args variable arguments (depending on the query)
450 VLC_API int vlc_demux_chained_ControlVa(vlc_demux_chained_t *, int query,
451 va_list args);
453 static inline int vlc_demux_chained_Control(vlc_demux_chained_t *dc, int query,
454 ...)
456 va_list ap;
457 int ret;
459 va_start(ap, query);
460 ret = vlc_demux_chained_ControlVa(dc, query, ap);
461 va_end(ap);
462 return ret;
466 * @}
470 * @}
473 #endif