MrSID Decode SDK for Raster Reference Manual  9.5.1.4427
mg3_status.h
Go to the documentation of this file.
1 /* $Id$ */
2 /* //////////////////////////////////////////////////////////////////////////
3 // //
4 // This code is Copyright (c) 2005 LizardTech, Inc, 1008 Western Avenue, //
5 // Suite 200, Seattle, WA 98104. Unauthorized use or distribution //
6 // prohibited. Access to and use of this code is permitted only under //
7 // license from LizardTech, Inc. Portions of the code are protected by //
8 // US and foreign patents and other filings. All Rights Reserved. //
9 // //
11 /* PUBLIC */
12 
13 #ifndef MG3_STATUS_H
14 #define MG3_STATUS_H
15 
16 // lt_lib_base
17 #include "lt_base.h"
18 
19 //
20 // On the Usage of Status Codes
21 // ----------------------------
22 //
23 // Status codes are used to report failure modes of an "unnatural" or
24 // "unexpected" nature. They are to be used when something happens that is
25 // not part of the normal course of events. They often are used in places
26 // where other, more mature programmers would throw exceptions.
27 //
28 // Applications that don't otherwise handle failure conditions should feel
29 // free to return these status values as exit codes back out to the shell.
30 // The kernel sample apps follow this convention.
31 //
32 // These status values are to be generally applicable across the whole
33 // kernel. They are not to be specific to a small set of cases ("the third
34 // parameter to this function was greater than 10"), nor are they to be
35 // overly generic ("an error occurred").
36 //
37 // The intent of status codes is to both signal to the user that something
38 // bad happened and to provide a mechanism for aborting execution gracefully.
39 // It is *not* the intent that these status codes would allow a caller to
40 // programmatically diagnose the error and retry the operation -- that would
41 // require a much richer semantics. To paraphrase Nathan, the kernel is
42 // designed for non-dummies.
43 //
44 // Status codes are *not* to be used for indicating negative success, such as
45 // in a function that attempts to find within a file a packet of some
46 // specified type and return a pointer to that packet. That function should
47 // return the "ok" status and use an "out" parameter to return the pointer,
48 // either set properly (packet was found) or as NULL (packet was not found).
49 // Finding packets in a file involves underlying I/O operations, and
50 // therefore is potentially a status-code-inducing operation. (Contrast this
51 // with a function which is just looking for some element in a list -- a
52 // standard list search probably won't entail any operations that might fail
53 // in bad ways, so returning the pointer directly is okay.)
54 //
55 // By convention, status codes are only to be used as function return values,
56 // never as parameters.
57 //
58 // If a function returns a status code, it's value MUST be checked for
59 // success and handled appropriately. If you are unsure how to handle the
60 // returned result, the least you should do is pass the status code back up
61 // the stack.
62 //
63 // Someday, we might unify these status codes with those used by Sparkle, the
64 // Core, the Stream library, etc.
65 //
66 // If you feel the urge to add a New status code, stop and consider your
67 // situation carefully. Can you use one of the ones already there? Could
68 // your New one replace an existing one? Will your New one be useful in some
69 // case other than the current one you have in mind? Have you talked it over
70 // with the other kernel folks yet?
71 //
72 // There is no "unknown" status code represented. Such a value would defeat
73 // the whole purpose. Lame-o.
74 //
75 // Recall that the kernel does not use explicit exception handling anywhere.
76 // Ever. At all. Period. We use status codes instead.
77 //
78 // Only the "OK" status code is given a numeric value (zero). Programmers
79 // should not rely on the numeric values or orderings of the enum values.
80 //
81 // The "OK()" function should always be used to test success. The idiom of
82 // choice is:
83 // stat = foo();
84 // if (!OK(stat)) return foo;
85 //
86 // The "invalid" status is to be used only for initializing variables of type
87 // MG3Status. No well-behaved function should ever return the "invalid"
88 // status.
89 //
90 // Note well that the meaning of each status code is documented. We'd like
91 // to keep it that way.
92 //
93 
94 
95 // note "name()" function is declared in MG3Types class
96 
97 #define MG3_STATUS_BASE 2000
98 LT_STATUSSTRING_ADD(MG3_STATUS_BASE, "mrsid kernel BASE")
99 
100 #define MG3_STATUS_MAX 2999
101 LT_STATUSSTRING_ADD(MG3_STATUS_MAX, "mrsid kernel MAX")
102 
103  // A "read" I/O operation failed: you hit EOF unexpectedly because the
104  // file was corrupt, someone unplugged your network cable on you, etc.
105 #define MG3_STATUS_READ_ERROR 2001
106 LT_STATUSSTRING_ADD(MG3_STATUS_READ_ERROR, "mrsid read error")
107 
108  // A "write" I/O operation failed: someone unplugged your network cable on
109  // you, you don't have write permission, the stream just ain't writable,
110  // etc.
111 #define MG3_STATUS_WRITE_ERROR 2002
112 LT_STATUSSTRING_ADD(MG3_STATUS_WRITE_ERROR, "mrsid write error")
113 
114  // An "open" I/O operation failed: someone unplugged your network cable
115  // (again...), you don't have permission to create the file, you don't
116  // have write access to the file, etc.
117 #define MG3_STATUS_OPEN_ERROR 2003
118 LT_STATUSSTRING_ADD(MG3_STATUS_OPEN_ERROR, "mrsid open error")
119 
120  // An I/O operation failed, for some reason other than read, write, or
121  // open: for example, seek() or close().
122 #define MG3_STATUS_IO_ERROR 2004
123 LT_STATUSSTRING_ADD(MG3_STATUS_IO_ERROR, "mrsid IO error")
124 
125  // The format the file being read was somehow broken: a field containing
126  // an enum had an illegal value, etc. This is largely for use by those
127  // functions which need to decode specific file formats, e.g. MG3.
128 #define MG3_STATUS_FORMAT_ERROR 2005
129 LT_STATUSSTRING_ADD(MG3_STATUS_FORMAT_ERROR, "mrsid format error")
130 
131  // A versioning problem has occurred: you're trying to read a version that
132  // you don't have support for. [I don't like this one much -- probably
133  // should be diagnosed more explicitly and handled more formally. BUG.]
134 #define MG3_STATUS_BAD_VERSION 2006
135 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_VERSION, "mrsid bad version")
136 
137  // The user has requested an interrupt, e.g. via a signal from our friends
138  // as LTProcessCallback::hasBeenTerminated().
139 #define MG3_STATUS_INTERRUPT 2007
140 LT_STATUSSTRING_ADD(MG3_STATUS_INTERRUPT, "mrsid interrupt")
141 
142 #define MG3_STATUS_RESERVED_2008 2008
143 
144  // One of the arguments to the function was incorrect: a value was out of
145  // range, a pointer was NULL, etc. (Compare this to the "bad context"
146  // error, which is more of an implicit problem.)
147 #define MG3_STATUS_BAD_ARGUMENT 2009
148 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_ARGUMENT, "mrsid bad argument")
149 
150  // The context in which the function was called is incorrect: for example,
151  // trying to add a certain unique packet type to the database when there
152  // is already one of that type in there -- the caller of function is not
153  // supposed to do that. Similarly, calling initialize() twice is not
154  // allowed, nor is calling execute() with calling initialize() first.
155  // (Compare this to the "bad argument" error, which is more of an explicit
156  // problem.)
157 #define MG3_STATUS_BAD_CONTEXT 2010
158 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_CONTEXT, "mrsid bad context")
159 
160  // We tried to do something that required a password or some such, and
161  // the operation didn't succeed. This should only happen around calls
162  // into secuirty packets and the encryption library and those sorts of
163  // places.
164 #define MG3_STATUS_SECURITY_ERROR 2011
165 LT_STATUSSTRING_ADD(MG3_STATUS_SECURITY_ERROR, "mrsid security error")
166 
167  // Unlikely, but could happen. Typically would be used by wrapping a call
168  // to a potentially large malloc() call in a try region and using this
169  // value if the catch region finds an out of memory exception.
170 #define MG3_STATUS_OUT_OF_MEMORY 2012
171 LT_STATUSSTRING_ADD(MG3_STATUS_OUT_OF_MEMORY, "mrsid out of memory")
172 
173  // A C++ exception occurred that we did not expect. In some cases, the
174  // kernel will wrap a call to a foreign library in a try region so as to
175  // manually catch any errors it may throw. This status value is used when
176  // the resulting exception is not something we can readily deal with.
177 #define MG3_STATUS_UNHANDLED_EXCEPTION 2013
178 LT_STATUSSTRING_ADD(MG3_STATUS_UNHANDLED_EXCEPTION, "mrsid unhandled exception")
179 
180  // A theoretically unreachable piece of code was reached. This should
181  // be used for things like the default case of a switch statement in which
182  // all possible legal values have already been handled explicitly. This
183  // value may be used in conjunction with LT_ASSERT(0).
184 #define MG3_STATUS_NOTREACHED 2014
185 LT_STATUSSTRING_ADD(MG3_STATUS_NOTREACHED, "mrsid NOTREACHED")
186 
187  // Use only for initializing a variable. Should never be returned as an
188  // actual status value.
189 #define MG3_STATUS_INVALID 2015
190 LT_STATUSSTRING_ADD(MG3_STATUS_INVALID, "mrsid status invalid")
191 
192  // No MSEs in the image: the image cannot be optimized or streamed.
193 #define MG3_STATUS_NO_MSES 2016
194 LT_STATUSSTRING_ADD(MG3_STATUS_NO_MSES, "mrsid no MSEs")
195 
196  // The streaming client made a bad request
197  // on the server side still send the reply
198 #define MG3_STATUS_BAD_CLIENT_REQUEST 2017
199 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_CLIENT_REQUEST, "mrsid bad client request")
200 
201  // The streaming server had any error: call getServerError()
202  // on the server side still send the reply
203 #define MG3_STATUS_SERVER_ERROR 2018
204 LT_STATUSSTRING_ADD(MG3_STATUS_SERVER_ERROR, "mrsid server error")
205 
206  // The MG3 image could not be added the client plane cache
207  // because the imageInfo does not match.
208 #define MG3_STATUS_IMAGE_NOT_COMPATIBLE 2019
209 LT_STATUSSTRING_ADD(MG3_STATUS_IMAGE_NOT_COMPATIBLE, "mrsid image not compatible")
210 
211  // Singed integer overflowed
212 #define MG3_STATUS_OVERFLOW 2020
213 LT_STATUSSTRING_ADD(MG3_STATUS_OVERFLOW, "mrsid integer overflow")
214 
215  // MG4/R inputs require an alpha band
216 //#define MG4_STATUS_ALPHA_REQUIRED 2021
217 //LT_STATUSSTRING_ADD(MG4_STATUS_ALPHA_REQUIRED, "mg4 format requires alpha")
218 
219  // MG4/R composites are subject to various constraints on their tiles
220 #define MG4_STATUS_COMPOSITE_IMPEDANCE_MISMATCH 2022
222  "mrsid composite impedance mismatch")
223 
224 // MG4/R floating point image must have quantization values
225 #define MG3_STATUS_QUANTIZATION_MISSING 2023
227  "mrsid floating point image needs quantization")
228 
229 // MG4/R floating point image quantization values will cause integer overflow
230 #define MG3_STATUS_BAD_QUANTIZATION 2024
232  "mrsid floating point image quantization values will overflow")
233 
234 // MG4/R floating point image quantization values will cause integer overflow
235 #define MG3_STATUS_NEEDS_REWRITE 2025
237  "mrsid db object needs rewrite")
238 
239 // MG4/R bad band selection
240 #define MG3_STATUS_BAD_BAND_SELECTION 2026
242  "mrsid bad band selection")
243 
244 //
245 #define MG3_STATUS_BAD_NUMBER_OF_LEVELS 2027
247  "bad number of levels")
248 
249 #define MG3_STATUS_BAD_FILE 2028
251  "corrupt file")
252 
253 
254 #endif // MG3_STATUS_H
#define MG3_STATUS_BAD_CLIENT_REQUEST
Definition: mg3_status.h:198
#define MG3_STATUS_READ_ERROR
Definition: mg3_status.h:105
#define MG3_STATUS_NO_MSES
Definition: mg3_status.h:193
#define MG3_STATUS_SERVER_ERROR
Definition: mg3_status.h:203
#define MG3_STATUS_BAD_FILE
Definition: mg3_status.h:249
#define MG3_STATUS_QUANTIZATION_MISSING
Definition: mg3_status.h:225
#define MG3_STATUS_SECURITY_ERROR
Definition: mg3_status.h:164
#define MG3_STATUS_UNHANDLED_EXCEPTION
Definition: mg3_status.h:177
#define MG3_STATUS_OPEN_ERROR
Definition: mg3_status.h:117
#define MG3_STATUS_BAD_QUANTIZATION
Definition: mg3_status.h:230
#define MG3_STATUS_NOTREACHED
Definition: mg3_status.h:184
#define MG3_STATUS_INTERRUPT
Definition: mg3_status.h:139
#define MG3_STATUS_FORMAT_ERROR
Definition: mg3_status.h:128
Include file for all LizardTech sources.
#define MG3_STATUS_IMAGE_NOT_COMPATIBLE
Definition: mg3_status.h:208
#define MG3_STATUS_BAD_VERSION
Definition: mg3_status.h:134
#define MG3_STATUS_INVALID
Definition: mg3_status.h:189
#define MG3_STATUS_WRITE_ERROR
Definition: mg3_status.h:111
#define MG3_STATUS_OVERFLOW
Definition: mg3_status.h:212
#define MG3_STATUS_MAX
Definition: mg3_status.h:100
#define MG3_STATUS_BAD_ARGUMENT
Definition: mg3_status.h:147
#define MG3_STATUS_NEEDS_REWRITE
Definition: mg3_status.h:235
#define MG4_STATUS_COMPOSITE_IMPEDANCE_MISMATCH
Definition: mg3_status.h:220
#define MG3_STATUS_BAD_CONTEXT
Definition: mg3_status.h:157
#define MG3_STATUS_BAD_NUMBER_OF_LEVELS
Definition: mg3_status.h:245
#define MG3_STATUS_BASE
Definition: mg3_status.h:97
#define MG3_STATUS_IO_ERROR
Definition: mg3_status.h:122
#define MG3_STATUS_OUT_OF_MEMORY
Definition: mg3_status.h:170
#define LT_STATUSSTRING_ADD(NUM, STR)
Definition: lt_define.h:141
#define MG3_STATUS_BAD_BAND_SELECTION
Definition: mg3_status.h:240

LizardTech