avio.h 23.9 KB
Newer Older
1 2 3
/*
 * copyright (c) 2001 Fabrice Bellard
 *
4
 * This file is part of Libav.
5
 *
6
 * Libav is free software; you can redistribute it and/or
7 8
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
9
 * version 2.1 of the License, or (at your option) any later version.
10
 *
11
 * Libav is distributed in the hope that it will be useful,
12 13 14 15 16
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
17
 * License along with Libav; if not, write to the Free Software
18 19
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */
20 21
#ifndef AVFORMAT_AVIO_H
#define AVFORMAT_AVIO_H
22

23
/**
24
 * @file
Anton Khirnov's avatar
Anton Khirnov committed
25
 * Buffered I/O operations
26 27
 */

28 29
#include <stdint.h>

30
#include "libavutil/common.h"
31
#include "libavutil/log.h"
32

33 34
#include "libavformat/version.h"

35 36 37 38 39 40 41 42 43

#define AVIO_SEEKABLE_NORMAL 0x0001 /**< Seeking works like for a local file */

/**
 * Bytestream IO Context.
 * New fields can be added to the end with minor version bumps.
 * Removal, reordering and changes to existing fields require a major
 * version bump.
 * sizeof(AVIOContext) must not be used outside libav*.
44 45 46 47 48
 *
 * @note None of the function pointers in AVIOContext should be called
 *       directly, they should only be set by the client application
 *       when implementing custom I/O. Normally these are set to the
 *       function pointers specified in avio_alloc_context()
49 50
 */
typedef struct {
51 52 53 54 55 56 57 58 59
    unsigned char *buffer;  /**< Start of the buffer. */
    int buffer_size;        /**< Maximum buffer size */
    unsigned char *buf_ptr; /**< Current position in the buffer */
    unsigned char *buf_end; /**< End of the data, may be less than
                                 buffer+buffer_size if the read function returned
                                 less data than requested, e.g. for streams where
                                 no more data has been received yet. */
    void *opaque;           /**< A private pointer, passed to the read/write/seek/...
                                 functions. */
60 61 62
    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);
63 64 65 66
    int64_t pos;            /**< position in the file of the current buffer */
    int must_flush;         /**< true if the next seek should flush */
    int eof_reached;        /**< true if eof reached */
    int write_flag;         /**< true if open for writing */
67 68 69 70 71 72 73
#if FF_API_OLD_AVIO
    attribute_deprecated int is_streamed;
#endif
    int max_packet_size;
    unsigned long checksum;
    unsigned char *checksum_ptr;
    unsigned long (*update_checksum)(unsigned long checksum, const uint8_t *buf, unsigned int size);
74
    int error;              /**< contains the error code or 0 if no error happened */
75 76 77
    /**
     * Pause or resume playback for network streaming protocols - e.g. MMS.
     */
78
    int (*read_pause)(void *opaque, int pause);
79 80 81 82 83
    /**
     * Seek to a given timestamp in stream with the specified stream_index.
     * Needed for some network streaming protocols which don't support seeking
     * to byte position.
     */
84 85 86 87 88 89 90 91
    int64_t (*read_seek)(void *opaque, int stream_index,
                         int64_t timestamp, int flags);
    /**
     * A combination of AVIO_SEEKABLE_ flags or 0 when the stream is not seekable.
     */
    int seekable;
} AVIOContext;

Fabrice Bellard's avatar
Fabrice Bellard committed
92 93
/* unbuffered I/O */

94
#if FF_API_OLD_AVIO
95 96 97
/**
 * URL Context.
 * New fields can be added to the end with minor version bumps.
Diego Biurrun's avatar
Diego Biurrun committed
98
 * Removal, reordering and changes to existing fields require a major
99
 * version bump.
Diego Biurrun's avatar
Diego Biurrun committed
100
 * sizeof(URLContext) must not be used outside libav*.
101
 * @deprecated This struct will be made private
102
 */
103
typedef struct URLContext {
104
    const AVClass *av_class; ///< information for av_log(). Set by url_open().
Fabrice Bellard's avatar
Fabrice Bellard committed
105
    struct URLProtocol *prot;
106
    int flags;
107 108
    int is_streamed;  /**< true if streamed (no seek possible), default = false */
    int max_packet_size;  /**< if non zero, the stream is packetized with this max packet size */
Fabrice Bellard's avatar
Fabrice Bellard committed
109
    void *priv_data;
110
    char *filename; /**< specified URL */
111
    int is_connected;
112
} URLContext;
Fabrice Bellard's avatar
Fabrice Bellard committed
113

