/* $Id$ */
/* //////////////////////////////////////////////////////////////////////////
//                                                                         //
// This code is Copyright (c) 2005 LizardTech, Inc, 1008 Western Avenue,   //
// Suite 200, Seattle, WA 98104.  Unauthorized use or distribution         //
// prohibited.  Access to and use of this code is permitted only under     //
// license from LizardTech, Inc.  Portions of the code are protected by    //
// US and foreign patents and other filings. All Rights Reserved.          //
//                                                                         //
////////////////////////////////////////////////////////////////////////// */     
/* PUBLIC */

#ifndef MG3_STATUS_H
#define MG3_STATUS_H

// lt_lib_base
#include "lt_base.h"

//
// On the Usage of Status Codes
// ----------------------------
//
// Status codes are used to report failure modes of an "unnatural" or
// "unexpected" nature.  They are to be used when something happens that is
// not part of the normal course of events.  They often are used in places
// where other, more mature programmers would throw exceptions.
//
// Applications that don't otherwise handle failure conditions should feel
// free to return these status values as exit codes back out to the shell.
// The kernel sample apps follow this convention.
//
// These status values are to be generally applicable across the whole
// kernel.  They are not to be specific to a small set of cases ("the third
// parameter to this function was greater than 10"), nor are they to be
// overly generic ("an error occurred").
//
// The intent of status codes is to both signal to the user that something
// bad happened and to provide a mechanism for aborting execution gracefully.
// It is *not* the intent that these status codes would allow a caller to
// programmatically diagnose the error and retry the operation -- that would
// require a much richer semantics.  To paraphrase Nathan, the kernel is
// designed for non-dummies.
//
// Status codes are *not* to be used for indicating negative success, such as
// in a function that attempts to find within a file a packet of some
// specified type and return a pointer to that packet.  That function should
// return the "ok" status and use an "out" parameter to return the pointer,
// either set properly (packet was found) or as NULL (packet was not found).
// Finding packets in a file involves underlying I/O operations, and
// therefore is potentially a status-code-inducing operation.  (Contrast this
// with a function which is just looking for some element in a list -- a
// standard list search probably won't entail any operations that might fail
// in bad ways, so returning the pointer directly is okay.)
//
// By convention, status codes are only to be used as function return values,
// never as parameters.
//
// If a function returns a status code, it's value MUST be checked for
// success and handled appropriately.  If you are unsure how to handle the
// returned result, the least you should do is pass the status code back up
// the stack.
//
// Someday, we might unify these status codes with those used by Sparkle, the
// Core, the Stream library, etc.
//
// If you feel the urge to add a New status code, stop and consider your
// situation carefully.  Can you use one of the ones already there?  Could
// your New one replace an existing one?  Will your New one be useful in some
// case other than the current one you have in mind?  Have you talked it over
// with the other kernel folks yet?
//
// There is no "unknown" status code represented.  Such a value would defeat
// the whole purpose.  Lame-o.
//
// Recall that the kernel does not use explicit exception handling anywhere.
// Ever.  At all.  Period.  We use status codes instead.
//
// Only the "OK" status code is given a numeric value (zero).  Programmers
// should not rely on the numeric values or orderings of the enum values.
//
// The "OK()" function should always be used to test success.  The idiom of
// choice is:
//   stat = foo();
//   if (!OK(stat)) return foo;
//
// The "invalid" status is to be used only for initializing variables of type
// MG3Status.  No well-behaved function should ever return the "invalid"
// status.
//
// Note well that the meaning of each status code is documented.  We'd like
// to keep it that way.
//


// note "name()" function is declared in MG3Types class

#define MG3_STATUS_BASE  2000
LT_STATUSSTRING_ADD(MG3_STATUS_BASE, "mrsid kernel BASE")

#define MG3_STATUS_MAX   2999
LT_STATUSSTRING_ADD(MG3_STATUS_MAX, "mrsid kernel MAX")

   // A "read" I/O operation failed: you hit EOF unexpectedly because the
   // file was corrupt, someone unplugged your network cable on you, etc.
