Buffered I/O operations. More...

#include <stdint.h>
#include "libavutil/common.h"
#include "libavutil/dict.h"
#include "libavutil/log.h"
#include "libavformat/version.h"

Go to the source code of this file.

Data Structures

struct  AVIOInterruptCB
 Callback for checking whether to abort blocking functions. More...
 
struct  AVIOContext
 Bytestream IO Context. More...
 

Macros

#define AVIO_SEEKABLE_NORMAL   (1 << 0)
 Seeking works like for a local file. More...
 
#define AVIO_SEEKABLE_TIME   (1 << 1)
 Seeking by timestamp with avio_seek_time() is possible. More...
 
#define AVSEEK_SIZE   0x10000
 ORing this as the "whence" parameter to a seek function causes it to return the filesize without seeking anywhere. More...
 
#define AVSEEK_FORCE   0x20000
 Passing this flag as the "whence" parameter to a seek function causes it to seek by any means (like reopening and linear reading) or other normally unreasonable means that can be extremely slow. More...
 
#define AVIO_FLAG_NONBLOCK   8
 Use non-blocking mode. More...
 
URL open modes

The flags argument to avio_open must be one of the following constants, optionally ORed with other flags.

#define AVIO_FLAG_READ   1
 read-only More...
 
#define AVIO_FLAG_WRITE   2
 write-only More...
 
#define AVIO_FLAG_READ_WRITE   (AVIO_FLAG_READ|AVIO_FLAG_WRITE)
 read-write pseudo flag More...
 

Enumerations

enum  AVIODataMarkerType {
  AVIO_DATA_MARKER_HEADER, AVIO_DATA_MARKER_SYNC_POINT, AVIO_DATA_MARKER_BOUNDARY_POINT, AVIO_DATA_MARKER_UNKNOWN,
  AVIO_DATA_MARKER_TRAILER
}
 Different data types that can be returned via the AVIO write_data_type callback. More...
 

Functions

int avio_check (const char *url, int flags)
 Return AVIO_FLAG_* access flags corresponding to the access permissions of the resource in url, or a negative value corresponding to an AVERROR code in case of failure. More...
 
AVIOContextavio_alloc_context (unsigned char *buffer, int buffer_size, int write_flag, void *opaque, int(*read_packet)(void *opaque, uint8_t *buf, int buf_size), int(*write_packet)(void *opaque, uint8_t *buf, int buf_size), int64_t(*seek)(void *opaque, int64_t offset, int whence))
 Allocate and initialize an AVIOContext for buffered I/O. More...
 
void avio_context_free (AVIOContext **s)
 Free the supplied IO context and everything associated with it. More...
 
void avio_w8 (AVIOContext *s, int b)
 
void avio_write (AVIOContext *s, const unsigned char *buf, int size)
 
void avio_wl64 (AVIOContext *s, uint64_t val)
 
void avio_wb64 (AVIOContext *s, uint64_t val)
 
void avio_wl32 (AVIOContext *s, unsigned int val)
 
void avio_wb32 (AVIOContext *s, unsigned int val)
 
void avio_wl24 (AVIOContext *s, unsigned int val)
 
void avio_wb24 (AVIOContext *s, unsigned int val)
 
void avio_wl16 (AVIOContext *s, unsigned int val)
 
void avio_wb16 (AVIOContext *s, unsigned int val)
 
int avio_put_str (AVIOContext *s, const char *str)
 Write a NULL-terminated string. More...
 
int avio_put_str16le (AVIOContext *s, const char *str)
 Convert an UTF-8 string to UTF-16LE and write it. More...
 
int avio_put_str16be (AVIOContext *s, const char *str)
 Convert an UTF-8 string to UTF-16BE and write it. More...
 
void avio_write_marker (AVIOContext *s, int64_t time, enum AVIODataMarkerType type)
 Mark the written bytestream as a specific type. More...
 
int64_t avio_seek (AVIOContext *s, int64_t offset, int whence)
 fseek() equivalent for AVIOContext. More...
 
static av_always_inline int64_t avio_skip (AVIOContext *s, int64_t offset)
 Skip given number of bytes forward. More...
 
static av_always_inline int64_t avio_tell (AVIOContext *s)
 ftell() equivalent for AVIOContext. More...
 
int64_t avio_size (AVIOContext *s)
 Get the filesize. More...
 