114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
#define URL_PROTOCOL_FLAG_NESTED_SCHEME 1 /*< The protocol name can be the first part of a nested protocol scheme */

/**
 * @deprecated This struct is to be made private. Use the higher-level
 *             AVIOContext-based API instead.
 */
typedef struct URLProtocol {
    const char *name;
    int (*url_open)(URLContext *h, const char *url, int flags);
    int (*url_read)(URLContext *h, unsigned char *buf, int size);
    int (*url_write)(URLContext *h, const unsigned char *buf, int size);
    int64_t (*url_seek)(URLContext *h, int64_t pos, int whence);
    int (*url_close)(URLContext *h);
    struct URLProtocol *next;
    int (*url_read_pause)(URLContext *h, int pause);
    int64_t (*url_read_seek)(URLContext *h, int stream_index,
                             int64_t timestamp, int flags);
    int (*url_get_file_handle)(URLContext *h);
    int priv_data_size;
    const AVClass *priv_data_class;
    int flags;
Stefano Sabatini's avatar
Stefano Sabatini committed
135
    int (*url_check)(URLContext *h, int mask);
136 137
} URLProtocol;

Fabrice Bellard's avatar
Fabrice Bellard committed
138 139 140 141 142 143
typedef struct URLPollEntry {
    URLContext *handle;
    int events;
    int revents;
} URLPollEntry;

144 145 146
/* not implemented */
attribute_deprecated int url_poll(URLPollEntry *poll_table, int n, int timeout);

147 148 149 150 151 152
/**
 * @defgroup open_modes URL open modes
 * The flags argument to url_open and cosins must be one of the following
 * constants, optionally ORed with other flags.
 * @{
 */
153 154 155
#define URL_RDONLY 1  /**< read-only */
#define URL_WRONLY 2  /**< write-only */
#define URL_RDWR   (URL_RDONLY|URL_WRONLY)  /**< read-write */
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
/**
 * @}
 */

/**
 * 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.
 */
#define URL_FLAG_NONBLOCK 4
173

174
typedef int URLInterruptCB(void);
175
extern URLInterruptCB *url_interrupt_cb;
176

177
/**
178 179 180
 * @defgroup old_url_funcs Old url_* functions
 * @deprecated use the buffered API based on AVIOContext instead
 * @{
181
 */
182 183
attribute_deprecated int url_open_protocol (URLContext **puc, struct URLProtocol *up,
                                            const char *url, int flags);
Anton Khirnov's avatar
Anton Khirnov committed
184
attribute_deprecated int url_alloc(URLContext **h, const char *url, int flags);
185
attribute_deprecated int url_connect(URLContext *h);
186
attribute_deprecated int url_open(URLContext **h, const char *url, int flags);
187
attribute_deprecated int url_read(URLContext *h, unsigned char *buf, int size);
188
attribute_deprecated int url_read_complete(URLContext *h, unsigned char *buf, int size);
189
attribute_deprecated int url_write(URLContext *h, const unsigned char *buf, int size);
190
attribute_deprecated int64_t url_seek(URLContext *h, int64_t pos, int whence);
191
attribute_deprecated int url_close(URLContext *h);
192
attribute_deprecated int64_t url_filesize(URLContext *h);
193
attribute_deprecated int url_get_file_handle(URLContext *h);
194
attribute_deprecated int url_get_max_packet_size(URLContext *h);
195
attribute_deprecated void url_get_filename(URLContext *h, char *buf, int buf_size);
196
attribute_deprecated int av_url_read_pause(URLContext *h, int pause);
197 198
attribute_deprecated int64_t av_url_read_seek(URLContext *h, int stream_index,
                                              int64_t timestamp, int flags);
199
attribute_deprecated void url_set_interrupt_cb(int (*interrupt_cb)(void));
200 201
/**
 * If protocol is NULL, returns the first registered protocol,
202
 * if protocol is non-NULL, returns the next registered protocol after protocol,
203 204
 * or NULL if protocol is the last one.
 */