#define MG3_STATUS_READ_ERROR                      2001
LT_STATUSSTRING_ADD(MG3_STATUS_READ_ERROR, "mrsid read error")

   // A "write" I/O operation failed: someone unplugged your network cable on
   // you, you don't have write permission, the stream just ain't writable,
   // etc.
#define MG3_STATUS_WRITE_ERROR                     2002
LT_STATUSSTRING_ADD(MG3_STATUS_WRITE_ERROR, "mrsid write error")

   // An "open" I/O operation failed: someone unplugged your network cable
   // (again...), you don't have permission to create the file, you don't
   // have write access to the file, etc.
#define MG3_STATUS_OPEN_ERROR                      2003
LT_STATUSSTRING_ADD(MG3_STATUS_OPEN_ERROR, "mrsid open error")

   // An I/O operation failed, for some reason other than read, write, or
   // open: for example, seek() or close().
#define MG3_STATUS_IO_ERROR                        2004
LT_STATUSSTRING_ADD(MG3_STATUS_IO_ERROR, "mrsid IO error")

   // The format the file being read was somehow broken: a field containing
   // an enum had an illegal value, etc.  This is largely for use by those
   // functions which need to decode specific file formats, e.g. MG3.
#define MG3_STATUS_FORMAT_ERROR                    2005
LT_STATUSSTRING_ADD(MG3_STATUS_FORMAT_ERROR, "mrsid format error")

   // A versioning problem has occurred: you're trying to read a version that
   // you don't have support for.  [I don't like this one much -- probably
   // should be diagnosed more explicitly and handled more formally. BUG.]
#define MG3_STATUS_BAD_VERSION                     2006
LT_STATUSSTRING_ADD(MG3_STATUS_BAD_VERSION, "mrsid bad version")

   // The user has requested an interrupt, e.g. via a signal from our friends
   // as LTProcessCallback::hasBeenTerminated().
#define MG3_STATUS_INTERRUPT                       2007
LT_STATUSSTRING_ADD(MG3_STATUS_INTERRUPT, "mrsid interrupt")

#define MG3_STATUS_RESERVED_2008                   2008

   // One of the arguments to the function was incorrect: a value was out of
   // range, a pointer was NULL, etc.  (Compare this to the "bad context"
   // error, which is more of an implicit problem.)
#define MG3_STATUS_BAD_ARGUMENT                    2009
LT_STATUSSTRING_ADD(MG3_STATUS_BAD_ARGUMENT, "mrsid bad argument")

   // The context in which the function was called is incorrect: for example,
   // trying to add a certain unique packet type to the database when there
   // is already one of that type in there -- the caller of function is not
   // supposed to do that.  Similarly, calling initialize() twice is not
   // allowed, nor is calling execute() with calling initialize() first.
   // (Compare this to the "bad argument" error, which is more of an explicit
   // problem.)
#define MG3_STATUS_BAD_CONTEXT                     2010
LT_STATUSSTRING_ADD(MG3_STATUS_BAD_CONTEXT, "mrsid bad context")

   // We tried to do something that required a password or some such, and
   // the operation didn't succeed.  This should only happen around calls
   // into secuirty packets and the encryption library and those sorts of
   // places.
#define MG3_STATUS_SECURITY_ERROR                  2011
LT_STATUSSTRING_ADD(MG3_STATUS_SECURITY_ERROR, "mrsid security error")

   // Unlikely, but could happen.  Typically would be used by wrapping a call
   // to a potentially large malloc() call in a try region and using this
   // value if the catch region finds an out of memory exception.
#define MG3_STATUS_OUT_OF_MEMORY                   2012
LT_STATUSSTRING_ADD(MG3_STATUS_OUT_OF_MEMORY, "mrsid out of memory")

   // A C++ exception occurred that we did not expect.  In some cases, the
   // kernel will wrap a call to a foreign library in a try region so as to
   // manually catch any errors it may throw.  This status value is used when
   // the resulting exception is not something we can readily deal with.
