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

Extensis