applications/jpip/libopenjpip/openjpip.h

   1 /*
   2  * $Id$
   3  *
   4  * Copyright (c) 2002-2011, Communications and Remote Sensing Laboratory, Universite catholique de Louvain (UCL), Belgium
   5  * Copyright (c) 2002-2011, Professor Benoit Macq
   6  * Copyright (c) 2010-2011, Kaori Hagihara
   7  * All rights reserved.
   8  *
   9  * Redistribution and use in source and binary forms, with or without
  10  * modification, are permitted provided that the following conditions
  11  * are met:
  12  * 1. Redistributions of source code must retain the above copyright
  13  *    notice, this list of conditions and the following disclaimer.
  14  * 2. Redistributions in binary form must reproduce the above copyright
  15  *    notice, this list of conditions and the following disclaimer in the
  16  *    documentation and/or other materials provided with the distribution.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS `AS IS'
  19  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  22  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28  * POSSIBILITY OF SUCH DAMAGE.
  29  */
  30
  31 #ifndef         OPENJPIP_H_
  32 # define        OPENJPIP_H_
  33
  34 #include "session_manager.h"
  35 #include "target_manager.h"
  36 #include "query_parser.h"
  37 #include "msgqueue_manager.h"
  38 #include "bool.h"
  39 #include "sock_manager.h"
  40 #include "auxtrans_manager.h"
  41
  42 #ifdef SERVER
  43
  44 #include "fcgi_stdio.h"
  45 #define logstream FCGI_stdout
  46
  47 #else
  48
  49 #define FCGI_stdout stdout
  50 #define FCGI_stderr stderr
  51 #define logstream stderr
  52
  53 #include "cache_manager.h"
  54 #include "byte_manager.h"
  55 #include "imgsock_manager.h"
  56
  57 #include "metadata_manager.h"
  58 #include "ihdrbox_manager.h"
  59 #include "index_manager.h"
  60
  61 #endif //SERVER
  62
  63 /*
  64  *==========================================================
  65  * JPIP server API
  66  *==========================================================
  67  */
  68
  69  #ifdef SERVER
  70
  71 //! Server static records
  72 typedef struct server_record{
  73   sessionlist_param_t *sessionlist; //!< list of session records
  74   targetlist_param_t *targetlist;   //!< list of target records
  75   auxtrans_param_t auxtrans;
  76 } server_record_t;
  77
  78 //! Query/response data for each client
  79 typedef struct QR{
  80   query_param_t *query;             //!< query parameters
  81   msgqueue_param_t *msgqueue;       //!< message queue
  82   channel_param_t *channel;         //!< channel, (NULL if stateless)
  83 } QR_t;
  84
  85 /**
  86  * Initialize the JPIP server
  87  *
  88  * @param[in] tcp_auxport opening tcp auxiliary port ( 0 not to open, valid No. 49152–65535)
  89  * @param[in] udp_auxport opening udp auxiliary port ( 0 not to open, valid No. 49152–65535)
  90  * @return                intialized server record pointer
  91  */
  92 server_record_t * init_JPIPserver( int tcp_auxport, int udp_auxport);
  93
  94 /**
  95  * Terminate the JPIP server
  96  *
  97  * @param[in] rec address of deleting server static record pointer
  98  */
  99 void terminate_JPIPserver( server_record_t **rec);
 100
 101 /**
 102  * 1st process per client request; parse query string
 103  *
 104  * @param[in]  query_string request query string
 105  * @return     initialized query/response data pointer
 106  */
 107 QR_t * parse_querystring( char *query_string);
 108
 109 /**
 110  * 2nd process; process JPIP request and construct message queue
 111  *
 112  * @param[in]  rec server static record pointer
 113  * @param[in]  qr  query/response data pointer
 114  * @return     true if succeed, otherwise false
 115  */
 116 bool process_JPIPrequest( server_record_t *rec, QR_t *qr);
 117
 118 /**
 119  * 3rd process; send response data JPT/JPP-stream
 120  *
 121  * @param[in]  rec server static record pointer
 122  * @param[in]  qr  query/response data pointer
 123  */
 124 void send_responsedata( server_record_t *rec, QR_t *qr);
 125
 126 /**
 127  * 4th (last) process;
 128  *
 129  * @param[in]  rec server static record pinter
 130  * @param[in]  qr  address of query/response data pointer
 131  */
 132 void end_QRprocess( server_record_t *rec, QR_t **qr);
 133
 134 /**
 135  * Option for local tests; print out parameter values to logstream (stderr)
 136  *
 137  * @param[in]  query    true if query parameters are to be printed out
 138  * @param[in]  messages true if queue of messages is to be printed out
 139  * @param[in]  sessions true if session list      is to be printed out
 140  * @param[in]  targets  true if target list       is  to be printed out
 141  * @param[in]  qr       query/response data pointer
 142  * @param[in]  rec      server static record pinter
 143  */
 144 void local_log( bool query, bool messages, bool sessions, bool targets, QR_t *qr, server_record_t *rec);
 145
 146 #endif //SERVER
 147
 148 /*
 149  *==========================================================
 150  *      JPIP decoding server API
 151  *==========================================================
 152  */
 153
 154 #ifndef SERVER
 155
 156 //! Decoding server static records
 157 typedef struct dec_server_record{
 158   cachelist_param_t *cachelist; //!< cache list
 159   Byte_t *jpipstream;           //!< JPT/JPP stream
 160   int jpipstreamlen;            //!< length of jpipstream
 161   msgqueue_param_t *msgqueue;   //!< parsed message queue of jpipstream
 162   SOCKET listening_socket;      //!< listenning socket
 163 } dec_server_record_t;
 164
 165
 166 //! Client socket identifier
 167 typedef SOCKET client_t;
 168
 169 /**
 170  * Initialize the image decoding server
 171  *
 172  * @param[in] port opening tcp port (valid No. 49152–65535)
 173  * @return         intialized decoding server record pointer
 174  */
 175 dec_server_record_t * init_dec_server( int port);
 176
 177 /**
 178  * Terminate the  image decoding server
 179  *
 180  * @param[in] rec address of deleting decoding server static record pointer
 181  */
 182 void terminate_dec_server( dec_server_record_t **rec);
 183
 184 /**
 185  * Accept client connection
 186  *
 187  * @param[in] rec decoding server static record pointer
 188  * @return        client socket ID, -1 if failed
 189  */
 190 client_t accept_connection( dec_server_record_t *rec);
 191
 192  /**
 193   * Handle client request
 194   *
 195   * @param[in] client client socket ID
 196   * @param[in] rec    decoding server static record pointer
 197   * @return           true if succeed
 198   */
 199 bool handle_clientreq( client_t client, dec_server_record_t *rec);
 200
 201  #endif //SERVER
 202
 203 /*
 204  *==========================================================
 205  *     JPIP tool API
 206  *==========================================================
 207  */
 208
 209 #ifndef SERVER
 210
 211 /*
 212  * jpip to JP2 or J2K
 213  */
 214
 215 //! JPIP decoding parameters
 216 typedef struct jpip_dec_param{
 217   Byte_t *jpipstream;                 //!< JPT/JPP-stream
 218   Byte8_t jpiplen;                    //!< length of jpipstream
 219   msgqueue_param_t *msgqueue;         //!< message queue
 220   metadatalist_param_t *metadatalist; //!< metadata list going into JP2 file
 221   ihdrbox_param_t *ihdrbox;           //!< ihdr box going into JP2 file
 222   Byte_t *jp2kstream;                 //!< J2K codestream or JP2 file codestream
 223   Byte8_t jp2klen;                    //!< length of j2kstream or JP2 file
 224 } jpip_dec_param_t;
 225
 226 /**
 227  * Initialize jpip decoder
 228  *
 229  * @param[in] jp2 true in case of jp2 file encoding, else j2k file encoding
 230  * @return        JPIP decoding parameters pointer
 231  */
 232 jpip_dec_param_t * init_jpipdecoder( bool jp2);
 233
 234 /**
 235  * Destroy jpip decoding parameters
 236  *
 237  * @param[in]  dec  address of JPIP decoding parameters pointer
 238  */
 239 void destroy_jpipdecoder( jpip_dec_param_t **dec);
 240
 241 /**
 242  * Read jpip codestream from a file
 243  *
 244  * @param[in]  fname file name
 245  * @param[in]  dec   JPIP decoding parameters pointer
 246  * @return           true if succeed
 247  */
 248 bool fread_jpip( char fname[], jpip_dec_param_t *dec);
 249
 250 /**
 251  * Decode jpip codestream
 252  *
 253  * @param[in]  dec   JPIP decoding parameters pointer
 254  */
 255 void decode_jpip( jpip_dec_param_t *dec);
 256
 257 /**
 258  * Write J2K/JP2 codestream to a file
 259  *
 260  * @param[in]  fname file name
 261  * @param[in]  dec   JPIP decoding parameters pointer
 262  * @return           true if succeed
 263  */
 264 bool fwrite_jp2k( char fname[], jpip_dec_param_t *dec);
 265
 266 /**
 267  * Option; print out parameter values to stderr
 268  *
 269  * @param[in]  messages true if queue of messages is to be printed out
 270  * @param[in]  metadata true if metadata          is to be printed out
 271  * @param[in]  ihdrbox  true if image header data is to be printed out
 272  * @param[in]  dec   JPIP decoding parameters pointer
 273  */
 274 void output_log( bool messages, bool metadata, bool ihdrbox, jpip_dec_param_t *dec);
 275
 276 /*
 277  *  test the format of index (cidx) box in JP2 file
 278  */
 279
 280 //! Redefinition of index parameters
 281 typedef index_param_t index_t;
 282
 283 /**
 284  * Parse JP2 file and get index information from cidx box inside
 285  *
 286  * @param[in] fd file descriptor of the JP2 file
 287  * @return       pointer to the generated structure of index parameters
 288  */
 289 index_t * get_index_from_JP2file( int fd);
 290
 291 /**
 292  * Destroy index parameters
 293  *
 294  * @param[in,out] idx addressof the index pointer
 295  */
 296 void destroy_index( index_t **idx);
 297
 298
 299 /**
 300  * print index parameters
 301  *
 302  * @param[in] index index parameters
 303  */
 304 void output_index( index_t *index);
 305
 306 #endif //SERVER
 307
 308 #endif /* !OPENJPIP_H_ */