205
attribute_deprecated URLProtocol *av_protocol_next(URLProtocol *p);
206
/**
207
 * Register the URLProtocol protocol.
208 209
 *
 * @param size the size of the URLProtocol struct referenced
210
 */
211
attribute_deprecated int av_register_protocol2(URLProtocol *protocol, int size);
212 213 214 215
/**
 * @}
 */

216

217 218
typedef attribute_deprecated AVIOContext ByteIOContext;

219
attribute_deprecated int init_put_byte(AVIOContext *s,
Fabrice Bellard's avatar
Fabrice Bellard committed
220 221 222 223
                  unsigned char *buffer,
                  int buffer_size,
                  int write_flag,
                  void *opaque,
224 225
                  int (*read_packet)(void *opaque, uint8_t *buf, int buf_size),
                  int (*write_packet)(void *opaque, uint8_t *buf, int buf_size),
226
                  int64_t (*seek)(void *opaque, int64_t offset, int whence));
227 228 229 230 231 232 233 234
attribute_deprecated AVIOContext *av_alloc_put_byte(
                  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));
235 236 237 238 239 240 241

/**
 * @defgroup old_avio_funcs Old put_/get_*() functions
 * @deprecated use the avio_ -prefixed functions instead.
 * @{
 */
attribute_deprecated int          get_buffer(AVIOContext *s, unsigned char *buf, int size);
242
attribute_deprecated int          get_partial_buffer(AVIOContext *s, unsigned char *buf, int size);
243 244 245 246 247 248 249 250 251
attribute_deprecated int          get_byte(AVIOContext *s);
attribute_deprecated unsigned int get_le16(AVIOContext *s);
attribute_deprecated unsigned int get_le24(AVIOContext *s);
attribute_deprecated unsigned int get_le32(AVIOContext *s);
attribute_deprecated uint64_t     get_le64(AVIOContext *s);
attribute_deprecated unsigned int get_be16(AVIOContext *s);
attribute_deprecated unsigned int get_be24(AVIOContext *s);
attribute_deprecated unsigned int get_be32(AVIOContext *s);
attribute_deprecated uint64_t     get_be64(AVIOContext *s);
252 253

attribute_deprecated void         put_byte(AVIOContext *s, int b);
Anton Khirnov's avatar
Anton Khirnov committed
254
attribute_deprecated void         put_nbyte(AVIOContext *s, int b, int count);
255 256 257 258 259 260 261 262 263
attribute_deprecated void         put_buffer(AVIOContext *s, const unsigned char *buf, int size);
attribute_deprecated void         put_le64(AVIOContext *s, uint64_t val);
attribute_deprecated void         put_be64(AVIOContext *s, uint64_t val);
attribute_deprecated void         put_le32(AVIOContext *s, unsigned int val);
attribute_deprecated void         put_be32(AVIOContext *s, unsigned int val);
attribute_deprecated void         put_le24(AVIOContext *s, unsigned int val);
attribute_deprecated void         put_be24(AVIOContext *s, unsigned int val);
attribute_deprecated void         put_le16(AVIOContext *s, unsigned int val);
attribute_deprecated void         put_be16(AVIOContext *s, unsigned int val);
Anton Khirnov's avatar
Anton Khirnov committed
264
attribute_deprecated void         put_tag(AVIOContext *s, const char *tag);
265 266 267
/**
 * @}
 */
268

269
attribute_deprecated int     av_url_read_fpause(AVIOContext *h,    int pause);
270
attribute_deprecated int64_t av_url_read_fseek (AVIOContext *h,    int stream_index,
271
                                                int64_t timestamp, int flags);
272 273 274 275 276 277 278 279

/**
 * @defgroup old_url_f_funcs Old url_f* functions
 * @deprecated use the avio_ -prefixed functions instead.
 * @{
 */
