NAME¶
Data::Buffer - Read/write buffer class
SYNOPSIS¶
use Data::Buffer;
my $buffer = Data::Buffer->new;
## Add a 32-bit integer.
$buffer->put_int32(10932930);
## Get it back.
my $int = $buffer->get_int32;
DESCRIPTION¶
Data::Buffer implements a low-level binary buffer in which you can get
and put integers, strings, and other data. Internally the implementation is
based on "pack" and "unpack", such that
Data::Buffer is really a layer on top of those built-in functions.
All of the
get_* and
put_* methods respect the internal offset
state in the buffer object. This means that you should read data out of the
buffer in the same order that you put it in. For example:
$buf->put_int16(24);
$buf->put_int32(1233455);
$buf->put_int16(99);
$buf->get_int16; # 24
$buf->get_int32; # 1233455
$buf->get_int16; # 99
Of course, this assumes that you
know the order of the data items in the
buffer. If your setup is such that your sending and receiving processes won't
necessarily know what's inside the buffers they receive, take a look at the
TEMPLATE USAGE section.
USAGE¶
Data::Buffer->new
Creates a new buffer object and returns it. The buffer is initially empty.
This method takes no arguments.
Data::Buffer->new_with_init(@strs)
Creates a new buffer object and appends to it each of the octet strings in
@strs.
Returns the new buffer object.
$buffer->get_int8
Returns the next 8-bit integer from the buffer (which is really just the ASCII
code for the next character/byte in the buffer).
$buffer->put_int8
Appends an 8-bit integer to the buffer (which is really just the character
corresponding to that integer, in ASCII).
$buffer->get_int16
Returns the next 16-bit integer from the buffer.
$buffer->put_int16($integer)
Appends a 16-bit integer to the buffer.
$buffer->get_int32
Returns the next 32-bit integer from the buffer.
$buffer->put_int32($integer)
Appends a 32-bit integer to the buffer.
$buffer->get_char
More appropriately called
get_byte, perhaps, this returns the next byte
from the buffer.
$buffer->put_char($bytes)
Appends a byte (or a sequence of bytes) to the buffer. There is no restriction
on the length of the byte string
$bytes; if it makes you uncomfortable
to call
put_char to put multiple bytes, you can instead call this
method as
put_chars. It's the same thing.
$buffer->get_bytes($n)
Grabs
$n bytes from the buffer, where
$n is a positive integer.
Increments the internal offset state by
$n.
$buffer->put_bytes($bytes [, $n ])
Appends a sequence of bytes to the buffer; if
$n is unspecified, appends
the entire length of
$bytes. Otherwise appends only the first
$n
bytes of
$bytes.
$buffer->get_str
Returns the next "string" from the buffer. A string here is
represented as the length of the string (a 32-bit integer) followed by the
string itself.
$buffer->put_str($string)
Appends a string (32-bit integer length and the string itself) to the buffer.
$buffer->extract($n)
Extracts the next
$n bytes from the buffer
$buffer, increments the
offset state in
$buffer, and returns a new buffer object containing the
extracted bytes.
TEMPLATE USAGE¶
Generally when you use
Data::Buffer it's to communicate with another
process (perhaps a C program) that bundles up its data into binary buffers. In
those cases, it's very likely that the data will be in some well-known order
in the buffer: in other words, it might be documented that a certain C program
creates a buffer containing:
- * an int8
- * a string
- * an int32
In this case, you would presumably know about the order of the data in the
buffer, and you could extract it accordingly:
$buffer->get_int8;
$buffer->get_str;
$buffer->get_int32;
In other cases, however, there may not be a well-defined order of data items in
the buffer. This might be the case if you're inventing your own protocol, and
you want your binary buffers to "know" about their contents. In this
case, you'll want to use the templating features of
Data::Buffer.
When you use the
put_ methods to place data in a buffer,
Data::Buffer keeps track of the types of data that you're inserting in
a template description of the buffer. This template contains all of the
information necessary for a process to receive a buffer and extract the data
in the buffer without knowledge of the order of the items.
To use this feature, simply use the
insert_template method after you've
filled your buffer to completion. For example:
my $buffer = Data::Buffer->new;
$buffer->put_str("foo");
$buffer->put_int32(9999);
$buffer->insert_template;
## Ship off the buffer to another process.
The receiving process should then invoke the
get_all method on the buffer
to extract all of the data:
my $buffer = Data::Buffer->new;
$buffer->append( $received_buffer_data );
my @data = $buffer->get_all;
@data will now contain two elements: "foo" and 9999.
LOW-LEVEL METHODS¶
$buffer->append($bytes)
Appends raw data
$bytes to the end of the in-memory buffer. Generally you
don't need to use this method unless you're initializing an empty buffer,
because when you need to add data to a buffer you should generally use one of
the
put_* methods.
$buffer->empty
Empties out the buffer object.
$buffer->bytes([ $offset [, $length [, $replacement ]]])
Behaves exactly like the
substr built-in function, except on the buffer
$buffer. Given no arguments,
bytes returns the entire buffer;
given one argument
$offset, returns everything from that position to
the end of the string; given
$offset and
$length, returns the
segment of the buffer starting at
$offset and consisting of
$length bytes; and given all three arguments, replaces that segment
with
$replacement.
This is a very low-level method, and you generally won't need to use it.
Also be warned that you should not intermix use of this method with use of the
get_* and
put_* methods; the latter classes of methods maintain
internal state of the buffer offset where arguments will be gotten from and
put, respectively. The
bytes method gives no thought to this internal
offset state.
$buffer->length
Returns the length of the buffer object.
$buffer->offset
Returns the internal offset state.
If you insist on intermixing calls to
bytes with calls to the
get_* and
put_* methods, you'll probably want to use this method
to get some status on that internal offset.
$buffer->set_offset($offset)
Sets the internal offset state to
$offset.
$buffer->reset_offset
Sets the internal offset state to 0.
$buffer->dump(@args)
Returns a hex dump of the buffer. The dump is of the
entire buffer
$buffer; in other words,
dump doesn't respect the internal
offset pointer.
@args is passed directly through to the
bytes method, which means
that you can supply arguments to emulate support of the internal offset:
my $dump = $buffer->dump($buffer->offset);
$buffer->insert_padding
A helper method: pads out the buffer so that the length of the transferred
packet will be evenly divisible by 8, which is a requirement of the SSH
protocol.
AUTHOR & COPYRIGHTS¶
Benjamin Trott, ben@rhumba.pair.com
Except where otherwise noted, Data::Buffer is Copyright 2001 Benjamin Trott. All
rights reserved. Data::Buffer is free software; you may redistribute it and/or
modify it under the same terms as Perl itself.