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          * User data length
  90          */
  91         OPJ_UINT64                              m_user_data_length;
  92
  93         /**
  94          * Pointer to actual read function (NULL at the initialization of the cio.
  95          */
  96         opj_stream_read_fn              m_read_fn;
  97
  98         /**
  99          * Pointer to actual write function (NULL at the initialization of the cio.
 100          */
 101         opj_stream_write_fn             m_write_fn;
 102
 103         /**
 104          * Pointer to actual skip function (NULL at the initialization of the cio.
 105          * There is no seek function to prevent from back and forth slow procedures.
 106          */
 107         opj_stream_skip_fn              m_skip_fn;
 108
 109         /**
 110          * Pointer to actual seek function (if available).
 111          */
 112         opj_stream_seek_fn              m_seek_fn;
 113
 114         /**
 115          * Actual data stored into the stream if readed from. Data is read by chunk of fixed size.
 116          * you should never access this data directly.
 117          */
 118         OPJ_BYTE *                                      m_stored_data;
 119
 120         /**
 121          * Pointer to the current read data.
 122          */
 123         OPJ_BYTE *                                      m_current_data;
 124
 125     /**
 126     * FIXME DOC.
 127     */
 128         OPJ_OFF_T (* m_opj_skip)(struct opj_stream_private * ,OPJ_OFF_T , struct opj_event_mgr *);
 129
 130     /**
 131     * FIXME DOC.
 132     */
 133         OPJ_BOOL (* m_opj_seek) (struct opj_stream_private * , OPJ_OFF_T , struct opj_event_mgr *);
 134
 135         /**
 136          * number of bytes containing in the buffer.
 137          */
 138         OPJ_SIZE_T                      m_bytes_in_buffer;
 139
 140         /**
 141          * The number of bytes read/written from the beginning of the stream
 142          */
 143         OPJ_OFF_T                       m_byte_offset;
 144
 145         /**
 146          * The size of the buffer.
 147          */
 148         OPJ_SIZE_T                      m_buffer_size;
 149
 150         /**
 151          * Flags to tell the status of the stream.
 152          */
 153         opj_stream_flag m_status;
 154
 155 }
 156 opj_stream_private_t;
 157
 158 /** @name Exported functions (see also openjpeg.h) */
 159 /*@{*/
 160 /* ----------------------------------------------------------------------- */
 161 /**
 162  * Write some bytes to the given data buffer, this function is used in Big Endian cpus.
 163  * @param p_buffer              pointer the data buffer to write data to.
 164  * @param p_value               the value to write
 165  * @param p_nb_bytes    the number of bytes to write
 166 */
 167 void opj_write_bytes_BE (OPJ_BYTE * p_buffer, OPJ_UINT32 p_value, OPJ_UINT32 p_nb_bytes);
 168
 169 /**
 170  * Reads some bytes from the given data buffer, this function is used in Big Endian cpus.
 171  * @param p_buffer              pointer the data buffer to read data from.
 172  * @param p_value               pointer to the value that will store the data.
 173  * @param p_nb_bytes    the nb bytes to read.
 174  * @return                              the number of bytes read or -1 if an error occured.
 175  */
 176 void opj_read_bytes_BE(const OPJ_BYTE * p_buffer, OPJ_UINT32 * p_value, OPJ_UINT32 p_nb_bytes);
 177
 178 /**
 179  * Write some bytes to the given data buffer, this function is used in Little Endian cpus.
 180  * @param p_buffer              pointer the data buffer to write data to.
 181  * @param p_value               the value to write
 182  * @param p_nb_bytes    the number of bytes to write
 183  * @return                              the number of bytes written or -1 if an error occured
 184 */
 185 void opj_write_bytes_LE (OPJ_BYTE * p_buffer, OPJ_UINT32 p_value, OPJ_UINT32 p_nb_bytes);
 186
 187 /**
 188  * Reads some bytes from the given data buffer, this function is used in Little Endian cpus.
 189  * @param p_buffer              pointer the data buffer to read data from.
 190  * @param p_value               pointer to the value that will store the data.
 191  * @param p_nb_bytes    the nb bytes to read.
 192  * @return                              the number of bytes read or -1 if an error occured.
 193  */
 194 void opj_read_bytes_LE(const OPJ_BYTE * p_buffer, OPJ_UINT32 * p_value, OPJ_UINT32 p_nb_bytes);
 195
 196
 197 /**
 198  * Write some bytes to the given data buffer, this function is used in Little Endian cpus.
 199  * @param p_buffer              pointer the data buffer to write data to.
 200  * @param p_value               the value to write
 201  */
 202 void opj_write_double_LE(OPJ_BYTE * p_buffer, OPJ_FLOAT64 p_value);
 203
 204 /***
 205  * Write some bytes to the given data buffer, this function is used in Big 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_BE(OPJ_BYTE * p_buffer, OPJ_FLOAT64 p_value);
 210
 211 /**
 212  * Reads some bytes from the given data buffer, this function is used in Little Endian cpus.
 213  * @param p_buffer              pointer the data buffer to read data from.
 214  * @param p_value               pointer to the value that will store the data.
 215  */
 216 void opj_read_double_LE(const OPJ_BYTE * p_buffer, OPJ_FLOAT64 * p_value);
 217
 218 /**
 219  * Reads some bytes from the given data buffer, this function is used in Big 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_BE(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 Little 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_float_LE(const OPJ_BYTE * p_buffer, OPJ_FLOAT32 * p_value);
 231
 232 /**
 233  * Reads some bytes from the given data buffer, this function is used in Big 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_BE(const OPJ_BYTE * p_buffer, OPJ_FLOAT32 * p_value);
 238
 239 /**
 240  * Write some bytes to the given data buffer, this function is used in Little Endian cpus.
 241  * @param p_buffer              pointer the data buffer to write data to.
 242  * @param p_value               the value to write
 243  */
 244 void opj_write_float_LE(OPJ_BYTE * p_buffer, OPJ_FLOAT32 p_value);
 245
 246 /***
 247  * Write some bytes to the given data buffer, this function is used in Big 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_BE(OPJ_BYTE * p_buffer, OPJ_FLOAT32 p_value);
 252
 253 /**
 254  * Reads some bytes from the stream.
 255  * @param               p_stream        the stream to read data from.
 256  * @param               p_buffer        pointer to the data buffer that will receive the data.
 257  * @param               p_size          number of bytes to read.
 258  * @param               p_event_mgr     the user event manager to be notified of special events.
 259  * @return              the number of bytes read, or -1 if an error occured or if the stream is at the end.
 260  */
 261 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);
 262
 263 /**
 264  * Writes some bytes to the stream.
 265  * @param               p_stream        the stream to write data to.
 266  * @param               p_buffer        pointer to the data buffer holds the data to be writtent.
 267  * @param               p_size          number of bytes to write.
 268  * @param               p_event_mgr     the user event manager to be notified of special events.
 269  * @return              the number of bytes writtent, or -1 if an error occured.
 270  */
 271 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);
 272
 273 /**
 274  * Writes the content of the stream buffer to the stream.
 275  * @param               p_stream        the stream to write data to.
 276  * @param               p_event_mgr     the user event manager to be notified of special events.
 277  * @return              true if the data could be flushed, false else.
 278  */
 279 OPJ_BOOL opj_stream_flush (opj_stream_private_t * p_stream, struct opj_event_mgr * p_event_mgr);
 280
 281 /**
 282  * Skips a number of bytes from the stream.
 283  * @param               p_stream        the stream to skip data from.
 284  * @param               p_size          the number of bytes to skip.
 285  * @param               p_event_mgr     the user event manager to be notified of special events.
 286  * @return              the number of bytes skipped, or -1 if an error occured.
 287  */
 288 OPJ_OFF_T opj_stream_skip (opj_stream_private_t * p_stream,OPJ_OFF_T p_size, struct opj_event_mgr * p_event_mgr);
 289
 290 /**
 291  * Tells the byte offset on the stream (similar to ftell).
 292  *
 293  * @param               p_stream        the stream to get the information from.
 294  *
 295  * @return              the current position o fthe stream.
 296  */
 297 OPJ_OFF_T opj_stream_tell (const opj_stream_private_t * p_stream);
 298
 299
 300 /**
 301  * Get the number of bytes left before the end of the stream (similar to cio_numbytesleft).
 302  *
 303  * @param               p_stream        the stream to get the information from.
 304  *
 305  * @return              Number of bytes left before the end of the stream.
 306  */
 307 OPJ_OFF_T opj_stream_get_number_byte_left (const opj_stream_private_t * p_stream);
 308
 309 /**
 310  * Skips a number of bytes from the stream.
 311  * @param               p_stream        the stream to skip data from.
 312  * @param               p_size          the number of bytes to skip.
 313  * @param               p_event_mgr     the user event manager to be notified of special events.
 314  * @return              the number of bytes skipped, or -1 if an error occured.
 315  */
 316 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);
 317
 318 /**
 319  * Skips a number of bytes from the stream.
 320  * @param               p_stream        the stream to skip data from.
 321  * @param               p_size          the number of bytes to skip.
 322  * @param               p_event_mgr     the user event manager to be notified of special events.
 323  * @return              the number of bytes skipped, or -1 if an error occured.
 324  */
 325 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);
 326
 327 /**
 328  * Skips a number of bytes from the stream.
 329  * @param               p_stream        the stream to skip data from.
 330  * @param               p_size          the number of bytes to skip.
 331  * @param               p_event_mgr     the user event manager to be notified of special events.
 332  * @return              OPJ_TRUE if success, or OPJ_FALSE if an error occured.
 333  */
 334 OPJ_BOOL opj_stream_read_seek (opj_stream_private_t * p_stream, OPJ_OFF_T p_size, struct opj_event_mgr * p_event_mgr);
 335
 336 /**
 337  * Skips a number of bytes from the stream.
 338  * @param               p_stream        the stream to skip data from.
 339  * @param               p_size          the number of bytes to skip.
 340  * @param               p_event_mgr     the user event manager to be notified of special events.
 341  * @return              the number of bytes skipped, or -1 if an error occured.
 342  */
 343 OPJ_BOOL opj_stream_write_seek (opj_stream_private_t * p_stream, OPJ_OFF_T p_size, struct opj_event_mgr * p_event_mgr);
 344
 345 /**
 346  * Seeks a number of bytes from the stream.
 347  * @param               p_stream        the stream to skip data from.
 348  * @param               p_size          the number of bytes to skip.
 349  * @param               p_event_mgr     the user event manager to be notified of special events.
 350  * @return              true if the stream is seekable.
 351  */
 352 OPJ_BOOL opj_stream_seek (opj_stream_private_t * p_stream, OPJ_OFF_T p_size, struct opj_event_mgr * p_event_mgr);
 353
 354 /**
 355  * Tells if the given stream is seekable.
 356  */
 357 OPJ_BOOL opj_stream_has_seek (const opj_stream_private_t * p_stream);
 358
 359 /**
 360  * FIXME DOC.
 361  */
 362 OPJ_SIZE_T opj_stream_default_read (void * p_buffer, OPJ_SIZE_T p_nb_bytes, void * p_user_data);
 363
 364 /**
 365  * FIXME DOC.
 366  */
 367 OPJ_SIZE_T opj_stream_default_write (void * p_buffer, OPJ_SIZE_T p_nb_bytes, void * p_user_data);
 368
 369 /**
 370  * FIXME DOC.
 371  */
 372 OPJ_OFF_T opj_stream_default_skip (OPJ_OFF_T p_nb_bytes, void * p_user_data);
 373
 374 /**
 375  * FIXME DOC.
 376  */
 377 OPJ_BOOL opj_stream_default_seek (OPJ_OFF_T p_nb_bytes, void * p_user_data);
 378
 379 /* ----------------------------------------------------------------------- */
 380 /*@}*/
 381
 382 /*@}*/
 383
 384
 385 #endif /* __CIO_H */
 386