libsswf: sswf::ErrorManager Class Reference

# sswf::ErrorManager Class Reference

This class helps the user to know what errors occur in the library. More...

`#include <libsswf.h>`

Inheritance diagram for sswf::ErrorManager:

List of all members.

## Public Types
enum | error_code_t { ERROR_CODE_NONE = 0, ERROR_CODE_ACTION_OVERFLOW, ERROR_CODE_ALPHA_MISMATCH, ERROR_CODE_BAD_STATE_FLAGS, ERROR_CODE_BAD_STRING, ERROR_CODE_BUTTON_MISSING_STATE, ERROR_CODE_CANNOT_CHANGE_STYLE, ERROR_CODE_CHILDREN_NOT_SUPPORTED, ERROR_CODE_COMPRESSED_SOUND_8BITS, ERROR_CODE_EMPTY_POSITION_RANGE, ERROR_CODE_ENDED_ACTION_SCRIPT, ERROR_CODE_END_OF_STATES, ERROR_CODE_ENHANCED_LINE_REQUIRES_ALPHA, ERROR_CODE_ENVELOPE_EXISTS, ERROR_CODE_ENVELOPE_OVERFLOW, ERROR_CODE_ERRONEOUS_FORMAT, ERROR_CODE_FILE_NOT_FOUND, ERROR_CODE_FORMAT_LOCKED, ERROR_CODE_GLYPH_DEFINED_TWICE, ERROR_CODE_ICONV_ENCODER_NOT_AVAILABLE, ERROR_CODE_ICONV_FAILED, ERROR_CODE_IO, ERROR_CODE_INCOMPATIBLE_CHILD, ERROR_CODE_INCOMPATIBLE_MORPH, ERROR_CODE_INTERNAL_ERROR, ERROR_CODE_INVALID_DEPTH, ERROR_CODE_INVALID_EM_SQUARE, ERROR_CODE_INVALID_FILL_PARAMETER, ERROR_CODE_INVALID_FOCAL, ERROR_CODE_INVALID_GLYPH, ERROR_CODE_INVALID_IDENTIFIER, ERROR_CODE_INVALID_IMAGE, ERROR_CODE_INVALID_INTERPOLATION_MODE, ERROR_CODE_INVALID_LINE_INFO, ERROR_CODE_INVALID_MORPH_INDEX, ERROR_CODE_INVALID_OBJECT_EXPORTED, ERROR_CODE_INVALID_POSITION, ERROR_CODE_INVALID_SHAPE, ERROR_CODE_INVALID_SPREAD_MODE, ERROR_CODE_INVALID_SPRITE_DEFINITION, ERROR_CODE_INVALID_STYLE, ERROR_CODE_INVALID_TEXT_SETUP, ERROR_CODE_JPEG, ERROR_CODE_LOOP_ZERO, ERROR_CODE_MISSING_FRAME_NAME, ERROR_CODE_MISSING_SHAPE, ERROR_CODE_MORPH_GRADIENT_LIMIT, ERROR_CODE_MORPH_REQUIRES_ALPHA, ERROR_CODE_NAME_TOO_LONG, ERROR_CODE_NEGATIVE_MITER, ERROR_CODE_NO_FOCAL_WITH_MORPH, ERROR_CODE_NO_HEADER, ERROR_CODE_NO_STATES, ERROR_CODE_NO_SUCH_GLYPH, ERROR_CODE_LABEL_NOT_FOUND, ERROR_CODE_LABEL_OVERFLOW, ERROR_CODE_MORPH_MISMATCH, ERROR_CODE_NOT_ENOUGH_DATA, ERROR_CODE_OBJECT_NOT_FOUND, ERROR_CODE_REGISTER_OVERFLOW, ERROR_CODE_SIZE_MISMATCH, ERROR_CODE_START_SOUND_NO_INFO, ERROR_CODE_TOO_MANY_STYLES, ERROR_CODE_TWO_OR_MORE_JPEGTABLES, ERROR_CODE_TWO_OR_MORE_METADATA, ERROR_CODE_UNEXPECTED_EVENT_FLAG, ERROR_CODE_UNKNOWN_ACTION, ERROR_CODE_UNKNOWN_FORMAT, ERROR_CODE_UNKNOWN_IMMEDIATE_DATA_TYPE, ERROR_CODE_UNKNOWN_OBJECT_EXPORTED, ERROR_CODE_UNKNOWN_TAG, ERROR_CODE_UNSUPPORTED_IMAGE_FORMAT, ERROR_CODE_UNSUPPORTED_SOUND_FORMAT, ERROR_CODE_UNSUPPORTED_ZONE_COUNT, ERROR_CODE_VERSION_UNSATISFIED, ERROR_CODE_VOLUME_OUT_OF_RANGE, ERROR_CODE_max }
| Enumeration of all the SSWF errors. More...
## Public Member Functions
int | Count (void) const
| Retrieve the value of the current error counter.
| ErrorManager (void)
| Initializes an error manager.
error_code_t | OnError (error_code_t errcode, const char *message,...) const
| Called whenever an error occurs.
error_code_t | OnError (error_code_t errcode, const char *message, va_list ap) const
| Called whenever an error occurs.
void | Reset (void)
| Reset the error counter.
ErrorHandler * | SetErrorHandler (ErrorHandler *error_handler)
| Defines a pointer to a user error handler.
## Static Public Member Functions
static error_code_t | KeepFirst (error_code_t a, error_code_t b)
| Keep the first error if not NONE, otherwise keep the second.
## Private Attributes
int | f_error_count
ErrorHandler * | f_error_handler
## Classes
class | ErrorHandler
| A sub-class to derive from to receive errors. More...
class | InternalErrorException
| Class defined to throw exceptions in the library. More...
class | OutOfBoundsErrorException

