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

Creates a read stream. It takes two 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.

$stream->add_stream( $binary_data )

Adds binary data to the stream.

$stream->require( $num )

Requires to keep $num bytes data to the stream. Then you can get $num bytes from the stream without short.

$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->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

Creates a write stream.

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