src/lib/openjp2/cio.h

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