MrSID Decode SDK for Raster Reference Manual 9.5.4.4709

- Main Page
- Namespaces
- Classes
- Files
- Examples

- File List
- File Members

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
221 LT_STATUSSTRING_ADD(MG4_STATUS_COMPOSITE_IMPEDANCE_MISMATCH,
222 "mrsid composite impedance mismatch")
223
224 // MG4/R floating point image must have quantization values
225 #define MG3_STATUS_QUANTIZATION_MISSING 2023
226 LT_STATUSSTRING_ADD(MG3_STATUS_QUANTIZATION_MISSING,
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
231 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_QUANTIZATION,
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
236 LT_STATUSSTRING_ADD(MG3_STATUS_NEEDS_REWRITE,
237 "mrsid db object needs rewrite")
238
239 // MG4/R bad band selection
240 #define MG3_STATUS_BAD_BAND_SELECTION 2026
241 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_BAND_SELECTION,
242 "mrsid bad band selection")
243
244 //
245 #define MG3_STATUS_BAD_NUMBER_OF_LEVELS 2027
246 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_NUMBER_OF_LEVELS,
247 "bad number of levels")
248
249 #define MG3_STATUS_BAD_FILE 2028
250 LT_STATUSSTRING_ADD(MG3_STATUS_BAD_FILE,
251 "corrupt file")
252
253
254 #endif // MG3_STATUS_H

LizardTech