The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-OBEX-1.001001
River stage zero No dependents
++
/ Net::OBEX::Response

NAME

Net::OBEX::Response - interpret OBEX protocol response packets

SYNOPSIS

    use strict;
    use warnings;
    use Net::OBEX::Response;

    my $res = Net::OBEX::Response->new;

    # read 7 bytes of the Connect packet from the socket there somewhere
    # now parse it:
    my $response_ref = $res->parse( $data_from_the_socket, 1 );

    if ( $response_ref->{headers_length} ) {
        # ok, looks like we got some headers in this packet
        # read $response_ref->{headers_length} bytes from the socket
        # here and parse the headers.
    }

    # OMG SO COMPLICATED!!
    # now, let's try the EZ way, let's assume that $sock
    # is a Socket::Class object already connected to our "device"...

    # this is NOT a Connect packet, so we will omit the second argument
    # to the ->parse_sock() method.
    my $response_ref = $res->parse_sock( $sock );

    # boomm, now $response_ref is fully loaded and no mess with socket reads.

DESCRIPTION

WARNING!!! this module is still in early alpha stage. It is recommended that you use it only for testing. The module provides means to interpret raw OBEX protocol responses.

CONSTRUCTOR

new

    my $res = Net::OBEX::Response->new;

Takes no arguments, returns a freshly baked, right out of the oven, juicy with a cherry on top Net::OBEX::Response object ready to be used and abused.

METHODS

parse

    # parse a generic response
    my $generic_response = $res->parse( $data_from_wire );

    # parse response from Connect
    my $connect_response = $res->parse( $data_from_wire, 1 );

Takes one mandatory and one optional arguments. The first argument is the raw data from the wire representing the packet. The second one is either a true or false value indicating if the packet is a response to a Connect request or not, it defaults to 0. Returns a hashref with the following keys/values:

Sample returns (descriptions are below):

    # generic response
    $VAR1 = {
        'packet_length' => 3,
        'response_code' => 200,
        'headers_length' => 0,
        'response_code_meaning' => 'OK, Success'
    };

    # Connect response
    $VAR1 = {
        'mtu' => 5126,
        'flags' => '00000000',
        'packet_length' => 31,
        'obex_version' => '00010000',
        'response_code' => 200,
        'headers_length' => 24,
        'response_code_meaning' => 'OK, Success'
    };

packet_length

    { 'packet_length' => 3 }

The packet_length key will contain the length of the packet in bytes.

headers_length

    { 'headers_length' => 24 }

The headers_length key will contain the length of packet's headers in bytes. You would use this value to finish reading the entire packet from the socket, however, see the parse_sock() method described below.

response_code

    { 'response_code' => 200 }

The response_code key will contain a response code, this will pretty much be HTTP response codes since that what OBEX prefers to use.

response_code_meaning

    { 'response_code_meaning' => 'OK, Success' }

The response_code_meaning key will contain a human parseable explanation of response_code.

Additionally, if the "is connect response" argument to parse() is to a true value (and, of course, providing the packet is a proper Connect response) the hashref will have the following keys/values:

mtu

    { 'mtu' => 5126 }

The mtu key will contain the MTU of the responding device, i.e. the maximum length of a packet (in bytes) the device can accept.

flags

    { 'flags' => '00000000' }

The flags key will contain an unpacked "flags" byte, all but the first of those 8 bits are reserved. If the first bit is set it indicates support for multiple IrLMP connections to the same LSAP-SEL

obex_version

    { 'obex_version' => '00010000' }

The obex_version key will contain an unpacked "version" byte. Which is the version of the OBEX protocol encoded with the major number in the high order 4 bits, and the minor version in the low order 4 bits.

parse_sock

    my $sock = Socket::Class->new(
        domain        => 'bluetooth',
        type          => 'stream',
        proto         => 'rfcomm',
        remote_addr   => '00:17:E3:37:76:BB',
        remote_port   => 9,
    );

    # then later....

    my $response = $res->parse_sock( $sock, $is_this_a_connect_response )
        or die $res->error;

To cut down on the code for additional reads from the socket to collect all the packet headers you may want to use the parse_sock() method. Note: this was tested only with Socket::Class socket object, but in theory should work with all objects which provide read() (implemented in a Socket::Class fashion) and error() methods.

Takes one mandatory and one optional arguments. The first argument is the socket object which we will read from (it must be connected and ready to be read from). The second optional argument is either true or false value; if true, the data from the socket will be treated as a response to Connect, if false the data will be treated as a generic OBEX packet, it defaults to 0.

On failure will return either undef or an empty list depending on the context and the reason for failure will be available via error() method.

On success returns a hashref with the following keys/values:

Sample dump (description is below):

  $VAR1 = {
    'info' => {
        'flags' => '00000000',
        'packet_length' => 31,
        'obex_version' => '00010000',
        'response_code' => 200,
        'headers_length' => 24,
        'response_code_meaning' => 'OK, Success',
        'mtu' => 5126
    },
    'headers' => {
        'connection_id' => '',
        'who' => '��{ĕ<ҘNRTܞ  '
    },
    'raw_packet' => '�J��{ĕ<ҘNRTܞ   �'
  };

info

The info key will contain the hashref which is the return value of parse() method (see above).

headers

The headers key will contain a hashref which is the return value of the parse() method of the Net::OBEX::Packet::Headers object, see Net::OBEX::Packet::Headers documentation for details.

raw_packet

The raw_packet key will contain the raw data representing the packet as it was read from the socket.

error

    my $response = $res->parse_sock( $sock, $is_this_a_connect_response )
        or die $res->error;

If an error occurred during the call to parse_sock() method it will return either undef or an empty list depending on the context and the reason for the error will be available via error() method. Takes no arguments, returns a human readable error message.

obj_connect

    my $obj = $res->obj_connect;

Takes no arguments, returns the Net::OBEX::Response::Connect object used in parsing.

obj_generic

    my $obj = $res->obj_generic;

Takes no arguments, returns the Net::OBEX::Response::Generic object used in parsing.

obj_head

    my $obj = $res->obj_generic;

Takes no arguments, returns the Net::OBEX::Packet::Headers object used in parsing.

SEE ALSO

Net::OBEX::Packet::Headers, Net::OBEX::Response::Connect, Net::OBEX::Response::Generic

REPOSITORY

Fork this module on GitHub: https://github.com/zoffixznet/Net-OBEX

BUGS

To report bugs or request features, please use https://github.com/zoffixznet/Net-OBEX/issues

If you can't access GitHub, you can email your request to bug-Net-OBEX at rt.cpan.org

AUTHOR

Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.