VLC  3.0.0-git
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Modules | Files | Data Structures | Macros | Enumerations | Functions
Stream

Buffered input byte streams. More...

Collaboration diagram for Stream:

Modules

 FIFO stream
 In-memory anonymous pipe.
 

Files

file  vlc_stream.h
 Byte streams and byte stream filter modules interface.
 

Data Structures

struct  stream_t
 stream_t definition More...
 

Macros

#define vlc_stream_MemoryNew(a, b, c, d)   vlc_stream_MemoryNew(VLC_OBJECT(a), b, c, d)
 
#define vlc_stream_NewMRL(a, b)   vlc_stream_NewMRL(VLC_OBJECT(a), b)
 
#define stream_FilterSetDefaultReadDir(stream)
 Sets vlc_stream_FilterDefaultReadDir as the pf_readdir callback for this stream filter. More...
 

Enumerations

enum  stream_query_e {
  STREAM_CAN_SEEK, STREAM_CAN_FASTSEEK, STREAM_CAN_PAUSE, STREAM_CAN_CONTROL_PACE,
  STREAM_GET_SIZE =6, STREAM_IS_DIRECTORY, STREAM_GET_PTS_DELAY = 0x101, STREAM_GET_TITLE_INFO,
  STREAM_GET_TITLE, STREAM_GET_SEEKPOINT, STREAM_GET_META, STREAM_GET_CONTENT_TYPE,
  STREAM_GET_SIGNAL, STREAM_SET_PAUSE_STATE = 0x200, STREAM_SET_TITLE, STREAM_SET_SEEKPOINT,
  STREAM_SET_RECORD_STATE, STREAM_SET_PRIVATE_ID_STATE = 0x1000, STREAM_SET_PRIVATE_ID_CA, STREAM_GET_PRIVATE_ID_STATE
}
 Possible commands to send to vlc_stream_Control() and vlc_stream_vaControl() More...
 

Functions

ssize_t vlc_stream_Read (stream_t *, void *buf, size_t len)
 Reads data from a byte stream. More...
 
ssize_t vlc_stream_ReadPartial (stream_t *, void *buf, size_t len)
 Reads partial data from a byte stream. More...
 
ssize_t vlc_stream_Peek (stream_t *, const uint8_t **, size_t)
 Peeks at data from a byte stream. More...
 
block_tvlc_stream_ReadBlock (stream_t *)
 Reads a data block from a byte stream. More...
 
uint64_t vlc_stream_Tell (const stream_t *)
 Tells the current stream position. More...
 
bool vlc_stream_Eof (const stream_t *)
 Checks for end of stream. More...
 
int vlc_stream_Seek (stream_t *, uint64_t offset)
 Sets the current stream position. More...
 
int vlc_stream_vaControl (stream_t *s, int query, va_list args)
 Use to control the "stream_t *". More...
 
static int vlc_stream_Control (stream_t *s, int query,...)
 
block_tvlc_stream_Block (stream_t *s, size_t)
 Read data into a block. More...
 
char * vlc_stream_ReadLine (stream_t *)
 
int vlc_stream_ReadDir (stream_t *, input_item_node_t *)
 Returns a node containing all the input_item of the directory pointer by this stream. More...
 
void vlc_stream_Delete (stream_t *s)
 Closes a byte stream. More...
 
stream_tvlc_stream_CommonNew (vlc_object_t *, void(*)(stream_t *))
 Allocates a VLC stream object. More...
 
static int vlc_stream_GetSize (stream_t *s, uint64_t *size)
 Get the size of the stream. More...
 
static int64_t stream_Size (stream_t *s)
 
static char * stream_ContentType (stream_t *s)
 Get the Content-Type of a stream, or NULL if unknown. More...
 
stream_tvlc_stream_MemoryNew (vlc_object_t *obj, uint8_t *base, size_t size, bool preserve)
 Create a stream from a memory buffer. More...
 
stream_tvlc_stream_NewMRL (vlc_object_t *obj, const char *url)
 Create a stream_t reading from a URL. More...
 