attribute_deprecated int url_fopen( AVIOContext **s, const char *url, int flags);
attribute_deprecated int url_fclose(AVIOContext *s);
280
attribute_deprecated int64_t url_fseek(AVIOContext *s, int64_t offset, int whence);
Anton Khirnov's avatar
Anton Khirnov committed
281
attribute_deprecated int url_fskip(AVIOContext *s, int64_t offset);
282
attribute_deprecated int64_t url_ftell(AVIOContext *s);
283
attribute_deprecated int64_t url_fsize(AVIOContext *s);
284 285
#define URL_EOF (-1)
attribute_deprecated int url_fgetc(AVIOContext *s);
286
attribute_deprecated int url_setbufsize(AVIOContext *s, int buf_size);
287
attribute_deprecated int url_fprintf(AVIOContext *s, const char *fmt, ...) av_printf_format(2, 3);
288
attribute_deprecated void put_flush_packet(AVIOContext *s);
289
attribute_deprecated int url_open_dyn_buf(AVIOContext **s);
290
attribute_deprecated int url_open_dyn_packet_buf(AVIOContext **s, int max_packet_size);
291
attribute_deprecated int url_close_dyn_buf(AVIOContext *s, uint8_t **pbuffer);
292
attribute_deprecated int url_fdopen(AVIOContext **s, URLContext *h);
293 294 295
/**
 * @}
 */
Anton Khirnov's avatar
Anton Khirnov committed
296 297 298 299 300

/**
 * @deprecated use AVIOContext.eof_reached
 */
attribute_deprecated int url_feof(AVIOContext *s);
Anton Khirnov's avatar
Anton Khirnov committed
301
attribute_deprecated int url_ferror(AVIOContext *s);
302 303 304

attribute_deprecated int udp_set_remote_url(URLContext *h, const char *uri);
attribute_deprecated int udp_get_local_port(URLContext *h);
305 306 307 308

attribute_deprecated void init_checksum(AVIOContext *s,
                   unsigned long (*update_checksum)(unsigned long c, const uint8_t *p, unsigned int len),
                   unsigned long checksum);
309
attribute_deprecated unsigned long get_checksum(AVIOContext *s);
310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339
attribute_deprecated void put_strz(AVIOContext *s, const char *buf);
/** @note unlike fgets, the EOL character is not returned and a whole
    line is parsed. return NULL if first char read was EOF */
attribute_deprecated char *url_fgets(AVIOContext *s, char *buf, int buf_size);
/**
 * @deprecated use avio_get_str instead
 */
attribute_deprecated char *get_strz(AVIOContext *s, char *buf, int maxlen);
/**
 * @deprecated Use AVIOContext.seekable field directly.
 */
attribute_deprecated static inline int url_is_streamed(AVIOContext *s)
{
    return !s->seekable;
}
attribute_deprecated URLContext *url_fileno(AVIOContext *s);

/**
 * @deprecated use AVIOContext.max_packet_size directly.
 */
attribute_deprecated int url_fget_max_packet_size(AVIOContext *s);

attribute_deprecated int url_open_buf(AVIOContext **s, uint8_t *buf, int buf_size, int flags);

/** return the written or read size */
attribute_deprecated int url_close_buf(AVIOContext *s);

/**
 * Return a non-zero value if the resource indicated by url
 * exists, 0 otherwise.
340
 * @deprecated Use avio_check instead.
341
 */
342 343
attribute_deprecated int url_exist(const char *url);
#endif // FF_API_OLD_AVIO
344

Stefano Sabatini's avatar
Stefano Sabatini committed
345
/**
346
 * Return AVIO_FLAG_* access flags corresponding to the access permissions
Stefano Sabatini's avatar
Stefano Sabatini committed
347 348 349 350 351 352 353 354 355 356 357 358
 * 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.
 */
int avio_check(const char *url, int flags);

359 360 361 362 363 364 365 366
/**
 * The callback is called in blocking functions to test regulary if
 * asynchronous interruption is needed. AVERROR_EXIT is returned
 * in this case by the interrupted function. 'NULL' means no interrupt
 * callback is given.
 */
void avio_set_interrupt_cb(int (*interrupt_cb)(void));

367 368 369 370 371
/**
 * Allocate and initialize an AVIOContext for buffered I/O. It must be later
 * freed with av_free().
 *
 * @param buffer Memory block for input/output operations via AVIOContext.
372
 *        The buffer must be allocated with av_malloc() and friends.
373 374 375 376 377 378 379 380 381 382 383
 * @param buffer_size The 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.
 * @param write_flag Set to 1 if the buffer should be writable, 0 otherwise.
 * @param opaque An opaque pointer to user-specific data.
 * @param read_packet  A function for refilling the buffer, may be NULL.
 * @param write_packet A function for writing the buffer contents, may be NULL.
 * @param seek A function for seeking to specified byte position, may be NULL.
 *
 * @return Allocated AVIOContext or NULL on failure.
 */