int avio_printf (AVIOContext *s, const char *fmt,...) av_printf_format(2
 
int void avio_flush (AVIOContext *s)
 
int avio_read (AVIOContext *s, unsigned char *buf, int size)
 Read size bytes from AVIOContext into buf. More...
 
int avio_read_partial (AVIOContext *s, unsigned char *buf, int size)
 Read size bytes from AVIOContext into buf. More...
 
int avio_get_str (AVIOContext *pb, int maxlen, char *buf, int buflen)
 Read a string from pb into buf. More...
 
int avio_get_str16le (AVIOContext *pb, int maxlen, char *buf, int buflen)
 Read a UTF-16 string from pb and convert it to UTF-8. More...
 
int avio_get_str16be (AVIOContext *pb, int maxlen, char *buf, int buflen)
 
int avio_open (AVIOContext **s, const char *url, int flags)
 Create and initialize a AVIOContext for accessing the resource indicated by url. More...
 
int avio_open2 (AVIOContext **s, const char *url, int flags, const AVIOInterruptCB *int_cb, AVDictionary **options)
 Create and initialize a AVIOContext for accessing the resource indicated by url. More...
 
int avio_close (AVIOContext *s)
 Close the resource accessed by the AVIOContext s and free it. More...
 
int avio_closep (AVIOContext **s)
 Close the resource accessed by the AVIOContext *s, free it and set the pointer pointing to it to NULL. More...
 
int avio_open_dyn_buf (AVIOContext **s)
 Open a write only memory stream. More...
 
int avio_close_dyn_buf (AVIOContext *s, uint8_t **pbuffer)
 Return the written size and a pointer to the buffer. More...
 
const char * avio_enum_protocols (void **opaque, int output)
 Iterate through names of available protocols. More...
 
int avio_pause (AVIOContext *h, int pause)
 Pause and resume playing - only meaningful if using a network streaming protocol (e.g. More...
 
int64_t avio_seek_time (AVIOContext *h, int stream_index, int64_t timestamp, int flags)
 Seek to a given timestamp relative to some component stream. More...
 
Functions for reading from AVIOContext
Note
return 0 if EOF, so you cannot use it if EOF handling is necessary
int avio_r8 (AVIOContext *s)
 
unsigned int avio_rl16 (AVIOContext *s)
 
unsigned int avio_rl24 (AVIOContext *s)
 
unsigned int avio_rl32 (AVIOContext *s)
 
uint64_t avio_rl64 (AVIOContext *s)
 
unsigned int avio_rb16 (AVIOContext *s)
 
unsigned int avio_rb24 (AVIOContext *s)
 
unsigned int avio_rb32 (AVIOContext *s)
 
uint64_t avio_rb64 (AVIOContext *s)
 

Detailed Description

Buffered I/O operations.

Definition in file avio.h.

Macro Definition Documentation

◆ AVIO_SEEKABLE_NORMAL

#define AVIO_SEEKABLE_NORMAL   (1 << 0)

Seeking works like for a local file.

Definition at line 40 of file avio.h.

◆ AVIO_SEEKABLE_TIME

#define AVIO_SEEKABLE_TIME   (1 << 1)

Seeking by timestamp with avio_seek_time() is possible.

Definition at line 45 of file avio.h.

◆ AVSEEK_SIZE

#define AVSEEK_SIZE   0x10000

ORing this as the "whence" parameter to a seek function causes it to return the filesize without seeking anywhere.

Supporting this is optional. If it is not supported then the seek function will return <0.

Definition at line 282 of file avio.h.

◆ AVSEEK_FORCE

#define AVSEEK_FORCE   0x20000

Passing this flag as the "whence" parameter to a seek function causes it to seek by any means (like reopening and linear reading) or other normally unreasonable means that can be extremely slow.

This may be ignored by the seek code.

Definition at line 290 of file avio.h.

◆ AVIO_FLAG_READ

#define AVIO_FLAG_READ   1

read-only

Definition at line 393 of file avio.h.

◆ AVIO_FLAG_WRITE

#define AVIO_FLAG_WRITE   2

write-only

Examples:
output.c, and transcode_aac.c.

Definition at line 394 of file avio.h.

Referenced by main(), and open_output_file().

◆ AVIO_FLAG_READ_WRITE

#define AVIO_FLAG_READ_WRITE   (AVIO_FLAG_READ|AVIO_FLAG_WRITE)

read-write pseudo flag

Definition at line 395 of file avio.h.

◆ AVIO_FLAG_NONBLOCK

#define AVIO_FLAG_NONBLOCK   8

Use non-blocking mode.

If this flag is set, operations on the context will return AVERROR(EAGAIN) if they can not be performed immediately. If this flag is not set, operations on the context will never return AVERROR(EAGAIN). Note that this flag does not affect the opening/connecting of the context. Connecting a protocol will always block if necessary (e.g. on network protocols) but never hang (e.g. on busy devices). Warning: non-blocking protocols is work-in-progress; this flag may be silently ignored.

Definition at line 412 of file avio.h.

Enumeration Type Documentation

◆ AVIODataMarkerType

Different data types that can be returned via the AVIO write_data_type callback.

Enumerator
AVIO_DATA_MARKER_HEADER 

Header data; this needs to be present for the stream to be decodeable.

AVIO_DATA_MARKER_SYNC_POINT 

A point in the output bytestream where a decoder can start decoding (i.e.

a keyframe). A demuxer/decoder given the data flagged with AVIO_DATA_MARKER_HEADER, followed by any AVIO_DATA_MARKER_SYNC_POINT, should give decodeable results.

AVIO_DATA_MARKER_BOUNDARY_POINT 

A point in the output bytestream where a demuxer can start parsing (for non self synchronizing bytestream formats).

That is, any non-keyframe packet start point.

AVIO_DATA_MARKER_UNKNOWN 

This is any, unlabelled data.

It can either be a muxer not marking any positions at all, it can be an actual boundary/sync point that the muxer chooses not to mark, or a later part of a packet/fragment that is cut into multiple write callbacks due to limited IO buffer size.

AVIO_DATA_MARKER_TRAILER 

Trailer data, which doesn't contain actual content, but only for finalizing the output file.

Definition at line 67 of file avio.h.

Function Documentation

◆ avio_check()

int avio_check ( const char *  url,
int  flags 
)

Return AVIO_FLAG_* access flags corresponding to the access permissions of the resource in url, or a negative value corresponding to an AVERROR code in case of failure.

The returned access flags are masked by the value in flags.

Note
This function is intrinsically unsafe, in the sense that the checked resource may change its existence or permission status from one call to another. Thus you should not trust the returned value, unless you are sure that no other processes are accessing the checked resource.

◆ avio_alloc_context()

AVIOContext* avio_alloc_context ( unsigned char *  buffer,
int  buffer_size,
int  write_flag,
void *  opaque,
int(*)(void *opaque, uint8_t *buf, int buf_size)  read_packet,
int(*)(void *opaque, uint8_t *buf, int buf_size)  write_packet,
int64_t(*)(void *opaque, int64_t offset, int whence)  seek 
)

Allocate and initialize an AVIOContext for buffered I/O.

It must be later freed with avio_context_free().

Parameters
bufferMemory block for input/output operations via AVIOContext. The buffer must be allocated with av_malloc() and friends.
buffer_sizeThe buffer size is very important for performance. For protocols with fixed blocksize it should be set to this blocksize. For others a typical size is a cache page, e.g. 4kb.
write_flagSet to 1 if the buffer should be writable, 0 otherwise.
opaqueAn opaque pointer to user-specific data.
read_packetA function for refilling the buffer, may be NULL.
write_packetA function for writing the buffer contents, may be NULL.
seekA function for seeking to specified byte position, may be NULL.
Returns
Allocated AVIOContext or NULL on failure.

◆ avio_context_free()

void avio_context_free ( AVIOContext **  s)

Free the supplied IO context and everything associated with it.

Parameters
sDouble pointer to the IO context. This function will write NULL into s.

◆ avio_w8()

void avio_w8 ( AVIOContext s,
int  b 
)

◆ avio_write()

void avio_write ( AVIOContext s,
const unsigned char *  buf,
int  size 
)

◆ avio_wl64()

void avio_wl64 ( AVIOContext s,
uint64_t  val 
)

◆ avio_wb64()

void avio_wb64 ( AVIOContext s,
uint64_t  val 
)

◆ avio_wl32()

void avio_wl32 ( AVIOContext s,
unsigned int  val 
)

◆ avio_wb32()

void avio_wb32 ( AVIOContext s,
unsigned int  val 
)

◆ avio_wl24()

void avio_wl24 ( AVIOContext s,
unsigned int  val 
)

◆ avio_wb24()

void avio_wb24 ( AVIOContext s,
unsigned int  val 
)

◆ avio_wl16()

void avio_wl16 ( AVIOContext s,
unsigned int  val 
)

◆ avio_wb16()

void avio_wb16 ( AVIOContext s,
unsigned int  val 
)

◆ avio_put_str()

int avio_put_str ( AVIOContext s,
const char *  str 
)

Write a NULL-terminated string.

Returns
number of bytes written.

◆ avio_put_str16le()

int avio_put_str16le ( AVIOContext s,
const char *  str 
)

Convert an UTF-8 string to UTF-16LE and write it.

Parameters
sthe AVIOContext
strNULL-terminated UTF-8 string
Returns
number of bytes written.

◆ avio_put_str16be()

int avio_put_str16be ( AVIOContext s,
const char *  str 
)

Convert an UTF-8 string to UTF-16BE and write it.

Parameters
sthe AVIOContext
strNULL-terminated UTF-8 string
Returns
number of bytes written.

◆ avio_write_marker()

void avio_write_marker ( AVIOContext s,
int64_t  time,
enum AVIODataMarkerType  type 
)

Mark the written bytestream as a specific type.

Zero-length ranges are omitted from the output.

Parameters
timethe stream time the current bytestream pos corresponds to (in AV_TIME_BASE units), or AV_NOPTS_VALUE if unknown or not applicable
typethe kind of data written starting at the current pos

◆ avio_seek()

int64_t avio_seek ( AVIOContext s,
int64_t  offset,
int  whence 
)

fseek() equivalent for AVIOContext.

Returns
new position or AVERROR.

Referenced by avio_skip(), and avio_tell().

◆ avio_skip()

static av_always_inline int64_t avio_skip ( AVIOContext s,
int64_t  offset 
)
static

Skip given number of bytes forward.

Returns
new position or AVERROR.

Definition at line 302 of file avio.h.

◆ avio_tell()

static av_always_inline int64_t avio_tell ( AVIOContext s)
static

ftell() equivalent for AVIOContext.

Returns
position or AVERROR.

Definition at line 311 of file avio.h.

◆ avio_size()

int64_t avio_size ( AVIOContext s)

Get the filesize.

Returns
filesize or AVERROR

Referenced by avio_tell().

◆ avio_printf()

int avio_printf ( AVIOContext s,
const char *  fmt,
  ... 
)
Warning
currently size is limited

Referenced by avio_tell().

◆ avio_flush()

int void avio_flush ( AVIOContext s)

Referenced by avio_tell().

◆ avio_read()

int avio_read ( AVIOContext s,
unsigned char *  buf,
int  size 
)

Read size bytes from AVIOContext into buf.

Returns
number of bytes read or AVERROR

Referenced by avio_tell().

◆ avio_read_partial()

int avio_read_partial ( AVIOContext s,
unsigned char *  buf,
int  size 
)

Read size bytes from AVIOContext into buf.

Unlike avio_read(), this is allowed to read fewer bytes than requested. The missing bytes can be read in the next call. This always tries to read at least 1 byte. Useful to reduce latency in certain cases.

Returns
number of bytes read or AVERROR

Referenced by avio_tell().

◆ avio_r8()

int avio_r8 ( AVIOContext s)

Referenced by avio_tell().

◆ avio_rl16()

unsigned int avio_rl16 ( AVIOContext s)

Referenced by avio_tell().

◆ avio_rl24()

unsigned int avio_rl24 ( AVIOContext s)

Referenced by avio_tell().

◆ avio_rl32()

unsigned int avio_rl32 ( AVIOContext s)

Referenced by avio_tell().

◆ avio_rl64()

uint64_t avio_rl64 ( AVIOContext s)

Referenced by avio_tell().

◆ avio_rb16()

unsigned int avio_rb16 ( AVIOContext s)

Referenced by avio_tell().

◆ avio_rb24()

unsigned int avio_rb24 ( AVIOContext s)

Referenced by avio_tell().

◆ avio_rb32()

unsigned int avio_rb32 ( AVIOContext s)

Referenced by avio_tell().

◆ avio_rb64()

uint64_t avio_rb64 ( AVIOContext s)

Referenced by avio_tell().

◆ avio_get_str()

int avio_get_str ( AVIOContext pb,
int  maxlen,
char *  buf,
int  buflen 
)

Read a string from pb into buf.

The reading will terminate when either a NULL character was encountered, maxlen bytes have been read, or nothing more can be read from pb. The result is guaranteed to be NULL-terminated, it will be truncated if buf is too small. Note that the string is not interpreted or validated in any way, it might get truncated in the middle of a sequence for multi-byte encodings.

Returns
number of bytes read (is always <= maxlen). If reading ends on EOF or error, the return value will be one more than bytes actually read.

Referenced by avio_tell().

◆ avio_get_str16le()

int avio_get_str16le ( AVIOContext pb,
int  maxlen,
char *  buf,
int  buflen 
)

Read a UTF-16 string from pb and convert it to UTF-8.

The reading will terminate when either a null or invalid character was encountered or maxlen bytes have been read.

Returns
number of bytes read (is always <= maxlen)

Referenced by avio_tell().

◆ avio_get_str16be()

int avio_get_str16be ( AVIOContext pb,
int  maxlen,
char *  buf,
int  buflen 
)

Referenced by avio_tell().

◆ avio_open()

int avio_open ( AVIOContext **  s,
const char *  url,
int  flags 
)

Create and initialize a AVIOContext for accessing the resource indicated by url.

Note
When the resource indicated by url has been opened in read+write mode, the AVIOContext can be used only for writing.
Parameters
sUsed to return the pointer to the created AVIOContext. In case of failure the pointed to value is set to NULL.
urlresource to access
flagsflags which control how the resource indicated by url is to be opened
Returns
0 in case of success, a negative value corresponding to an AVERROR code in case of failure
Examples:
output.c, and transcode_aac.c.

Referenced by main(), and open_output_file().

◆ avio_open2()

int avio_open2 ( AVIOContext **  s,
const char *  url,
int  flags,
const AVIOInterruptCB int_cb,
AVDictionary **  options 
)

Create and initialize a AVIOContext for accessing the resource indicated by url.

Note
When the resource indicated by url has been opened in read+write mode, the AVIOContext can be used only for writing.
Parameters
sUsed to return the pointer to the created AVIOContext. In case of failure the pointed to value is set to NULL.
urlresource to access
flagsflags which control how the resource indicated by url is to be opened
int_cban interrupt callback to be used at the protocols level
optionsA dictionary filled with protocol-private options. On return this parameter will be destroyed and replaced with a dict containing options that were not found. May be NULL.
Returns
0 in case of success, a negative value corresponding to an AVERROR code in case of failure

◆ avio_close()

int avio_close ( AVIOContext s)

Close the resource accessed by the AVIOContext s and free it.

This function can only be used if s was opened by avio_open().

The internal buffer is automatically flushed before closing the resource.

Returns
0 on success, an AVERROR < 0 on error.
See also
avio_closep
Examples:
output.c, and transcode_aac.c.

Referenced by main(), and open_output_file().

◆ avio_closep()

int avio_closep ( AVIOContext **  s)

Close the resource accessed by the AVIOContext *s, free it and set the pointer pointing to it to NULL.

This function can only be used if s was opened by avio_open().

The internal buffer is automatically flushed before closing the resource.

Returns
0 on success, an AVERROR < 0 on error.
See also
avio_close

◆ avio_open_dyn_buf()

int avio_open_dyn_buf ( AVIOContext **  s)

Open a write only memory stream.

Parameters
snew IO context
Returns
zero if no error.

◆ avio_close_dyn_buf()

int avio_close_dyn_buf ( AVIOContext s,
uint8_t **  pbuffer 
)

Return the written size and a pointer to the buffer.

The buffer must be freed with av_free(). Padding of AV_INPUT_BUFFER_PADDING_SIZE is added to the buffer.

Parameters
sIO context
pbufferpointer to a byte buffer
Returns
the length of the byte buffer

◆ avio_enum_protocols()

const char* avio_enum_protocols ( void **  opaque,
int  output 
)

Iterate through names of available protocols.

Parameters
opaqueA private pointer representing current protocol. It must be a pointer to NULL on first iteration and will be updated by successive calls to avio_enum_protocols.
outputIf set to 1, iterate over output protocols, otherwise over input protocols.
Returns
A static string containing the name of current protocol or NULL

◆ avio_pause()

int avio_pause ( AVIOContext h,
int  pause 
)

Pause and resume playing - only meaningful if using a network streaming protocol (e.g.

MMS).

Parameters
hIO context from which to call the read_pause function pointer
pause1 for pause, 0 for resume

◆ avio_seek_time()

int64_t avio_seek_time ( AVIOContext h,
int  stream_index,
int64_t  timestamp,
int  flags 
)

Seek to a given timestamp relative to some component stream.

Only meaningful if using a network streaming protocol (e.g. MMS.).

Parameters
hIO context from which to call the seek function pointers
stream_indexThe stream index that the timestamp is relative to. If stream_index is (-1) the timestamp should be in AV_TIME_BASE units from the beginning of the presentation. If a stream_index >= 0 is used and the protocol does not support seeking based on component streams, the call will fail with ENOTSUP.
timestamptimestamp in AVStream.time_base units or if there is no stream specified then in AV_TIME_BASE units.
flagsOptional combination of AVSEEK_FLAG_BACKWARD, AVSEEK_FLAG_BYTE and AVSEEK_FLAG_ANY. The protocol may silently ignore AVSEEK_FLAG_BACKWARD and AVSEEK_FLAG_ANY, but AVSEEK_FLAG_BYTE will fail with ENOTSUP if used and not supported.
Returns
>= 0 on success
See also
AVInputFormat::read_seek