NAME

SWF::BinStream - Read and write binary stream.

SYNOPSIS

  use SWF::BinStream;

  $read_stream = SWF::BinStream::Read->new($binary_data, \&adddata);
  $byte = $read_stream->get_UI8;
  $signedbyte = $read_stream->get_SI8;
  $string = $read_stream->get_string($length);
  $bits = $read_stream->get_bits($bitlength);
  ....

  sub adddata {
      if ($nextdata) {
	  shift->add_stream($nextdata);
      } else {
	  die "The stream ran short ";
      }
  }

  $write_stream = SWF::BinStream::Write->new;
  $write_stream->set_UI8($byte);
  $write_stream->set_SI8($signedbyte);
  $write_stream->set_string($string);
  $write_stream->set_bits($bits, $bitlength);
  $binary_data=$write_stream->flush_stream;
  ....

DESCRIPTION

SWF::BinStream module provides a binary byte and bit data stream. It can handle bit-compressed data such as SWF file.

SWF::BinStream::Read

Provides a read stream. Add the binary data to the stream, and you get byte and bit data. The stream calls a user subroutine when the stream data runs short. get_UI16, get_SI16, get_UI32, and get_SI32 get a number in VAX byte order from the stream. get_bits and get_sbits get the bits from MSB to LSB. get_UI*, get_SI*, and get_string skip the remaining bits in the current byte and read data from the next byte. If you want to skip remaining bits manually, use flush_bits.

METHODS

SWF::BinStream::Read->new( [ $initialdata, \&callback_in_short, $version ] )

Creates a read stream. It takes three optional arguments. The first arg is a binary string to set as initial data of the stream. The second is a reference of a subroutine which is called when the stream data runs short. The subroutine is called with two ARGS, the first is $stream itself, and the second is how many bytes wanted. The third arg is SWF version number. Default is 5. It is necessary to set proper version because some SWF tags change their structure by the version number.

$stream->Version

returns SWF version number of the stream.

$stream->add_codec( $codec_name )

Adds stream decoder. Decoder 'Zlib' is only available now.

$stream->add_stream( $binary_data )

Adds binary data to the stream.

$stream->Length

Returns how many bytes remain in the stream.

$stream->tell

Returns how many bytes have been read from the stream.

$stream->get_string( $num )

Returns $num bytes as a string.

$stream->get_UI8

Returns an unsigned byte number.

$stream->get_SI8

Returns a signed byte number.

$stream->get_UI16

Returns an unsigned word (2 bytes) number.

$stream->get_SI16

Returns a signed word (2 bytes) number.

$stream->get_UI32

Returns an unsigned double word (4 bytes) number.

$stream->get_SI32

Returns a signed double word (4 bytes) number.

$stream->get_bits( $num )

Returns the $num bit unsigned number.

$stream->get_sbits( $num )

Returns the $num bit signed number.

$stream->lookahead_string( $offset, $num )

$stream->lookahead_UI8( $offset )

$stream->lookahead_SI8( $offset )

$stream->lookahead_UI16( $offset )

$stream->lookahead_SI16( $offset )

$stream->lookahead_UI32( $offset )

$stream->lookahead_SI32( $offset )

Returns the stream data $offset bytes ahead of the current read point. The read pointer does not move.

$stream->flush_bits

Skips the rest bits in the byte and aligned read pointer to the next byte. It does not anything when the read pointer already byte-aligned.

SWF::BinStream::Write

Provides a write stream. Write byte and bit data, then get the stream data as binary string using flush_stream. autoflush requests to the stream to automatically flush the stream and call a user subroutine. set_UI16, set_SI16, set_UI32, and set_SI32 write a number in VAX byte order to the stream. set_bits and set_sbits write the bits from MSB to LSB. set_UI*, set_SI*, and set_string set the rest bits in the last byte to 0 and write data to the next byte boundary. If you want to write bit data and align the write pointer to byte boundary, use flush_bits.

METHODS

SWF::BinStream::Write->new( [$version] )

Creates a write stream. One optional argument is SWF version number. Default is 5. It is necessary to set proper version because some SWF tags change their structure by the version number.

$stream->Version( [$version] )

returns SWF version number of the stream. You can change the version before you write data to the stream.

$stream->add_codec( $codec_name )

Adds stream encoder. Encoder 'Zlib' is only available now.

$stream->autoflush( $size, \&callback_when_flush )

Requests to the stream to automatically flush the stream and call sub with the stream data when the stream size becomes larger than $size bytes.

$stream->flush_stream( [$size] )

Flushes the stream and returns the stream data. Call with $size, it returns $size bytes from the stream. When call without arg or with larger $size than the stream data size, it returns all data including the last bit data ( by calling flush_bits internally).

$stream->flush_bits

Sets the rest bits in the last byte to 0, and aligns write pointer to the next byte boundary.

$stream->Length

Returns how many bytes remain in the stream.

$stream->tell

Returns how many bytes have written.

$stream->mark( [$key, [$obj]] )

Keeps current tell number with $key and $obj. When called without $obj, it returns tell number associated with $key and a list of tell number and object in scalar and list context, respectively. When called without any parameter, it returns mark list ( KEY1, [ TELL_NUMBER1, OBJ1 ], KEY2, [...).

$stream->sub_stream

Creates temporaly sub stream. When flush_stream the sub stream, it's data and marks are written to the parent stream and the sub stream is freed.

Ex. write various length of data following it's length.

$sub_stream=$parent_stream->sub_stream;
write_data($sub_stream);
$parent_stream->set_UI32($sub_stream->Length);
$sub_stream->flush_stream;

$stream->set_string( $str )

Writes string to the stream.

$stream->set_UI8( $num )

Writes $num as an unsigned byte.

$stream->set_SI8( $num )

Writes $num as a signed byte.

$stream->set_UI16( $num )

Writes $num as an unsigned word.

$stream->set_SI16( $num )

Writes $num as a signed word.

$stream->set_UI32( $num )

Writes $num as an unsigned double word.

$stream->set_SI32( $num )

Writes $num as an unsigned double word.

$stream->set_bits( $num, $nbits )

Write $num as $nbits length unsigned bit data.

$stream->set_sbits( $num, $nbits )

Write $num as $nbits length signed bit data.

$stream->set_bits_list( $nbitsbit, @list )

Makes @list as unsigned bit data list. It writes the maximal bit length of each @list (nbits) as $nbitsbit length unsigned bit data, and then writes each @list number as nbits length unsigned bit data.

$stream->set_sbits_list( $nbitsbit, @list )

Makes @list as signed bit data list. It writes the maximal bit length of each @list (nbits) as $nbitsbit length unsigned bit data, and then writes each @list number as nbits-length signed bit data.

UTILITY FUNCTIONS

&SWF::BinStream::Write::get_maxbits_of_bits_list( @list )

&SWF::BinStream::Write::get_maxbits_of_sbits_list( @list )

Gets the necessary and sufficient bit length to represent the values of @list. -_bits_list is for unsigned values, and -_sbits_list is for signed.

COPYRIGHT

Copyright 2000 Yasuhiro Sasama (ySas), <ysas@nmt.ne.jp>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.