stream_tvlc_stream_FilterNew (stream_t *p_source, const char *psz_stream_filter)
 Try to add a stream filter to an open stream. More...
 
int vlc_stream_FilterDefaultReadDir (stream_t *s, input_item_node_t *p_node)
 Default ReadDir implementation for stream Filter. More...
 

Detailed Description

Buffered input byte streams.

Macro Definition Documentation

#define stream_FilterSetDefaultReadDir (   stream)
Value:
do { \
(stream)->pf_readdir = vlc_stream_FilterDefaultReadDir; \
} while (0)
int vlc_stream_FilterDefaultReadDir(stream_t *s, input_item_node_t *p_node)
Default ReadDir implementation for stream Filter.
Definition: stream_filter.c:117

Sets vlc_stream_FilterDefaultReadDir as the pf_readdir callback for this stream filter.

#define vlc_stream_MemoryNew (   a,
  b,
  c,
 
)    vlc_stream_MemoryNew(VLC_OBJECT(a), b, c, d)
#define vlc_stream_NewMRL (   a,
 
)    vlc_stream_NewMRL(VLC_OBJECT(a), b)

Referenced by DownloadArt(), and ImageReadUrl().

Enumeration Type Documentation

Possible commands to send to vlc_stream_Control() and vlc_stream_vaControl()

Enumerator
STREAM_CAN_SEEK 

arg1= bool * res=cannot fail

STREAM_CAN_FASTSEEK 

arg1= bool * res=cannot fail

STREAM_CAN_PAUSE 

arg1= bool * res=cannot fail

STREAM_CAN_CONTROL_PACE 

arg1= bool * res=cannot fail

STREAM_GET_SIZE 

arg1= uint64_t * res=can fail

STREAM_IS_DIRECTORY 

arg1= bool *, res=can fail

STREAM_GET_PTS_DELAY 

arg1= int64_t* res=cannot fail

STREAM_GET_TITLE_INFO 

arg1=input_title_t*** arg2=int* res=can fail

STREAM_GET_TITLE 

arg1=unsigned * res=can fail

STREAM_GET_SEEKPOINT 

arg1=unsigned * res=can fail

STREAM_GET_META 

arg1= vlc_meta_t * res=can fail

STREAM_GET_CONTENT_TYPE 

arg1= char ** res=can fail

STREAM_GET_SIGNAL 

arg1=double *pf_quality, arg2=double *pf_strength res=can fail

STREAM_SET_PAUSE_STATE 

arg1= bool res=can fail

STREAM_SET_TITLE 

arg1= int res=can fail

STREAM_SET_SEEKPOINT 

arg1= int res=can fail

STREAM_SET_RECORD_STATE 

arg1=bool, arg2=const char *psz_ext (if arg1 is true) res=can fail

STREAM_SET_PRIVATE_ID_STATE 
STREAM_SET_PRIVATE_ID_CA 
STREAM_GET_PRIVATE_ID_STATE 

Function Documentation

static char* stream_ContentType ( stream_t s)
inlinestatic

Get the Content-Type of a stream, or NULL if unknown.

Result must be free()'d.

References STREAM_GET_CONTENT_TYPE, and vlc_stream_Control().

Referenced by demux_IsContentType(), demux_NewAdvanced(), and ImageReadUrl().

static int64_t stream_Size ( stream_t s)
inlinestatic

References vlc_stream_GetSize().

Referenced by demux_vaControlHelper().

block_t* vlc_stream_Block ( stream_t s,
size_t  size 
)

Read data into a block.

Parameters
sstream to read data from
sizenumber of bytes to read
Returns
a block of data, or NULL on error @ note The block size may be shorter than requested if the end-of-stream was reached.

References block_Alloc(), block_Release(), block_t::i_buffer, block_t::p_buffer, unlikely, and vlc_stream_Read().

Referenced by ImageReadUrl().

stream_t* vlc_stream_CommonNew ( vlc_object_t ,
void(*)(stream_t *)   
)
static int vlc_stream_Control ( stream_t s,
int  query,
  ... 
)
inlinestatic
void vlc_stream_Delete ( stream_t s)

