Made to Order Software Corporation Logo

libsswf: sswf::Data Class Reference

Buffer object used to save the SWF movie. More...

#include <libsswf.h>

Inheritance diagram for sswf::Data:

:MemoryManager

List of all members.


Public Member Functions

void Align (void)
 Align the buffer position to the next byte.
void Append (const Data &append)
 Append another Data buffer.
unsigned long ByteSize (void) const
 Returns the size of the buffer in bytes.
 Data (void)
 Initialize a Data buffer.
void Empty (void)
 Reset the size.
ErrorManager::error_code_t GetBits (int &value, size_t bits) const
 Read the specified number of bits from the buffer.
ErrorManager::error_code_t GetByte (uint8_t &c) const
 Retrieve one unsign byte from the data buffer.
ErrorManager::error_code_t GetByte (int8_t &c) const
 Retrieve one signed byte from the data buffer.
ErrorManager::error_code_t GetDLong (uint64_t &ll) const
 Retrieve one signed double long from the data buffer.
ErrorManager::error_code_t GetDLong (int64_t &ll) const
 Retrieve one signed double long from the data buffer.
ErrorManager::error_code_t GetDoubleFloat (double &f) const
 Retrieve one double from the data buffer.
ErrorManager::error_code_t GetLong (uint32_t &l) const
 Retrieve one signed long from the data buffer.
ErrorManager::error_code_t GetLong (int32_t &l) const
 Retrieve one signed long from the data buffer.
ErrorManager::error_code_t GetLongFloat (float &f) const
 Retrieve one float from the data buffer.
size_t GetReadPosition (void) const
 Retrieve the current pointer used by the Get...() functions.
ErrorManager::error_code_t GetShort (uint16_t &s) const
 Retrieve one signed short from the data buffer.
ErrorManager::error_code_t GetShort (int16_t &s) const
 Retrieve one signed short from the data buffer.
ErrorManager::error_code_t GetShortFloat (float &f) const
 Retrieve one float from the data buffer.
unsigned long GetSize (void) const
 Returns the current size of the buffer.
ErrorManager::error_code_t GetString (MemoryManager *mem, int l, char **str) const
 Read a null terminated string.
bool IsEndOfData (void) const
 Check whether we reached the end of the buffer.
unsigned long Limit (unsigned long limit, bool offset) const
 Set the limit for the following Get...() calls.
void Overwrite (size_t offset, const void *ptr, size_t size)
 Overwrite data at the specified offset.
void OverwriteByte (size_t offset, char c)
 Overwrite data at the specified offset.
void OverwriteLong (size_t offset, long l)
 Overwrite data at the specified offset.
void OverwriteShort (size_t offset, short s)
 Overwrite data at the specified offset.
void PutByte (char c)
 Save one byte.
void PutDLong (int64_t ll)
 Save one 64 bits long.
void PutDoubleFloat (double f)
 Save one 64 bits floating point in IEEE format.
void PutLong (long l)
 Save one 32 bits long.
void PutLongFloat (float f)
 Save one 32 bits floating point in IEEE format.
void PutShort (short s)
 Save one short.
void PutShortFloat (float f)
 Save one 16 bits floating point in IEEE format.
void PutString (const char *string)
 Save one string.
void Read (const void *&ptr, size_t &size) const
 Read the data buffer information.
void Read (void *&ptr, size_t &size)
 Read the data buffer information.
ErrorManager::error_code_t ReadAlign (void) const
 Align to the next byte.
ErrorManager::error_code_t ReadBytes (void *ptr, size_t size) const
 Read the specified number of bytes in the supplied buffer.
ErrorManager::error_code_t SetReadPosition (size_t pos) const
 Position the pointer for the Get...() functions.
void SetSize (unsigned long size)
 Set the size in bits.
void Write (const void *ptr, size_t size)
 Write data at the end of the buffer.
void WriteBits (long value, size_t bits)
 Write bits at the end of the buffer.
 ~Data ()
 Cleanup a Data buffer.

Private Member Functions

void AdjustSize (size_t size)
 Make sure that the buffer is at least of that size.

Private Attributes