384
AVIOContext *avio_alloc_context(
385 386 387 388
                  unsigned char *buffer,
                  int buffer_size,
                  int write_flag,
                  void *opaque,
389
                  int (*read_packet)(void *opaque, uint8_t *buf, int buf_size),
Michael Niedermayer's avatar
Michael Niedermayer committed
390
                  int (*write_packet)(void *opaque, uint8_t *buf, int buf_size),
391
                  int64_t (*seek)(void *opaque, int64_t offset, int whence));
Fabrice Bellard's avatar
Fabrice Bellard committed
392

393 394 395 396 397 398 399 400 401 402
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);
Fabrice Bellard's avatar
Fabrice Bellard committed
403

404 405 406 407
/**
 * Write a NULL-terminated string.
 * @return number of bytes written.
 */
408
int avio_put_str(AVIOContext *s, const char *str);
409

410 411 412 413
/**
 * Convert an UTF-8 string to UTF-16LE and write it.
 * @return number of bytes written.
 */
414
int avio_put_str16le(AVIOContext *s, const char *str);
415

416 417 418 419 420 421 422 423 424 425 426 427 428 429 430
/**
 * Passing 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.
 */
#define AVSEEK_SIZE 0x10000

/**
 * Oring this flag as into the "whence" parameter to a seek function causes it to
 * seek by any means (like reopening and linear reading) or other normally unreasonble
 * means that can be extreemly slow.
 * This may be ignored by the seek code.
 */
#define AVSEEK_FORCE 0x20000

431
/**
432
 * fseek() equivalent for AVIOContext.
433 434
 * @return new position or AVERROR.
 */
435
int64_t avio_seek(AVIOContext *s, int64_t offset, int whence);
436

Peter Ross's avatar
Peter Ross committed
437 438 439 440
/**
 * Skip given number of bytes forward
 * @return new position or AVERROR.
 */
441 442 443 444
static av_always_inline int64_t avio_skip(AVIOContext *s, int64_t offset)
{
    return avio_seek(s, offset, SEEK_CUR);
}
Peter Ross's avatar
Peter Ross committed
445

446
/**
447
 * ftell() equivalent for AVIOContext.
448 449
 * @return position or AVERROR.
 */
450 451 452 453
static av_always_inline int64_t avio_tell(AVIOContext *s)
{
    return avio_seek(s, 0, SEEK_CUR);
}
454 455

/**
456
 * Get the filesize.
457 458
 * @return filesize or AVERROR
 */
459
int64_t avio_size(AVIOContext *s);
460

461
/** @warning currently size is limited */
462
int avio_printf(AVIOContext *s, const char *fmt, ...) av_printf_format(2, 3);
463

464
void avio_flush(AVIOContext *s);
Fabrice Bellard's avatar
Fabrice Bellard committed
465

Michael Niedermayer's avatar
Michael Niedermayer committed
466 467

/**
468
 * Read size bytes from AVIOContext into buf.
Benoit Fouet's avatar
Benoit Fouet committed
469
 * @return number of bytes read or AVERROR
Michael Niedermayer's avatar
Michael Niedermayer committed
470
 */
471
int avio_read(AVIOContext *s, unsigned char *buf, int size);
Michael Niedermayer's avatar
Michael Niedermayer committed
472

473 474 475 476 477 478 479
/**
 * @defgroup avio_read Functions for reading from AVIOContext.
 * @{
 *
 * @note return 0 if EOF, so you cannot use it if EOF handling is
 *       necessary
 */
480 481 482 483 484
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);
485 486 487 488 489 490 491
unsigned int avio_rb16(AVIOContext *s);
unsigned int avio_rb24(AVIOContext *s);
unsigned int avio_rb32(AVIOContext *s);
uint64_t     avio_rb64(AVIOContext *s);
/**
 * @}
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
492

Reimar Döffinger's avatar
Reimar Döffinger committed
493 494 495 496 497 498 499 500 501 502 503 504 505 506
/**
 * 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.
 *
 * @return 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.
 */
