NAME

"Protocol::CassandraCQL::Frames" - build or parse frame bodies for specific message types

SYNOPSIS

 use Protocol::CassandraCQL qw( build_frame );
 use Protocol::CassandraCQL::Frames qw( build_query_frame );

 my $bytes = build_frame( 0x01, 0, $streamid, OPCODE_QUERY,
    build_query_frame( 1,
       cql => "CQL STRING",
       consistency => $consistency
    )->bytes
 );

DESCRIPTION

This module provides a number of convenient functions to build and parse frame bodies for specific kinds of "CQL" message. Each should be paired with a call to "build_frame" or "send_frame" with the appropriate opcode constant, or invoked after "parse_frame" or "recv_frame" has received a frame with the appropriate opcode.

Each "build_*" function takes as its first argument the "CQL" protocol version (the value that will be passed to "build_frame" or "send_frame"). This value is used to ensure all the correct information is present in the frame body, and that no optional parameters are passed that the chosen version of the protocol cannot support.

FUNCTIONS

$frame = build_startup_frame( $version, options => \%options )

Builds the frame for an "OPCODE_STARTUP" message. Takes a reference to a hash of named options. These options should include "CQL_VERSION".

$frame = build_credentials_frame( $version, credentials => \%credentials )

Builds the frame for an "OPCODE_CREDENTIALS" message. Takes a reference to a hash of credentials, the exact keys of which will depend on the authenticator returned by the "OPCODE_AUTHENTICATE" message.

$frame = build_query_frame( $version, cql => $cql, QUERY_PARAMS )

Builds the frame for an "OPCODE_QUERY" message. Takes the CQL string and the query parameters.

"QUERY_PARAMS" contains the following keys:

consistency => INT: The consistency level. (required)
values => ARRAY of STRING: The encoded byte values of the bind parameters (optional, v2+ only)
skip_metadata => BOOL: If true, sets the "QUERY_SKIP_METADATA" flag. (optional, v2+ only)
page_size => INT: The paging size (optional, v2+ only)
paging_state => STRING: The paging state from the previous result to a query or execute. (optional, v2+ only)
serial_consistency => INT: The consistency level for CAS serialisation operations (optional, v2+ only)

RESULT_VOID
$result is "undef". (This is returned by data modification queries such as "INSERT", "UPDATE" and "DELETE").
RESULT_ROWS
$result is an instance of Protocol::CassandraCQL::Result containing the row data. (This is returned by "SELECT" queries).
RESULT_SET_KEYSPACE
$result is a string containing the new keyspace name. (This is returned by "USE" queries).
RESULT_PREPARED
$result is an ARRAY reference containing the query ID as a string, and the bind parameters' metadata as an instance of Protocol::CassandraCQL::ColumnMeta. For v2+ this will also return the result metadata as another "Protocol::CassandraCQL::ColumnMeta" instance.
RESULT_SCHEMA_CHANGE
$result is an ARRAY reference containing three strings, giving the type of change, the keyspace, and the table name. (This is returned by data definition queries such as "CREATE", "ALTER" and "DROP").

If any other type is encountered, $result will be the $frame object itself.

( $event, @args ) = parse_event_frame( $version, $frame )

Parses the frame from an "OPCODE_EVENT" message. Returns the event name and a list of its arguments; which will vary depending on the event name.

TOPOLOGY_CHANGE
@args will contain the change type string and a node inet address
STATUS_CHANGE
@args will contain the status type string and a node inet address
SCHEMA_CHANGE
@args will contain three strings, containing the change type, keyspace, and table name

If the event name is unrecognised, @args will return just the $frame object itself.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

$frame = build_startup_frame( $version, options => \%options )

$frame = build_credentials_frame( $version, credentials => \%credentials )

$frame = build_query_frame( $version, cql => $cql, QUERY_PARAMS )

$frame = build_prepare_frame( $version, cql => $cql )

$frame = build_execute_frame( $version, id => $id, QUERY_PARAMS )

$frame = build_register_frame( $version, events => \@events )

( $err, $message ) = parse_error_frame( $version, $frame )

( $authenticator ) = parse_authenticate_frame( $version, $frame )

( $options ) = parse_supported_frame( $version, $frame )

( $type, $result ) = parse_result_frame( $version, $frame )

( $event, @args ) = parse_event_frame( $version, $frame )

SPONSORS

AUTHOR