Closes a byte stream.

Parameters
sbyte stream to close

Closes a byte stream.

References stream_priv_t::destroy, and stream_CommonDelete().

Referenced by AStreamDestroy(), demux_DestroyDemux(), DownloadArt(), ImageReadUrl(), input_DemuxNew(), StreamDelete(), and vlc_demux_chained_New().

bool vlc_stream_Eof ( const stream_t )

Checks for end of stream.

Checks if the last attempt to reads data from the stream encountered the end of stream before the attempt could be fully satisfied. The value is initially false, and is reset to false by vlc_stream_Seek().

Note
The function can return false even though the current stream position is equal to the stream size. It will return true after the following attempt to read more than zero bytes.
It might be possible to read after the end of the stream. It implies the size of the stream increased asynchronously in the mean time. Streams of most types cannot trigger such a case, but regular local files notably can.
In principles, the stream size should match the stream offset when the end-of-stream is reached. But that rule is not enforced; it is entirely dependent on the underlying implementation of the stream.

References stream_priv_t::eof.

Referenced by AStreamReadBlock(), and AStreamReadStream().

int vlc_stream_FilterDefaultReadDir ( stream_t s,
input_item_node_t p_node 
)

Default ReadDir implementation for stream Filter.

This implementation just forward the pf_readdir call to the p_source stream.

References stream_t::p_source, and vlc_stream_ReadDir().

stream_t* vlc_stream_FilterNew ( stream_t p_source,
const char *  psz_stream_filter 
)

Try to add a stream filter to an open stream.

Returns
New stream to use, or NULL if the filter could not be added.

References module_need, stream_t::obj, stream_t::p_input, stream_t::p_module, stream_t::p_source, vlc_common_members::parent, stream_t::psz_url, strdup(), stream_CommonDelete(), StreamDelete(), unlikely, and vlc_stream_CommonNew().

Referenced by stream_FilterAutoNew(), and stream_FilterChainNew().

static int vlc_stream_GetSize ( stream_t s,
uint64_t *  size 
)
inlinestatic

Get the size of the stream.

References STREAM_GET_SIZE, and vlc_stream_Control().

Referenced by ImageReadUrl(), and stream_Size().

stream_t* vlc_stream_MemoryNew ( vlc_object_t obj,
uint8_t *  base,
size_t  size,
bool  preserve 
)

Create a stream from a memory buffer.

Parameters
objparent VLC object
basestart address of the memory buffer to read from
sizesize in bytes of the memory buffer
preserveif false, free(base) will be called when the stream is destroyed; if true, the memory buffer is preserved

References Control(), stream_sys_t::i_pos, stream_sys_t::i_size, stream_sys_t::p_buffer, stream_t::p_sys, stream_t::pf_control, stream_t::pf_read, stream_t::pf_seek, Read(), Seek(), stream_CommonDelete(), stream_MemoryDelete(), stream_MemoryPreserveDelete(), and vlc_stream_CommonNew().

stream_t* vlc_stream_NewMRL ( vlc_object_t obj,
const char *  url 
)

Create a stream_t reading from a URL.

You must delete it using vlc_stream_Delete.

References msg_Err, and stream_AccessNew().

ssize_t vlc_stream_Peek ( stream_t ,
const uint8_t **  ,
size_t   
)

Peeks at data from a byte stream.

This function buffers for the requested number of bytes, waiting if necessary. Then it stores a pointer to the buffer. Unlike vlc_stream_Read() or vlc_stream_Block(), this function does not modify the stream read offset.

Note
The buffer remains valid until the next read/peek or seek operation on the same stream. In case of error, the buffer address is undefined.
Parameters
bufpstorage space for the buffer address [OUT]
lennumber of bytes to peek
Returns
the number of bytes actually available (shorter than requested if the end-of-stream is reached), or a negative value on error.
ssize_t vlc_stream_Read ( stream_t ,
void *  buf,
size_t  len 
)

