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