char * f_data
unsigned long f_limit
unsigned long f_pos
unsigned long f_rpos
unsigned long f_size

Classes

class  DataLimit

Detailed Description

This object is a buffer used to save the SWF movie in a memory buffer.

It grows as required and has functions specific to SWF such as Align() and WriteBits().

See also:
sswf::Data::Align()

sswf::Data::WriteBits()


Constructor & Destructor Documentation

Data::Data ( void   ) 

This function initializes a Data buffer. By default, a Data buffer is empty.

References f_data, f_limit, f_pos, f_rpos, and f_size.

Data::~Data (  ) 

This function does nothing since the memory used by the Data buffer is managed by the memory manager directly.


Member Function Documentation

void Data::AdjustSize ( size_t  size  )  [private]

This function ensures that the output buffer is at least of the specified number of bits (notice: BITS, bot BYTES.)

This is used to create a buffer for a tag that can later be modified with the Overwrite functions.

Parameters:
[in] size The new buffer size in bits
See also:
sswf::Data::Overwrite

sswf::Data::OverwriteByte

sswf::Data::OverwriteShort

sswf::Data::OverwriteLong

References f_data, f_pos, f_size, and sswf::MemoryManager::MemRealloc().

Referenced by Append(), Write(), and WriteBits().

void Data::Align ( void   ) 

Whenever writing an SWF movie, it is most often compressed on bytes and quite often on bits. Whenever bits are used to save one structure (such as a rectangle), the following data which are aligned on a byte need to appear on a byte.

This function ensures that this is indeed the case.

This function can safely be called multiple times in a raw. The position will be adjusted only the first time and only if necessary.

References f_pos.

Referenced by Append(), sswf::TagFont::PreSave2ndPass(), Read(), sswf::Matrix::Save(), sswf::ColorTransform::Save(), sswf::TagText::Save(), sswf::TagShape::Save(), sswf::TagHeader::Save(), sswf::TagFont::Save(), sswf::TagEditText::Save(), sswf::Style::Save(), and Write().

void Data::Append ( const Data data  ) 

This function appends a Data buffer to this Data buffer.

The source Data buffer is not modified.

The destination is first aligned with a call to Align(). The buffer is grown as required, then the source is copied at the end of the destination.

Parameters:
[in] data The source Data buffer

References AdjustSize(), Align(), f_data, and f_pos.

Referenced by sswf::TagScalingGrid::GridSave(), sswf::TagText::Save(), sswf::TagSprite::Save(), sswf::TagSound::Save(), sswf::TagStartSound::Save(), sswf::TagShape::Save(), sswf::TagPlace::Save(), sswf::TagImport::Save(), sswf::TagImage::Save(), sswf::TagHeader::Save(), sswf::TagFont::Save(), sswf::TagExport::Save(), sswf::TagEditText::Save(), sswf::TagDoAction::Save(), sswf::TagButton::Save(), sswf::Action::Save(), sswf::ActionTry::SaveData(), and sswf::TagShape::SaveWithoutStyles().

sswf::Data::Empty ( void   )  [inline]

This function marks the Data buffer as empty.

All the data previously saved in this buffer is lost.

References f_limit, f_pos, and f_rpos.

Referenced by sswf::TagHeader::Load(), sswf::TagFont::PreSave2ndPass(), sswf::TagPlace::Save(), sswf::TagFont::Save(), and sswf::TagButton::Save().

ErrorManager::error_code_t Data::GetByte ( uint8_t &  c  )  const

This function reads one byte from this data buffer.

Parameters:
[in] c The new read position for the Get...() functions in bits
Returns:
An error (buffer overflow) or NONE.

References sswf::assert(), sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_NOT_ENOUGH_DATA, f_data, f_limit, f_pos, f_rpos, and ReadAlign().

ErrorManager::error_code_t Data::GetDLong ( uint64_t &  l  )  const

This function reads one long (32 bit integer) from this data buffer.

Parameters:
[in] l The long value read
Returns:
An error (buffer overflow) or NONE.

References sswf::ErrorManager::ERROR_CODE_NONE, and GetByte().

ErrorManager::error_code_t Data::GetDLong ( int64_t &  l  )  const

