media/liboggz/include/oggz/oggz_deprecated.h

   1 /*
   2    Copyright (C) 2003 Commonwealth Scientific and Industrial Research
   3    Organisation (CSIRO) Australia
   4
   5    Redistribution and use in source and binary forms, with or without
   6    modification, are permitted provided that the following conditions
   7    are met:
   8
   9    - Redistributions of source code must retain the above copyright
  10    notice, this list of conditions and the following disclaimer.
  11
  12    - Redistributions in binary form must reproduce the above copyright
  13    notice, this list of conditions and the following disclaimer in the
  14    documentation and/or other materials provided with the distribution.
  15
  16    - Neither the name of CSIRO Australia nor the names of its
  17    contributors may be used to endorse or promote products derived from
  18    this software without specific prior written permission.
  19
  20    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  23    PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE ORGANISATION OR
  24    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  27    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  28    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  29    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  30    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 */
  32
  33 #ifndef __OGGZ_DEPRECATED_H__
  34 #define __OGGZ_DEPRECATED_H__
  35
  36 /** \file
  37  * Deprecated interfaces
  38  */
  39
  40 /**
  41  * DEPRECATED CONSTANT.
  42  * OGGZ_ERR_USER_STOPPED was introduced during development (post 0.8.3),
  43  * and is similar in functionality to and numerically equal to (ie. ABI
  44  * compatible with) OGGZ_ERR_STOP_OK in <oggz/oggz_constants.h>.
  45  * It was badly named, as the preferred functionality distinguishes between
  46  * a user's OggzReadCallback returning OGGZ_STOP_OK or OGGZ_STOP_ERR; your
  47  * code should distinguish between these two too :-) Hence, don't use this
  48  * (unreleased) name in new code.
  49  */
  50 #define OGGZ_ERR_USER_STOPPED OGGZ_ERR_STOP_OK
  51
  52 /**
  53  * DEPRECATED CONSTANT.
  54  * OGGZ_ERR_READ_STOP_OK, OGGZ_ERR_READ_STOP_ERR were introduced to allow
  55  * the user to differentiate between a cancelled oggz_read_*() returning
  56  * due to error or an ok condition.
  57  * From 0.9.4 similar functionality was added for oggz_write_*(), hence this
  58  * constant was renamed.
  59  */
  60 #define OGGZ_ERR_READ_STOP_OK  OGGZ_ERR_STOP_OK
  61
  62 /**
  63  * DEPRECATED CONSTANT.
  64  * OGGZ_ERR_READ_STOP_OK, OGGZ_ERR_READ_STOP_ERR were introduced to allow
  65  * the user to differentiate between a cancelled oggz_read_*() returning
  66  * due to error or an ok condition.
  67  * From 0.9.4 similar functionality was added for oggz_write_*(), hence this
  68  * constant was renamed.
  69  */
  70 #define OGGZ_ERR_READ_STOP_ERR OGGZ_ERR_STOP_ERR
  71
  72 /**
  73  * DEPRECATED FUNCTION
  74  * This function has been replaced with the more clearly named
  75  * oggz_set_granulerate().
  76  * Specify that a logical bitstream has a linear metric
  77  * \param oggz An OGGZ handle
  78  * \param serialno Identify the logical bitstream in \a oggz to attach
  79  * this linear metric to. A value of -1 indicates that the metric should
  80  * be attached to all unattached logical bitstreams in \a oggz.
  81  * \param granule_rate_numerator The numerator of the granule rate
  82  * \param granule_rate_denominator The denominator of the granule rate
  83  * \returns 0 Success
  84  * \retval OGGZ_ERR_BAD_SERIALNO \a serialno does not identify an existing
  85  * logical bitstream in \a oggz.
  86  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
  87  */
  88 int oggz_set_metric_linear (OGGZ * oggz, long serialno,
  89                             ogg_int64_t granule_rate_numerator,
  90                             ogg_int64_t granule_rate_denominator);
  91
  92 /**
  93  * DEPRECATED FUNCTION
  94  * This function has been replaced with oggz_comments_generate(), which
  95  * does not require the packet_type argument. Instead, the packet type is
  96  * determined by the content type of the stream, which was discovered when
  97  * the bos packet was passed to oggz_write_feed.
  98  *
  99  * Output a comment packet for the specified stream.
 100  * \param oggz A OGGZ* handle (created with OGGZ_WRITE)
 101  * \param serialno Identify a logical bitstream within \a oggz
 102  * \param packet_type Type of comment packet to generate,
 103  * FLAC, OggPCM, Speex, Theora and Vorbis are supported
 104  * \param FLAC_final_metadata_block Set this to zero unless the packet_type is
 105  * FLAC, and there are no further metadata blocks to follow. See note below
 106  * for details.
 107  * \returns A comment packet for the stream. When no longer needed it
 108  * should be freed with oggz_packet_destroy().
 109  * \retval NULL content type does not support comments, not enough memory
 110  * or comment was too long for FLAC
 111  * \note FLAC streams may contain multiple metadata blocks of different types.
 112  * When encapsulated in Ogg the first of these must be a Vorbis comment packet
 113  * but PADDING, APPLICATION, SEEKTABLE, CUESHEET and PICTURE may follow.
 114  * The last metadata block must have its first bit set to 1. Since liboggz does
 115  * not know whether you will supply more metadata blocks you must tell it if
 116  * this is the last (or only) metadata block by setting
 117  * FLAC_final_metadata_block to 1.
 118  * \n As FLAC metadata blocks are limited in size to 16MB minus 1 byte, this
 119  * function will refuse to produce longer comment packets for FLAC.
 120  * \n See http://flac.sourceforge.net/format.html for more details.
 121  */
 122 ogg_packet *
 123 oggz_comment_generate(OGGZ * oggz, long serialno,
 124                       OggzStreamContent packet_type,
 125                       int FLAC_final_metadata_block);
 126
 127 #endif /* __OGGZ_DEPRECATED_H__ */