Why not adopt me?

This distribution is up for adoption! If you're interested then please contact the PAUSE module admins via email.

NAME

Net::OBEX - implementation of OBEX protocol

SYNOPSIS

use strict;
use warnings;

use Net::OBEX;

my $obex = Net::OBEX->new;

my $response_ref = $obex->connect(
    address => '00:17:E3:37:76:BB',
    port    => 9,
    target  => 'F9EC7BC4953C11D2984E525400DC9E09', # OBEX FTP UUID
) or die "Failed to connect: " . $obex->error;

unless ( $response_ref->{info}{response_code} == 200 ) {
    die "Server no liky :( " . $response_ref->{info}{response_code_meaning};
}

$response_ref = $obex->set_path
    or die "Error: " . $obex->error;

unless ( $response_ref->{info}{response_code} == 200 ) {
    die "Server no liky :( " . $response_ref->{info}{response_code_meaning};
}

# this is an OBEX FTP example, so we'll get the folder listing now
$response_ref = $obex->get( type => 'x-obex/folder-listing' )
    or die "Error: " . $obex->error;

# note: for gets, there might be multiple requests, so there is no {info}
my $code = $response_ref->{response_code};
unless ( $code == 200 or $code == 100 ) {
    die "Server no liky :( "
            . $response_ref->{response_code_meaning};
}

print "This is folder listing XML: \n$response_ref->{body}\n";

# send Disconnect packet with description header and close the socket
$obex->close('No want you no moar');

DESCRIPTION

WARNING!!! This module is still in its early alpha stage, it is recommended that you use it only for testing. A lot of functionality is still not implemented.

The module is a Perl implementation of IrOBEX protocol.

CONSTRUCTOR

new

my $obex = Net::OBEX->new;

Takes no arguments, returns a freshly baked Net::OBEX object ready to use and abuse.

METHODS

connect

my $response_ref = $obex->connect(
    address => '00:17:E3:37:76:BB',
    port    => 9,
) or die "Failed to connect: " . $obex->error;

my $response_ref = $obex->connect(
    address => '00:17:E3:37:76:BB',
    port    => 9,
    version => "\x10",
    mtu     => 4096,
    domain  => 'bluetooth',
    type    => 'stream',
    proto   => 'rfcomm',
    headers => [ $some, $raw, $headers ],
) or die "Failed to connect: " . $obex->error;

Creates a new socket and connects it. Takes a bunch of arguments, two of which (address and port) are mandatory. Net::OBEX uses Socket::Class as its "horse" but it might be possible to use a different socket if you want to (see sock() method). Returns a hashref which is described below after arguments. Possible arguments are as follows:

address

