In other cases, however, there may not be a well-defined order of data items in the buffer. This might be the case if youre inventing your own protocol, and you want your binary buffers to know about their contents. In this case, youll 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 youre 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 youve filled your buffer to completion. For example:
my $buffer = Data::Buffer->new;
## 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.
CW$buffer->append($bytes)Appends raw data $bytes to the end of the in-memory buffer. Generally you dont need to use this method unless youre initializing an empty buffer, because when you need to add data to a buffer you should generally use one of the put_* methods.
CW$buffer->emptyEmpties out the buffer object.
CW$buffer->bytes([ CW$offset [, CW$length [, CW$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 wont 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.
CW$buffer->lengthReturns the length of the buffer object.
CW$buffer->offsetReturns the internal offset state.
If you insist on intermixing calls to bytes with calls to the get_* and put_* methods, youll probably want to use this method to get some status on that internal offset.
CW$buffer->set_offset($offset)Sets the internal offset state to $offset.
CW$buffer->reset_offsetSets the internal offset state to 0.
CW$buffer->dump(@args)Returns a hex dump of the buffer. The dump is of the entire buffer $buffer; in other words, dump doesnt 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);
CW$buffer->insert_paddingA 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.
Benjamin Trott, email@example.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.
|perl v5.20.3||BUFFER (3)||2001-07-28|