containers/containers.h

   1 /*
   2 Copyright (c) 2012, Broadcom Europe Ltd
   3 All rights reserved.
   4
   5 Redistribution and use in source and binary forms, with or without
   6 modification, are permitted provided that the following conditions are met:
   7     * Redistributions of source code must retain the above copyright
   8       notice, this list of conditions and the following disclaimer.
   9     * Redistributions in binary form must reproduce the above copyright
  10       notice, this list of conditions and the following disclaimer in the
  11       documentation and/or other materials provided with the distribution.
  12     * Neither the name of the copyright holder nor the
  13       names of its contributors may be used to endorse or promote products
  14       derived from this software without specific prior written permission.
  15
  16 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  17 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
  20 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  25 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 */
  27 #ifndef VC_CONTAINERS_H
  28 #define VC_CONTAINERS_H
  29
  30 /** \file containers.h
  31  * Public API for container readers and writers
  32  */
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 #include "containers/containers_types.h"
  39
  40 /** \defgroup VcContainerApi Container API
  41  *  API for container readers and writers */
  42 /* @{ */
  43
  44 /** Status codes returned by the container API */
  45 typedef enum
  46 {
  47    VC_CONTAINER_SUCCESS = 0,                        /**< No error */
  48    VC_CONTAINER_ERROR_FORMAT_NOT_SUPPORTED,         /**< Format of container is not supported */
  49    VC_CONTAINER_ERROR_FORMAT_FEATURE_NOT_SUPPORTED, /**< Format of container uses unsupported features */
  50    VC_CONTAINER_ERROR_FORMAT_INVALID,               /**< Format of container is invalid */
  51    VC_CONTAINER_ERROR_CORRUPTED,                    /**< Container is corrupted */
  52    VC_CONTAINER_ERROR_URI_NOT_FOUND,                /**< URI could not be found */
  53    VC_CONTAINER_ERROR_URI_OPEN_FAILED,              /**< URI could not be opened */
  54    VC_CONTAINER_ERROR_OUT_OF_MEMORY,                /**< Out of memory */
  55    VC_CONTAINER_ERROR_OUT_OF_SPACE,                 /**< Out of disk space (used when writing) */
  56    VC_CONTAINER_ERROR_OUT_OF_RESOURCES,             /**< Out of resources (other than memory) */
  57    VC_CONTAINER_ERROR_EOS,                          /**< End of stream reached */
  58    VC_CONTAINER_ERROR_LIMIT_REACHED,                /**< User defined limit reached (used when writing) */
  59    VC_CONTAINER_ERROR_BUFFER_TOO_SMALL,             /**< Given buffer is too small for data to be copied */
  60    VC_CONTAINER_ERROR_INCOMPLETE_DATA,              /**< Requested data is incomplete */
  61    VC_CONTAINER_ERROR_NO_TRACK_AVAILABLE,           /**< Container doesn't have any track */
  62    VC_CONTAINER_ERROR_TRACK_FORMAT_NOT_SUPPORTED,   /**< Format of the track is not supported */
  63    VC_CONTAINER_ERROR_UNSUPPORTED_OPERATION,        /**< The requested operation is not supported */
  64    VC_CONTAINER_ERROR_INVALID_ARGUMENT,             /**< The argument provided is invalid */
  65    VC_CONTAINER_ERROR_CONTINUE,                     /**< The requested operation was interrupted and needs to be tried again */
  66    VC_CONTAINER_ERROR_ABORTED,                      /**< The requested operation was aborted */
  67    VC_CONTAINER_ERROR_NOT_FOUND,                    /**< The requested data was not found */
  68    VC_CONTAINER_ERROR_DRM_NOT_AUTHORIZED,           /**< The DRM was not authorized */
  69    VC_CONTAINER_ERROR_DRM_EXPIRED,                  /**< The DRM has expired */
  70    VC_CONTAINER_ERROR_DRM_FAILED,                   /**< Generic DRM error */
  71    VC_CONTAINER_ERROR_FAILED,                       /**< Generic error */
  72    VC_CONTAINER_ERROR_NOT_READY                     /**< The container was not yet able to carry out the operation. */
  73 } VC_CONTAINER_STATUS_T;
  74
  75 /** Four Character Code type used to identify codecs, etc. */
  76 typedef uint32_t VC_CONTAINER_FOURCC_T;
  77
  78 /** Type definition for language codes.
  79  * Language are defined as ISO639 Alpha-3 codes (http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) */
  80 typedef uint8_t VC_CONTAINER_LANGUAGE_T[3];
  81
  82 /** Enumeration of the character encodings supported. */
  83 typedef enum {
  84    VC_CONTAINER_CHAR_ENCODING_UNKNOWN = 0, /**< Encoding is unknown */
  85    VC_CONTAINER_CHAR_ENCODING_UTF8         /**< UTF8 encoding */
  86 } VC_CONTAINER_CHAR_ENCODING_T;
  87
  88 /** \name Container Capabilities
  89  * The following flags are exported by containers to describe their capabilities */
  90 /* @{ */
  91 /** Type definition for container capabilities */
  92 typedef uint32_t VC_CONTAINER_CAPABILITIES_T;
  93 /** The container can seek */
  94 #define VC_CONTAINER_CAPS_CAN_SEEK               0x1
  95 /** Seeking is fast. The absence of this flag can be used as a hint to avoid seeking as much as possible */
  96 #define VC_CONTAINER_CAPS_SEEK_IS_FAST           0x2
  97 /** The container controls the pace at which it is reading the data */
  98 #define VC_CONTAINER_CAPS_CAN_CONTROL_PACE       0x4
  99 /** The container provides an index. This basically means that seeking will be precise and fast */
 100 #define VC_CONTAINER_CAPS_HAS_INDEX              0x8
 101 /** The container provides keyframe information */
 102 #define VC_CONTAINER_CAPS_DATA_HAS_KEYFRAME_FLAG 0x10
 103 /** The container supports adding tracks after TRACK_ADD_DONE control message has been sent */
 104 #define VC_CONTAINER_CAPS_DYNAMIC_TRACK_ADD      0x20
 105 /** The container supports forcing reading of a given track */
 106 #define VC_CONTAINER_CAPS_FORCE_TRACK            0x40
 107 /* @} */
 108
 109 /** \defgroup VcContainerMetadata Container Metadata
 110  * Container metadata contains descriptive information which is associated with the multimedia data */
 111 /* @{ */
 112
 113 /** Enumeration of the different metadata keys available. */
 114 typedef enum {
 115    /* Metadata of global scope */
 116    VC_CONTAINER_METADATA_KEY_TITLE       = VC_FOURCC('t','i','t','l'),
 117    VC_CONTAINER_METADATA_KEY_ARTIST      = VC_FOURCC('a','r','t','i'),
 118    VC_CONTAINER_METADATA_KEY_ALBUM       = VC_FOURCC('a','l','b','m'),
 119    VC_CONTAINER_METADATA_KEY_DESCRIPTION = VC_FOURCC('d','e','s','c'),
 120    VC_CONTAINER_METADATA_KEY_YEAR        = VC_FOURCC('y','e','a','r'),
 121    VC_CONTAINER_METADATA_KEY_GENRE       = VC_FOURCC('g','e','n','r'),
 122    VC_CONTAINER_METADATA_KEY_TRACK       = VC_FOURCC('t','r','a','k'),
 123    VC_CONTAINER_METADATA_KEY_LYRICS      = VC_FOURCC('l','y','r','x'),
 124
 125    VC_CONTAINER_METADATA_KEY_UNKNOWN     = 0
 126
 127 } VC_CONTAINER_METADATA_KEY_T;
 128
 129 /** Definition of the metadata type.
 130  * This type is used to store one element of metadata */
 131 typedef struct VC_CONTAINER_METADATA_T
 132 {
 133    /** Identifier for the type of metadata the value refers to.
 134     * Using an enum for the id will mean that a list of possible values will have to be
 135     * defined and maintained. This might limit extensibility and customisation.\n
 136     * Maybe it would be better to use a FOURCC or even a string here. */
 137    VC_CONTAINER_METADATA_KEY_T key;
 138
 139    VC_CONTAINER_LANGUAGE_T language; /**< Language code for the metadata */
 140    VC_CONTAINER_CHAR_ENCODING_T encoding; /**< Encoding of the metadata */
 141
 142    /** Metadata value. This value is defined as null-terminated UTF-8 string.\n
 143     * Do we want to support other types than strings (e.g. integer) ?\n
 144     * We need an encoding conversion library! */
 145    char *value;
 146
 147    /** Size of the memory area reserved for metadata value (including any
 148     * terminating characters). */
 149    unsigned int size;
 150 } VC_CONTAINER_METADATA_T;
 151 /* @} */
 152
 153 /** \defgroup VcContainerESFormat Container Elementary Stream Format
 154  * This describes the format of an elementary stream associated with a track */
 155 /* @{ */
 156
 157 /** Enumeration of the different types of elementary streams.
 158  * This divides elementary streams into 4 big categories. */
 159 typedef enum
 160 {
 161    VC_CONTAINER_ES_TYPE_UNKNOWN,     /**< Unknown elementary stream type */
 162    VC_CONTAINER_ES_TYPE_AUDIO,       /**< Audio elementary stream */
 163    VC_CONTAINER_ES_TYPE_VIDEO,       /**< Video elementary stream */
 164    VC_CONTAINER_ES_TYPE_SUBPICTURE   /**< Sub-picture elementary stream (e.g. subtitles, overlays) */
 165
 166 } VC_CONTAINER_ES_TYPE_T;
 167
 168 /** Definition of a video format.
 169  * This describes the properties specific to a video stream */
 170 typedef struct VC_CONTAINER_VIDEO_FORMAT_T
 171 {
 172    uint32_t width;           /**< Width of the frame */
 173    uint32_t height;          /**< Height of the frame */
 174    uint32_t visible_width;   /**< Width of the visible area of the frame */
 175    uint32_t visible_height;  /**< Height of the visible area of the frame */
 176    uint32_t x_offset;        /**< Offset to the start of the visible width */
 177    uint32_t y_offset;        /**< Offset to the start of the visible height */
 178    uint32_t frame_rate_num;  /**< Frame rate numerator */
 179    uint32_t frame_rate_den;  /**< Frame rate denominator */
 180    uint32_t par_num;         /**< Pixel aspect ratio numerator */
 181    uint32_t par_den;         /**< Pixel aspect ratio denominator */
 182 } VC_CONTAINER_VIDEO_FORMAT_T;
 183
 184 /** Enumeration for the different channel locations */
 185 typedef enum
 186 {
 187    VC_CONTAINER_AUDIO_CHANNEL_LEFT = 0,            /**< Left channel */
 188    VC_CONTAINER_AUDIO_CHANNEL_RIGHT,               /**< Right channel */
 189    VC_CONTAINER_AUDIO_CHANNEL_CENTER,              /**< Center channel */
 190    VC_CONTAINER_AUDIO_CHANNEL_LOW_FREQUENCY,       /**< Low frequency channel */
 191    VC_CONTAINER_AUDIO_CHANNEL_BACK_LEFT,           /**< Back left channel */
 192    VC_CONTAINER_AUDIO_CHANNEL_BACK_RIGHT,          /**< Back right channel */
 193    VC_CONTAINER_AUDIO_CHANNEL_BACK_CENTER,         /**< Back center channel */
 194    VC_CONTAINER_AUDIO_CHANNEL_SIDE_LEFT,           /**< Side left channel */
 195    VC_CONTAINER_AUDIO_CHANNEL_SIDE_RIGHT,          /**< Side right channel */
 196
 197    VC_CONTAINER_AUDIO_CHANNELS_MAX = 32            /**< Maximum number of channels supported */
 198
 199 } VC_CONTAINER_AUDIO_CHANNEL_T;
 200
 201 /** \name Audio format flags
 202  * \anchor audioformatflags
 203  * The following flags describe properties of an audio stream */
 204 /* @{ */
 205 #define VC_CONTAINER_AUDIO_FORMAT_FLAG_CHANNEL_MAPPING 0x1 /**< Channel mapping available */
 206 /* @} */
 207
 208 /** Definition of an audio format.
 209  * This describes the properties specific to an audio stream */
 210 typedef struct VC_CONTAINER_AUDIO_FORMAT_T
 211 {
 212    uint32_t channels;           /**< Number of audio channels */
 213    uint32_t sample_rate;        /**< Sample rate */
 214
 215    uint32_t bits_per_sample;    /**< Bits per sample */
 216    uint32_t block_align;        /**< Size of a block of data */
 217
 218    uint32_t flags;              /**< Flags describing the audio format.
 219                                  * See \ref audioformatflags "Audio format flags". */
 220
 221    /** Mapping of the channels in order of appearance */
 222    VC_CONTAINER_AUDIO_CHANNEL_T channel_mapping[VC_CONTAINER_AUDIO_CHANNELS_MAX];
 223
 224    uint16_t gap_delay;   /**< Delay introduced by the encoder. Used for gapless playback */
 225    uint16_t gap_padding; /**< Padding introduced by the encoder. Used for gapless playback */
 226
 227    /** Replay gain information. First element is the track information and the second
 228     * is the album information. */
 229    struct {
 230       float peak; /**< Peak value (full range is 1.0) */
 231       float gain; /**< Gain value in dB */
 232    } replay_gain[2];
 233
 234 } VC_CONTAINER_AUDIO_FORMAT_T;
 235
 236 /** Definition of a subpicture format.
 237  * This describes the properties specific to a subpicture stream */
 238 typedef struct VC_CONTAINER_SUBPICTURE_FORMAT_T
 239 {
 240    VC_CONTAINER_CHAR_ENCODING_T encoding; /**< Encoding for text based subpicture formats */
 241    uint32_t x_offset;        /**< Width offset to the start of the subpicture */
 242    uint32_t y_offset;        /**< Height offset to the start of the subpicture */
 243 } VC_CONTAINER_SUBPICTURE_FORMAT_T;
 244
 245 /** \name Elementary stream format flags
 246  * \anchor esformatflags
 247  * The following flags describe properties of an elementary stream */
 248 /* @{ */
 249 #define VC_CONTAINER_ES_FORMAT_FLAG_FRAMED 0x1 /**< Elementary stream is framed */
 250 /* @} */
 251
 252 /** Definition of the type specific format.
 253  * This describes the type specific information of the elementary stream. */
 254 typedef union
 255 {
 256    VC_CONTAINER_AUDIO_FORMAT_T      audio;      /**< Audio specific information */
 257    VC_CONTAINER_VIDEO_FORMAT_T      video;      /**< Video specific information */
 258    VC_CONTAINER_SUBPICTURE_FORMAT_T subpicture; /**< Subpicture specific information */
 259 } VC_CONTAINER_ES_SPECIFIC_FORMAT_T;
 260
 261 /** Definition of an elementary stream format */
 262 typedef struct VC_CONTAINER_ES_FORMAT_T
 263 {
 264    VC_CONTAINER_ES_TYPE_T es_type;    /**< Type of the elementary stream */
 265    VC_CONTAINER_FOURCC_T  codec;      /**< Coding of the elementary stream */
 266    VC_CONTAINER_FOURCC_T  codec_variant;  /**< If set, indicates a variant of the coding */
 267
 268    VC_CONTAINER_ES_SPECIFIC_FORMAT_T *type; /**< Type specific information for the elementary stream */
 269
 270    uint32_t bitrate;         /**< Bitrate */
 271
 272    VC_CONTAINER_LANGUAGE_T language; /**< Language code for the elementary stream */
 273    uint32_t group_id;                /**< ID of the group this elementary stream belongs to */
 274
 275    uint32_t flags;         /**< Flags describing the properties of an elementary stream.
 276                             * See \ref esformatflags "Elementary stream format flags". */
 277
 278    unsigned int extradata_size; /**< Size of the codec specific data */
 279    uint8_t *extradata;     /**< Codec specific data */
 280
 281 } VC_CONTAINER_ES_FORMAT_T;
 282 /* @} */
 283
 284 /** \defgroup VcContainerPacket Container Packet
 285  * A container packet is the unit of data that is being read from or written to a container */
 286 /* @{ */
 287
 288 /** Structure describing a data packet */
 289 typedef struct VC_CONTAINER_PACKET_T
 290 {
 291    struct VC_CONTAINER_PACKET_T *next; /**< Used to build lists of packets */
 292    uint8_t *data;              /**< Pointer to the buffer containing the actual data for the packet */
 293    unsigned int buffer_size;   /**< Size of the p_data buffer. This is used to indicate how much data can be read in p_data */
 294    unsigned int size;          /**< Size of the data contained in p_data */
 295    unsigned int frame_size;    /**< If set, indicates the size of the frame this packet belongs to */
 296    int64_t pts;                /**< Presentation Timestamp of the packet */
 297    int64_t dts;                /**< Decoding Timestamp of the packet */
 298    uint64_t num;               /**< Number of this packet */
 299    uint32_t track;             /**< Track associated with this packet */
 300    uint32_t flags;             /**< Flags associated with this packet */
 301
 302    void *user_data;            /**< Field reserved for use by the client */
 303    void *framework_data;       /**< Field reserved for use by the framework */
 304
 305 } VC_CONTAINER_PACKET_T;
 306
 307 /** \name Container Packet Flags
 308  * The following flags describe properties of the data packet */
 309 /* @{ */
 310 #define VC_CONTAINER_PACKET_FLAG_KEYFRAME       0x01   /**< Packet is a keyframe */
 311 #define VC_CONTAINER_PACKET_FLAG_FRAME_START    0x02   /**< Packet starts a frame */
 312 #define VC_CONTAINER_PACKET_FLAG_FRAME_END      0x04   /**< Packet ends a frame */
 313 #define VC_CONTAINER_PACKET_FLAG_FRAME          0x06   /**< Packet contains only complete frames */
 314 #define VC_CONTAINER_PACKET_FLAG_DISCONTINUITY  0x08   /**< Packet comes after a discontinuity in the stream. Decoders might have to be flushed */
 315 #define VC_CONTAINER_PACKET_FLAG_ENCRYPTED      0x10   /**< Packet contains DRM encrypted data */
 316 #define VC_CONTAINER_PACKET_FLAG_CONFIG         0x20   /**< Packet contains stream specific config data */
 317 /* @} */
 318
 319 /** \name Special Unknown Time Value
 320  * This is the special value used to signal that a timestamp is not known */
 321 /* @{ */
 322 #define VC_CONTAINER_TIME_UNKNOWN (INT64_C(1)<<63)     /**< Special value for signalling that time is not known */
 323 /* @} */
 324
 325 /* @} */
 326
 327 /** \name Track flags
 328  * \anchor trackflags
 329  * The following flags describe properties of a track */
 330 /* @{ */
 331 #define VC_CONTAINER_TRACK_FLAG_CHANGED 0x1 /**< Track definition has changed */
 332 /* @} */
 333
 334 /** Definition of the track type */
 335 typedef struct VC_CONTAINER_TRACK_T
 336 {
 337    struct VC_CONTAINER_TRACK_PRIVATE_T *priv; /**< Private member used by the implementation */
 338    uint32_t is_enabled;               /**< Flag to specify if the track is enabled */
 339    uint32_t flags;                    /**< Flags describing the properties of a track.
 340                                        * See \ref trackflags "Track flags". */
 341
 342    VC_CONTAINER_ES_FORMAT_T *format;  /**< Format of the elementary stream contained in the track */
 343
 344    unsigned int meta_num;             /**< Number of metadata elements associated with the track */
 345    VC_CONTAINER_METADATA_T **meta;    /**< Array of metadata elements associated with the track */
 346
 347 } VC_CONTAINER_TRACK_T;
 348
 349 /** Definition of the DRM type */
 350 typedef struct VC_CONTAINER_DRM_T
 351 {
 352    VC_CONTAINER_FOURCC_T format;    /**< Four character code describing the format of the DRM in use */
 353    unsigned int views_max;          /**< Maximum number of views allowed */
 354    unsigned int views_current;      /**< Current number of views */
 355
 356 } VC_CONTAINER_DRM_T;
 357
 358 /** Type definition for the progress reporting function. This function will be called regularly
 359  * by the container during a call which blocks for too long and will report the progress of the
 360  * operation as an estimated total length in microseconds and a percentage done.
 361  * Returning anything else than VC_CONTAINER_SUCCESS in this function will abort the current
 362  * operation. */
 363 typedef VC_CONTAINER_STATUS_T (*VC_CONTAINER_PROGRESS_REPORT_FUNC_T)(void *userdata,
 364    int64_t length, unsigned int percentage_done);
 365
 366 /** \name Container Events
 367  * The following flags are exported by containers to notify the application of events */
 368 /* @{ */
 369 /** Type definition for container events */
 370 typedef uint32_t VC_CONTAINER_EVENTS_T;
 371 #define VC_CONTAINER_EVENT_TRACKS_CHANGE   1    /**< Track information has changed */
 372 #define VC_CONTAINER_EVENT_METADATA_CHANGE 2    /**< Metadata has changed */
 373 /* @} */
 374
 375 /** Definition of the container context */
 376 typedef struct VC_CONTAINER_T
 377 {
 378    struct VC_CONTAINER_PRIVATE_T *priv; /**< Private member used by the implementation */
 379
 380    VC_CONTAINER_EVENTS_T events; /**< Events generated by the container */
 381    VC_CONTAINER_CAPABILITIES_T capabilities; /**< Capabilities exported by the container */
 382
 383    VC_CONTAINER_PROGRESS_REPORT_FUNC_T pf_progress; /**< Progress report function pointer */
 384    void *progress_userdata;                          /**< Progress report user data */
 385
 386    int64_t duration;                  /**< Duration of the media in microseconds */
 387    int64_t position;                  /**< Current time position into the media */
 388    int64_t size;                      /**< Size of the media in bytes */
 389
 390    unsigned int tracks_num;           /**< Number of tracks available */
 391    /** Pointer to an array of pointers to track elements.
 392     * The reasoning for using a pointer to pointers here is to allow us to extend
 393     * VC_CONTAINER_TRACK_T without losing binary backward compatibility. */
 394    VC_CONTAINER_TRACK_T **tracks;
 395
 396    unsigned int meta_num;             /**< Number of metadata elements associated with the container */
 397    VC_CONTAINER_METADATA_T **meta;    /**< Array of metadata elements associated with the container */
 398
 399    VC_CONTAINER_DRM_T *drm;           /**< Description used for DRM protected content */
 400
 401 } VC_CONTAINER_T;
 402
 403 /** Forward declaration of a container input / output context.
 404  * This structure defines the context for a container io instance */
 405 typedef struct VC_CONTAINER_IO_T VC_CONTAINER_IO_T;
 406
 407 /** Opens the media container pointed to by the URI for reading.
 408  * This will create an an instance of a container reader and its associated context.
 409  * The context returned will also be filled with the information retrieved from the media.
 410  *
 411  * If the media isn't accessible or recognized, this will return a null pointer as well as
 412  * an error code indicating why this failed.
 413  *
 414  * \param  psz_uri      Unified Resource Identifier pointing to the media container
 415  * \param  status       Returns the status of the operation
 416  * \param  pf_progress  User provided function pointer to a progress report function. Can be set to
 417  *                      null if no progress report is wanted. This function will be used during
 418  *                      the whole lifetime of the instance (i.e. it will be used during
 419  *                      open / seek / close)
 420  * \param  progress_userdata User provided pointer that will be passed during the progress report
 421  *                      function call.
 422  * \return              A pointer to the context of the new instance of the
 423  *                      container reader. Returns NULL on failure.
 424  */
 425 VC_CONTAINER_T *vc_container_open_reader( const char *psz_uri, VC_CONTAINER_STATUS_T *status,
 426    VC_CONTAINER_PROGRESS_REPORT_FUNC_T pf_progress, void *progress_userdata);
 427
 428 /** Opens for reading the media container pointed to by the container i/o.
 429  * This will create an an instance of a container reader and its associated context.
 430  * The context returned will also be filled with the information retrieved from the media.
 431  *
 432  * If the media isn't accessible or recognized, this will return a null pointer as well as
 433  * an error code indicating why this failed.
 434  *
 435  * \param  p_io         Instance of the container i/o to use
 436  * \param  psz_uri      Unified Resource Identifier pointing to the media container (optional)
 437  * \param  status       Returns the status of the operation
 438  * \param  pf_progress  User provided function pointer to a progress report function. Can be set to
 439  *                      null if no progress report is wanted. This function will be used during
 440  *                      the whole lifetime of the instance (i.e. it will be used during
 441  *                      open / seek / close)
 442  * \param  progress_userdata User provided pointer that will be passed during the progress report
 443  *                      function call.
 444  * \return              A pointer to the context of the new instance of the
 445  *                      container reader. Returns NULL on failure.
 446  */
 447 VC_CONTAINER_T *vc_container_open_reader_with_io( VC_CONTAINER_IO_T *p_io,
 448    const char *psz_uri, VC_CONTAINER_STATUS_T *status,
 449    VC_CONTAINER_PROGRESS_REPORT_FUNC_T pf_progress, void *progress_userdata);
 450
 451 /** Opens the media container pointed to by the URI for writing.
 452  * This will create an an instance of a container writer and its associated context.
 453  * The context returned will be initialised to sensible values.
 454  *
 455  * The application will need to add all the media tracks using \ref vc_container_control before
 456  * it starts writing data using \ref vc_container_write.
 457  *
 458  * If the media isn't accessible or recognized, this will return a null pointer as well as
 459  * an error code indicating why this failed.
 460  *
 461  * \param  psz_uri      Unified Resource Identifier pointing to the media container
 462  * \param  status       Returns the status of the operation
 463  * \param  pf_progress User provided function pointer to a progess report function. Can be set to
 464  *                      null if no progress report is wanted.
 465  * \param  progress_userdata User provided pointer that will be passed during the progress report
 466  *                      function call.
 467  * \return              A pointer to the context of the new instance of the
 468  *                      container writer. Returns NULL on failure.
 469  */
 470 VC_CONTAINER_T *vc_container_open_writer( const char *psz_uri, VC_CONTAINER_STATUS_T *status,
 471    VC_CONTAINER_PROGRESS_REPORT_FUNC_T pf_progress, void *progress_userdata);
 472
 473 /** Closes an instance of a container reader / writer.
 474  * This will free all the resources associated with the context.
 475  *
 476  * \param  context   Pointer to the context of the instance to close
 477  * \return           the status of the operation
 478  */
 479 VC_CONTAINER_STATUS_T vc_container_close( VC_CONTAINER_T *context );
 480
 481 /** \name Container read flags
 482  * The following flags can be passed during a read call */
 483 /* @{ */
 484 /** Type definition for the read flags */
 485 typedef uint32_t VC_CONTAINER_READ_FLAGS_T;
 486 /** Ask the container to only return information on the next packet without reading it */
 487 #define VC_CONTAINER_READ_FLAG_INFO   1
 488 /** Ask the container to skip the next packet */
 489 #define VC_CONTAINER_READ_FLAG_SKIP   2
 490 /** Force the container to read data from the specified track */
 491 #define VC_CONTAINER_READ_FLAG_FORCE_TRACK 4
 492 /* @} */
 493
 494 /** Reads a data packet from a container reader.
 495  * By default, the reader will read whatever packet comes next in the container and update the
 496  * given \ref VC_CONTAINER_PACKET_T structure with this packet's information.
 497  * This behaviour can be changed using the \ref VC_CONTAINER_READ_FLAGS_T.\n
 498  * \ref VC_CONTAINER_READ_FLAG_INFO will instruct the reader to only return information on the
 499  * following packet but not its actual data. The data can be retreived later by issuing another
 500  * read request.\n
 501  * \ref VC_CONTAINER_READ_FLAG_FORCE_TRACK will force the reader to read the next packet for the
 502  * selected track (as present in the \ref VC_CONTAINER_PACKET_T structure) instead of defaulting
 503  * to reading the packet which comes next in the container.\n
 504  * \ref VC_CONTAINER_READ_FLAG_SKIP will instruct the reader to skip the next packet. In this case
 505  * it isn't necessary for the caller to pass a pointer to a \ref VC_CONTAINER_PACKET_T structure
 506  * unless the \ref VC_CONTAINER_READ_FLAG_INFO is also given.\n
 507  * A combination of all these flags can be used.
 508  *
 509  * \param  context   Pointer to the context of the reader to use
 510  * \param  packet    Pointer to the VC_CONTAINER_PACKET_T structure describing the data packet
 511  *                   This needs to be partially filled before the call (buffer, buffer_size)
 512  * \param  flags     Flags controlling the read operation
 513  * \return           the status of the operation
 514  */
 515 VC_CONTAINER_STATUS_T vc_container_read( VC_CONTAINER_T *context,
 516    VC_CONTAINER_PACKET_T *packet, VC_CONTAINER_READ_FLAGS_T flags );
 517
 518 /** Writes a data packet to a container writer.
 519  *
 520  * \param  context   Pointer to the context of the writer to use
 521  * \param  packet    Pointer to the VC_CONTAINER_PACKET_T structure describing the data packet
 522  * \return           the status of the operation
 523  */
 524 VC_CONTAINER_STATUS_T vc_container_write( VC_CONTAINER_T *context,
 525    VC_CONTAINER_PACKET_T *packet );
 526
 527 /** Definition of the different seek modes */
 528 typedef enum
 529 {
 530    /** The offset provided for seeking is an absolute time offset in microseconds */
 531    VC_CONTAINER_SEEK_MODE_TIME = 0,
 532    /** The offset provided for seeking is a percentage (Q32 ?) */
 533    VC_CONTAINER_SEEK_MODE_PERCENT
 534
 535 } VC_CONTAINER_SEEK_MODE_T;
 536
 537 /** \name Container Seek Flags
 538  * The following flags control seek operations */
 539 /* @{ */
 540 /** Type definition for the seek flags */
 541 typedef uint32_t VC_CONTAINER_SEEK_FLAGS_T;
 542 /** Choose precise seeking even if slower */
 543 #define VC_CONTAINER_SEEK_FLAG_PRECISE     0x1
 544 /** By default a seek will always seek to the keyframe which comes just before the requested
 545  * position. This flag allows the caller to force the container to seek to the keyframe which
 546  * comes just after the requested position. */
 547 #define VC_CONTAINER_SEEK_FLAG_FORWARD     0x2
 548 /* @} */
 549
 550 /** Seek into a container reader.
 551  *
 552  * \param  context   Pointer to the context of the reader to use
 553  * \param  offset    Offset to seek to. Used as an input as well as output value.
 554  * \param  mode      Seeking mode requested.
 555  * \param  flags     Flags affecting the seeking operation.
 556  * \return           the status of the operation
 557  */
 558 VC_CONTAINER_STATUS_T vc_container_seek( VC_CONTAINER_T *context, int64_t *offset,
 559       VC_CONTAINER_SEEK_MODE_T mode, VC_CONTAINER_SEEK_FLAGS_T flags);
 560
 561 /** Performance statistics.
 562  */
 563 /** The maximum number of bins a statistics value is held in */
 564 #define VC_CONTAINER_STATS_BINS 10
 565
 566 /** This type is used to represent multiple values of a statistic.
 567  */
 568 typedef struct VC_CONTAINER_STATS_T
 569 {
 570    /** The number of places to right shift count before using.  Resulting values
 571     * of zero are rounded to 1. */
 572    uint32_t shift;
 573
 574    /** We store VC_CONTAINER_STATS_BINS+1 records, in sorted order of numpc.
 575     * At least one will be invalid and all zero.  We combine adjacent records
 576     * as necessary. */
 577    struct {
 578       /** Sum of count.  For single value statistics this is the freqency, for paired statistics
 579        * this is the number of bytes written. */
 580       uint32_t count;
 581       /** Number of count. For single value statistics this is the total value, for paired statistics
 582        * this is the total length of time.  */
 583       uint32_t num;
 584       /** Number>>shift per count.  Stored to save recalculation. */
 585       uint32_t numpc;
 586    } record[VC_CONTAINER_STATS_BINS+1];
 587 } VC_CONTAINER_STATS_T;
 588
 589 /** This type represents the statistics saved by the io layer. */
 590 typedef struct VC_CONTAINER_WRITE_STATS_T
 591 {
 592    /** This logs the number of bytes written in count, and the microseconds taken to write
 593     * in num. */
 594    VC_CONTAINER_STATS_T write;
 595    /** This logs the length of time the write function has to wait for the asynchronous task. */
 596    VC_CONTAINER_STATS_T wait;
 597    /** This logs the length of time that we wait for a flush command to complete. */
 598    VC_CONTAINER_STATS_T flush;
 599 } VC_CONTAINER_WRITE_STATS_T;
 600
 601
 602 /** Control operations which can be done on containers. */
 603 typedef enum
 604 {
 605    /** Adds a new track to the list of tracks. This should be used by writers to create
 606     * their list of tracks.\n
 607     * Arguments:\n
 608     *   arg1= VC_CONTAINER_ES_FORMAT_T *: format of the track to add\n
 609     *   return=  VC_CONTAINER_ERROR_TRACK_FORMAT_NOT_SUPPORTED if the format is not supported */
 610    VC_CONTAINER_CONTROL_TRACK_ADD = 0,
 611
 612    /** Specifies that we're done adding new tracks. This is optional but can be used by writers
 613     * to trigger the writing of the container header early. If this isn't used, the header will be
 614     * written when the first data packet is received.\n
 615     * No arguments.\n
 616     *   return=  VC_CONTAINER_ERROR_TRACK_FORMAT_NOT_SUPPORTED if the format is not supported */
 617    VC_CONTAINER_CONTROL_TRACK_ADD_DONE,
 618
 619    /** Change the format of a track in the list of tracks. This should be used by writers to modify
 620     * the format of a track at run-time.\n
 621     * Arguments:\n
 622     *   arg1= unsigned int: index of track to change\n
 623     *   arg2= VC_CONTAINER_ES_FORMAT_T *: format of the track to add\n
 624     *   return=  VC_CONTAINER_ERROR_TRACK_FORMAT_NOT_SUPPORTED if the format is not supported */
 625    VC_CONTAINER_CONTROL_TRACK_CHANGE,
 626
 627    /** Deletes a track from the list of tracks. This should be used by writers to delete tracks
 628     * during run-time. Note that vc_container_close will automatically delete all track so it
 629     * isn't necessary to call this before closing a writer.\n
 630     * Arguments:\n
 631     *   arg1= index of the track to delete  */
 632    VC_CONTAINER_CONTROL_TRACK_DEL,
 633
 634    /** Activate the playback of DRM protected content.\n
 635     * No arguments.\n
 636     *   return=  one of the VC_CONTAINER_ERROR_DRM error codes if content can't be played */
 637    VC_CONTAINER_CONTROL_DRM_PLAY,
 638
 639    /** TBD */
 640    VC_CONTAINER_CONTROL_METADATA_ADD,
 641    /** TBD */
 642    VC_CONTAINER_CONTROL_METADATA_CHANGE,
 643    /** TBD */
 644    VC_CONTAINER_CONTROL_METADATA_DEL,
 645
 646    /** TBD */
 647    VC_CONTAINER_CONTROL_CHAPTER_ADD,
 648    /** TBD */
 649    VC_CONTAINER_CONTROL_CHAPTER_DEL,
 650
 651    /** Set a maximum size for files generated by writers.\n
 652     * Arguments:\n
 653     *   arg1= uint64_t: maximum size */
 654    VC_CONTAINER_CONTROL_SET_MAXIMUM_SIZE,
 655
 656    /** Enables/disabled performance statistic gathering.\n
 657     * Arguments:\n
 658     *   arg1= bool: enable or disable */
 659    VC_CONTAINER_CONTROL_SET_IO_PERF_STATS,
 660
 661    /** Collects performance statistics.\n
 662     * Arguments:\n
 663     *   arg1= VC_CONTAINER_WRITE_STATS_T *: */
 664    VC_CONTAINER_CONTROL_GET_IO_PERF_STATS,
 665
 666    /** HACK.\n
 667     * Arguments:\n
 668     *   arg1= void (*)(void *): callback function
 669     *   arg1= void *: opaque pointer to pass during the callback */
 670    VC_CONTAINER_CONTROL_SET_IO_BUFFER_FULL_CALLBACK,
 671
 672    /** Set the I/O read buffer size to be used.\n
 673     * Arguments:\n
 674     *   arg1= uint32_t: New buffer size in bytes*/
 675    VC_CONTAINER_CONTROL_IO_SET_READ_BUFFER_SIZE,
 676
 677    /** Set the timeout on I/O read operations, if applicable.\n
 678     * Arguments:\n
 679     *   arg1= uint32_t: New timeout in milliseconds, or VC_CONTAINER_READ_TIMEOUT_BLOCK */
 680    VC_CONTAINER_CONTROL_IO_SET_READ_TIMEOUT_MS,
 681
 682    /** Set the timestamp base.\n
 683     * The timestamp passed equates to time zero for the stream.\n
 684     * Arguments:\n
 685     *   arg1= uint32_t: Timestamp base in stream clock units. */
 686    VC_CONTAINER_CONTROL_SET_TIMESTAMP_BASE,
 687
 688    /** Set the next expected sequence number for the stream.\n
 689     * Arguments:\n
 690     *   arg1= uint32_t: Next expected sequence number. */
 691    VC_CONTAINER_CONTROL_SET_NEXT_SEQUENCE_NUMBER,
 692
 693    /** Set the source ID for the container.\n
 694     * Arguments:\n
 695     *   arg1= uint32_t: Source identifier. */
 696    VC_CONTAINER_CONTROL_SET_SOURCE_ID,
 697
 698    /** Arguments:\n
 699     *   arg1= void *: metadata buffer
 700     *   arg2= unsigned long: length of metadata in bytes */
 701    VC_CONTAINER_CONTROL_GET_DRM_METADATA,
 702
 703    /** Arguments:\n
 704     *   arg1= unsigned long: track number
 705     *   arg2= VC_CONTAINER_FOURCC_T : drm type
 706     *   arg3= void *: encryption configuration parameters.
 707     *   arg4= unsigned long: configuration data length */
 708    VC_CONTAINER_CONTROL_ENCRYPT_TRACK,
 709
 710    /** Causes the io to be flushed.\n
 711     * Arguments: none */
 712    VC_CONTAINER_CONTROL_IO_FLUSH,
 713
 714    /** Request the container reader to packetize data for the specified track.
 715     * Arguments:\n
 716     *   arg1= unsigned long: track number
 717     *   arg2= VC_CONTAINER_FOURCC_T: codec variant to output */
 718    VC_CONTAINER_CONTROL_TRACK_PACKETIZE,
 719
 720    /** Private user extensions must be above this number */
 721    VC_CONTAINER_CONTROL_USER_EXTENSIONS = 0x1000
 722
 723 } VC_CONTAINER_CONTROL_T;
 724
 725 /** Used with the VC_CONTAINER_CONTROL_IO_SET_READ_TIMEOUT_MS control to indicate the read shall
 726  * block until either data is available, or an error occurs.
 727  */
 728 #define VC_CONTAINER_READ_TIMEOUT_BLOCK   (uint32_t)(-1)
 729
 730 /** Extensible control function for container readers and writers.
 731  * This function takes a variable number of arguments which will depend on the specific operation.
 732  *
 733  * \param  context   Pointer to the VC_CONTAINER_T context to use
 734  * \param  operation The requested operation
 735  * \return           the status of the operation. Can be \ref VC_CONTAINER_ERROR_UNSUPPORTED_OPERATION
 736  *                   if the operation is not supported or implemented by the container.
 737  */
 738 VC_CONTAINER_STATUS_T vc_container_control( VC_CONTAINER_T *context, VC_CONTAINER_CONTROL_T operation, ... );
 739
 740 /* @} */
 741
 742 #ifdef __cplusplus
 743 }
 744 #endif
 745
 746 #endif /* VC_CONTAINERS_H */