This function reads one long (32 bit integer) from this data buffer.

Parameters:
[in] l The long value read
Returns:
An error (buffer overflow) or NONE.

References sswf::ErrorManager::ERROR_CODE_NONE, and GetByte().

Referenced by GetDoubleFloat().

ErrorManager::error_code_t Data::GetDoubleFloat ( double &  f  )  const

This function reads one double float (64 bit floating point number) from this data buffer.

Bug:
Note that the double float values saved in a PushData action are NOT loaded with this function. Those doubles are saved swapped instead and thus the PushData class takes care of loading the double floats as required.
Parameters:
[in] f The double value read
Returns:
An error (buffer overflow) or NONE.

References GetDLong().

ErrorManager::error_code_t Data::GetLong ( uint32_t &  l  )  const

This function reads one long (32 bit integer) from this data buffer.

Parameters:
[in] l The long value read
Returns:
An error (buffer overflow) or NONE.

References sswf::ErrorManager::ERROR_CODE_NONE, and GetByte().

ErrorManager::error_code_t Data::GetLong ( int32_t &  l  )  const

This function reads one long (32 bit integer) from this data buffer.

Parameters:
[in] l The long value read
Returns:
An error (buffer overflow) or NONE.

References sswf::ErrorManager::ERROR_CODE_NONE, and GetByte().

Referenced by GetLongFloat(), sswf::ActionPushData::ParseData(), and sswf::TagBinaryData::ParseTag().

ErrorManager::error_code_t Data::GetLongFloat ( float &  f  )  const

This function reads one long float (32 bit floating point number) from this data buffer.

Parameters:
[in] f The float value read
Returns:
An error (buffer overflow) or NONE.

References GetLong().

Referenced by sswf::ActionPushData::ParseData(), and sswf::TagCSMTextSettings::ParseTag().

size_t Data::GetReadPosition ( void   )  const

This function retrieves the current pointer used by the different Get...() functions.

The pointer is defined as a bit position.

At the start, the position is set to 0.

Returns:
The current read position for the Get...() functions in bits

References f_rpos.

Referenced by sswf::Action::Parse().

ErrorManager::error_code_t Data::GetShort ( uint16_t &  s  )  const

This function reads one short (16 bit integer) from this data buffer.

Parameters:
[in] s The short value read
Returns:
An error (buffer overflow) or NONE.

References sswf::ErrorManager::ERROR_CODE_NONE, and GetByte().

ErrorManager::error_code_t Data::GetShortFloat ( float &  f  )  const

This function reads one float (16 bit floating point number) from this data buffer.

Parameters:
[in] f The float value read
Returns:
An error (buffer overflow) or NONE.

References sswf::ErrorManager::ERROR_CODE_NONE, and GetByte().

Referenced by sswf::TagShape::ParseAlignZone().

sswf::Data::GetSize ( void   )  const [inline]

Returns the size of the buffer in bits. This is the exact position in the buffer.

In general, one needs to call ByteSize() instead.

Returns:
The size of the buffer in bits

References f_pos.

Referenced by sswf::Action::Save(), and sswf::ActionTry::SaveData().

ErrorManager::error_code_t Data::GetString ( MemoryManager mem,
int  l,
char **  str 
) const

This function reads a null terminated string.

By default 99% of the strings in Flash are null terminated, thus, by default this function expects to read a null terminated string.

The l parameter is the expected size of the string. Set to 0 if the string length isn't known.

If the string has a specific size and is not expected to be null terminated, set l to '-<string size>'.

This function will manage the string buffer. If the pointer is not null, then it will be freed with a call to MemClean().

Note:
When l is positive, it MUST include the null terminator. So if you have a string of 3 characters, l is expected to be 4.
To the contrary, when l is negative, it is expected to NOT include the null terminator. This function then adds 1 to the length of the allocated string.
Parameters:
[in] mem An object with a memory manager to be used to allocate the string
[in] l The expected length of the string
[in] str Pointer to the string pointer
Returns:
An error or ERROR_CODE_NONE.

