The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Protocol-CassandraCQL-0.05
River stage one • 1 direct dependent • 1 total dependent
/ Protocol::CassandraCQL::Frame

NAME

Protocol::CassandraCQL::Frame - a byte buffer storing the content of a CQL message frame

DESCRIPTION

This class provides wire-protocol encoding and decoding support for constructing and parsing Cassandra CQL message frames. An object represents a buffer during construction or parsing.

To construct a message frame, create a new empty object and use the pack_* methods to append data to it, before eventually obtaining the actual frame bytes using bytes. Each pack_* method returns the frame object, allowing them to be easily chained:

 my $bytes = Protocol::CassandraCQL::Frame->new
    ->pack_short( 123 )
    ->pack_int( 45678 )
    ->pack_string( "here is the data" )
    ->bytes;

To parse a message frame, create a new object from the bytes in the message, and use the unpack_* methods to consume the values from it.

 my $frame = Protocol::CassandraCQL::Frame->new( $bytes );
 my $s   = $frame->unpack_short;
 my $i   = $frame->unpack_int;
 my $str = $frame->unpack_string;

CONSTRUCTOR

$frame = Protocol::CassandraCQL::Frame->new( $bytes )

Returns a new frame buffer, optionally initialised with the given byte string.

( $version, $flags, $streamid, $opcode, $frame ) = Protocol::CassandraCQL::Frame->parse( $bytes )

Attempts to parse a complete frame from the given byte string. If it succeeds, it returns the header fields and an object containing the frame body. If it fails, it returns an empty list.

If successful, it will remove the bytes of the message from the $bytes scalar, which must therefore be mutable.

( $version, $flags, $streamid, $opcode, $frame ) = Protocol::CassandraCQL::Frame->recv( $fh )

Attempts to read a complete frame from the given filehandle, blocking until it is available. If an IO error happens, returns an empty list. The results are undefined if this method is called on a non-blocking filehandle.

METHODS

$bytes = $frame->bytes

Returns the byte string currently in the buffer.

$bytes = $frame->build( $version, $flags, $streamid, $opcode )

Returns a byte string containing a complete message with the given fields as the header and the frame as the body.

$frame->pack_short( $v )

$v = $frame->unpack_short

Add or remove a short value.

$frame->pack_int( $v )

$v = $frame->unpack_int

Add or remove an int value.

$frame->pack_string( $v )

$v = $frame->unpack_string

Add or remove a string value.

$frame->pack_lstring( $v )

$v = $frame->unpack_lstring

Add or remove a long string value.

$frame->pack_uuid( $v )

$v = $frame->unpack_uuid

Add or remove a UUID as a plain 16-byte raw scalar

$frame->pack_string_list( $v )

$v = $frame->unpack_string_list

Add or remove a list of strings from or to an ARRAYref

$frame->pack_bytes( $v )

$v = $frame->unpack_bytes

Add or remove opaque bytes or undef.

$frame->pack_short_bytes( $v )

$v = $frame->unpack_short_bytes

Add or remove opaque short bytes.

$frame->pack_inet( $v )

$v = $frame->unpack_inet

Add or remove an IPv4 or IPv6 address from or to a packed sockaddr string (such as returned from pack_sockaddr_in or pack_sockaddr_in6.

$frame->pack_string_map( $v )

$v = $frame->unpack_string_map

Add or remove a string map from or to a HASH of strings.

SPONSORS

This code was paid for by

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>