Reads data from a byte stream.

This function always waits for the requested number of bytes, unless a fatal error is encountered or the end-of-stream is reached first.

If the buffer is NULL, data is skipped instead of read. This is effectively a relative forward seek, but it works even on non-seekable streams.

Parameters
bufstart of buffer to read data into [OUT]
lennumber of bytes to read
Returns
the number of bytes read or a negative value on error.

References vlc_stream_ReadPartial().

Referenced by DownloadArt(), SkipAPETag(), SkipID3Tag(), vlc_stream_Block(), and vlc_stream_ReadLine().

block_t* vlc_stream_ReadBlock ( stream_t )

Reads a data block from a byte stream.

This function dequeues the next block of data from the byte stream. The byte stream back-end decides on the size of the block; the caller cannot make any assumption about it.

The function might also return NULL spuriously - this does not necessarily imply that the stream is ended nor that it has encountered a nonrecoverable error.

This function should be used instead of vlc_stream_Read() or vlc_stream_Peek() when the caller can handle reads of any size.

Returns
either a data block or NULL

References stream_priv_t::block, block_Alloc(), block_Release(), stream_priv_t::eof, block_t::i_buffer, stream_priv_t::offset, block_t::p_buffer, stream_priv_t::peek, stream_t::pf_block, stream_t::pf_read, unlikely, and vlc_killed().

Referenced by AStreamReadBlock().

int vlc_stream_ReadDir ( stream_t s,
input_item_node_t p_node 
)

Returns a node containing all the input_item of the directory pointer by this stream.

returns VLC_SUCCESS on success.

References stream_t::pf_readdir.

Referenced by vlc_stream_FilterDefaultReadDir().

char* vlc_stream_ReadLine ( stream_t )
ssize_t vlc_stream_ReadPartial ( stream_t ,
void *  buf,
size_t  len 
)

Reads partial data from a byte stream.

This function waits until some data is available for reading from the stream, a fatal error is encountered or the end-of-stream is reached.

Unlike vlc_stream_Read(), this function does not wait for the full requested bytes count. It can return a short count even before the end of the stream and in the absence of any error.

Parameters
bufstart of buffer to read data into [OUT]
lenbuffer size (maximum number of bytes to read)
Returns
the number of bytes read or a negative value on error.

References stream_priv_t::eof, stream_priv_t::offset, stream_priv_t::peek, vlc_stream_CopyBlock(), and vlc_stream_ReadRaw().

Referenced by AStreamReadStream(), and vlc_stream_Read().

int vlc_stream_Seek ( stream_t ,
uint64_t  offset 
)

Sets the current stream position.

Parameters
offsetbyte offset from the beginning of the stream
Returns
zero on success, a negative value on error

< No error

< No error

< Unspecified error

< No error

< No error

References stream_priv_t::block, block_Release(), stream_priv_t::eof, block_t::i_buffer, stream_priv_t::offset, block_t::p_buffer, stream_priv_t::peek, stream_t::pf_seek, VLC_EGENERIC, and VLC_SUCCESS.

Referenced by AStreamSeek(), and demux_vaControlHelper().

uint64_t vlc_stream_Tell ( const stream_t )

Tells the current stream position.

Returns
the byte offset from the beginning of the stream (cannot fail)

References stream_priv_t::offset.

Referenced by demux_vaControlHelper(), and vlc_stream_ReadLine().

int vlc_stream_vaControl ( stream_t s,
int  cmd,
va_list  args 
)

Use to control the "stream_t *".

Look at stream_query_e for possible "i_query" value and format arguments. Return VLC_SUCCESS if ... succeed ;) and VLC_EGENERIC if failed or unimplemented

< No error

< No error

References stream_priv_t::block, block_Release(), stream_priv_t::offset, stream_priv_t::peek, stream_t::pf_control, STREAM_SET_SEEKPOINT, STREAM_SET_TITLE, and VLC_SUCCESS.

Referenced by AStreamControl(), demux_vaControl(), demux_vaControlHelper(), and vlc_stream_Control().