## Detailed Description

This class was introduced in version 1.8.0.

The ErrorManager class is used to let the library call one of your function to handle the error (i.e. so you can print out the message, exit your program, etc.)

The callback happens at the time the error occurs.

At this time, only the TagHeader derives from this object. All the tags and the Actions call the sswf::ErrorManager::OnError() function.

See also:
  sswf::TagHeader

## Member Enumeration Documentation

enum sswf::ErrorManager::error_code_t

This enumeration is a list of the different errors that can occur while using the SSWF library. Most errors are considered bad and should not happen.

To catch the errors, derive from the ErrorHandler sub-class and implement the ErrorManager::ErrorHandler::OnError(error_code_t errcode, const char *message, va_list args) function.

If your function generates multiple errors or call sub-functions which themselves can generate multiple errors, then you can use the KeepFirst(error_code_t a, error_code_t b) function to make sure that you keep the first error.

            ec = ErrorManager::ERROR_CODE_NONE;
            ...
            ec = ErrorManager::KeepFirst(ec, SaveMore(obj[idx]));
            ...
            return ec;

Enumerator:

  ERROR_CODE_NONE | No error occured. This value should never be passed via the OnError() function. However, some functions return an error and this value can be used when the function does not generate an error.
  ERROR_CODE_ACTION_OVERFLOW | Trying to add too many actions in the same buffer. Action buffers are limited in the number of actions they can record. In general this is about 64Kb of action data including constant strings, dictionaries, etc. In some circumstances, only 255 bytes are available.
  ERROR_CODE_ALPHA_MISMATCH |
  ERROR_CODE_BAD_STATE_FLAGS |
  ERROR_CODE_BAD_STRING |
  ERROR_CODE_BUTTON_MISSING_STATE | Buttons do not work without at least one state. This errors tells you that you are trying to save a button which has no states whatsoever.
  ERROR_CODE_CANNOT_CHANGE_STYLE |
  ERROR_CODE_CHILDREN_NOT_SUPPORTED | Tag passed as parent cannot accept children. Whenever a tag is created, you need to specify a parent tag. However, most tags do not accept children. These tags will generate this error when used as a parent of another tag. At this time, only an sswf::TagHeader and sswf::TagSprite can be used as a parent.
  ERROR_CODE_COMPRESSED_SOUND_8BITS | Library cannot compress 8 bits sound data. Only 16 bits sound data can be compressed at this time. The library may later be capable of converting the 8 bits sound data in a 16 bits buffer ready for compression. See also: sswf::ErrorManager::ERROR_CODE_START_SOUND_NO_INFO sswf::ErrorManager::ERROR_CODE_UNSUPPORTED_SOUND_FORMAT
  ERROR_CODE_EMPTY_POSITION_RANGE |
  ERROR_CODE_ENDED_ACTION_SCRIPT | The END action was found before the end. This error occurs when the list of actions includes an END action within the list instead of being at the end. There is usually no need for you to include the END action so just don't do so and let the system close your list of actions as expected.
  ERROR_CODE_END_OF_STATES |
  ERROR_CODE_ENHANCED_LINE_REQUIRES_ALPHA |
  ERROR_CODE_ENVELOPE_EXISTS |
  ERROR_CODE_ENVELOPE_OVERFLOW |
  ERROR_CODE_ERRONEOUS_FORMAT |
  ERROR_CODE_FILE_NOT_FOUND |
  ERROR_CODE_FORMAT_LOCKED |
  ERROR_CODE_GLYPH_DEFINED_TWICE |
  ERROR_CODE_ICONV_ENCODER_NOT_AVAILABLE |
  ERROR_CODE_ICONV_FAILED |
  ERROR_CODE_IO |
  ERROR_CODE_INCOMPATIBLE_CHILD | Parent refused that child (by type). Whenever a tag is created, you need to specify a parent tag; except for the sswf::TagHeader object which represents the root tag. The parent tag checks whether it can accept the child depending on its type. If not, an error is generated and the new tag will have no parent. The only two tags which currently accept children are the sswf::TagHeader and sswf::TagSprite. The sswf::TagSprite has rather limited number of tags which can be added as a child.
  ERROR_CODE_INCOMPATIBLE_MORPH |
  ERROR_CODE_INTERNAL_ERROR | An error which should never occur! This indicates a problem in logic in the library. Please report such errors if you can produce them!
  ERROR_CODE_INVALID_DEPTH |
  ERROR_CODE_INVALID_EM_SQUARE |
  ERROR_CODE_INVALID_FILL_PARAMETER |
  ERROR_CODE_INVALID_FOCAL |
  ERROR_CODE_INVALID_GLYPH |
  ERROR_CODE_INVALID_IDENTIFIER |
  ERROR_CODE_INVALID_IMAGE |
  ERROR_CODE_INVALID_INTERPOLATION_MODE |
  ERROR_CODE_INVALID_LINE_INFO |
  ERROR_CODE_INVALID_MORPH_INDEX |
  ERROR_CODE_INVALID_OBJECT_EXPORTED |
  ERROR_CODE_INVALID_POSITION |
  ERROR_CODE_INVALID_SHAPE |
  ERROR_CODE_INVALID_SPREAD_MODE |
  ERROR_CODE_INVALID_SPRITE_DEFINITION |
  ERROR_CODE_INVALID_STYLE |
  ERROR_CODE_INVALID_TEXT_SETUP |
  ERROR_CODE_JPEG |
  ERROR_CODE_LOOP_ZERO |
  ERROR_CODE_MISSING_FRAME_NAME | A required frame name is missing. Some objects such as the WaitForFrame action need to be given the name of a frame to properly be defined. This error occurs if the name was not defined or set to the empty string.
  ERROR_CODE_MISSING_SHAPE |
  ERROR_CODE_MORPH_GRADIENT_LIMIT |
  ERROR_CODE_MORPH_REQUIRES_ALPHA |
  ERROR_CODE_NAME_TOO_LONG |
  ERROR_CODE_NEGATIVE_MITER |
  ERROR_CODE_NO_FOCAL_WITH_MORPH |
  ERROR_CODE_NO_HEADER |
  ERROR_CODE_NO_STATES |
  ERROR_CODE_NO_SUCH_GLYPH |
  ERROR_CODE_LABEL_NOT_FOUND | No label corresponding to a branch instruction was found. Branch instructions specify the name of a label to which they jump. No label with that name could be found in the label block of action at the same level. This happens when the label was not added or when the label is in a sub-block or a parent block (i.e. you cannot branch from within a With action block to outside of that block.)
  ERROR_CODE_LABEL_OVERFLOW | A label is too far from a corresponding branch. The distance between a label and a corresponding branch is limited by the offset one can use with the branch instructions. If the label is too far (i.e. more than 32Kb before or after), the branch cannot be used and the library generates this error.
  ERROR_CODE_MORPH_MISMATCH |
  ERROR_CODE_NOT_ENOUGH_DATA |
  ERROR_CODE_OBJECT_NOT_FOUND | An object or a tag could not be found. Different functions use references to other objects or tags. This error occurs if a named object or tag cannot be found in the list of tags. Verify the names and try again.
  ERROR_CODE_REGISTER_OVERFLOW | Too large a register number was specified. Registers are limited to 0, 1, 2 and 3 in older versions of SWF. In version 7 and over, registers 0 to 255 can be used (255 seems to be special in some ways though!) within a function. If a register number larger than what is allowed is used, the library generates this error.
  ERROR_CODE_SIZE_MISMATCH |
  ERROR_CODE_START_SOUND_NO_INFO | Cannot create a StartSound tag without information about the sound. This error occurs when a StartSound tag is saved without some sound information (i.e. what sound needs to be started?!) See also: sswf::ErrorManager::ERROR_CODE_COMPRESSED_SOUND_8BITS sswf::ErrorManager::ERROR_CODE_UNSUPPORTED_SOUND_FORMAT
  ERROR_CODE_TOO_MANY_STYLES |
  ERROR_CODE_TWO_OR_MORE_JPEGTABLES |
  ERROR_CODE_TWO_OR_MORE_METADATA |
  ERROR_CODE_UNEXPECTED_EVENT_FLAG |
  ERROR_CODE_UNKNOWN_ACTION |
  ERROR_CODE_UNKNOWN_FORMAT |
  ERROR_CODE_UNKNOWN_IMMEDIATE_DATA_TYPE |
  ERROR_CODE_UNKNOWN_OBJECT_EXPORTED |
  ERROR_CODE_UNKNOWN_TAG |
  ERROR_CODE_UNSUPPORTED_IMAGE_FORMAT |
  ERROR_CODE_UNSUPPORTED_SOUND_FORMAT | The library does not currently support this sound format. Thought the specified sound format is a valid SWF format, it is not currently supported by the library. See also: sswf::ErrorManager::ERROR_CODE_COMPRESSED_SOUND_8BITS sswf::ErrorManager::ERROR_CODE_START_SOUND_NO_INFO
  ERROR_CODE_UNSUPPORTED_ZONE_COUNT |
  ERROR_CODE_VERSION_UNSATISFIED |
  ERROR_CODE_VOLUME_OUT_OF_RANGE |
  ERROR_CODE_max | The last error + 1. This value represents the last error + 1.

