src/lib/openjp2/cio.h

   1 /*
   2  * The copyright in this software is being made available under the 2-clauses
   3  * BSD License, included below. This software may be subject to other third
   4  * party and contributor rights, including patent rights, and no such rights
   5  * are granted under this license.
   6  *
   7  * Copyright (c) 2002-2014, Universite catholique de Louvain (UCL), Belgium
   8  * Copyright (c) 2002-2014, Professor Benoit Macq
   9  * Copyright (c) 2001-2003, David Janssens
  10  * Copyright (c) 2002-2003, Yannick Verschueren
  11  * Copyright (c) 2003-2007, Francois-Olivier Devaux
  12  * Copyright (c) 2003-2014, Antonin Descampe
  13  * Copyright (c) 2005, Herve Drolon, FreeImage Team
  14  * Copyright (c) 2008, 2011-2012, Centre National d'Etudes Spatiales (CNES), FR
  15  * Copyright (c) 2012, CS Systemes d'Information, France
  16  * All rights reserved.
  17  *
  18  * Redistribution and use in source and binary forms, with or without
  19  * modification, are permitted provided that the following conditions
  20  * are met:
  21  * 1. Redistributions of source code must retain the above copyright
  22  *    notice, this list of conditions and the following disclaimer.
  23  * 2. Redistributions in binary form must reproduce the above copyright
  24  *    notice, this list of conditions and the following disclaimer in the
  25  *    documentation and/or other materials provided with the distribution.
  26  *
  27  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS `AS IS'
  28  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  29  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  30  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  31  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  32  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  33  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  34  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  35  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  36  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  37  * POSSIBILITY OF SUCH DAMAGE.
  38  */
  39
  40 #ifndef OPJ_CIO_H
  41 #define OPJ_CIO_H
  42 /**
  43 @file cio.h
  44 @brief Implementation of a byte input-output process (CIO)
  45
  46 The functions in CIO.C have for goal to realize a byte input / output process.
  47 */
  48
  49 /** @defgroup CIO CIO - byte input-output stream */
  50 /*@{*/
  51
  52 #include "opj_config_private.h"
  53
  54 /* ----------------------------------------------------------------------- */
  55
  56 #if defined(OPJ_BIG_ENDIAN)
  57 #define opj_write_bytes     opj_write_bytes_BE
  58 #define opj_read_bytes      opj_read_bytes_BE
  59 #define opj_write_double    opj_write_double_BE
  60 #define opj_read_double     opj_read_double_BE
  61 #define opj_write_float     opj_write_float_BE
  62 #define opj_read_float      opj_read_float_BE
  63 #else
  64 #define opj_write_bytes     opj_write_bytes_LE
  65 #define opj_read_bytes      opj_read_bytes_LE
  66 #define opj_write_double    opj_write_double_LE
  67 #define opj_read_double     opj_read_double_LE
  68 #define opj_write_float     opj_write_float_LE
  69 #define opj_read_float      opj_read_float_LE
  70 #endif
  71
  72
  73 #define OPJ_STREAM_STATUS_OUTPUT  0x1U
  74 #define OPJ_STREAM_STATUS_INPUT   0x2U
  75 #define OPJ_STREAM_STATUS_END     0x4U
  76 #define OPJ_STREAM_STATUS_ERROR   0x8U
  77
  78 /**
  79 Byte input-output stream.
  80 */
  81 typedef struct opj_stream_private {
  82     /**
  83      * User data, be it files, ... The actual data depends on the type of the stream.
  84      */
  85     void *                  m_user_data;
  86
  87     /**
  88      * Pointer to function to free m_user_data (NULL at initialization)
  89      * when destroying the stream. If pointer is NULL the function is not
  90      * called and the m_user_data is not freed (even if non-NULL).
  91      */
  92     opj_stream_free_user_data_fn        m_free_user_data_fn;
  93
  94     /**
  95      * User data length
  96      */
  97     OPJ_UINT64              m_user_data_length;
  98
  99     /**
 100      * Pointer to actual read function (NULL at the initialization of the cio.
 101      */
 102     opj_stream_read_fn      m_read_fn;
 103
 104     /**
 105      * Pointer to actual write function (NULL at the initialization of the cio.
 106      */
 107     opj_stream_write_fn     m_write_fn;
 108
 109     /**
 110      * Pointer to actual skip function (NULL at the initialization of the cio.
 111      * There is no seek function to prevent from back and forth slow procedures.
 112      */
 113     opj_stream_skip_fn      m_skip_fn;
 114
 115     /**
 116      * Pointer to actual seek function (if available).
 117      */
 118     opj_stream_seek_fn      m_seek_fn;
 119
 120     /**
 121      * Actual data stored into the stream if readed from. Data is read by chunk of fixed size.
 122      * you should never access this data directly.
 123      */
 124     OPJ_BYTE *                  m_stored_data;
 125
 126     /**
 127      * Pointer to the current read data.
 128      */
 129     OPJ_BYTE *                  m_current_data;
 130
 131     /**
 132     * FIXME DOC.
 133     */
 134     OPJ_OFF_T(* m_opj_skip)(struct opj_stream_private *, OPJ_OFF_T,
 135                             struct opj_event_mgr *);
 136
 137     /**
 138     * FIXME DOC.
 139     */
 140     OPJ_BOOL(* m_opj_seek)(struct opj_stream_private *, OPJ_OFF_T,
 141                            struct opj_event_mgr *);
 142
 143     /**
 144      * number of bytes containing in the buffer.
 145      */
 146     OPJ_SIZE_T          m_bytes_in_buffer;
 147
 148     /**
 149      * The number of bytes read/written from the beginning of the stream
 150      */
 151     OPJ_OFF_T           m_byte_offset;
 152
 153     /**
 154      * The size of the buffer.
 155      */
 156     OPJ_SIZE_T          m_buffer_size;
 157
 158     /**
 159      * Flags to tell the status of the stream.
 160      * Used with OPJ_STREAM_STATUS_* defines.
 161      */
 162     OPJ_UINT32 m_status;
 163
 164 }
 165 opj_stream_private_t;
 166
 167 /** @name Exported functions (see also openjpeg.h) */
 168 /*@{*/
 169 /* ----------------------------------------------------------------------- */
 170 /**
 171  * Write some bytes to the given data buffer, this function is used in Big Endian cpus.
 172  * @param p_buffer      pointer the data buffer to write data to.
 173  * @param p_value       the value to write
 174  * @param p_nb_bytes    the number of bytes to write
 175 */
 176 void opj_write_bytes_BE(OPJ_BYTE * p_buffer, OPJ_UINT32 p_value,
 177                         OPJ_UINT32 p_nb_bytes);
 178
 179 /**
 180  * Reads some bytes from the given data buffer, this function is used in Big Endian cpus.
 181  * @param p_buffer      pointer the data buffer to read data from.
 182  * @param p_value       pointer to the value that will store the data.
 183  * @param p_nb_bytes    the nb bytes to read.
 184  * @return              the number of bytes read or -1 if an error occurred.
 185  */
 186 void opj_read_bytes_BE(const OPJ_BYTE * p_buffer, OPJ_UINT32 * p_value,
 187                        OPJ_UINT32 p_nb_bytes);
 188
 189 /**
 190  * Write some bytes to the given data buffer, this function is used in Little Endian cpus.
 191  * @param p_buffer      pointer the data buffer to write data to.
 192  * @param p_value       the value to write
 193  * @param p_nb_bytes    the number of bytes to write
 194  * @return              the number of bytes written or -1 if an error occurred
 195 */
 196 void opj_write_bytes_LE(OPJ_BYTE * p_buffer, OPJ_UINT32 p_value,
 197                         OPJ_UINT32 p_nb_bytes);
 198
 199 /**
 200  * Reads some bytes from the given data buffer, this function is used in Little Endian cpus.
 201  * @param p_buffer      pointer the data buffer to read data from.
 202  * @param p_value       pointer to the value that will store the data.
 203  * @param p_nb_bytes    the nb bytes to read.
 204  * @return              the number of bytes read or -1 if an error occurred.
 205  */
 206 void opj_read_bytes_LE(const OPJ_BYTE * p_buffer, OPJ_UINT32 * p_value,
 207                        OPJ_UINT32 p_nb_bytes);
 208
 209
 210 /**
 211  * Write some bytes to the given data buffer, this function is used in Little Endian cpus.
 212  * @param p_buffer      pointer the data buffer to write data to.
 213  * @param p_value       the value to write
 214  */
 215 void opj_write_double_LE(OPJ_BYTE * p_buffer, OPJ_FLOAT64 p_value);
 216
 217 /***
 218  * Write some bytes to the given data buffer, this function is used in Big Endian cpus.
 219  * @param p_buffer      pointer the data buffer to write data to.
 220  * @param p_value       the value to write
 221  */
 222 void opj_write_double_BE(OPJ_BYTE * p_buffer, OPJ_FLOAT64 p_value);
 223
 224 /**
 225  * Reads some bytes from the given data buffer, this function is used in Little Endian cpus.
 226  * @param p_buffer      pointer the data buffer to read data from.
 227  * @param p_value       pointer to the value that will store the data.
 228  */
 229 void opj_read_double_LE(const OPJ_BYTE * p_buffer, OPJ_FLOAT64 * p_value);
 230
 231 /**
 232  * Reads some bytes from the given data buffer, this function is used in Big Endian cpus.
 233  * @param p_buffer      pointer the data buffer to read data from.
 234  * @param p_value       pointer to the value that will store the data.
 235  */
 236 void opj_read_double_BE(const OPJ_BYTE * p_buffer, OPJ_FLOAT64 * p_value);
 237
 238 /**
 239  * Reads some bytes from the given data buffer, this function is used in Little Endian cpus.
 240  * @param p_buffer      pointer the data buffer to read data from.
 241  * @param p_value       pointer to the value that will store the data.
 242  */
 243 void opj_read_float_LE(const OPJ_BYTE * p_buffer, OPJ_FLOAT32 * p_value);
 244
 245 /**
 246  * Reads some bytes from the given data buffer, this function is used in Big Endian cpus.
 247  * @param p_buffer      pointer the data buffer to read data from.
 248  * @param p_value       pointer to the value that will store the data.
 249  */
 250 void opj_read_float_BE(const OPJ_BYTE * p_buffer, OPJ_FLOAT32 * p_value);
 251
 252 /**
 253  * Write some bytes to the given data buffer, this function is used in Little Endian cpus.
 254  * @param p_buffer      pointer the data buffer to write data to.
 255  * @param p_value       the value to write
 256  */
 257 void opj_write_float_LE(OPJ_BYTE * p_buffer, OPJ_FLOAT32 p_value);
 258
 259 /***
 260  * Write some bytes to the given data buffer, this function is used in Big Endian cpus.
 261  * @param p_buffer      pointer the data buffer to write data to.
 262  * @param p_value       the value to write
 263  */
 264 void opj_write_float_BE(OPJ_BYTE * p_buffer, OPJ_FLOAT32 p_value);
 265
 266 /**
 267  * Reads some bytes from the stream.
 268  * @param       p_stream    the stream to read data from.
 269  * @param       p_buffer    pointer to the data buffer that will receive the data.
 270  * @param       p_size      number of bytes to read.
 271  * @param       p_event_mgr the user event manager to be notified of special events.
 272  * @return      the number of bytes read, or -1 if an error occurred or if the stream is at the end.
 273  */
 274 OPJ_SIZE_T opj_stream_read_data(opj_stream_private_t * p_stream,
 275                                 OPJ_BYTE * p_buffer, OPJ_SIZE_T p_size, struct opj_event_mgr * p_event_mgr);
 276
 277 /**
 278  * Writes some bytes to the stream.
 279  * @param       p_stream    the stream to write data to.
 280  * @param       p_buffer    pointer to the data buffer holds the data to be writtent.
 281  * @param       p_size      number of bytes to write.
 282  * @param       p_event_mgr the user event manager to be notified of special events.
 283  * @return      the number of bytes writtent, or -1 if an error occurred.
 284  */
 285 OPJ_SIZE_T opj_stream_write_data(opj_stream_private_t * p_stream,
 286                                  const OPJ_BYTE * p_buffer, OPJ_SIZE_T p_size,
 287                                  struct opj_event_mgr * p_event_mgr);
 288
 289 /**
 290  * Writes the content of the stream buffer to the stream.
 291  * @param       p_stream    the stream to write data to.
 292  * @param       p_event_mgr the user event manager to be notified of special events.
 293  * @return      true if the data could be flushed, false else.
 294  */
 295 OPJ_BOOL opj_stream_flush(opj_stream_private_t * p_stream,
 296                           struct opj_event_mgr * p_event_mgr);
 297
 298 /**
 299  * Skips a number of bytes from the stream.
 300  * @param       p_stream    the stream to skip data from.
 301  * @param       p_size      the number of bytes to skip.
 302  * @param       p_event_mgr the user event manager to be notified of special events.
 303  * @return      the number of bytes skipped, or -1 if an error occurred.
 304  */
 305 OPJ_OFF_T opj_stream_skip(opj_stream_private_t * p_stream, OPJ_OFF_T p_size,
 306                           struct opj_event_mgr * p_event_mgr);
 307
 308 /**
 309  * Tells the byte offset on the stream (similar to ftell).
 310  *
 311  * @param       p_stream    the stream to get the information from.
 312  *
 313  * @return      the current position o fthe stream.
 314  */
 315 OPJ_OFF_T opj_stream_tell(const opj_stream_private_t * p_stream);
 316
 317
 318 /**
 319  * Get the number of bytes left before the end of the stream (similar to cio_numbytesleft).
 320  *
 321  * @param       p_stream    the stream to get the information from.
 322  *
 323  * @return      Number of bytes left before the end of the stream.
 324  */
 325 OPJ_OFF_T opj_stream_get_number_byte_left(const opj_stream_private_t *
 326         p_stream);
 327
 328 /**
 329  * Skips a number of bytes from the stream.
 330  * @param       p_stream    the stream to skip data from.
 331  * @param       p_size      the number of bytes to skip.
 332  * @param       p_event_mgr the user event manager to be notified of special events.
 333  * @return      the number of bytes skipped, or -1 if an error occurred.
 334  */
 335 OPJ_OFF_T opj_stream_write_skip(opj_stream_private_t * p_stream,
 336                                 OPJ_OFF_T p_size, struct opj_event_mgr * p_event_mgr);
 337
 338 /**
 339  * Skips a number of bytes from the stream.
 340  * @param       p_stream    the stream to skip data from.
 341  * @param       p_size      the number of bytes to skip.
 342  * @param       p_event_mgr the user event manager to be notified of special events.
 343  * @return      the number of bytes skipped, or -1 if an error occurred.
 344  */
 345 OPJ_OFF_T opj_stream_read_skip(opj_stream_private_t * p_stream,
 346                                OPJ_OFF_T p_size, struct opj_event_mgr * p_event_mgr);
 347
 348 /**
 349  * Skips a number of bytes from the stream.
 350  * @param       p_stream    the stream to skip data from.
 351  * @param       p_size      the number of bytes to skip.
 352  * @param       p_event_mgr the user event manager to be notified of special events.
 353  * @return      OPJ_TRUE if success, or OPJ_FALSE if an error occurred.
 354  */
 355 OPJ_BOOL opj_stream_read_seek(opj_stream_private_t * p_stream, OPJ_OFF_T p_size,
 356                               struct opj_event_mgr * p_event_mgr);
 357
 358 /**
 359  * Skips a number of bytes from the stream.
 360  * @param       p_stream    the stream to skip data from.
 361  * @param       p_size      the number of bytes to skip.
 362  * @param       p_event_mgr the user event manager to be notified of special events.
 363  * @return      the number of bytes skipped, or -1 if an error occurred.
 364  */
 365 OPJ_BOOL opj_stream_write_seek(opj_stream_private_t * p_stream,
 366                                OPJ_OFF_T p_size, struct opj_event_mgr * p_event_mgr);
 367
 368 /**
 369  * Seeks a number of bytes from the stream.
 370  * @param       p_stream    the stream to skip data from.
 371  * @param       p_size      the number of bytes to skip.
 372  * @param       p_event_mgr the user event manager to be notified of special events.
 373  * @return      true if the stream is seekable.
 374  */
 375 OPJ_BOOL opj_stream_seek(opj_stream_private_t * p_stream, OPJ_OFF_T p_size,
 376                          struct opj_event_mgr * p_event_mgr);
 377
 378 /**
 379  * Tells if the given stream is seekable.
 380  */
 381 OPJ_BOOL opj_stream_has_seek(const opj_stream_private_t * p_stream);
 382
 383 /**
 384  * FIXME DOC.
 385  */
 386 OPJ_SIZE_T opj_stream_default_read(void * p_buffer, OPJ_SIZE_T p_nb_bytes,
 387                                    void * p_user_data);
 388
 389 /**
 390  * FIXME DOC.
 391  */
 392 OPJ_SIZE_T opj_stream_default_write(void * p_buffer, OPJ_SIZE_T p_nb_bytes,
 393                                     void * p_user_data);
 394
 395 /**
 396  * FIXME DOC.
 397  */
 398 OPJ_OFF_T opj_stream_default_skip(OPJ_OFF_T p_nb_bytes, void * p_user_data);
 399
 400 /**
 401  * FIXME DOC.
 402  */
 403 OPJ_BOOL opj_stream_default_seek(OPJ_OFF_T p_nb_bytes, void * p_user_data);
 404
 405 /* ----------------------------------------------------------------------- */
 406 /*@}*/
 407
 408 /*@}*/
 409
 410
 411 #endif /* OPJ_CIO_H */
 412