References sswf::ErrorManager::ERROR_CODE_BAD_STRING, sswf::ErrorManager::ERROR_CODE_NONE, GetByte(), sswf::MemoryManager::MemAlloc(), sswf::MemoryManager::MemClean(), and sswf::MemoryManager::MemRealloc().

Referenced by sswf::ActionURL::ParseData(), sswf::ActionTry::ParseData(), sswf::ActionSetTarget::ParseData(), sswf::ActionPushData::ParseData(), sswf::ActionGoto::ParseData(), sswf::ActionFunction::ParseData(), sswf::ActionDictionary::ParseData(), sswf::TagProtect::ParseTag(), sswf::TagFont::ParseTag(), sswf::TagExport::ParseTag(), and sswf::TagEditText::ParseTag().

bool Data::IsEndOfData ( void   )  const

This function checks whether the Read & Get functions reached the end of the Data buffer. If a limit is currently imposed, this function returns true if that limit was reached. In other words, there could still be data available after the limit is left off.

Returns:
true if the end of the current Data limit was reached

References f_limit, f_pos, and f_rpos.

Referenced by sswf::ActionPushData::ParseData(), sswf::Action::ParseList(), and sswf::TagButton::ParseTag().

unsigned long Data::Limit ( unsigned long  limit,
bool  offset 
) const

This function limits the size of the data the following Get...() function calls can make until they fail with an End of File reached error.

The function returns the current limit which you need to restore once you are done with your read.

Please, in C++, make use of the RAII DataLimit class instead. It ensures that the limit is automatically reset to the previous value for you.

Note:
This function does NOT affect the ReadBytes() function.
Exceptions:
OutOfBoundsErrorException is raised if the limit is more than the current size of the Data buffer.
Parameters:
[in] limit The new limit in bits. Set to zero (0) to reset.
[in] offset Whether the limit is an offset from the current position.
Returns:
The limit before the call.

References f_limit, f_pos, and f_rpos.

Referenced by sswf::Data::DataLimit::Restore().

void Data::Overwrite ( size_t  offset,
const void *  ptr,
size_t  size 
)

This function is used to overwrite data at offset on size bytes with the data pointed by ptr. This function will not enlarge the Data buffer and thus is must be used to overwrite only.

See also:
sswf::Data::OverwriteByte

sswf::Data::OverwriteShort

sswf::Data::OverwriteLong

References sswf::assert(), f_data, and f_pos.

void Data::OverwriteByte ( size_t  offset,
char  c 
)

This function is used to overwrite one byte at the specified offset. This function will not enlarge the Data buffer and thus is must be used to overwrite only.

See also:
sswf::Data::Overwrite

sswf::Data::OverwriteShort

sswf::Data::OverwriteLong

References sswf::assert(), f_data, and f_pos.

void Data::OverwriteLong ( size_t  offset,
long  l 
)

This function is used to overwrite one long at the specified offset (i.e. 4 bytes). This function will not enlarge the Data buffer and thus is must be used to overwrite only.

The long value is saved in little endian (least significant byte first.)

See also:
sswf::Data::Overwrite

sswf::Data::OverwriteByte

sswf::Data::OverwriteShort

References sswf::assert(), f_data, and f_pos.

void Data::OverwriteShort ( size_t  offset,
short  s 
)

This function is used to overwrite one short at the specified offset. This function will not enlarge the Data buffer and thus is must be used to overwrite only.

The short value is saved in little endian (least significant byte first.)

See also:
sswf::Data::Overwrite

sswf::Data::OverwriteByte

sswf::Data::OverwriteLong

References sswf::assert(), f_data, and f_pos.

Referenced by sswf::TagSprite::Save(), and sswf::ActionBranch::Save2ndPass().

void Data::PutDLong ( int64_t  ll  ) 

This is a convenient function used to save one 64 bits long in the Data buffer.

The long least significant byte is saved first.

This function implicitly calls Align().

Parameters:
[in] ll The 64 bits long to save
See also:
sswf::Data::PutByte()

sswf::Data::PutShort()

sswf::Data::PutLong()

sswf::Data::PutShortFloat()

sswf::Data::PutLongFloat()

sswf::Data::PutDoubleFloat()

