src/lib/openjpip/openjpip.h

   1 /*
   2  * $Id$
   3  *
   4  * Copyright (c) 2002-2014, Universite catholique de Louvain (UCL), Belgium
   5  * Copyright (c) 2002-2014, 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 "sock_manager.h"
  39 #include "auxtrans_manager.h"
  40
  41 #ifdef SERVER
  42
  43 #include "fcgi_stdio.h"
  44 #define logstream FCGI_stdout
  45
  46 #else
  47
  48 #define FCGI_stdout stdout
  49 #define FCGI_stderr stderr
  50 #define logstream stderr
  51
  52 #include "cache_manager.h"
  53 #include "byte_manager.h"
  54 #include "imgsock_manager.h"
  55
  56 #include "metadata_manager.h"
  57 #include "ihdrbox_manager.h"
  58 #include "index_manager.h"
  59
  60 #endif /*SERVER*/
  61
  62 /*
  63  *==========================================================
  64  * JPIP server API
  65  *==========================================================
  66  */
  67
  68 #ifdef SERVER
  69
  70 /** Server static records*/
  71 typedef struct server_record {
  72     sessionlist_param_t *sessionlist; /**< list of session records*/
  73     targetlist_param_t *targetlist;   /**< list of target records*/
  74     auxtrans_param_t auxtrans;
  75 } server_record_t;
  76
  77 /** Query/response data for each client*/
  78 typedef struct QR {
  79     query_param_t *query;             /**< query parameters*/
  80     msgqueue_param_t *msgqueue;       /**< message queue*/
  81     channel_param_t *channel;         /**< channel, (NULL if stateless)*/
  82 } QR_t;
  83
  84 /**
  85  * Initialize the JPIP server
  86  *
  87  * @param[in] tcp_auxport opening tcp auxiliary port ( 0 not to open, valid No. 49152-65535)
  88  * @param[in] udp_auxport opening udp auxiliary port ( 0 not to open, valid No. 49152-65535)
  89  * @return                initialized server record pointer
  90  */
  91 server_record_t * init_JPIPserver(int tcp_auxport, int udp_auxport);
  92
  93 /**
  94  * Terminate the JPIP server
  95  *
  96  * @param[in] rec address of deleting server static record pointer
  97  */
  98 void terminate_JPIPserver(server_record_t **rec);
  99
 100 /**
 101  * 1st process per client request; parse query string
 102  *
 103  * @param[in]  query_string request query string
 104  * @return     initialized query/response data pointer
 105  */
 106 QR_t * parse_querystring(const char *query_string);
 107
 108 /**
 109  * 2nd process; process JPIP request and construct message queue
 110  *
 111  * @param[in]  rec server static record pointer
 112  * @param[in]  qr  query/response data pointer
 113  * @return     true if succeed, otherwise false
 114  */
 115 OPJ_BOOL process_JPIPrequest(server_record_t *rec, QR_t *qr);
 116
 117 /**
 118  * 3rd process; send response data JPT/JPP-stream
 119  *
 120  * @param[in]  rec server static record pointer
 121  * @param[in]  qr  query/response data pointer
 122  */
 123 void send_responsedata(server_record_t *rec, QR_t *qr);
 124
 125 /**
 126  * 4th (last) process;
 127  *
 128  * @param[in]  rec server static record pinter
 129  * @param[in]  qr  address of query/response data pointer
 130  */
 131 void end_QRprocess(server_record_t *rec, QR_t **qr);
 132
 133 /**
 134  * Option for local tests; print out parameter values to logstream (stderr)
 135  *
 136  * @param[in]  query    true if query parameters are to be printed out
 137  * @param[in]  messages true if queue of messages is to be printed out
 138  * @param[in]  sessions true if session list      is to be printed out
 139  * @param[in]  targets  true if target list       is  to be printed out
 140  * @param[in]  qr       query/response data pointer
 141  * @param[in]  rec      server static record pinter
 142  */
 143 void local_log(OPJ_BOOL query, OPJ_BOOL messages, OPJ_BOOL sessions,
 144                OPJ_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     OPJ_SIZE_T 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         initialized decoding server record pointer
 174  */
 175 OPJ_API dec_server_record_t * OPJ_CALLCONV 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 OPJ_API void OPJ_CALLCONV 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 OPJ_API client_t OPJ_CALLCONV 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 OPJ_API OPJ_BOOL OPJ_CALLCONV handle_clientreq(client_t client,
 200         dec_server_record_t *rec);
 201
 202 #endif /*SERVER*/
 203
 204 /*
 205  *==========================================================
 206  *     JPIP tool API
 207  *==========================================================
 208  */
 209
 210 #ifndef SERVER
 211
 212 /*
 213  * jpip to JP2 or J2K
 214  */
 215
 216 /** JPIP decoding parameters*/
 217 typedef struct jpip_dec_param {
 218     Byte_t *jpipstream;                 /**< JPT/JPP-stream*/
 219     Byte8_t jpiplen;                    /**< length of jpipstream*/
 220     msgqueue_param_t *msgqueue;         /**< message queue*/
 221     metadatalist_param_t *metadatalist; /**< metadata list going into JP2 file*/
 222     ihdrbox_param_t *ihdrbox;           /**< ihdr box going into JP2 file*/
 223     Byte_t *jp2kstream;                 /**< J2K codestream or JP2 file codestream*/
 224     Byte8_t jp2klen;                    /**< length of j2kstream or JP2 file*/
 225 } jpip_dec_param_t;
 226
 227 /**
 228  * Initialize jpip decoder
 229  *
 230  * @param[in] jp2 true in case of jp2 file encoding, else j2k file encoding
 231  * @return        JPIP decoding parameters pointer
 232  */
 233 OPJ_API jpip_dec_param_t * OPJ_CALLCONV init_jpipdecoder(OPJ_BOOL jp2);
 234
 235 /**
 236  * Destroy jpip decoding parameters
 237  *
 238  * @param[in]  dec  address of JPIP decoding parameters pointer
 239  */
 240 OPJ_API void OPJ_CALLCONV destroy_jpipdecoder(jpip_dec_param_t **dec);
 241
 242 /**
 243  * Read jpip codestream from a file
 244  *
 245  * @param[in]  fname file name
 246  * @param[in]  dec   JPIP decoding parameters pointer
 247  * @return           true if succeed
 248  */
 249 OPJ_API OPJ_BOOL OPJ_CALLCONV fread_jpip(const char fname[],
 250         jpip_dec_param_t *dec);
 251
 252 /**
 253  * Decode jpip codestream
 254  *
 255  * @param[in]  dec   JPIP decoding parameters pointer
 256  */
 257 OPJ_API void OPJ_CALLCONV decode_jpip(jpip_dec_param_t *dec);
 258
 259 /**
 260  * Write J2K/JP2 codestream to a file
 261  *
 262  * @param[in]  fname file name
 263  * @param[in]  dec   JPIP decoding parameters pointer
 264  * @return           true if succeed
 265  */
 266 OPJ_API OPJ_BOOL OPJ_CALLCONV fwrite_jp2k(const char fname[],
 267         jpip_dec_param_t *dec);
 268
 269 /**
 270  * Option; print out parameter values to stderr
 271  *
 272  * @param[in]  messages true if queue of messages is to be printed out
 273  * @param[in]  metadata true if metadata          is to be printed out
 274  * @param[in]  ihdrbox  true if image header data is to be printed out
 275  * @param[in]  dec   JPIP decoding parameters pointer
 276  */
 277 OPJ_API void OPJ_CALLCONV output_log(OPJ_BOOL messages, OPJ_BOOL metadata,
 278                                      OPJ_BOOL ihdrbox, jpip_dec_param_t *dec);
 279
 280 /*
 281  *  test the format of index (cidx) box in JP2 file
 282  */
 283
 284 /** Redefinition of index parameters*/
 285 typedef index_param_t index_t;
 286
 287 /**
 288  * Parse JP2 file and get index information from cidx box inside
 289  *
 290  * @param[in] fd file descriptor of the JP2 file
 291  * @return       pointer to the generated structure of index parameters
 292  */
 293 OPJ_API index_t * OPJ_CALLCONV get_index_from_JP2file(int fd);
 294
 295 /**
 296  * Destroy index parameters
 297  *
 298  * @param[in,out] idx addressof the index pointer
 299  */
 300 OPJ_API void OPJ_CALLCONV destroy_index(index_t **idx);
 301
 302
 303 /**
 304  * print index parameters
 305  *
 306  * @param[in] index index parameters
 307  */
 308 OPJ_API void OPJ_CALLCONV output_index(index_t *index);
 309
 310 #endif /*SERVER*/
 311
 312 #endif /* !OPENJPIP_H_ */