libsswf: sswf::TagHeader Class Reference

Enumerator:

LOAD_FLAG_IGNORE_UNKNOWN_TAGS

Enumerator:

HEADER_LOAD_STATUS_RESET
HEADER_LOAD_STATUS_HEADER
HEADER_LOAD_STATUS_TAG
HEADER_LOAD_STATUS_TAG_SIZE
HEADER_LOAD_STATUS_DATA
HEADER_LOAD_STATUS_DONE
HEADER_LOAD_STATUS_ERROR

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().

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.

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.

Parameters:

[out]

min_version

The minimum version

Returns:

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().

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.

Returns:

A rectangle with the frame sizes.

See also:

SetFrame(const SRectangle& rect)

References f_frame.

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.

Bug:

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.

Exceptions:

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.

Parameters:

[in]

tag

The tag for which we're looking to get a factory.

Returns:

A pointer to a factory or NULL if not found

References g_list_of_factories.

Referenced by Load().

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.

Parameters:

[in]	data	A Data buffer with data read from a Flash file
[in]	flags	A set of LOAD_FLAG_... bits

Returns:

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().

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.

Parameters:

[in]

version

The minimum version.

Reimplemented from sswf::TagBase.

References sswf::assert(), and f_min_version.

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

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.

Returns:

A unique identifier.

See also:

RemoveID(sswf_id_t id)

References f_next_id.

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

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

Parameters:

[in]	errcode	The code of this error
[in]	message	The message for this error
[in]	...	Arguments for the message

Returns:

Usually the input error code; the user may change it

Reimplemented from sswf::ErrorManager.

References sswf::ErrorManager::OnError().

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

Parameters:

[in]	errcode	The code of this error
[in]	message	The message for this error
[in]	ap	Arguments for the message

Returns:

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().

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.

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.

Exceptions:

ErrorManager::InternalErrorException

is raised whenever this function is called.

Parameters:

[in]	tag	The tag that generated this call, ignored.
[in]	data	The Data buffer from the Flash file being loaded, ignored.

Returns:

Never returns

Implements sswf::TagBase.

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.

Returns:

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().

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

Returns:

The frame rate in a floating point.

See also:

SetRate(float rate)

References f_rate.

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.

Parameters:

[in]

id

The identifier which is not needed anymore.

See also:

NextID(void)

References f_next_id.

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

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.

Parameters:

[in,out]

data

The buffer where the movie is to be saved

Returns:

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().

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.

Parameters:

[in,out]	data	The buffer where the string is to be saved
[in]	string	The string to save in the buffer

Returns:

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().

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.

Parameters:

[in]

auto_order

Whether you want the library to re-order the definition tags for you.

References f_auto_order.

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.

Parameters:

[in]

compress

Set to whether true or false

References f_compress.

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).

Parameters:

[in]

rect

The rectangle used to define the frame sizes.

See also:

Frame(void)

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

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.

Parameters:

[in]

version

The maximum version the output movie should use

See also:

DefineMinimumVersion(), Save(), SetVersion(), SetMinimumVersion()

References f_maximum_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.

Parameters:

[in]

version

The minimum version the output movie should use

See also:

DefineMinimumVersion(), Save(), SetVersion(), SetMaximumVersion()

References f_minimum_version.

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.

Parameters:

[in]

encoding

The name of the encoding as support by your iconv

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

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.

Parameters:

[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:

Rate(void)

References f_rate.

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.

Parameters:

[in]

use_network

Whether the network can be used.

References f_use_network.

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.

Parameters:

[in]

version

The exact version the output movie should use

See also:

DefineMinimumVersion(), Save(), SetMinimumVersion(), SetMaximumVersion()

References f_version.

This function returns the flags representing the TagHeader.

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

Returns:

The set of flags representing that TagHeader

Implements sswf::TagBase.

References SWF_TYPE_HEADER, SWF_TYPE_START, and SWF_TYPE_UNIQUE.

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;
        }

Returns:

The version used to save the movie.

Warning:

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().

Referenced by SetAutoOrder(), and TagHeader().

Referenced by DefineMinimumVersion(), Save(), SetCompress(), and TagHeader().

Referenced by Load().

Referenced by Load().

Referenced by Frame(), Save(), SetFrame(), and TagHeader().

Referenced by PreSave(), and TagHeader().

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

Referenced by SaveEncodedString(), TagHeader(), and ~TagHeader().

Referenced by SaveEncodedString(), TagHeader(), and ~TagHeader().

Referenced by Load(), and TagHeader().

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

Referenced by DefineMinimumVersion(), MinimumVersion(), Save(), SaveEncodedString(), TagHeader(), and Version().

Referenced by DefineMinimumVersion(), SetMinimumVersion(), and TagHeader().

Referenced by NextID(), RemoveID(), and TagHeader().

Referenced by SaveEncodedString(), SetOutputEncoding(), and TagHeader().

Referenced by Load().

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

Referenced by Load().

Referenced by Load().

Referenced by Load().

Referenced by Load().

Referenced by Load().

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

Referenced by DefineMinimumVersion(), Load(), Save(), SaveEncodedString(), SetVersion(), TagHeader(), and Version().

Referenced by Load().