sswf::Data::PutString()

References PutByte().

Referenced by PutDoubleFloat(), and sswf::TagProductInfo::Save().

void Data::PutDoubleFloat ( double  d  ) 

This is a convenient function used to save a 64 bits floating point.

Bug:
Note that the double float values saved in a PushData action are NOT saved with this function. Those doubles are saved swapped instead and thus the PushData class takes care of saving the double floats as required.
Parameters:
[in] d The floating point to save
See also:
sswf::Data::PutByte()

sswf::Data::PutShort()

sswf::Data::PutLong()

sswf::Data::PutDLong()

sswf::Data::PutShortFloat()

sswf::Data::PutLongFloat()

sswf::Data::PutString()

References PutDLong().

void Data::PutLongFloat ( float  f  ) 

This is a convenient function used to save a 32 bits floating point.

Parameters:
[in] f The floating point to save
See also:
sswf::Data::PutByte()

sswf::Data::PutShort()

sswf::Data::PutLong()

sswf::Data::PutDLong()

sswf::Data::PutShortFloat()

sswf::Data::PutDoubleFloat()

sswf::Data::PutString()

References PutLong().

Referenced by sswf::TagCSMTextSettings::SaveCSMTextSettings().

void Data::PutShortFloat ( float  f  ) 

This is a convenient function used to save a floating point on 16 bits. This is not a fixed point value, it really is a floating point defined as:

  • 1 bit of sign
  • 5 bits of exponent
  • 10 bits of mantissa
Bug:
This function assumes that the input floating point is a valid number, not a NaN. Your SWF will work better that way anyway.
Parameters:
[in] f The floating point to convert and save
See also:
sswf::Data::PutByte()

sswf::Data::PutShort()

sswf::Data::PutLong()

sswf::Data::PutDLong()

sswf::Data::PutLongFloat()

sswf::Data::PutDoubleFloat()

sswf::Data::PutString()

References PutShort().

Referenced by sswf::TagShape::SaveAlignZone().

void Data::PutString ( const char *  string  ) 

This is a convenient function used to save a string in the Data buffer.

It is valid to call the function with a NULL pointer. It is considered to be an empty string and just one zero byte is written.

Otherwise, strlen(string) + 1 bytes are saved (i.e. the string characters and the nul terminator.)

This function implicitly calls Align().

Parameters:
[in] string The string to save
See also:
sswf::Data::PutByte()

sswf::Data::PutShort()

sswf::Data::PutLong()

sswf::Data::PutDLong()

sswf::Data::PutShortFloat()

sswf::Data::PutLongFloat()

sswf::Data::PutDoubleFloat()

References PutByte(), and Write().

Referenced by sswf::TagHeader::SaveEncodedString().

void Data::Read ( const void *&  ptr,
size_t &  size 
) const

This function can be used to get access to the internal buffer pointer and size for read-only purposes.

In general, this function is while loading a file and we need to check the content of the buffer.

Note:
This function does not calls Align() since this function is const and Align() is not. So if the file was not properly flushed, you may not get access to the last few bits.
Bug:
Warning: this function returns direct access to the internal buffer pointer and size. If any other function is used, it invalidates these pointers. So use them, and forget about them right away!
Parameters:
[out] ptr Receives the Data buffer pointer
[out] size Receives the size in bytes of the buffer pointer

References f_data, and f_pos.

void Data::Read ( void *&  ptr,
size_t &  size 
)

This function can be used to get access to the internal buffer pointer and size.

In general, this function is used at the end to save the Data buffer in a file.

This function implicitly calls Align().

Bug:
Warning: this function returns direct access to the internal buffer pointer and size. If any other function is used, it invalidates these pointers. So use them, and forget about them right away!
Parameters:
[out] ptr Receives the Data buffer pointer
[out] size Receives the size in bytes of the buffer pointer

References Align(), f_data, and f_pos.

Referenced by sswf::TagHeader::Load(), and sswf::TagHeader::Save().

ErrorManager::error_code_t Data::ReadAlign ( void   )  const

This function adjusts the read pointer so it points to the next byte.