int avio_get_str(AVIOContext *pb, int maxlen, char *buf, int buflen);

507 508 509 510 511 512
/**
 * 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.
 * @return number of bytes read (is always <= maxlen)
 */
513 514
int avio_get_str16le(AVIOContext *pb, int maxlen, char *buf, int buflen);
int avio_get_str16be(AVIOContext *pb, int maxlen, char *buf, int buflen);
515

Fabrice Bellard's avatar
Fabrice Bellard committed
516

517 518 519 520 521 522
/**
 * @defgroup open_modes URL open modes
 * The flags argument to avio_open must be one of the following
 * constants, optionally ORed with other flags.
 * @{
 */
523 524 525
#define AVIO_FLAG_READ  1                                      /**< read-only */
#define AVIO_FLAG_WRITE 2                                      /**< write-only */
#define AVIO_FLAG_READ_WRITE (AVIO_FLAG_READ|AVIO_FLAG_WRITE)  /**< read-write pseudo flag */
526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541
/**
 * @}
 */

/**
 * 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.
 */
542
#define AVIO_FLAG_NONBLOCK 8
543

Stefano Sabatini's avatar
Stefano Sabatini committed
544
/**
545
 * Create and initialize a AVIOContext for accessing the
Stefano Sabatini's avatar
Stefano Sabatini committed
546 547
 * resource indicated by url.
 * @note When the resource indicated by url has been opened in
548
 * read+write mode, the AVIOContext can be used only for writing.
Stefano Sabatini's avatar
Stefano Sabatini committed
549
 *
550
 * @param s Used to return the pointer to the created AVIOContext.
Stefano Sabatini's avatar
Stefano Sabatini committed
551 552 553 554 555 556
 * In case of failure the pointed to value is set to NULL.
 * @param flags flags which control how the resource indicated by url
 * is to be opened
 * @return 0 in case of success, a negative value corresponding to an
 * AVERROR code in case of failure
 */
557
int avio_open(AVIOContext **s, const char *url, int flags);
Stefano Sabatini's avatar
Stefano Sabatini committed
558

Anton Khirnov's avatar
Anton Khirnov committed
559 560 561 562 563 564
/**
 * Close the resource accessed by the AVIOContext s and free it.
 * This function can only be used if s was opened by avio_open().
 *
 * @return 0 on success, an AVERROR < 0 on error.
 */
565
int avio_close(AVIOContext *s);
566

567
/**
568 569 570 571 572
 * Open a write only memory stream.
 *
 * @param s new IO context
 * @return zero if no error.
 */
573
int avio_open_dyn_buf(AVIOContext **s);
574

575
/**
576
 * Return the written size and a pointer to the buffer. The buffer
577 578
 * must be freed with av_free().
 * Padding of FF_INPUT_BUFFER_PADDING_SIZE is added to the buffer.
579
 *
580
 * @param s IO context
581
 * @param pbuffer pointer to a byte buffer
582 583
 * @return the length of the byte buffer
 */
584
int avio_close_dyn_buf(AVIOContext *s, uint8_t **pbuffer);
585

586 587 588 589 590 591 592 593 594 595 596 597 598
/**
 * Iterate through names of available protocols.
 *
 * @param opaque A 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.
 * @param output If set to 1, iterate over output protocols,
 *               otherwise over input protocols.
 *
 * @return A static string containing the name of current protocol or NULL
 */
const char *avio_enum_protocols(void **opaque, int output);

599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625
/**
 * Pause and resume playing - only meaningful if using a network streaming
 * protocol (e.g. MMS).
 * @param pause 1 for pause, 0 for resume
 */
int     avio_pause(AVIOContext *h, int pause);

/**
 * Seek to a given timestamp relative to some component stream.
 * Only meaningful if using a network streaming protocol (e.g. MMS.).
 * @param stream_index The 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.
 * @param timestamp timestamp in AVStream.time_base units
 *        or if there is no stream specified then in AV_TIME_BASE units.
 * @param flags Optional 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.
 * @return >= 0 on success
 * @see AVInputFormat::read_seek
 */
int64_t avio_seek_time(AVIOContext *h, int stream_index,
                       int64_t timestamp, int flags);

626
#endif /* AVFORMAT_AVIO_H */