->connect( address => '00:17:E3:37:76:BB', ...

Mandatory. Specifies the MAC address of the device to connect to.

port

->connect( port => 9, ...

Mandatory. Specifies the port of the device to connect to.

version

->connect( version => "\x10", ...

Optional. Specifies the OBEX protocol version to use, takes a "version" byte to use in the Connect packet encoded with the major number in the high order 4 bits, and the minor version in the low order 4 bits. Generally speaking you won't have to touch this one. Defaults to: 0x10 (version 1.0)

mtu

->connect( mtu     => 4096, ...

Optional. Specifies the MTU of your device, i.e. the maximum length of the packet in bytes it can accept. Defaults to: 4096

domain

->connect( domain  => 'bluetooth', ...

Optional. Specifies the domain argument to pass to Socket::Class constructor. See documentation for Socket::Class for more information. Defaults to: bluetooth

type

->connect( type    => 'stream', ...

Optional. Specifies the type argument to pass to Socket::Class constructor. See documentation for Socket::Class for more information. Defaults to: stream

proto

->connect( proto   => 'rfcomm', ...

Optional. Specifies the proto argument to pass to Socket::Class constructor. See documentation for Socket::Class for more information. Defaults to: rfcomm

headers

->connect( headers => [ $some, $raw, $headers ], ...

Optional. If you want to pass along some additional packet headers to the Connect packet you can use the headers argument which takes an arrayref elements of which are OBEX packet headers. See Net::OBEX::Packet::Headers for information on how to make them. Defaults to: [] (no headers)

target

->connect( target => 'F9EC7BC4953C11D2984E525400DC9E09', ....

Optional. Since it's common that you will need a Target header in the Connect packet you can use the target argument instead of manually creating the header. Note: the module will automatically pack() what you specify in the target argument, so you can just use the UUID (without dashes). By default no target is specified.

`connect` RETURN VALUE

$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Üž   ï¿½'
};

If an error occured during the request, connect() will return either undef or an empty list, depending on the context and the reason for the error will be available via error() method. Otherwise it will return a hashref presented above. If the dump above is not self explanatory see Net::OBEX::Response parse_sock() method description for the return value when "is connect packet" option is true.

SPECIAL NOTE ON CONNECTION ID HEADER

If the Connection ID header is present in the Connect response packet the module will save it and automatically include it in any other packet as the first header as per specification. The raw generated Connection ID header which will be included in all other packets is accessible via connection_id() accessor/mutator. If you want to override the automatic inclusion of the header in all packets set connection_id('') after the call to connect() but generally this is a BadIdea(tm) and you probably will get a 403 on all the requests.

disconnect

my $response_ref = $obex->disconnect
    or die "Error: " . $obex->error;

my $response_ref = $obex->disconnect(
    description => 'die in a fire!',
    headers     => [ $some, $other, $raw, $headers ],
) or die "Error: " . $obex->error;

Instructs the object to send a Disconnect packet without closing the socket (whether it will actually stay open is another matter). If you want to close the socket as well, you probably would want to use the close() method instead. Takes two optional arguments:

description

$obex->disconnect( description => 'die in a fire!' );

Optional. Takes a scalar as an argument which will be passed in the Description header in the Disconnect packet. By default no description is supplied.

headers

$obex->disconnect( headers => [ $some, $raw, $headers ] );

Optional. If you want to pass along some additional packet headers to the Disconnect packet you can use the headers argument which takes an arrayref elements of which are OBEX packet headers. See Net::OBEX::Packet::Headers for information on how to make them. Defaults to: [] (no headers)

`disconnect` RETURN VALUE

$VAR1 = {
    'info' => {
        'packet_length' => 3,
        'response_code' => 200,
        'headers_length' => 0,
        'response_code_meaning' => 'OK, Success'
    },
    'raw_packet' => 'ï¿½'
};

If an error occured during the request, disconnect() will return either undef or an empty list, depending on the context and the reason for the error will be available via error() method. Otherwise it will return a hashref presented above. If the dump above is not self explanatory see Net::OBEX::Response parse_sock() method description for the return value when "is connect packet" option is false.

set_path

my $response_ref = $obex->set_path
    or die "Error: " . $obex->error;

my $response_ref = $obex->set_path(
    path    => 'there_somewhere',
    headers => [ $bunch, $of, $raw, $headers ],
) or die "Error: " . $obex->error;

Instructs the object to send a SetPath packet. Takes four optional arguments which are as follows:

path

$obex->set_path( path => 'there_somewhere' );

Optional. Whatever you specify in the path argument will be sent out in the packet's Name header, which is the path to change to. By default no path is set, meaning set path to "root folder".

do_up

$obex->set_path( do_up => 1 );

Optional. Takes either true or false value, indicating whether or not to set the "backup a level before applying name" flag in the SetPath packet. Defaults to: 0

no_create

$obex->set_path( no_create => 0 );

Optional. Takes either true or false value, indicating whether or not to set the "don't create directory if it does not exist, return an error instead." flag in the SetPath packet. Defaults to: 1

headers

$obex->set_path( headers => [ $some, $raw, $headers ] );

Optional. If you want to pass along some additional packet headers to the SetPath packet you can use the headers argument which takes an arrayref elements of which are OBEX packet headers. See Net::OBEX::Packet::Headers for information on how to make them. Defaults to: [] (no headers)

`set_path` RETURN VALUE

$VAR1 = {
    'info' => {
        'packet_length' => 3,
        'response_code' => 200,
        'headers_length' => 0,
        'response_code_meaning' => 'OK, Success'
    },
    'raw_packet' => 'ï¿½'
};

If an error occured during the request, set_path() will return either undef or an empty list, depending on the context and the reason for the error will be available via error() method. Otherwise it will return a hashref presented above. If the dump above is not self explanatory see Net::OBEX::Response parse_sock() method description for the return value when "is connect packet" option is false.

get

$response_ref = $obex->get
    or die "Error: " . $obex->error;

$response_ref = $obex->get(
    is_final    => 1,
    headers     => [ $bunch, $of, $raw, $headers ],
    type        => 'x-obex/folder-listing',
    name        => 'some_file',
    no_continue => 1,
    file        => $fh,
) or die "Error: " . $obex->error;

Instructs the obect to send an OBEX Get packet and any number of Get (Continue) packets needed to finish the request (by default). Takes several arguments, all of which are optional. The possible arguments are as follows:

is_final

$obex->get( is_final => 1 );

Optional. When set to a true value will instruct the object to set the high bit of the Get packet on. When set to a false value will set the high bit off. Defaults to: 1

headers

$obex->get( headers => [ $some, $raw, $headers ] );

Optional. If you want to pass along some additional packet headers to the Get packet you can use the headers argument which takes an arrayref elements of which are OBEX packet headers. See Net::OBEX::Packet::Headers for information on how to make them. Defaults to: [] (no headers)

type

$obex->get( type => 'x-obex/folder-listing' );

Optional. Takes a scalar as value, whatever you specify will be packed up into a OBEX Type header and shipped along with your Get packet. By default type is not specified.

name

$obex->get( name => 'some_file' );

Optional. Takes a scalar as value, whatever you specify will be packed up into a OBEX Name header and shipped along with your Get packet. By default name is not specified.

no_continue

$obex->get( no_continue => 1 );

Optional. By default the get() method will automatically send out any Get (Continue) packets to get the entire data. However, if that's not what you want set the no_continue to a true value. When set to a false value will automatically send as many Get (Continue) packets as needed to get the entire thing, when set to a true value will send only one Get packet leaving the rest up to you. Defaults to: 0

file

$obex->get( file => $file_handle );

Optional. If you are retrieving large quantities of data it is probably not a good idea to stuff all of it into a hashref. The file argument takes an open file handle, and when specified will write the data into that file instead of storing it in the return hashref. By default fetched data will be returned in the return hashref.

`get` RETURN VALUE

$VAR1 = {
        'body' => '<?xml version="1.0" ?>
<!DOCTYPE folder-listing SYSTEM "obex-folder-listing.dtd">
<folder-listing>
<parent-folder />
<folder name="audio" size="0" type="folder" modified="19700101T000000Z" user-perm="RW" />
<folder name="video" size="0" type="folder" modified="19700101T000000Z" user-perm="RW" />
<folder name="picture" size="0" type="folder" modified="19700101T000000Z" user-perm="RW" />
</folder-listing>
',
        'responses' => [
                        {
                            'info' => {
                                        'packet_length' => 6,
                                        'response_code' => 100,
                                        'headers_length' => 3,
                                        'response_code_meaning' => 'Continue'
                                    },
                            'headers' => {
                                            'body' => ''
                                        },
                            'raw_packet' => 'ï¿½H'
                        },
                        {
                            'info' => {
                                        'packet_length' => 413,
                                        'response_code' => 100,
                                        'headers_length' => 410,
                                        'response_code_meaning' => 'Continue'
                                    },
                            'headers' => {
                                            'body' => '<?xml version="1.0" ?>
<!DOCTYPE folder-listing SYSTEM "obex-folder-listing.dtd">
<folder-listing>
<parent-folder />
<folder name="audio" size="0" type="folder" modified="19700101T000000Z" user-perm="RW" />
<folder name="video" size="0" type="folder" modified="19700101T000000Z" user-perm="RW" />
<folder name="picture" size="0" type="folder" modified="19700101T000000Z" user-perm="RW" />
</folder-listing>
'
                                        },
                            'raw_packet' => 'ï¿½ï¿½Hï¿½<?xml version="1.0" ?>
<!DOCTYPE folder-listing SYSTEM "obex-folder-listing.dtd">
<folder-listing>
<parent-folder />
<folder name="audio" size="0" type="folder" modified="19700101T000000Z" user-perm="RW" />
<folder name="video" size="0" type="folder" modified="19700101T000000Z" user-perm="RW" />
<folder name="picture" size="0" type="folder" modified="19700101T000000Z" user-perm="RW" />
</folder-listing>
'
                        },
                        {
                            'info' => {
                                        'packet_length' => 6,
                                        'response_code' => 200,
                                        'headers_length' => 3,
                                        'response_code_meaning' => 'OK, Success'
                                    },
                            'headers' => {
                                            'end_of_body' => ''
                                        },
                            'raw_packet' => 'ï¿½I'
                        }
                        ],
        'response_code' => 100,
        'response_code_meaning' => 'Continue'
        };

The get() method returns either undef or an empty list (depending on the context) if an error occured and the explanation of the error will by available via error() method. Otherwise it returns a big hashref. As opposed to connect(), disconnect() and set_path() method the returned hashref from get() method is a bit different because it can send (by default) several Get requests to fetch entire data. The keys/values of the return are as follows:

body

The <body> key will contain the entire data that was retrieved (if no_continue is false) or the contents of the Body header of the packet (if no_continue is set to a true value). If file argument is set, the body key will be empty.

response_code

The response_code key will contain the response code of the first received packet, note that if the request requires several Get packets to be sent out, the response code will be 100 (Continue) not 200.

response_code_meaning

The response_code_meaning key will contain the meaning of the response code of the first received packet.

responses

The responses key will contain an arrayref elements of which will be the return values of parse_sock() method from Net::OBEX::Headers module. There will be as many elements as many Get packets were sent out to retrieve entire data; of course, there will be only one if no_continue argument to get() is set to a true value. For more information, see parse_sock() method in Net::OBEX::Headers with the "is connect packet" flag set to false. If file argument is set, responses arrayref will be empty.

close

$obex->close;

$obex->close('No want you no moar');

Similiar to disconnect() method, except this one also closes the socket. Takes one optional argument which is the text to send out in the Description header of the Disconnect packet. Always returns 1.

response

my $last_response_ref = $obex->response;

Takes no arguments, returns the return value of the last successful get(), set_path(), connect() or disconnect() method.

sock

my $socket = $obex->sock;

$obex->sock( $new_socket );

Returns a Socket::Class object which is used by the module for communications. Technically you can swap it out to the socket of your choice by giving it as an argument (but should you? :) ).

error

my $response_ref = $obex->set_path
    or die "Error: " . $obex->error;

If any of the connect(), disconnect(), set_path or get() methods fail they will return either undef or an empty list depending on the context and the reason for the failure will be available via error() method. Takes no arguments, returns a human readable error message.

connection_id

my $raw_connection_id_header = $obex->connection_id;

If Connection ID header was present in the response to the Connect packet when calling the connect() method the Net::OBEX object will automatically store it and include it in any other packets sent after connection (as per specs). The connection_id() method returns a raw Connection ID header, it may take an argument which will override the set header, but it's probably a BadIdea(tm).

obj_res

my $net_obex_response_object = $obex->obj_res;

Takes no arguments, returns a Net::OBEX::Response object used internally.

obj_head

my $net_obex_packet_headers_object = $obex->obj_head;

Takes no arguments, returns a Net::OBEX::Packet::Headers object used internally. You can use this object to create any additional headers you'd want to include in headers arguments (where applicable).

obj_req

my $net_obex_packet_request = $obex->obj_req;

Takes no arguments, returns a Net::OBEX::Packet::Request object used internally.

AUTHOR

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

BUGS

Please report any bugs or feature requests to bug-net-obex at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-OBEX. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::OBEX

You can also look for information at:

RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-OBEX
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Net-OBEX
CPAN Ratings

http://cpanratings.perl.org/d/Net-OBEX
Search CPAN

http://search.cpan.org/dist/Net-OBEX

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 474:: Non-ASCII character seen before =encoding in ''ï¿½ï¿½{Ä•<Ò˜NRTÜž'. Assuming CP1252

To install Net::OBEX, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::OBEX

CPAN shell

perl -MCPAN -e shell
install Net::OBEX

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

Why not adopt me?

NAME

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

new

METHODS

connect

address

port

version

mtu

domain

type

proto

headers

target

connect RETURN VALUE

SPECIAL NOTE ON CONNECTION ID HEADER

disconnect

description

headers

disconnect RETURN VALUE

set_path

path

do_up

no_create

headers

set_path RETURN VALUE

get

is_final

headers

type

name

no_continue

file

get RETURN VALUE

body

response_code

response_code_meaning

responses

close

response

sock

error

connection_id

obj_res

obj_head

obj_req

AUTHOR

BUGS

SUPPORT

COPYRIGHT & LICENSE

Module Install Instructions

`connect` RETURN VALUE

`disconnect` RETURN VALUE

`set_path` RETURN VALUE

`get` RETURN VALUE