MrSID Decode SDK for Raster Reference Manual  9.5.1.4427
mg3_status.h
Go to the documentation of this file.
00001 /* $Id$ */
00002 /* //////////////////////////////////////////////////////////////////////////
00003 //                                                                         //
00004 // This code is Copyright (c) 2005 LizardTech, Inc, 1008 Western Avenue,   //
00005 // Suite 200, Seattle, WA 98104.  Unauthorized use or distribution         //
00006 // prohibited.  Access to and use of this code is permitted only under     //
00007 // license from LizardTech, Inc.  Portions of the code are protected by    //
00008 // US and foreign patents and other filings. All Rights Reserved.          //
00009 //                                                                         //
00011 /* PUBLIC */
00012 
00013 #ifndef MG3_STATUS_H
00014 #define MG3_STATUS_H
00015 
00016 // lt_lib_base
00017 #include "lt_base.h"
00018 
00019 //
00020 // On the Usage of Status Codes
00021 // ----------------------------
00022 //
00023 // Status codes are used to report failure modes of an "unnatural" or
00024 // "unexpected" nature.  They are to be used when something happens that is
00025 // not part of the normal course of events.  They often are used in places
00026 // where other, more mature programmers would throw exceptions.
00027 //
00028 // Applications that don't otherwise handle failure conditions should feel
00029 // free to return these status values as exit codes back out to the shell.
00030 // The kernel sample apps follow this convention.
00031 //
00032 // These status values are to be generally applicable across the whole
00033 // kernel.  They are not to be specific to a small set of cases ("the third
00034 // parameter to this function was greater than 10"), nor are they to be
00035 // overly generic ("an error occurred").
00036 //
00037 // The intent of status codes is to both signal to the user that something
00038 // bad happened and to provide a mechanism for aborting execution gracefully.
00039 // It is *not* the intent that these status codes would allow a caller to
00040 // programmatically diagnose the error and retry the operation -- that would
00041 // require a much richer semantics.  To paraphrase Nathan, the kernel is
00042 // designed for non-dummies.
00043 //
00044 // Status codes are *not* to be used for indicating negative success, such as
00045 // in a function that attempts to find within a file a packet of some
00046 // specified type and return a pointer to that packet.  That function should
00047 // return the "ok" status and use an "out" parameter to return the pointer,
00048 // either set properly (packet was found) or as NULL (packet was not found).
00049 // Finding packets in a file involves underlying I/O operations, and
00050 // therefore is potentially a status-code-inducing operation.  (Contrast this
00051 // with a function which is just looking for some element in a list -- a
00052 // standard list search probably won't entail any operations that might fail
00053 // in bad ways, so returning the pointer directly is okay.)
00054 //
00055 // By convention, status codes are only to be used as function return values,
00056 // never as parameters.
00057 //
00058 // If a function returns a status code, it's value MUST be checked for
00059 // success and handled appropriately.  If you are unsure how to handle the
00060 // returned result, the least you should do is pass the status code back up
00061 // the stack.
00062 //
00063 // Someday, we might unify these status codes with those used by Sparkle, the
00064 // Core, the Stream library, etc.
00065 //
00066 // If you feel the urge to add a New status code, stop and consider your
00067 // situation carefully.  Can you use one of the ones already there?  Could
00068 // your New one replace an existing one?  Will your New one be useful in some
00069 // case other than the current one you have in mind?  Have you talked it over
00070 // with the other kernel folks yet?
00071 //
00072 // There is no "unknown" status code represented.  Such a value would defeat
00073 // the whole purpose.  Lame-o.
00074 //
00075 // Recall that the kernel does not use explicit exception handling anywhere.
00076 // Ever.  At all.  Period.  We use status codes instead.
00077 //
00078 // Only the "OK" status code is given a numeric value (zero).  Programmers
00079 // should not rely on the numeric values or orderings of the enum values.
00080 //
00081 // The "OK()" function should always be used to test success.  The idiom of
00082 // choice is:
00083 //   stat = foo();
00084 //   if (!OK(stat)) return foo;
00085 //
00086 // The "invalid" status is to be used only for initializing variables of type
00087 // MG3Status.  No well-behaved function should ever return the "invalid"
00088 // status.
00089 //
00090 // Note well that the meaning of each status code is documented.  We'd like
00091 // to keep it that way.
00092 //
00093 
00094 
00095 // note "name()" function is declared in MG3Types class
00096 
00097 #define MG3_STATUS_BASE  2000
00098 LT_STATUSSTRING_ADD(MG3_STATUS_BASE, "mrsid kernel BASE")
00099 
00100 #define MG3_STATUS_MAX   2999
00101 LT_STATUSSTRING_ADD(MG3_STATUS_MAX, "mrsid kernel MAX")
00102 
00103    // A "read" I/O operation failed: you hit EOF unexpectedly because the
00104    // file was corrupt, someone unplugged your network cable on you, etc.
00105 #define MG3_STATUS_READ_ERROR                      2001
00106 LT_STATUSSTRING_ADD(MG3_STATUS_READ_ERROR, "mrsid read error")
00107 
00108    // A "write" I/O operation failed: someone unplugged your network cable on
00109    // you, you don't have write permission, the stream just ain't writable,
00110    // etc.
00111 #define MG3_STATUS_WRITE_ERROR                     2002
00112 LT_STATUSSTRING_ADD(MG3_STATUS_WRITE_ERROR, "mrsid write error")
00113 
00114    // An "open" I/O operation failed: someone unplugged your network cable
00115    // (again...), you don't have permission to create the file, you don't
00116    // have write access to the file, etc.
00117 #define MG3_STATUS_OPEN_ERROR                      2003
00118 LT_STATUSSTRING_ADD(MG3_STATUS_OPEN_ERROR, "mrsid open error")
00119 
00120    // An I/O operation failed, for some reason other than read, write, or
00121    // open: for example, seek() or close().
00122 #define MG3_STATUS_IO_ERROR                        2004
00123 LT_STATUSSTRING_ADD(MG3_STATUS_IO_ERROR, "mrsid IO error")
00124 
00125    // The format the file being read was somehow broken: a field containing
00126    // an enum had an illegal value, etc.  This is largely for use by those
00127    // functions which need to decode specific file formats, e.g. MG3.
00128 #define MG3_STATUS_FORMAT_ERROR                    2005
00129 LT_STATUSSTRING_ADD(MG3_STATUS_FORMAT_ERROR, "mrsid format error")
00130 
00131    // A versioning problem has occurred: you're trying to read a version that
00132    // you don't have support for.  [I don't like this one much -- probably
00133    // should be diagnosed more explicitly and handled more formally. BUG.]
00134 #define MG3_STATUS_BAD_VERSION                     2006
00135 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_VERSION, "mrsid bad version")
00136 
00137    // The user has requested an interrupt, e.g. via a signal from our friends
00138    // as LTProcessCallback::hasBeenTerminated().
00139 #define MG3_STATUS_INTERRUPT                       2007
00140 LT_STATUSSTRING_ADD(MG3_STATUS_INTERRUPT, "mrsid interrupt")
00141 
00142 #define MG3_STATUS_RESERVED_2008                   2008
00143 
00144    // One of the arguments to the function was incorrect: a value was out of
00145    // range, a pointer was NULL, etc.  (Compare this to the "bad context"
00146    // error, which is more of an implicit problem.)
00147 #define MG3_STATUS_BAD_ARGUMENT                    2009
00148 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_ARGUMENT, "mrsid bad argument")
00149 
00150    // The context in which the function was called is incorrect: for example,
00151    // trying to add a certain unique packet type to the database when there
00152    // is already one of that type in there -- the caller of function is not
00153    // supposed to do that.  Similarly, calling initialize() twice is not
00154    // allowed, nor is calling execute() with calling initialize() first.
00155    // (Compare this to the "bad argument" error, which is more of an explicit
00156    // problem.)
00157 #define MG3_STATUS_BAD_CONTEXT                     2010
00158 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_CONTEXT, "mrsid bad context")
00159 
00160    // We tried to do something that required a password or some such, and
00161    // the operation didn't succeed.  This should only happen around calls
00162    // into secuirty packets and the encryption library and those sorts of
00163    // places.
00164 #define MG3_STATUS_SECURITY_ERROR                  2011
00165 LT_STATUSSTRING_ADD(MG3_STATUS_SECURITY_ERROR, "mrsid security error")
00166 
00167    // Unlikely, but could happen.  Typically would be used by wrapping a call
00168    // to a potentially large malloc() call in a try region and using this
00169    // value if the catch region finds an out of memory exception.
00170 #define MG3_STATUS_OUT_OF_MEMORY                   2012
00171 LT_STATUSSTRING_ADD(MG3_STATUS_OUT_OF_MEMORY, "mrsid out of memory")
00172 
00173    // A C++ exception occurred that we did not expect.  In some cases, the
00174    // kernel will wrap a call to a foreign library in a try region so as to
00175    // manually catch any errors it may throw.  This status value is used when
00176    // the resulting exception is not something we can readily deal with.
00177 #define MG3_STATUS_UNHANDLED_EXCEPTION             2013
00178 LT_STATUSSTRING_ADD(MG3_STATUS_UNHANDLED_EXCEPTION, "mrsid unhandled exception")
00179 
00180    // A theoretically unreachable piece of code was reached.  This should
00181    // be used for things like the default case of a switch statement in which
00182    // all possible legal values have already been handled explicitly.  This
00183    // value may be used in conjunction with LT_ASSERT(0).
00184 #define MG3_STATUS_NOTREACHED                      2014
00185 LT_STATUSSTRING_ADD(MG3_STATUS_NOTREACHED, "mrsid NOTREACHED")
00186 
00187    // Use only for initializing a variable.  Should never be returned as an
00188    // actual status value.
00189 #define MG3_STATUS_INVALID                         2015
00190 LT_STATUSSTRING_ADD(MG3_STATUS_INVALID, "mrsid status invalid")
00191 
00192    // No MSEs in the image: the image cannot be optimized or streamed.
00193 #define MG3_STATUS_NO_MSES                         2016
00194 LT_STATUSSTRING_ADD(MG3_STATUS_NO_MSES, "mrsid no MSEs")
00195 
00196    // The streaming client made a bad request
00197    // on the server side still send the reply
00198 #define MG3_STATUS_BAD_CLIENT_REQUEST              2017
00199 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_CLIENT_REQUEST, "mrsid bad client request")
00200 
00201    // The streaming server had any error: call getServerError()
00202    // on the server side still send the reply
00203 #define MG3_STATUS_SERVER_ERROR                    2018
00204 LT_STATUSSTRING_ADD(MG3_STATUS_SERVER_ERROR, "mrsid server error")
00205 
00206    // The MG3 image could not be added the client plane cache
00207    // because the imageInfo does not match.
00208 #define MG3_STATUS_IMAGE_NOT_COMPATIBLE            2019
00209 LT_STATUSSTRING_ADD(MG3_STATUS_IMAGE_NOT_COMPATIBLE, "mrsid image not compatible")
00210 
00211    // Singed integer overflowed
00212 #define MG3_STATUS_OVERFLOW                        2020
00213 LT_STATUSSTRING_ADD(MG3_STATUS_OVERFLOW, "mrsid integer overflow")
00214 
00215    // MG4/R inputs require an alpha band
00216 //#define MG4_STATUS_ALPHA_REQUIRED                  2021
00217 //LT_STATUSSTRING_ADD(MG4_STATUS_ALPHA_REQUIRED, "mg4 format requires alpha")
00218 
00219    // MG4/R composites are subject to various constraints on their tiles
00220 #define MG4_STATUS_COMPOSITE_IMPEDANCE_MISMATCH    2022
00221 LT_STATUSSTRING_ADD(MG4_STATUS_COMPOSITE_IMPEDANCE_MISMATCH,
00222                     "mrsid composite impedance mismatch")
00223 
00224 // MG4/R floating point image must have quantization values
00225 #define MG3_STATUS_QUANTIZATION_MISSING            2023
00226 LT_STATUSSTRING_ADD(MG3_STATUS_QUANTIZATION_MISSING,
00227                     "mrsid floating point image needs quantization")
00228 
00229 // MG4/R floating point image quantization values will cause integer overflow 
00230 #define MG3_STATUS_BAD_QUANTIZATION                2024
00231 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_QUANTIZATION,
00232                     "mrsid floating point image quantization values will overflow")
00233 
00234 // MG4/R floating point image quantization values will cause integer overflow 
00235 #define MG3_STATUS_NEEDS_REWRITE                   2025
00236 LT_STATUSSTRING_ADD(MG3_STATUS_NEEDS_REWRITE,
00237                     "mrsid db object needs rewrite")
00238 
00239 // MG4/R bad band selection 
00240 #define MG3_STATUS_BAD_BAND_SELECTION              2026
00241 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_BAND_SELECTION,
00242                     "mrsid bad band selection")
00243 
00244 // 
00245 #define MG3_STATUS_BAD_NUMBER_OF_LEVELS            2027
00246 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_NUMBER_OF_LEVELS,
00247                     "bad number of levels")
00248 
00249 #define MG3_STATUS_BAD_FILE             2028
00250 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_FILE,
00251                     "corrupt file")
00252 
00253 
00254 #endif // MG3_STATUS_H