#define MG3_STATUS_UNHANDLED_EXCEPTION             2013
LT_STATUSSTRING_ADD(MG3_STATUS_UNHANDLED_EXCEPTION, "mrsid unhandled exception")

   // A theoretically unreachable piece of code was reached.  This should
   // be used for things like the default case of a switch statement in which
   // all possible legal values have already been handled explicitly.  This
   // value may be used in conjunction with LT_ASSERT(0).
#define MG3_STATUS_NOTREACHED                      2014
LT_STATUSSTRING_ADD(MG3_STATUS_NOTREACHED, "mrsid NOTREACHED")

   // Use only for initializing a variable.  Should never be returned as an
   // actual status value.
#define MG3_STATUS_INVALID                         2015
LT_STATUSSTRING_ADD(MG3_STATUS_INVALID, "mrsid status invalid")

   // No MSEs in the image: the image cannot be optimized or streamed.
#define MG3_STATUS_NO_MSES                         2016
LT_STATUSSTRING_ADD(MG3_STATUS_NO_MSES, "mrsid no MSEs")

   // The streaming client made a bad request
   // on the server side still send the reply
#define MG3_STATUS_BAD_CLIENT_REQUEST              2017
LT_STATUSSTRING_ADD(MG3_STATUS_BAD_CLIENT_REQUEST, "mrsid bad client request")

   // The streaming server had any error: call getServerError()
   // on the server side still send the reply
#define MG3_STATUS_SERVER_ERROR                    2018
LT_STATUSSTRING_ADD(MG3_STATUS_SERVER_ERROR, "mrsid server error")

   // The MG3 image could not be added the client plane cache
   // because the imageInfo does not match.
#define MG3_STATUS_IMAGE_NOT_COMPATIBLE            2019
LT_STATUSSTRING_ADD(MG3_STATUS_IMAGE_NOT_COMPATIBLE, "mrsid image not compatible")

   // Singed integer overflowed
#define MG3_STATUS_OVERFLOW                        2020
LT_STATUSSTRING_ADD(MG3_STATUS_OVERFLOW, "mrsid integer overflow")

   // MG4/R inputs require an alpha band
//#define MG4_STATUS_ALPHA_REQUIRED                  2021
//LT_STATUSSTRING_ADD(MG4_STATUS_ALPHA_REQUIRED, "mg4 format requires alpha")

   // MG4/R composites are subject to various constraints on their tiles
#define MG4_STATUS_COMPOSITE_IMPEDANCE_MISMATCH    2022
LT_STATUSSTRING_ADD(MG4_STATUS_COMPOSITE_IMPEDANCE_MISMATCH,
                    "mrsid composite impedance mismatch")

// MG4/R floating point image must have quantization values
#define MG3_STATUS_QUANTIZATION_MISSING            2023
LT_STATUSSTRING_ADD(MG3_STATUS_QUANTIZATION_MISSING,
                    "mrsid floating point image needs quantization")

// MG4/R floating point image quantization values will cause integer overflow 
#define MG3_STATUS_BAD_QUANTIZATION                2024
LT_STATUSSTRING_ADD(MG3_STATUS_BAD_QUANTIZATION,
                    "mrsid floating point image quantization values will overflow")

// MG4/R floating point image quantization values will cause integer overflow 
#define MG3_STATUS_NEEDS_REWRITE                   2025
LT_STATUSSTRING_ADD(MG3_STATUS_NEEDS_REWRITE,
                    "mrsid db object needs rewrite")

// MG4/R bad band selection 
#define MG3_STATUS_BAD_BAND_SELECTION              2026
LT_STATUSSTRING_ADD(MG3_STATUS_BAD_BAND_SELECTION,
                    "mrsid bad band selection")


#endif // MG3_STATUS_H