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
93LT_STATUSSTRING_ADD(MG3_STATUS_BASE, "mrsid kernel BASE")
94
95#define MG3_STATUS_MAX 2999
96LT_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
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
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
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
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
124LT_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
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
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
143LT_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
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
160LT_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
166LT_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
173LT_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
181
182 // Use only for initializing a variable. Should never be returned as an
183 // actual status value.
184#define MG3_STATUS_INVALID 2015
185LT_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
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
194LT_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
199LT_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
204LT_STATUSSTRING_ADD(MG3_STATUS_IMAGE_NOT_COMPATIBLE, "mrsid image not compatible")
205
206 // Singed integer overflowed
207#define MG3_STATUS_OVERFLOW 2020
208LT_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