avio.h 31 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861
  1. /*
  2. * copyright (c) 2001 Fabrice Bellard
  3. *
  4. * This file is part of FFmpeg.
  5. *
  6. * FFmpeg is free software; you can redistribute it and/or
  7. * modify it under the terms of the GNU Lesser General Public
  8. * 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. * FFmpeg is distributed in the hope that it will be useful,
  12. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  14. * Lesser General Public License for more details.
  15. *
  16. * You should have received a copy of the GNU Lesser General Public
  17. * License along with FFmpeg; if not, write to the Free Software
  18. * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  19. */
  20. #ifndef AVFORMAT_AVIO_H
  21. #define AVFORMAT_AVIO_H
  22. /**
  23. * @file
  24. * @ingroup lavf_io
  25. * Buffered I/O operations
  26. */
  27. #include <stdint.h>
  28. #include "libavutil/common.h"
  29. #include "libavutil/dict.h"
  30. #include "libavutil/log.h"
  31. #include "libavformat/version.h"
  32. /**
  33. * Seeking works like for a local file.
  34. */
  35. #define AVIO_SEEKABLE_NORMAL (1 << 0)
  36. /**
  37. * Seeking by timestamp with avio_seek_time() is possible.
  38. */
  39. #define AVIO_SEEKABLE_TIME (1 << 1)
  40. /**
  41. * Callback for checking whether to abort blocking functions.
  42. * AVERROR_EXIT is returned in this case by the interrupted
  43. * function. During blocking operations, callback is called with
  44. * opaque as parameter. If the callback returns 1, the
  45. * blocking operation will be aborted.
  46. *
  47. * No members can be added to this struct without a major bump, if
  48. * new elements have been added after this struct in AVFormatContext
  49. * or AVIOContext.
  50. */
  51. typedef struct AVIOInterruptCB {
  52. int (*callback)(void*);
  53. void *opaque;
  54. } AVIOInterruptCB;
  55. /**
  56. * Directory entry types.
  57. */
  58. enum AVIODirEntryType {
  59. AVIO_ENTRY_UNKNOWN,
  60. AVIO_ENTRY_BLOCK_DEVICE,
  61. AVIO_ENTRY_CHARACTER_DEVICE,
  62. AVIO_ENTRY_DIRECTORY,
  63. AVIO_ENTRY_NAMED_PIPE,
  64. AVIO_ENTRY_SYMBOLIC_LINK,
  65. AVIO_ENTRY_SOCKET,
  66. AVIO_ENTRY_FILE,
  67. AVIO_ENTRY_SERVER,
  68. AVIO_ENTRY_SHARE,
  69. AVIO_ENTRY_WORKGROUP,
  70. };
  71. /**
  72. * Describes single entry of the directory.
  73. *
  74. * Only name and type fields are guaranteed be set.
  75. * Rest of fields are protocol or/and platform dependent and might be unknown.
  76. */
  77. typedef struct AVIODirEntry {
  78. char *name; /**< Filename */
  79. int type; /**< Type of the entry */
  80. int utf8; /**< Set to 1 when name is encoded with UTF-8, 0 otherwise.
  81. Name can be encoded with UTF-8 even though 0 is set. */
  82. int64_t size; /**< File size in bytes, -1 if unknown. */
  83. int64_t modification_timestamp; /**< Time of last modification in microseconds since unix
  84. epoch, -1 if unknown. */
  85. int64_t access_timestamp; /**< Time of last access in microseconds since unix epoch,
  86. -1 if unknown. */
  87. int64_t status_change_timestamp; /**< Time of last status change in microseconds since unix
  88. epoch, -1 if unknown. */
  89. int64_t user_id; /**< User ID of owner, -1 if unknown. */
  90. int64_t group_id; /**< Group ID of owner, -1 if unknown. */
  91. int64_t filemode; /**< Unix file mode, -1 if unknown. */
  92. } AVIODirEntry;
  93. typedef struct AVIODirContext {
  94. struct URLContext *url_context;
  95. } AVIODirContext;
  96. /**
  97. * Different data types that can be returned via the AVIO
  98. * write_data_type callback.
  99. */
  100. enum AVIODataMarkerType {
  101. /**
  102. * Header data; this needs to be present for the stream to be decodeable.
  103. */
  104. AVIO_DATA_MARKER_HEADER,
  105. /**
  106. * A point in the output bytestream where a decoder can start decoding
  107. * (i.e. a keyframe). A demuxer/decoder given the data flagged with
  108. * AVIO_DATA_MARKER_HEADER, followed by any AVIO_DATA_MARKER_SYNC_POINT,
  109. * should give decodeable results.
  110. */
  111. AVIO_DATA_MARKER_SYNC_POINT,
  112. /**
  113. * A point in the output bytestream where a demuxer can start parsing
  114. * (for non self synchronizing bytestream formats). That is, any
  115. * non-keyframe packet start point.
  116. */
  117. AVIO_DATA_MARKER_BOUNDARY_POINT,
  118. /**
  119. * This is any, unlabelled data. It can either be a muxer not marking
  120. * any positions at all, it can be an actual boundary/sync point
  121. * that the muxer chooses not to mark, or a later part of a packet/fragment
  122. * that is cut into multiple write callbacks due to limited IO buffer size.
  123. */
  124. AVIO_DATA_MARKER_UNKNOWN,
  125. /**
  126. * Trailer data, which doesn't contain actual content, but only for
  127. * finalizing the output file.
  128. */
  129. AVIO_DATA_MARKER_TRAILER,
  130. /**
  131. * A point in the output bytestream where the underlying AVIOContext might
  132. * flush the buffer depending on latency or buffering requirements. Typically
  133. * means the end of a packet.
  134. */
  135. AVIO_DATA_MARKER_FLUSH_POINT,
  136. };
  137. /**
  138. * Bytestream IO Context.
  139. * New fields can be added to the end with minor version bumps.
  140. * Removal, reordering and changes to existing fields require a major
  141. * version bump.
  142. * sizeof(AVIOContext) must not be used outside libav*.
  143. *
  144. * @note None of the function pointers in AVIOContext should be called
  145. * directly, they should only be set by the client application
  146. * when implementing custom I/O. Normally these are set to the
  147. * function pointers specified in avio_alloc_context()
  148. */
  149. typedef struct AVIOContext {
  150. /**
  151. * A class for private options.
  152. *
  153. * If this AVIOContext is created by avio_open2(), av_class is set and
  154. * passes the options down to protocols.
  155. *
  156. * If this AVIOContext is manually allocated, then av_class may be set by
  157. * the caller.
  158. *
  159. * warning -- this field can be NULL, be sure to not pass this AVIOContext
  160. * to any av_opt_* functions in that case.
  161. */
  162. const AVClass *av_class;
  163. /*
  164. * The following shows the relationship between buffer, buf_ptr,
  165. * buf_ptr_max, buf_end, buf_size, and pos, when reading and when writing
  166. * (since AVIOContext is used for both):
  167. *
  168. **********************************************************************************
  169. * READING
  170. **********************************************************************************
  171. *
  172. * | buffer_size |
  173. * |---------------------------------------|
  174. * | |
  175. *
  176. * buffer buf_ptr buf_end
  177. * +---------------+-----------------------+
  178. * |/ / / / / / / /|/ / / / / / /| |
  179. * read buffer: |/ / consumed / | to be read /| |
  180. * |/ / / / / / / /|/ / / / / / /| |
  181. * +---------------+-----------------------+
  182. *
  183. * pos
  184. * +-------------------------------------------+-----------------+
  185. * input file: | | |
  186. * +-------------------------------------------+-----------------+
  187. *
  188. *
  189. **********************************************************************************
  190. * WRITING
  191. **********************************************************************************
  192. *
  193. * | buffer_size |
  194. * |--------------------------------------|
  195. * | |
  196. *
  197. * buf_ptr_max
  198. * buffer (buf_ptr) buf_end
  199. * +-----------------------+--------------+
  200. * |/ / / / / / / / / / / /| |
  201. * write buffer: | / / to be flushed / / | |
  202. * |/ / / / / / / / / / / /| |
  203. * +-----------------------+--------------+
  204. * buf_ptr can be in this
  205. * due to a backward seek
  206. *
  207. * pos
  208. * +-------------+----------------------------------------------+
  209. * output file: | | |
  210. * +-------------+----------------------------------------------+
  211. *
  212. */
  213. unsigned char *buffer; /**< Start of the buffer. */
  214. int buffer_size; /**< Maximum buffer size */
  215. unsigned char *buf_ptr; /**< Current position in the buffer */
  216. unsigned char *buf_end; /**< End of the data, may be less than
  217. buffer+buffer_size if the read function returned
  218. less data than requested, e.g. for streams where
  219. no more data has been received yet. */
  220. void *opaque; /**< A private pointer, passed to the read/write/seek/...
  221. functions. */
  222. int (*read_packet)(void *opaque, uint8_t *buf, int buf_size);
  223. int (*write_packet)(void *opaque, uint8_t *buf, int buf_size);
  224. int64_t (*seek)(void *opaque, int64_t offset, int whence);
  225. int64_t pos; /**< position in the file of the current buffer */
  226. int eof_reached; /**< true if was unable to read due to error or eof */
  227. int write_flag; /**< true if open for writing */
  228. int max_packet_size;
  229. unsigned long checksum;
  230. unsigned char *checksum_ptr;
  231. unsigned long (*update_checksum)(unsigned long checksum, const uint8_t *buf, unsigned int size);
  232. int error; /**< contains the error code or 0 if no error happened */
  233. /**
  234. * Pause or resume playback for network streaming protocols - e.g. MMS.
  235. */
  236. int (*read_pause)(void *opaque, int pause);
  237. /**
  238. * Seek to a given timestamp in stream with the specified stream_index.
  239. * Needed for some network streaming protocols which don't support seeking
  240. * to byte position.
  241. */
  242. int64_t (*read_seek)(void *opaque, int stream_index,
  243. int64_t timestamp, int flags);
  244. /**
  245. * A combination of AVIO_SEEKABLE_ flags or 0 when the stream is not seekable.
  246. */
  247. int seekable;
  248. /**
  249. * max filesize, used to limit allocations
  250. * This field is internal to libavformat and access from outside is not allowed.
  251. */
  252. int64_t maxsize;
  253. /**
  254. * avio_read and avio_write should if possible be satisfied directly
  255. * instead of going through a buffer, and avio_seek will always
  256. * call the underlying seek function directly.
  257. */
  258. int direct;
  259. /**
  260. * Bytes read statistic
  261. * This field is internal to libavformat and access from outside is not allowed.
  262. */
  263. int64_t bytes_read;
  264. /**
  265. * seek statistic
  266. * This field is internal to libavformat and access from outside is not allowed.
  267. */
  268. int seek_count;
  269. /**
  270. * writeout statistic
  271. * This field is internal to libavformat and access from outside is not allowed.
  272. */
  273. int writeout_count;
  274. /**
  275. * Original buffer size
  276. * used internally after probing and ensure seekback to reset the buffer size
  277. * This field is internal to libavformat and access from outside is not allowed.
  278. */
  279. int orig_buffer_size;
  280. /**
  281. * Threshold to favor readahead over seek.
  282. * This is current internal only, do not use from outside.
  283. */
  284. int short_seek_threshold;
  285. /**
  286. * ',' separated list of allowed protocols.
  287. */
  288. const char *protocol_whitelist;
  289. /**
  290. * ',' separated list of disallowed protocols.
  291. */
  292. const char *protocol_blacklist;
  293. /**
  294. * A callback that is used instead of write_packet.
  295. */
  296. int (*write_data_type)(void *opaque, uint8_t *buf, int buf_size,
  297. enum AVIODataMarkerType type, int64_t time);
  298. /**
  299. * If set, don't call write_data_type separately for AVIO_DATA_MARKER_BOUNDARY_POINT,
  300. * but ignore them and treat them as AVIO_DATA_MARKER_UNKNOWN (to avoid needlessly
  301. * small chunks of data returned from the callback).
  302. */
  303. int ignore_boundary_point;
  304. /**
  305. * Internal, not meant to be used from outside of AVIOContext.
  306. */
  307. enum AVIODataMarkerType current_type;
  308. int64_t last_time;
  309. /**
  310. * A callback that is used instead of short_seek_threshold.
  311. * This is current internal only, do not use from outside.
  312. */
  313. int (*short_seek_get)(void *opaque);
  314. int64_t written;
  315. /**
  316. * Maximum reached position before a backward seek in the write buffer,
  317. * used keeping track of already written data for a later flush.
  318. */
  319. unsigned char *buf_ptr_max;
  320. /**
  321. * Try to buffer at least this amount of data before flushing it
  322. */
  323. int min_packet_size;
  324. } AVIOContext;
  325. /**
  326. * Return the name of the protocol that will handle the passed URL.
  327. *
  328. * NULL is returned if no protocol could be found for the given URL.
  329. *
  330. * @return Name of the protocol or NULL.
  331. */
  332. const char *avio_find_protocol_name(const char *url);
  333. /**
  334. * Return AVIO_FLAG_* access flags corresponding to the access permissions
  335. * of the resource in url, or a negative value corresponding to an
  336. * AVERROR code in case of failure. The returned access flags are
  337. * masked by the value in flags.
  338. *
  339. * @note This function is intrinsically unsafe, in the sense that the
  340. * checked resource may change its existence or permission status from
  341. * one call to another. Thus you should not trust the returned value,
  342. * unless you are sure that no other processes are accessing the
  343. * checked resource.
  344. */
  345. int avio_check(const char *url, int flags);
  346. /**
  347. * Move or rename a resource.
  348. *
  349. * @note url_src and url_dst should share the same protocol and authority.
  350. *
  351. * @param url_src url to resource to be moved
  352. * @param url_dst new url to resource if the operation succeeded
  353. * @return >=0 on success or negative on error.
  354. */
  355. int avpriv_io_move(const char *url_src, const char *url_dst);
  356. /**
  357. * Delete a resource.
  358. *
  359. * @param url resource to be deleted.
  360. * @return >=0 on success or negative on error.
  361. */
  362. int avpriv_io_delete(const char *url);
  363. /**
  364. * Open directory for reading.
  365. *
  366. * @param s directory read context. Pointer to a NULL pointer must be passed.
  367. * @param url directory to be listed.
  368. * @param options A dictionary filled with protocol-private options. On return
  369. * this parameter will be destroyed and replaced with a dictionary
  370. * containing options that were not found. May be NULL.
  371. * @return >=0 on success or negative on error.
  372. */
  373. int avio_open_dir(AVIODirContext **s, const char *url, AVDictionary **options);
  374. /**
  375. * Get next directory entry.
  376. *
  377. * Returned entry must be freed with avio_free_directory_entry(). In particular
  378. * it may outlive AVIODirContext.
  379. *
  380. * @param s directory read context.
  381. * @param[out] next next entry or NULL when no more entries.
  382. * @return >=0 on success or negative on error. End of list is not considered an
  383. * error.
  384. */
  385. int avio_read_dir(AVIODirContext *s, AVIODirEntry **next);
  386. /**
  387. * Close directory.
  388. *
  389. * @note Entries created using avio_read_dir() are not deleted and must be
  390. * freeded with avio_free_directory_entry().
  391. *
  392. * @param s directory read context.
  393. * @return >=0 on success or negative on error.
  394. */
  395. int avio_close_dir(AVIODirContext **s);
  396. /**
  397. * Free entry allocated by avio_read_dir().
  398. *
  399. * @param entry entry to be freed.
  400. */
  401. void avio_free_directory_entry(AVIODirEntry **entry);
  402. /**
  403. * Allocate and initialize an AVIOContext for buffered I/O. It must be later
  404. * freed with avio_context_free().
  405. *
  406. * @param buffer Memory block for input/output operations via AVIOContext.
  407. * The buffer must be allocated with av_malloc() and friends.
  408. * It may be freed and replaced with a new buffer by libavformat.
  409. * AVIOContext.buffer holds the buffer currently in use,
  410. * which must be later freed with av_free().
  411. * @param buffer_size The buffer size is very important for performance.
  412. * For protocols with fixed blocksize it should be set to this blocksize.
  413. * For others a typical size is a cache page, e.g. 4kb.
  414. * @param write_flag Set to 1 if the buffer should be writable, 0 otherwise.
  415. * @param opaque An opaque pointer to user-specific data.
  416. * @param read_packet A function for refilling the buffer, may be NULL.
  417. * For stream protocols, must never return 0 but rather
  418. * a proper AVERROR code.
  419. * @param write_packet A function for writing the buffer contents, may be NULL.
  420. * The function may not change the input buffers content.
  421. * @param seek A function for seeking to specified byte position, may be NULL.
  422. *
  423. * @return Allocated AVIOContext or NULL on failure.
  424. */
  425. AVIOContext *avio_alloc_context(
  426. unsigned char *buffer,
  427. int buffer_size,
  428. int write_flag,
  429. void *opaque,
  430. int (*read_packet)(void *opaque, uint8_t *buf, int buf_size),
  431. int (*write_packet)(void *opaque, uint8_t *buf, int buf_size),
  432. int64_t (*seek)(void *opaque, int64_t offset, int whence));
  433. /**
  434. * Free the supplied IO context and everything associated with it.
  435. *
  436. * @param s Double pointer to the IO context. This function will write NULL
  437. * into s.
  438. */
  439. void avio_context_free(AVIOContext **s);
  440. void avio_w8(AVIOContext *s, int b);
  441. void avio_write(AVIOContext *s, const unsigned char *buf, int size);
  442. void avio_wl64(AVIOContext *s, uint64_t val);
  443. void avio_wb64(AVIOContext *s, uint64_t val);
  444. void avio_wl32(AVIOContext *s, unsigned int val);
  445. void avio_wb32(AVIOContext *s, unsigned int val);
  446. void avio_wl24(AVIOContext *s, unsigned int val);
  447. void avio_wb24(AVIOContext *s, unsigned int val);
  448. void avio_wl16(AVIOContext *s, unsigned int val);
  449. void avio_wb16(AVIOContext *s, unsigned int val);
  450. /**
  451. * Write a NULL-terminated string.
  452. * @return number of bytes written.
  453. */
  454. int avio_put_str(AVIOContext *s, const char *str);
  455. /**
  456. * Convert an UTF-8 string to UTF-16LE and write it.
  457. * @param s the AVIOContext
  458. * @param str NULL-terminated UTF-8 string
  459. *
  460. * @return number of bytes written.
  461. */
  462. int avio_put_str16le(AVIOContext *s, const char *str);
  463. /**
  464. * Convert an UTF-8 string to UTF-16BE and write it.
  465. * @param s the AVIOContext
  466. * @param str NULL-terminated UTF-8 string
  467. *
  468. * @return number of bytes written.
  469. */
  470. int avio_put_str16be(AVIOContext *s, const char *str);
  471. /**
  472. * Mark the written bytestream as a specific type.
  473. *
  474. * Zero-length ranges are omitted from the output.
  475. *
  476. * @param time the stream time the current bytestream pos corresponds to
  477. * (in AV_TIME_BASE units), or AV_NOPTS_VALUE if unknown or not
  478. * applicable
  479. * @param type the kind of data written starting at the current pos
  480. */
  481. void avio_write_marker(AVIOContext *s, int64_t time, enum AVIODataMarkerType type);
  482. /**
  483. * ORing this as the "whence" parameter to a seek function causes it to
  484. * return the filesize without seeking anywhere. Supporting this is optional.
  485. * If it is not supported then the seek function will return <0.
  486. */
  487. #define AVSEEK_SIZE 0x10000
  488. /**
  489. * Passing this flag as the "whence" parameter to a seek function causes it to
  490. * seek by any means (like reopening and linear reading) or other normally unreasonable
  491. * means that can be extremely slow.
  492. * This may be ignored by the seek code.
  493. */
  494. #define AVSEEK_FORCE 0x20000
  495. /**
  496. * fseek() equivalent for AVIOContext.
  497. * @return new position or AVERROR.
  498. */
  499. int64_t avio_seek(AVIOContext *s, int64_t offset, int whence);
  500. /**
  501. * Skip given number of bytes forward
  502. * @return new position or AVERROR.
  503. */
  504. int64_t avio_skip(AVIOContext *s, int64_t offset);
  505. /**
  506. * ftell() equivalent for AVIOContext.
  507. * @return position or AVERROR.
  508. */
  509. static av_always_inline int64_t avio_tell(AVIOContext *s)
  510. {
  511. return avio_seek(s, 0, SEEK_CUR);
  512. }
  513. /**
  514. * Get the filesize.
  515. * @return filesize or AVERROR
  516. */
  517. int64_t avio_size(AVIOContext *s);
  518. /**
  519. * Similar to feof() but also returns nonzero on read errors.
  520. * @return non zero if and only if at end of file or a read error happened when reading.
  521. */
  522. int avio_feof(AVIOContext *s);
  523. /** @warning Writes up to 4 KiB per call */
  524. int avio_printf(AVIOContext *s, const char *fmt, ...) av_printf_format(2, 3);
  525. /**
  526. * Force flushing of buffered data.
  527. *
  528. * For write streams, force the buffered data to be immediately written to the output,
  529. * without to wait to fill the internal buffer.
  530. *
  531. * For read streams, discard all currently buffered data, and advance the
  532. * reported file position to that of the underlying stream. This does not
  533. * read new data, and does not perform any seeks.
  534. */
  535. void avio_flush(AVIOContext *s);
  536. /**
  537. * Read size bytes from AVIOContext into buf.
  538. * @return number of bytes read or AVERROR
  539. */
  540. int avio_read(AVIOContext *s, unsigned char *buf, int size);
  541. /**
  542. * Read size bytes from AVIOContext into buf. Unlike avio_read(), this is allowed
  543. * to read fewer bytes than requested. The missing bytes can be read in the next
  544. * call. This always tries to read at least 1 byte.
  545. * Useful to reduce latency in certain cases.
  546. * @return number of bytes read or AVERROR
  547. */
  548. int avio_read_partial(AVIOContext *s, unsigned char *buf, int size);
  549. /**
  550. * @name Functions for reading from AVIOContext
  551. * @{
  552. *
  553. * @note return 0 if EOF, so you cannot use it if EOF handling is
  554. * necessary
  555. */
  556. int avio_r8 (AVIOContext *s);
  557. unsigned int avio_rl16(AVIOContext *s);
  558. unsigned int avio_rl24(AVIOContext *s);
  559. unsigned int avio_rl32(AVIOContext *s);
  560. uint64_t avio_rl64(AVIOContext *s);
  561. unsigned int avio_rb16(AVIOContext *s);
  562. unsigned int avio_rb24(AVIOContext *s);
  563. unsigned int avio_rb32(AVIOContext *s);
  564. uint64_t avio_rb64(AVIOContext *s);
  565. /**
  566. * @}
  567. */
  568. /**
  569. * Read a string from pb into buf. The reading will terminate when either
  570. * a NULL character was encountered, maxlen bytes have been read, or nothing
  571. * more can be read from pb. The result is guaranteed to be NULL-terminated, it
  572. * will be truncated if buf is too small.
  573. * Note that the string is not interpreted or validated in any way, it
  574. * might get truncated in the middle of a sequence for multi-byte encodings.
  575. *
  576. * @return number of bytes read (is always <= maxlen).
  577. * If reading ends on EOF or error, the return value will be one more than
  578. * bytes actually read.
  579. */
  580. int avio_get_str(AVIOContext *pb, int maxlen, char *buf, int buflen);
  581. /**
  582. * Read a UTF-16 string from pb and convert it to UTF-8.
  583. * The reading will terminate when either a null or invalid character was
  584. * encountered or maxlen bytes have been read.
  585. * @return number of bytes read (is always <= maxlen)
  586. */
  587. int avio_get_str16le(AVIOContext *pb, int maxlen, char *buf, int buflen);
  588. int avio_get_str16be(AVIOContext *pb, int maxlen, char *buf, int buflen);
  589. /**
  590. * @name URL open modes
  591. * The flags argument to avio_open must be one of the following
  592. * constants, optionally ORed with other flags.
  593. * @{
  594. */
  595. #define AVIO_FLAG_READ 1 /**< read-only */
  596. #define AVIO_FLAG_WRITE 2 /**< write-only */
  597. #define AVIO_FLAG_READ_WRITE (AVIO_FLAG_READ|AVIO_FLAG_WRITE) /**< read-write pseudo flag */
  598. /**
  599. * @}
  600. */
  601. /**
  602. * Use non-blocking mode.
  603. * If this flag is set, operations on the context will return
  604. * AVERROR(EAGAIN) if they can not be performed immediately.
  605. * If this flag is not set, operations on the context will never return
  606. * AVERROR(EAGAIN).
  607. * Note that this flag does not affect the opening/connecting of the
  608. * context. Connecting a protocol will always block if necessary (e.g. on
  609. * network protocols) but never hang (e.g. on busy devices).
  610. * Warning: non-blocking protocols is work-in-progress; this flag may be
  611. * silently ignored.
  612. */
  613. #define AVIO_FLAG_NONBLOCK 8
  614. /**
  615. * Use direct mode.
  616. * avio_read and avio_write should if possible be satisfied directly
  617. * instead of going through a buffer, and avio_seek will always
  618. * call the underlying seek function directly.
  619. */
  620. #define AVIO_FLAG_DIRECT 0x8000
  621. /**
  622. * Create and initialize a AVIOContext for accessing the
  623. * resource indicated by url.
  624. * @note When the resource indicated by url has been opened in
  625. * read+write mode, the AVIOContext can be used only for writing.
  626. *
  627. * @param s Used to return the pointer to the created AVIOContext.
  628. * In case of failure the pointed to value is set to NULL.
  629. * @param url resource to access
  630. * @param flags flags which control how the resource indicated by url
  631. * is to be opened
  632. * @return >= 0 in case of success, a negative value corresponding to an
  633. * AVERROR code in case of failure
  634. */
  635. int avio_open(AVIOContext **s, const char *url, int flags);
  636. /**
  637. * Create and initialize a AVIOContext for accessing the
  638. * resource indicated by url.
  639. * @note When the resource indicated by url has been opened in
  640. * read+write mode, the AVIOContext can be used only for writing.
  641. *
  642. * @param s Used to return the pointer to the created AVIOContext.
  643. * In case of failure the pointed to value is set to NULL.
  644. * @param url resource to access
  645. * @param flags flags which control how the resource indicated by url
  646. * is to be opened
  647. * @param int_cb an interrupt callback to be used at the protocols level
  648. * @param options A dictionary filled with protocol-private options. On return
  649. * this parameter will be destroyed and replaced with a dict containing options
  650. * that were not found. May be NULL.
  651. * @return >= 0 in case of success, a negative value corresponding to an
  652. * AVERROR code in case of failure
  653. */
  654. int avio_open2(AVIOContext **s, const char *url, int flags,
  655. const AVIOInterruptCB *int_cb, AVDictionary **options);
  656. /**
  657. * Close the resource accessed by the AVIOContext s and free it.
  658. * This function can only be used if s was opened by avio_open().
  659. *
  660. * The internal buffer is automatically flushed before closing the
  661. * resource.
  662. *
  663. * @return 0 on success, an AVERROR < 0 on error.
  664. * @see avio_closep
  665. */
  666. int avio_close(AVIOContext *s);
  667. /**
  668. * Close the resource accessed by the AVIOContext *s, free it
  669. * and set the pointer pointing to it to NULL.
  670. * This function can only be used if s was opened by avio_open().
  671. *
  672. * The internal buffer is automatically flushed before closing the
  673. * resource.
  674. *
  675. * @return 0 on success, an AVERROR < 0 on error.
  676. * @see avio_close
  677. */
  678. int avio_closep(AVIOContext **s);
  679. /**
  680. * Open a write only memory stream.
  681. *
  682. * @param s new IO context
  683. * @return zero if no error.
  684. */
  685. int avio_open_dyn_buf(AVIOContext **s);
  686. /**
  687. * Return the written size and a pointer to the buffer.
  688. * The AVIOContext stream is left intact.
  689. * The buffer must NOT be freed.
  690. * No padding is added to the buffer.
  691. *
  692. * @param s IO context
  693. * @param pbuffer pointer to a byte buffer
  694. * @return the length of the byte buffer
  695. */
  696. int avio_get_dyn_buf(AVIOContext *s, uint8_t **pbuffer);
  697. /**
  698. * Return the written size and a pointer to the buffer. The buffer
  699. * must be freed with av_free().
  700. * Padding of AV_INPUT_BUFFER_PADDING_SIZE is added to the buffer.
  701. *
  702. * @param s IO context
  703. * @param pbuffer pointer to a byte buffer
  704. * @return the length of the byte buffer
  705. */
  706. int avio_close_dyn_buf(AVIOContext *s, uint8_t **pbuffer);
  707. /**
  708. * Iterate through names of available protocols.
  709. *
  710. * @param opaque A private pointer representing current protocol.
  711. * It must be a pointer to NULL on first iteration and will
  712. * be updated by successive calls to avio_enum_protocols.
  713. * @param output If set to 1, iterate over output protocols,
  714. * otherwise over input protocols.
  715. *
  716. * @return A static string containing the name of current protocol or NULL
  717. */
  718. const char *avio_enum_protocols(void **opaque, int output);
  719. /**
  720. * Pause and resume playing - only meaningful if using a network streaming
  721. * protocol (e.g. MMS).
  722. *
  723. * @param h IO context from which to call the read_pause function pointer
  724. * @param pause 1 for pause, 0 for resume
  725. */
  726. int avio_pause(AVIOContext *h, int pause);
  727. /**
  728. * Seek to a given timestamp relative to some component stream.
  729. * Only meaningful if using a network streaming protocol (e.g. MMS.).
  730. *
  731. * @param h IO context from which to call the seek function pointers
  732. * @param stream_index The stream index that the timestamp is relative to.
  733. * If stream_index is (-1) the timestamp should be in AV_TIME_BASE
  734. * units from the beginning of the presentation.
  735. * If a stream_index >= 0 is used and the protocol does not support
  736. * seeking based on component streams, the call will fail.
  737. * @param timestamp timestamp in AVStream.time_base units
  738. * or if there is no stream specified then in AV_TIME_BASE units.
  739. * @param flags Optional combination of AVSEEK_FLAG_BACKWARD, AVSEEK_FLAG_BYTE
  740. * and AVSEEK_FLAG_ANY. The protocol may silently ignore
  741. * AVSEEK_FLAG_BACKWARD and AVSEEK_FLAG_ANY, but AVSEEK_FLAG_BYTE will
  742. * fail if used and not supported.
  743. * @return >= 0 on success
  744. * @see AVInputFormat::read_seek
  745. */
  746. int64_t avio_seek_time(AVIOContext *h, int stream_index,
  747. int64_t timestamp, int flags);
  748. /* Avoid a warning. The header can not be included because it breaks c++. */
  749. struct AVBPrint;
  750. /**
  751. * Read contents of h into print buffer, up to max_size bytes, or up to EOF.
  752. *
  753. * @return 0 for success (max_size bytes read or EOF reached), negative error
  754. * code otherwise
  755. */
  756. int avio_read_to_bprint(AVIOContext *h, struct AVBPrint *pb, size_t max_size);
  757. /**
  758. * Accept and allocate a client context on a server context.
  759. * @param s the server context
  760. * @param c the client context, must be unallocated
  761. * @return >= 0 on success or a negative value corresponding
  762. * to an AVERROR on failure
  763. */
  764. int avio_accept(AVIOContext *s, AVIOContext **c);
  765. /**
  766. * Perform one step of the protocol handshake to accept a new client.
  767. * This function must be called on a client returned by avio_accept() before
  768. * using it as a read/write context.
  769. * It is separate from avio_accept() because it may block.
  770. * A step of the handshake is defined by places where the application may
  771. * decide to change the proceedings.
  772. * For example, on a protocol with a request header and a reply header, each
  773. * one can constitute a step because the application may use the parameters
  774. * from the request to change parameters in the reply; or each individual
  775. * chunk of the request can constitute a step.
  776. * If the handshake is already finished, avio_handshake() does nothing and
  777. * returns 0 immediately.
  778. *
  779. * @param c the client context to perform the handshake on
  780. * @return 0 on a complete and successful handshake
  781. * > 0 if the handshake progressed, but is not complete
  782. * < 0 for an AVERROR code
  783. */
  784. int avio_handshake(AVIOContext *c);
  785. #endif /* AVFORMAT_AVIO_H */