## Constructor & Destructor Documentation

ErrorManager::ErrorManager | ( | void |  | ) |

The constructor sets the number of errors to zero and the error handler pointer to null.

References f_error_count, and f_error_handler.

## Member Function Documentation

int ErrorManager::Count | ( | void |  | ) | const

This function can be used to retrieve the current error counter. This is set to zero on creation of an error manager and whenever the Reset() function is called.

You can use this counter to print out the total number of errors which occured once a function you called returns.

Returns:
  The number of errors so far or zero when no errors occured

See also:
  sswf::ErrorManager::ErrorManager(void)

  sswf::ErrorManager::OnError(error_code_t errcode, const char *message, va_list args) const

  sswf::ErrorManager::OnError(error_code_t errcode, const char *message, ...) const

  sswf::ErrorManager::Reset(void)

References f_error_count.

ErrorManager::error_code_t ErrorManager::KeepFirst | ( | error_code_t | a,
|  | error_code_t | b |
| ) |  |  | `[static]`

This function returns the first error code (a) if it is not ErrorManager::ERROR_CODE_NONE, otherwise it returns the second error code (b).

This is used in many functions where an error does not stop the function processing. Instead the very first error generated is kept and returned to the caller.

This is especially useful to generate as many errors as possible without requiring the user to re-run the Save() process 100 times if there are 100 errors.

