MrSID Decode SDK for Raster Reference Manual
9.5.4.4709
|
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