1 /*****************************************************************************
2 * vlc_stream.h: Stream (between access and demux) descriptor and methods
3 *****************************************************************************
4 * Copyright (C) 1999-2004 VLC authors and VideoLAN
6 * Authors: Laurent Aimar <fenrir@via.ecp.fr>
8 * This program is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU Lesser General Public License as published by
10 * the Free Software Foundation; either version 2.1 of the License, or
11 * (at your option) any later version.
13 * This program 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.
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with this program; if not, write to the Free Software Foundation,
20 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
21 *****************************************************************************/
24 #define VLC_STREAM_H 1
26 #include <vlc_block.h>
33 * \defgroup stream Stream
35 * Buffered input byte streams
38 * Byte streams and byte stream filter modules interface
47 struct vlc_object_t obj
;
50 char *psz_url
; /**< Full URL or MRL (can be NULL) */
51 const char *psz_location
; /**< Location (URL with the scheme stripped) */
52 char *psz_filepath
; /**< Local file path (if applicable) */
53 bool b_preparsing
; /**< True if this access is used to preparse */
54 input_item_t
*p_input_item
;/**< Input item (can be NULL) */
60 * Depending on the module capability:
61 * - "stream filter" or "demux": input byte stream (not NULL)
62 * - "access": a NULL pointer
63 * - "demux_filter": undefined
69 * If the module capability is "demux_filter", this is the upstream
70 * demuxer or demux filter. Otherwise, this is undefined.
76 es_out_t
*out
; /* our p_es_out */
81 * Callback to read data from the stream into a caller-supplied buffer.
83 * This may be NULL if the stream is actually a directory rather than a
84 * byte stream, or if \ref stream_t.pf_block is non-NULL.
86 * \param buf buffer to read data into
87 * \param len buffer length (in bytes)
89 * \retval -1 no data available yet
90 * \retval 0 end of stream (incl. fatal error)
91 * \retval positive number of bytes read (no more than len)
93 ssize_t (*pf_read
)(stream_t
*, void *buf
, size_t len
);
98 * Callback to read a block of data. The data is read into a block of
99 * memory allocated by the stream. For some streams, data can be read more
100 * efficiently in block of a certain size, and/or using a custom allocator
101 * for buffers. In such case, this callback should be provided instead of
102 * \ref stream_t.pf_read; otherwise, this should be NULL.
104 * \param eof storage space for end-of-stream flag [OUT]
105 * (*eof is always false when invoking pf_block(); pf_block() should set
106 * *eof to true if it detects the end of the stream)
108 * \return a data block,
109 * NULL if no data available yet, on error and at end-of-stream
111 block_t
*(*pf_block
)(stream_t
*, bool *eof
);
116 * Callback to fill an item node from a directory
117 * (see doc/browsing.txt for details).
119 * NULL if the stream is not a directory.
121 int (*pf_readdir
)(stream_t
*, input_item_node_t
*);
123 int (*pf_demux
)(stream_t
*);
128 * Callback to set the stream pointer (in bytes from start).
130 * May be NULL if seeking is not supported.
132 int (*pf_seek
)(stream_t
*, uint64_t);
139 * \see stream_query_e
141 int (*pf_control
)(stream_t
*, int i_query
, va_list);
144 * Private data pointer
150 * Possible commands to send to vlc_stream_Control() and vlc_stream_vaControl()
155 STREAM_CAN_SEEK
, /**< arg1= bool * res=cannot fail*/
156 STREAM_CAN_FASTSEEK
, /**< arg1= bool * res=cannot fail*/
157 STREAM_CAN_PAUSE
, /**< arg1= bool * res=cannot fail*/
158 STREAM_CAN_CONTROL_PACE
, /**< arg1= bool * res=cannot fail*/
160 STREAM_GET_SIZE
=6, /**< arg1= uint64_t * res=can fail */
163 STREAM_GET_PTS_DELAY
= 0x101,/**< arg1= vlc_tick_t* res=cannot fail */
164 STREAM_GET_TITLE_INFO
, /**< arg1=input_title_t*** arg2=int* res=can fail */
165 STREAM_GET_TITLE
, /**< arg1=unsigned * res=can fail */
166 STREAM_GET_SEEKPOINT
, /**< arg1=unsigned * res=can fail */
167 STREAM_GET_META
, /**< arg1= vlc_meta_t * res=can fail */
168 STREAM_GET_CONTENT_TYPE
, /**< arg1= char ** res=can fail */
169 STREAM_GET_SIGNAL
, /**< arg1=double *pf_quality, arg2=double *pf_strength res=can fail */
170 STREAM_GET_TAGS
, /**< arg1=const block_t ** res=can fail */
172 STREAM_SET_PAUSE_STATE
= 0x200, /**< arg1= bool res=can fail */
173 STREAM_SET_TITLE
, /**< arg1= int res=can fail */
174 STREAM_SET_SEEKPOINT
, /**< arg1= int res=can fail */
176 /* XXX only data read through vlc_stream_Read/Block will be recorded */
177 STREAM_SET_RECORD_STATE
, /**< arg1=bool, arg2=const char *psz_ext (if arg1 is true) res=can fail */
179 STREAM_SET_PRIVATE_ID_STATE
= 0x1000, /* arg1= int i_private_data, bool b_selected res=can fail */
180 STREAM_SET_PRIVATE_ID_CA
, /* arg1= void * */
181 STREAM_GET_PRIVATE_ID_STATE
, /* arg1=int i_private_data arg2=bool * res=can fail */
185 * Reads data from a byte stream.
187 * This function always waits for the requested number of bytes, unless a fatal
188 * error is encountered or the end-of-stream is reached first.
190 * If the buffer is NULL, data is skipped instead of read. This is effectively
191 * a relative forward seek, but it works even on non-seekable streams.
193 * \param buf start of buffer to read data into [OUT]
194 * \param len number of bytes to read
195 * \return the number of bytes read or a negative value on error.
197 VLC_API ssize_t
vlc_stream_Read(stream_t
*, void *buf
, size_t len
) VLC_USED
;
200 * Reads partial data from a byte stream.
202 * This function waits until some data is available for reading from the
203 * stream, a fatal error is encountered or the end-of-stream is reached.
205 * Unlike vlc_stream_Read(), this function does not wait for the full requested
206 * bytes count. It can return a short count even before the end of the stream
207 * and in the absence of any error.
209 * \param buf start of buffer to read data into [OUT]
210 * \param len buffer size (maximum number of bytes to read)
211 * \return the number of bytes read or a negative value on error.
213 VLC_API ssize_t
vlc_stream_ReadPartial(stream_t
*, void *buf
, size_t len
)
217 * Peeks at data from a byte stream.
219 * This function buffers for the requested number of bytes, waiting if
220 * necessary. Then it stores a pointer to the buffer. Unlike vlc_stream_Read()
221 * or vlc_stream_Block(), this function does not modify the stream read offset.
224 * The buffer remains valid until the next read/peek or seek operation on the
225 * same stream. In case of error, the buffer address is undefined.
227 * \param bufp storage space for the buffer address [OUT]
228 * \param len number of bytes to peek
229 * \return the number of bytes actually available (shorter than requested if
230 * the end-of-stream is reached), or a negative value on error.
232 VLC_API ssize_t
vlc_stream_Peek(stream_t
*, const uint8_t **, size_t) VLC_USED
;
235 * Reads a data block from a byte stream.
237 * This function dequeues the next block of data from the byte stream. The
238 * byte stream back-end decides on the size of the block; the caller cannot
239 * make any assumption about it.
241 * The function might also return NULL spuriously - this does not necessarily
242 * imply that the stream is ended nor that it has encountered a nonrecoverable
245 * This function should be used instead of vlc_stream_Read() or
246 * vlc_stream_Peek() when the caller can handle reads of any size.
248 * \return either a data block or NULL
250 VLC_API block_t
*vlc_stream_ReadBlock(stream_t
*) VLC_USED
;
253 * Tells the current stream position.
255 * This function tells the current read offset (in bytes) from the start of
256 * the start of the stream.
257 * @note The read offset may be larger than the stream size, either because of
258 * a seek past the end, or because the stream shrank asynchronously.
260 * @return the byte offset from the beginning of the stream (cannot fail)
262 VLC_API
uint64_t vlc_stream_Tell(const stream_t
*) VLC_USED
;
265 * Checks for end of stream.
267 * Checks if the last attempt to reads data from the stream encountered the
268 * end of stream before the attempt could be fully satisfied.
269 * The value is initially false, and is reset to false by vlc_stream_Seek().
271 * \note The function can return false even though the current stream position
272 * is equal to the stream size. It will return true after the following attempt
273 * to read more than zero bytes.
275 * \note It might be possible to read after the end of the stream.
276 * It implies the size of the stream increased asynchronously in the mean time.
277 * Streams of most types cannot trigger such a case,
278 * but regular local files notably can.
280 * \note In principles, the stream size should match the stream offset when
281 * the end-of-stream is reached. But that rule is not enforced; it is entirely
282 * dependent on the underlying implementation of the stream.
284 VLC_API
bool vlc_stream_Eof(const stream_t
*) VLC_USED
;
287 * Sets the current stream position.
289 * This function changes the read offset within a stream, if the stream
290 * supports seeking. In case of error, the read offset is not changed.
292 * @note It is possible (but not useful) to seek past the end of a stream.
294 * @param offset byte offset from the beginning of the stream
295 * @return zero on success, a negative value on error
297 VLC_API
int vlc_stream_Seek(stream_t
*, uint64_t offset
) VLC_USED
;
299 VLC_API
int vlc_stream_vaControl(stream_t
*s
, int query
, va_list args
);
301 static inline int vlc_stream_Control(stream_t
*s
, int query
, ...)
307 ret
= vlc_stream_vaControl(s
, query
, ap
);
312 VLC_API block_t
*vlc_stream_Block(stream_t
*s
, size_t);
313 VLC_API
char *vlc_stream_ReadLine(stream_t
*);
318 * This function fills an input item node with any and all the items within
319 * a directory. The behaviour is undefined if the stream is not a directory.
321 * \param s directory object to read from
322 * \param node node to store the items into
323 * \return VLC_SUCCESS on success
325 VLC_API
int vlc_stream_ReadDir(stream_t
*s
, input_item_node_t
*node
);
328 * Closes a byte stream.
329 * \param s byte stream to close
331 VLC_API
void vlc_stream_Delete(stream_t
*s
);
333 VLC_API stream_t
*vlc_stream_CommonNew(vlc_object_t
*, void (*)(stream_t
*));
336 * Get the size of the stream.
338 VLC_USED
static inline int vlc_stream_GetSize( stream_t
*s
, uint64_t *size
)
340 return vlc_stream_Control( s
, STREAM_GET_SIZE
, size
);
343 static inline int64_t stream_Size( stream_t
*s
)
347 if( vlc_stream_GetSize( s
, &i_pos
) )
350 return (int64_t)1 << 62;
355 static inline bool stream_HasExtension( stream_t
*s
, const char *extension
)
357 const char *name
= (s
->psz_filepath
!= NULL
) ? s
->psz_filepath
359 const char *ext
= strrchr( name
, '.' );
360 return ext
!= NULL
&& !strcasecmp( ext
, extension
);
364 * Get the Content-Type of a stream, or NULL if unknown.
365 * Result must be free()'d.
367 static inline char *stream_ContentType( stream_t
*s
)
370 if( vlc_stream_Control( s
, STREAM_GET_CONTENT_TYPE
, &res
) )
376 * Get the mime-type of a stream
378 * \warning the returned resource is to be freed by the caller
379 * \return the mime-type, or `NULL` if unknown
382 static inline char *stream_MimeType( stream_t
*s
)
384 char* mime_type
= stream_ContentType( s
);
386 if( mime_type
) /* strip parameters */
387 mime_type
[strcspn( mime_type
, " ;" )] = '\0';
393 * Checks for a MIME type.
395 * Checks if the stream has a specific MIME type.
398 static inline bool stream_IsMimeType(stream_t
*s
, const char *type
)
400 char *mime
= stream_MimeType(s
);
404 bool ok
= !strcasecmp(mime
, type
);
410 * Create a stream from a memory buffer.
412 * \param obj parent VLC object
413 * \param base start address of the memory buffer to read from
414 * \param size size in bytes of the memory buffer
415 * \param preserve if false, free(base) will be called when the stream is
416 * destroyed; if true, the memory buffer is preserved
418 VLC_API stream_t
*vlc_stream_MemoryNew(vlc_object_t
*obj
, uint8_t *base
,
419 size_t size
, bool preserve
) VLC_USED
;
420 #define vlc_stream_MemoryNew(a, b, c, d) \
421 vlc_stream_MemoryNew(VLC_OBJECT(a), b, c, d)
424 * Create a stream_t reading from a URL.
425 * You must delete it using vlc_stream_Delete.
427 VLC_API stream_t
* vlc_stream_NewURL(vlc_object_t
*obj
, const char *url
)
429 #define vlc_stream_NewURL(a, b) vlc_stream_NewURL(VLC_OBJECT(a), b)
432 * \defgroup stream_fifo FIFO stream
433 * In-memory anonymous pipe
437 typedef struct vlc_stream_fifo vlc_stream_fifo_t
;
440 * Creates a FIFO stream.
442 * Creates a non-seekable byte stream object whose byte stream is generated
443 * by another thread in the process. This is the LibVLC equivalent of an
444 * anonymous pipe/FIFO.
446 * On the reader side, the normal stream functions are used,
447 * e.g. vlc_stream_Read() and vlc_stream_Delete().
449 * The created stream object is automatically destroyed when both the reader
450 * and the writer sides have been closed, with vlc_stream_Delete() and
451 * vlc_stream_fifo_Close() respectively.
453 * \param parent parent VLC object for the stream
454 * \param reader location to store read side stream pointer [OUT]
455 * \return a FIFO stream object or NULL on memory error.
457 VLC_API vlc_stream_fifo_t
*vlc_stream_fifo_New(vlc_object_t
*parent
,
461 * Writes a block to a FIFO stream.
463 * \param s FIFO stream created by vlc_stream_fifo_New()
464 * \param block data block to write to the stream
465 * \return 0 on success. -1 if the reader end has already been closed
466 * (errno is then set to EPIPE, and the block is deleted).
468 * \bug No congestion control is performed. If the reader end is not keeping
469 * up with the writer end, buffers will accumulate in memory.
471 VLC_API
int vlc_stream_fifo_Queue(vlc_stream_fifo_t
*s
, block_t
*block
);
474 * Writes data to a FIFO stream.
476 * This is a convenience helper for vlc_stream_fifo_Queue().
477 * \param s FIFO stream created by vlc_stream_fifo_New()
478 * \param buf start address of data to write
479 * \param len length of data to write in bytes
480 * \return len on success, or -1 on error (errno is set accordingly)
482 VLC_API ssize_t
vlc_stream_fifo_Write(vlc_stream_fifo_t
*s
, const void *buf
,
486 * Terminates a FIFO stream.
488 * Marks the end of the FIFO stream and releases any underlying resources.
489 * \param s FIFO stream created by vlc_stream_fifo_New()
491 VLC_API
void vlc_stream_fifo_Close(vlc_stream_fifo_t
*s
);
498 * Try to add a stream filter to an open stream.
499 * @return New stream to use, or NULL if the filter could not be added.
501 VLC_API stream_t
* vlc_stream_FilterNew( stream_t
*p_source
, const char *psz_stream_filter
);