See also:
  sswf::ErrorManager::error_code_t

  sswf::ErrorManager::OnError(error_code_t errcode, const char *msg)

References ERROR_CODE_NONE.

Referenced by sswf::TagHeader::Save(), sswf::TagExport::Save(), sswf::TagEditText::Save(), sswf::Action::Save(), sswf::ActionWaitForFrame::SaveData(), sswf::ActionURL::SaveData(), sswf::ActionTry::SaveData(), sswf::ActionPushData::SaveData(), sswf::ActionFunction::SaveData(), and sswf::Action::SaveList().

ErrorManager::error_code_t ErrorManager::OnError | ( | error_code_t | errcode,
|  | const char * | message,
|  |  | ... |
| ) |  |  | const

This function is called by the library whenever an error occurs (you can also call it yourself).

The message and following arguments are defined as for printf(3C).

This function simple calls the sswf::ErrorManager::OnError(error_code_t errcode, const char *message, va_list args) const

Note:
  This function is not visible in the C library.

Parameters:

  `[in]` | errcode | On of the ERROR_CODE_... values
  `[in]` | message | The message, can include formatting characters
  `[in]` | ... | The arguments for the message formatting characters

Returns:
  An error code; usually the input error code

See also:
  sswf::ErrorManager::Count(void) const

  sswf::ErrorManager::OnError(error_code_t errcode, const char *message, va_list args) const

Reimplemented in sswf::TagHeader.

References OnError().

