Made to Order Software Corporation Logo

libsswf: sswf::TagHeader Class Reference

The header or root of the SWF movie. More...

#include <libsswf.h>

Inheritance diagram for sswf::TagHeader:

:TagBase :ErrorManager :MemoryManager

List of all members.

Public Types

enum  load_flag_t { LOAD_FLAG_IGNORE_UNKNOWN_TAGS = 0x0001 }

Public Member Functions

ErrorManager::error_code_t DefineMinimumVersion (int &min_version)
 Define the minimum SWF version required for a successful Save().
const SRectangleFrame (void) const
 Retrieve the current frame sizes.
const FactoryGetFactory (TagBase::swf_tag_t tag) const
 Return the this factory priority.
ErrorManager::error_code_t Load (const Data &data, load_flag_t flags)
 Load a Flash file.
virtual void MinimumVersion (unsigned char version)
 Defines what the minimum version shall be to save this movie.
sswf_id_t NextID (void)
 Get the next unique identifier.
virtual ErrorManager::error_code_t OnError (ErrorManager::error_code_t errcode, const char *message,...) const
 Call the error manager OnError() function.
virtual ErrorManager::error_code_t OnError (ErrorManager::error_code_t errcode, const char *message, va_list ap) const
 Call the error manager OnError() function.
float Rate (void) const
 Set the speed at which the frames are to be played.
void RemoveID (sswf_id_t id)
 Release an identifier previously allocated with NextID.
virtual ErrorManager::error_code_t Save (Data &data)
 Save the movie in a Data buffer.
ErrorManager::error_code_t SaveEncodedString (Data &data, const char *string)
 Save a string in a movie with the proper encoding.
void SetAutoOrder (bool auto_order=true)
 Let the library re-order the objects.
void SetCompress (bool compress=true)
 Set whether the movie should be compressed or not.
void SetFrame (const SRectangle &rect)
 Defines the size of the output.
void SetMaximumVersion (unsigned char version)
 Set the maximum version for the output movie.
void SetMinimumVersion (unsigned char version)
 Set the minimum version for the output movie.
void SetOutputEncoding (const char *encoding)
 Defines the encoding of the entire movie.
void SetRate (float rate)
 Set the speed at which the frames are to be played.
void SetUseNetwork (bool use_network=true)
 Whether a locally played movie can use the network.
void SetVersion (unsigned char version)
 Set the version of the output movie.
 TagHeader (void)
 Initialize the TagHeader object.
virtual swf_type_t TypeFlags (void) const
 Return the type flags as defined in TagBase.
virtual unsigned char Version (void) const
 Read the current output movie version.
virtual ~TagHeader ()
 Destroy a TagHeader object.

Protected Member Functions

virtual ErrorManager::error_code_t OnNewChild (const char *child_name) const
 Check that the child is not a TagHeader.
virtual ErrorManager::error_code_t ParseTag (TagBase::swf_tag_t tag, const Data &data)
 Defined because it is required.
virtual ErrorManager::error_code_t PreSave (void)
 Prepare the children objects to be saved.

Private Types