In effect, it ensures that the last 3 bits of the pointer are all zeroes. If not, move to the next byte and then clear the bits.

Returns:
An error (buffer overflow) or NONE.

References sswf::assert(), sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_NOT_ENOUGH_DATA, f_limit, f_pos, and f_rpos.

Referenced by GetByte(), sswf::Matrix::Parse(), sswf::ColorTransform::Parse(), sswf::SRectangle::Parse(), sswf::TagEditText::ParseTag(), and ReadBytes().

ErrorManager::error_code_t Data::ReadBytes ( void *  ptr,
size_t  size 
) const

This function reads the specified number of bytes in the buffer pointed by ptr. It is assumed that the buffer is large enough to receive that many bytes.

Parameters:
[in] ptr The pointer where the data is read
[in] size The number of bytes to read
Returns:
An error when one occurs, ERROR_CODE_NONE otherwise

References sswf::assert(), sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_NOT_ENOUGH_DATA, f_data, f_limit, f_pos, f_rpos, and ReadAlign().

Referenced by sswf::TagHeader::Load(), sswf::TagFrameLabel::ParseTag(), and sswf::TagBinaryData::ParseTag().

ErrorManager::error_code_t Data::SetReadPosition ( size_t  rpos  )  const

This function changes the pointer used by the different Get...() functions.

The pointer is defined as a bit position.

If the input offset is defined outside of the available data, then an error is returned. Note that the position 0 is always available.

Parameters:
[in] rpos The new read position for the Get...() functions in bits
Returns:
An error (buffer overflow) or NONE.

References sswf::assert(), sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_NOT_ENOUGH_DATA, f_limit, f_pos, and f_rpos.

void Data::SetSize ( unsigned long  size  ) 

This function can be used to shrink the buffer.

This is used after an AdjustSize() with a size which was too large.

In general, because the resulting size is determined after compression.

Parameters:
[in] size The new bit size of the buffer

References sswf::assert(), f_limit, f_pos, and f_rpos.

Referenced by sswf::Action::Save(), and sswf::ActionTry::SaveData().

void Data::Write ( const void *  ptr,
size_t  size 
)

This function writes size bytes from ptr at the end of the buffer. It automatically calls Align() to make sure that the alignment is correct.

Parameters:
[in] ptr The pointer to the data to append
[in] size The number of bytes to append

References AdjustSize(), Align(), f_data, and f_pos.

Referenced by sswf::TagHeader::Load(), PutByte(), PutString(), sswf::TagSound::Save(), sswf::TagSceneFrameData::Save(), sswf::TagProtect::Save(), sswf::TagMetadata::Save(), sswf::TagImage::Save(), sswf::TagHeader::Save(), sswf::TagFont::Save(), sswf::TagBinaryData::Save(), and sswfWriteData().

void Data::WriteBits ( long  value,
size_t  bits 
)

This function writes the specified number of bits from the specified value.

The least significant bits of value are used. Thus, a 1 bit value is defined as 0 or 1. A 2 bits value is defined as 0, 1, 2 or 3. And so on...

It is valid to save up to 31 bits with this function. In debug mode, the function asserts if it looks like the parameters are invalid.

Parameters:
[in] value The value of which bits are saved
[in] bits The number of bits to be saved

References AdjustSize(), sswf::assert(), f_data, and f_pos.

Referenced by sswf::Matrix::Save(), sswf::ColorTransform::Save(), sswf::SRectangle::Save(), sswf::TagText::Save(), sswf::TagSound::Save(), sswf::SoundInfo::Save(), sswf::TagShape::Save(), sswf::TagPlace::Save(), sswf::TagHeader::Save(), sswf::TagFont::Save(), sswf::TagEditText::Save(), sswf::Style::Save(), sswf::TagCSMTextSettings::SaveCSMTextSettings(), sswf::ActionTry::SaveData(), sswf::Edges::SaveEdge(), sswf::TagShape::SaveSetup(), sswf::TagShape::SaveShape(), and sswf::TagShape::SaveWithoutStyles().


Member Data Documentation

unsigned long sswf::Data::f_size [private]

Referenced by AdjustSize(), and Data().


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


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