ErrorManager::error_code_t ErrorManager::OnError | ( | error_code_t | errcode,
|  | const char * | message,
|  | va_list | args |
| ) |  |  | const

This function is called by the library whenever an error occurs (you can also call it yourself).

The message and following arguments are defined as for vprintf(3C).

The error code is defined as one of the ErrorManager error code.

Each time this function is called, the number of errors is increased. You can use the sswf::ErrorManager::Count(void) const function to retrieve the value of the current counter.

There is no level for errors. All are considered as errors, some are fatal meaning that the process in progress will end immediately.

Note:
  The error code returned by this function is usually the input error code. The user handler may, however, modify that value and return any other error code including ERROR_CODE_NONE to (try to) cancel the error.

Parameters:

  `[in]` | errcode | On of the ERROR_CODE_... values
  `[in]` | message | The message, can include formatting characters
  `[in]` | args | The arguments for the message formatting characters

Returns:
  An error code; usually the input error code

See also:
  sswf::ErrorManager::Count(void) const

  sswf::ErrorManager::OnError(error_code_t errcode, const char *message, ...) const

Reimplemented in sswf::TagHeader.

References f_error_count, f_error_handler, and sswf::ErrorManager::ErrorHandler::OnError().

Referenced by sswf::SoundInfo::AddEnvelope(), sswf::TagHeader::OnError(), OnError(), sswf::Style::operator==(), sswf::SoundInfo::PreSave(), sswf::TagHeader::Save(), sswf::State::Save(), sswf::Style::Save(), sswf::TagHeader::SaveEncodedString(), sswf::Style::SetBitmap(), sswf::Style::SetColor(), sswf::State::SetFlags(), sswf::Style::SetGradient(), sswf::Style::SetGradientFocal(), sswf::Style::SetGradientModes(), sswf::Style::SetLine(), sswf::Style::SetLineCaps(), sswf::Style::SetLineFillStyle(), sswf::Style::SetLineJoin(), sswf::SoundInfo::SetLoop(), sswf::Style::SetMatrix(), sswf::SoundInfo::SetRange(), sswf::SoundInfo::SetSoundID(), and sswf::Style::SetType().

void ErrorManager::Reset | ( | void |  | ) |

This function resets the error counter. The counter is set to zero on creation of an ErrorManager object. It is increased each time the OnError() function is called and can be retrieved using the Count() function.

See also:
  sswf::ErrorManager::ErrorManager(void)

  sswf::ErrorManager::OnError(error_code_t errcode, const char *message, va_list args) const

  sswf::ErrorManager::OnError(error_code_t errcode, const char *message, ...) const

  sswf::ErrorManager::Count(void) const

References f_error_count.

ErrorManager::ErrorHandler * ErrorManager::SetErrorHandler | ( | ErrorManager::ErrorHandler * | error_handler | ) |

This function is called to define the pointer to use as the error handler pointer.

The function returns the current error handler. You may either call it or ignore it from within your function. By calling it you in effect create a chain and all error handlers can be called in this way.

Note:
  You should save the returned pointer and restore it when you are done with your pointer. However, this is not a 100% viable scheme since another function could add another pointer after you put yours. Then restoring would in effect prevent the newer function from being called.

My point of view is that it won't be necessary to put more than one error handler in the error manager. If need be, create a class which handles one to many a bit like the following code:

            class MyStuff
            {
            public:
                    void AddHandler(ErrorHandler *handler)
                    {
                            f_handlers += handler;
                    }
                    std::vector<ErrorHandler*>      f_handlers;
                    error_code_t OnError(error_code_t errcode, ...)
                    {
                            for(i = 0; i < f_handlers.size(); ++i) {
                                    f_handlers[i].OnError(errcode, ...);
                            }
                            return errcode;
                    }
            };

Warning:
  This function is not visible in the C library. Instead, you need to use the specialized function:

     void sswf_error_manager_set_callback(struct SSWF_ErrorManager *error_manager, sswf_error_manager_on_error_callback callback);

The error_manager pointer is taken by casting your tag header as required.

Parameters:

  `[in]` | error_handler | The handler to attach to this error manager

Returns:
  The previous error handler

References f_error_handler.

## Member Data Documentation

int sswf::ErrorManager::f_error_count`[mutable, private]`

Referenced by Count(), ErrorManager(), OnError(), and Reset().

ErrorHandler* sswf::ErrorManager::f_error_handler`[private]`

Referenced by ErrorManager(), OnError(), and SetErrorHandler().

The documentation for this class was generated from the following files:

- libsswf.h
- libsswf_errormanager.c++