enum  load_status_t {

Private Attributes

bool f_auto_order
bool f_compress
bool f_compressed_input
size_t f_file_size
SRectangle f_frame
bool f_has_jpegtables
bool f_has_metadata
iconv_t f_iconvertor
bool f_iconvertor_open
load_status_t f_load_status
unsigned char f_maximum_version
unsigned char f_min_version
unsigned char f_minimum_version
sswf_id_t f_next_id
char * f_output_encoding
size_t f_position
float f_rate
size_t f_sprite_size
swf_tag_t f_tag
Data f_tag_data
size_t f_tag_size
bool f_use_network
unsigned char f_version
z_stream f_zstream


class  Factory

Detailed Description

The TagHeader class is used as the root of an SWF movie. In order to create a movie you must first create a TagHeader. This is the parent tag of most of the other tags (the exception, at this time, are the objects put in a Sprite; but Sprites are defined in a TagHeader)

Use the SetCompress(), SetUseNetwork(), SetVersion(), SetMaximumVersion() SetAutoOrder(), SetFrame(), SetOutputEncoding(), SetRate() to initialize the movie.

Call Save() once all the tags have been saved in the movie.

See also:
SWF Alexis' Reference—The File Header

Member Enumeration Documentation



Constructor & Destructor Documentation

TagHeader::TagHeader ( void   ) 

The TagHeader create a movie with a frame set to 0, 100, 0, 100 by default.

The rate is set to 30.0 frames a second.

There is no minimum, maximum or specific version required.

By default, the use of the network by a movie played locally is turned off. Yet, this is not fully enforced since it does not force the library into creating a version 8 movie. Use SetVersion() to force a version 8 movie.

References f_auto_order, f_compress, f_frame, f_has_jpegtables, f_has_metadata, f_iconvertor, f_iconvertor_open, f_load_status, f_maximum_version, f_min_version, f_minimum_version, f_next_id, f_output_encoding, f_rate, f_use_network, f_version, HEADER_LOAD_STATUS_RESET, and sswf::SRectangle::Set().

TagHeader::~TagHeader (  )  [virtual]

In particular, the destructor ensures that if an iconv(3) handle has been created, it gets closed.

The TagHeader derives from the TagBase which itself derives from the MemoryManager. This one is used to manage all the memory allocation and the destructor will release any buffer the TagHeader has allocated.

See also:
TagBase::~TagBase(), MemoryManager::~MemoryManager()

References f_iconvertor, and f_iconvertor_open.

Member Function Documentation

ErrorManager::error_code_t TagHeader::DefineMinimumVersion ( int &  min_version  ) 

This function is used to determine the minimum SWF version required to save the current movie. It is automatically called by the Save() function before the movie is created in a Data buffer to know whether it will be possible to create that movie.

This funtion goes through all the TagHeader childrens recursively and each one determine what minimum SWF version the it requires to properly be saved in a movie. Note that the TagDoAction, and other tags supporting actions, checks every single action.

By default, the minimum version is set to 1 unless you requested a compressed movie in which case it starts at 6. You can start with a different minimum version by calling the SetMinimumVersion() function. Note however that if you set the minimum version to 5 and request a compressed movie, the result will be that the minimum starts at 6 anyway.

If you called SetVersion(), which fixes the version of the output movie, the minimum is set to that version directly. If any tag cannot be saved with that specific version, then the Save() function fails and no movie is created.

If you want to make sure that a movie is not created with too large a version, then use the SetMaximumVersion() function. The Save() will fail if the minimum required is larger than the maximum you defined.

[out] min_version The minimum version
An error code number
See also:
Save(), SetVersion(), SetMinimumVersion(), SetMaximumVersion()

References sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_VERSION_UNSATISFIED, f_compress, f_min_version, f_minimum_version, f_version, OnError(), PreSave(), and sswf::TagBase::PreSave2ndPass().

Referenced by Save().

const SRectangle & TagHeader::Frame ( void   )  const

This function returns a constant reference to the current frame object defined in the header.

This can, for instance, be used to create the necessary HTML code to play back the movie.

A rectangle with the frame sizes.
See also:
SetFrame(const SRectangle& rect)

References f_frame.

const TagHeader::Factory * TagHeader::GetFactory ( TagBase::swf_tag_t  tag  )  const

This function searches the list of factories currently registered with the TagHeader class. If there is no factory registered, then the function throws an exception.

When the factory does not exist for the specified tag (i.e. tag not yet supported by the sswf library) then the function returns NULL.

Do not forget that the libsswf is not thread safe. In other words, if you register a new factory while the Load() function is running will cause crashes.
ErrorManager::InternalErrorException is raised whenever the function is called before the factories had a chance to register themselves. Factories registers themselves on load since they are global objects.
[in] tag The tag for which we're looking to get a factory.
A pointer to a factory or NULL if not found

References g_list_of_factories.

Referenced by Load().

ErrorManager::error_code_t TagHeader::Load ( const Data data,
load_flag_t  flags 

This function can be called as many times as necessary to load an entire Flash animation in memory.

The Data buffer is expected to contain some data (i.e. ByteSize() != 0). However, it does not need to contain a complete tag. Yet, nothing will happen until an entire tag is available (i.e. the function will simply return.)

This feature lets you read data from a slow Internet connection.

Since the header includes a size for the entire file, the function will know once the end of the file was reached. At that point, the function returns ERROR_CODE_NONE to let you know that the Load() is done.

By default, any error will stop the processing. To avoid that behavior and load as much as the library can load, use the LOAD_FLAG_IGNORE_UNKNOWN_TAGS and implement your own class derived from TagHeader in which you overload the OnError() function that can then be used to return ERROR_CODE_NONE instead of whatever error code.

Ignoring errors is safe, although what will be loaded will not be an equivalent of the input file.

[in] data A Data buffer with data read from a Flash file
[in] flags A set of LOAD_FLAG_... bits
An error code is something wrong happen, ERROR_CODE_CONTINUE if the function can be called again with more data, and ERROR_CODE_NONE once the end of the stream is reached

References sswf::Data::ByteSize(), sswf::Data::Empty(), sswf::ErrorManager::ERROR_CODE_ERRONEOUS_FORMAT, sswf::ErrorManager::ERROR_CODE_INVALID_SPRITE_DEFINITION, sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_UNKNOWN_FORMAT, sswf::ErrorManager::ERROR_CODE_UNKNOWN_TAG, f_compressed_input, f_file_size, f_load_status, f_position, f_sprite, f_sprite_size, f_tag, f_tag_data, f_tag_size, f_version, f_zstream, GetFactory(), HEADER_LOAD_STATUS_DATA, HEADER_LOAD_STATUS_DONE, HEADER_LOAD_STATUS_ERROR, HEADER_LOAD_STATUS_HEADER, HEADER_LOAD_STATUS_RESET, HEADER_LOAD_STATUS_TAG, HEADER_LOAD_STATUS_TAG_SIZE, LOAD_FLAG_IGNORE_UNKNOWN_TAGS, sswf::TagHeader::Factory::NewTag(), OnError(), sswf::TagBase::ParseTag(), sswf::Data::Read(), sswf::Data::ReadBytes(), sswf::TagBase::SWF_TAG_DEFINE_SPRITE, sswf::TagBase::SWF_TAG_END, sswf::TagBase::SWF_TAG_UNKNOWN, and sswf::Data::Write().

void TagHeader::MinimumVersion ( unsigned char  version  )  [virtual]

Whenever you create a movie, you may want to use a minimum version to make sure that certain options are properly taken in account.

For instance, if you want to make use of the Use Network flag, you need a minimum version of 8. If you want to be sure that your movie works all over the world, in regard to text, then you need to use a version of 6 as a minimum.

The version defined with this function is the one used to start defining the minimum version necessary by calling the DefineMinimumVersion() function.

[in] version The minimum version.

Reimplemented from sswf::TagBase.

References sswf::assert(), and f_min_version.

Referenced by sswf::TagBase::MinimumVersion().

unsigned short TagHeader::NextID ( void   ) 

All the definition tags require an identifier. In order to generate only unique identifier, one can use this function.

Notice that there is a maximum of 32766 identifiers. Values larger than 32767 have special meanings and 0 cannot legally be used as an object identifier.

A unique identifier.
See also:
RemoveID(sswf_id_t id)

References f_next_id.

Referenced by sswf::TagImport::AddName(), and sswf::TagBaseID::TagBaseID().

ErrorManager::error_code_t TagHeader::OnError ( ErrorManager::error_code_t  errcode,
const char *  message,
) const [virtual]

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

[in] errcode The code of this error
[in] message The message for this error
[in] ... Arguments for the message
Usually the input error code; the user may change it

Reimplemented from sswf::ErrorManager.

References sswf::ErrorManager::OnError().

ErrorManager::error_code_t TagHeader::OnError ( ErrorManager::error_code_t  errcode,
const char *  message,
va_list  ap 
) const [virtual]

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

[in] errcode The code of this error
[in] message The message for this error
[in] ap Arguments for the message
Usually the input error code; the user may change it

Reimplemented from sswf::ErrorManager.

References sswf::ErrorManager::OnError().

Referenced by DefineMinimumVersion(), Load(), and sswf::TagBase::OnError().

ErrorManager::error_code_t TagHeader::OnNewChild ( const char *  child_name  )  const [protected, virtual]

A sswf::TagHeader cannot be a child of any other tag. Any other tag can be a child of a TagHeader so far.

This function returns an error whenever the child is a tag header.

See also:
sswf::TagBase::OnNewChild(const char *child)

sswf::TagSprite::OnNewChild(const char *child)

Reimplemented from sswf::TagBase.

References sswf::ErrorManager::ERROR_CODE_INCOMPATIBLE_CHILD, and sswf::ErrorManager::ERROR_CODE_NONE.

ErrorManager::error_code_t TagHeader::ParseTag ( TagBase::swf_tag_t  tag,
const Data data 
) [protected, virtual]

This function only raises an exception. Do not call it. It is defined because the TagBase::ParseTag() function is defined as a pure virtual pointer.

ErrorManager::InternalErrorException is raised whenever this function is called.
[in] tag The tag that generated this call, ignored.
[in] data The Data buffer from the Flash file being loaded, ignored.
Never returns

Implements sswf::TagBase.

ErrorManager::error_code_t TagHeader::PreSave ( void   )  [protected, virtual]

This function calls all the children PreSave() function. It is used for the children to have a chance to prepare themselves before being saved. This is necessary for the few tags which need forward look ups. Also some special structures need preparation. For the fonts, it is also necessary to have a PreSave2ndPass()

The TagHeader object overwrites this TagBase function in order to search for a TagMetadata and TagJPEGTables. It ensures unicity of these tags, and in a version 8 animation, it needs to set a flag in the FileAttributes tags when there is a TagMetadata in the file.

0 when it worked; some other non-zero value when it fails

Reimplemented from sswf::TagBase.

References sswf::TagBase::Children(), sswf::ErrorManager::ERROR_CODE_TWO_OR_MORE_JPEGTABLES, sswf::ErrorManager::ERROR_CODE_TWO_OR_MORE_METADATA, f_has_jpegtables, f_has_metadata, sswf::TagBase::Name(), sswf::TagBase::Next(), and sswf::TagBase::PreSave().

Referenced by DefineMinimumVersion().

float TagHeader::Rate ( void   )  const

This function returns the rate you set with SetRate().

The frame rate in a floating point.
See also:
SetRate(float rate)

References f_rate.

void TagHeader::RemoveID ( sswf_id_t  id  ) 

At times, an object foresees the necessity to have its own identifier. Then later it may either be merged with another object or jointly used with another object. In that case, it is possible to release an identifier.

At this time, if you release the very last identifier which was allocated, it is made available again, otherwise the function does nothing.

[in] id The identifier which is not needed anymore.
See also:

References f_next_id.

Referenced by sswf::TagBaseID::NoIdentification().

ErrorManager::error_code_t TagHeader::Save ( Data data  )  [virtual]

The Save() function first calls the DefineMinimumVersion() function. Even if you do not specify a minimum, maximum or specific version, it is necessary to know the version before starting the save process since certain tags can either be optimized or are required to be used instead of others depending on the version (for instance, a version 5 can make use of SWF_TAG_PROTECT_DEBUG, but other versions will use SWF_TAG_PROTECT or SWF_TAG_PROTECT_DEBUG2).

Once it determined it could save the movie, it recursively saves all the objects in the data parameter.

If everything works as expected, it returns zero meaning that the data buffer holds the resulting movie.

[in,out] data The buffer where the movie is to be saved
0 when the Save() succeeded; a non-zero value otherwise

Implements sswf::TagBase.

References sswf::Data::Align(), sswf::Data::Append(), sswf::Data::ByteSize(), sswf::TagBase::Children(), DefineMinimumVersion(), sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_VERSION_UNSATISFIED, f_compress, f_frame, f_has_metadata, f_maximum_version, f_min_version, f_rate, f_use_network, f_version, sswf::TagBase::FrameCount(), sswf::ErrorManager::KeepFirst(), sswf::MemoryManager::MemAlloc(), sswf::MemoryManager::MemFree(), sswf::TagBase::Name(), sswf::TagBase::Next(), sswf::ErrorManager::OnError(), sswf::Data::PutByte(), sswf::Data::PutLong(), sswf::Data::PutShort(), sswf::Data::Read(), sswf::TagBase::ResetFrames(), sswf::SRectangle::Save(), sswf::TagBase::Save(), sswf::TagBase::SaveTag(), sswf::TagBase::ShowFrame(), sswf::TagBase::SWF_TAG_END, sswf::TagBase::SWF_TAG_FILE_ATTRIBUTES, sswf::TagBase::SWF_TAG_SHOW_FRAME, sswf::Data::Write(), and sswf::Data::WriteBits().

ErrorManager::error_code_t TagHeader::SaveEncodedString ( Data data,
const char *  string 

All the strings giving to any tag in an SWF movie must be UTF-8. This function will ensure that the encoding of the string in the resulting SWF movie is set according to the user specification (when the version is 5 or less) or left alone (when the version is 6 or more.)

This function is used by the tags to save strings in the data buffer. It should not otherwise be called directly.

For movies with version 5 or less, you should use the SetOutputEncoding() to ensure that it is saved with the correct caracters. By default, ISO-8859-1 is used.

[in,out] data The buffer where the string is to be saved
[in] string The string to save in the buffer
The number of bytes saved in the buffer
See also:
TagBase::PutString(const char *string)

References sswf::assert(), sswf::ErrorManager::ERROR_CODE_ICONV_ENCODER_NOT_AVAILABLE, sswf::ErrorManager::ERROR_CODE_ICONV_FAILED, sswf::ErrorManager::ERROR_CODE_NONE, f_iconvertor, f_iconvertor_open, f_min_version, f_output_encoding, f_version, ICONV_INPUT_CAST, sswf::MemoryManager::MemAlloc(), sswf::MemoryManager::MemFree(), sswf::ErrorManager::OnError(), sswf::Data::PutByte(), and sswf::Data::PutString().

Referenced by sswf::TagBase::SaveString().

void TagHeader::SetAutoOrder ( bool  auto_order = true  ) 

Note: this is currently ignored

The ultimate would be to have the library sort out the definitions of objects so they happen only when necessary. This is very problematic now that you can write complex ActionScripts which can reference an object (and the library could not really know... unless it is told.)

So at this time I did not work on this functionality.

[in] auto_order Whether you want the library to re-order the definition tags for you.

References f_auto_order.

void TagHeader::SetCompress ( bool  compress = true  ) 

Since version 6, it is possible to create SWF files which are compressed with zlib. This flag is false by default. Setting the flag to true forces the library to save at least a version 6 movie.

[in] compress Set to whether true or false

References f_compress.

void TagHeader::SetFrame ( const SRectangle rect  ) 

This function defines the size of the output frame.

By default, the TagHeader sets the frame to (0, 100, 0, 100).

The frame must have x and y positions set to (0, 0).

[in] rect The rectangle used to define the frame sizes.
See also:

References f_frame, sswf::SRectangle::SetReorder(), sswf::SRectangle::XMax(), sswf::SRectangle::XMin(), sswf::SRectangle::YMax(), and sswf::SRectangle::YMin().

void TagHeader::SetMaximumVersion ( unsigned char  version  ) 

This function is used to ensure that the output movie will not be more than that version. If a tag requires a higher versions then it won't be possible to save the movie.

This is useful if you want to create a movie for Linux which at this time (Oct 2006) still does not support version 8 of the Macromedia player.

This is used by the Save() function to verify that the movie can indeed be saved before to proceed.

[in] version The maximum version the output movie should use
See also:
DefineMinimumVersion(), Save(), SetVersion(), SetMinimumVersion()

References f_maximum_version.

void TagHeader::SetMinimumVersion ( unsigned char  version  ) 

This function is used to ensure that the output movie will be at least of that version. Lower versions will not be considered.

This is useful if you want to create a version 6 movie but you don't want to be prevented from creating a version 7 or 8.

This is used by the DefineMinimumVersion() function.

[in] version The minimum version the output movie should use
See also:
DefineMinimumVersion(), Save(), SetVersion(), SetMaximumVersion()

References f_minimum_version.

void TagHeader::SetOutputEncoding ( const char *  encoding  ) 

Whenever you are using a version 6 or better movie, you endup using UTF-8 strings.

When creating an older version, you may need to convert your input in a specific encoding so it works for your viewers. This function can be used to set the encoding used in the movie.

[in] encoding The name of the encoding as support by your iconv

References f_output_encoding, sswf::MemoryManager::MemFree(), and sswf::MemoryManager::StrDup().

void TagHeader::SetRate ( float  rate  ) 

This function sets the speed at which the frames in the movie needs to be played back.

By default, the frame rate is set to 30.0 (i.e. close to the NTSC refresh rate).

A smaller value makes the movie play slower. A larger value makes the movie play faster.

PAL uses 25 frames a second. Older movies can have as few as 15 images a second.

[in] rate The frame rate (saved in a short float in the movie, the range is 1.0 to nearly 256.0, thought over 60 it tends to be way too fast)
See also:

References f_rate.

void TagHeader::SetUseNetwork ( bool  use_network = true  ) 

When you use a local player to run an SWF animation, this flag determines whether that movie can make use of the network or not.

Movies played via a browser connected to the Internet ignore this flag.

Note that only movies of version 8 or more can use this flag.

[in] use_network Whether the network can be used.

References f_use_network.

void TagHeader::SetVersion ( unsigned char  version  ) 

This function can be used to force the output movie to use a specific version.

It is not recommanded to use this function.

If any tag cannot be represented in the specified version, then the Save() function will fail.

This is used by the DefineMinimumVersion() function and the Save() function.

[in] version The exact version the output movie should use
See also:
DefineMinimumVersion(), Save(), SetMinimumVersion(), SetMaximumVersion()

References f_version.

TagBase::swf_type_t TagHeader::TypeFlags ( void   )  const [virtual]

This function returns the flags representing the TagHeader.

At this time it includes: HEADER, UNIQUE and START.

The set of flags representing that TagHeader

Implements sswf::TagBase.


unsigned char TagHeader::Version ( void   )  const [virtual]

This function retrieves the version in which the movie will be saved.

Unless you called the SetVersion() function, this is the minimum version as defined by the DefineMinimumVersion() function.

This function can be overloaded in order to control what it shall return. For instance, you may always prevent a version of 1 or 2 to appear. Then your Version() function would look like this:

        unsigned char MyObject::Version(void) const
                unsigned char version;

                version = TagHeader::Version();

                if(version < 3) {
                        version = 3;

                return version;

The version used to save the movie.
the version returned by this function will be valid only after you called the DefineMinimumVersion() function.
See also:
SetVersion(unsigned char version), DefineMinimumVersion(void)

Reimplemented from sswf::TagBase.

References f_min_version, and f_version.

Referenced by sswf::TagBase::Version().

Member Data Documentation

Referenced by SetAutoOrder(), and TagHeader().

Referenced by Load().

size_t sswf::TagHeader::f_file_size [private]

Referenced by Load().

Referenced by PreSave(), and TagHeader().

Referenced by PreSave(), Save(), and TagHeader().

unsigned char sswf::TagHeader::f_maximum_version [private]

Referenced by Save(), SetMaximumVersion(), and TagHeader().

size_t sswf::TagHeader::f_position [private]

Referenced by Load().

float sswf::TagHeader::f_rate [private]

Referenced by Rate(), Save(), SetRate(), and TagHeader().

Referenced by Load().

Referenced by Load().

Referenced by Load().

Referenced by Load().

size_t sswf::TagHeader::f_tag_size [private]

Referenced by Load().

z_stream sswf::TagHeader::f_zstream [private]

Referenced by Load().

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

Generated on Wed Mar 18 15:13:59 2009 for libsswf by  doxygen 1.5.5