/ 
POE-Component-Client-opentick-0.01
River stage one • 1 direct dependent • 1 total dependent
/ POE::Component::Client::opentick::Error

NAME

POE::Component::Client::opentick::Error - Error handling routines for opentick client.

SYNOPSIS

use POE::Component::Client::opentick::Error;

my $error = POE::Component::Client::opentick::Error->new(
       Message     => 'Something kasplodinated!',
);

-or-

my $error = POE::Component::Client::opentick::Error->new(
       Data        => $packet_error_data,   # Error body, off the wire
       Command     => $OT_LOGIN,            # an integer
       DumpStack   => 1,                    # a true value
       RequestID   => 42,                   # Protocol ReqID, integer
);

# Easy.
print "$error\n";

# Other available methods.
print $error->get_message(), "\n";
print $error->get_stack(), "\n";
my $cmd_id = $error->get_command();

# Expand the raw protocol error message
my( $errcode, $errdesc ) = $error->get_data();    # list context
# Just get the raw data itself
my $data                 = $error->get_data();    # scalar context

DESCRIPTION

This module contains all of the error-handling routines used by the rest of POE::Component::Client::opentick.

It overloads stringification to print a formatted message when used within "" (quotes) for ease of use, but you are free to call its methods to reach all of the contents yourself.

It can also be subclassed to encapsulate and perform your own error handling, if so desired.

METHODS

new( [ @args ] ) -- create and bless a new object

Checks that arguments are passed in in even numbers, croaks if not.

RETURNS: $object

ARGUMENTS:

Message     => $error_msg      stringified error message
Data        => $data           packed binary data from OT's protocol
DumpStack   => $boolean        [opt] dump the call stack (defaults to false)
RequestID   => $integer        [opt] Request ID from which this packet came
CommandID   => $integer        [opt] opentick <CommandType>

*** (at least ONE of Message or Data are REQUIRED)

initialize( [ @args ] ) -- configure a new object

RETURNS: undef

ARGUMENTS:

Actually, all of the above arguments are passed onto initialize() and stored at that point.

stringify( ) -- stringify the object

RETURNS: $stringified_error_message

ARGUMENTS: none

throw( $item ) -- explode with an error message

RETURNS: Sure doesn't.

ARGUMENTS: a message or an Error (or subclassed Error) object.

ACCESSORS

Obviously, to use the object effectively, you should be able to reach its contents. Here are accessor methods for grabbing the various fields that may be available within the object.

These will return appropriate contents, or undef if nothing was supplied.

get_message( )

Returns the message supplied in the constructor.

get_stack( )

Returns the call stack at the time of object construction.

dump_stack( )

Returns BOOLEAN as to whether DumpStack was specified in the constructor.

set_dump_stack( $bool )

Use to set dump_stack later if you should change your mind.

get_request_id( )

Returns the Request ID passed in the constructor.

get_command_id( )

Returns the integral command id supplied

get_command( )

Returns ( $cmd_name, $cmd_id ) in list context.

get_data( )

Returns the raw packet data in scalar context, expanded packet data into two fields in list context: ( $error_code, $error_description ).

SUBCLASSING

To subclass Error.pm, overload the initialize(), stringify() and throw methods with functions of your own choosing, to dump the appropriate data. new() should not be overloaded.

NOTES

This module uses the Perl 'overload' pragma to overload the stringification operator '""', and point it to the stringify() method. This makes error dumpage easier. This is also why you should overload stringify() with a method of your own design, if you should subclass the module.

SEE ALSO

POE, POE::Component::Client::opentick

http://poe.perl.org

http://www.opentick.com/

AUTHOR

Jason McManus (infi)

LICENSE

Copyright (c) Jason McManus

This module may be used, modified, and distributed under the same terms as Perl itself. Please see the license that came with your Perl distribution for details.

The data from opentick.com are under an entirely separate license that varies according to exchange rules, etc. It is your responsibility to follow the opentick.com and exchange license agreements with the data.

Further details are available on http://www.opentick.com/.