.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bluetooth 3pm"
.TH Bluetooth 3pm "2018-11-01" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Bluetooth \- Perl Bluetooth Interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::Bluetooth;
\&
\&  #### list all remote devices in the area
\&  my $device_ref = get_remote_devices();
\&  foreach $addr (keys %$device_ref) {
\&        print "Address: $addr Name: $device_ref\->{$addr}\en";
\&  }
\&
\&
\&  #### search for a specific service (0x1101) on a remote device 
\&  my @sdp_array = sdp_search($addr, "1101", "");
\&
\&  #### foreach service record
\&  foreach $rec_ref (@sdp_array) {
\&        #### Print all available information for service
\&        foreach $attr (keys %$rec_ref) {
\&                print "Attribute: $attr Value: $rec_ref\->{$attr}\en";
\&        }
\&  }
\&
\&
\&  #### Create a RFCOMM client 
\&  $obj = Net::Bluetooth\->newsocket("RFCOMM");
\&  die "socket error $!\en" unless(defined($obj)); 
\&  if($obj\->connect($addr, $port) != 0) {
\&        die "connect error: $!\en";
\&  }
\&
\&  #### create a Perl filehandle for reading and writing
\&  *SERVER = $obj\->perlfh();
\&  $amount = read(SERVER, $buf, 256);
\&  close(SERVER);
\&
\&
\&
\&  #### create a RFCOMM server
\&  $obj = Net::Bluetooth\->newsocket("RFCOMM");
\&  #### bind to port 1
\&  if($obj\->bind(1) != 0) {
\&        die "bind error: $!\en";
\&  }
\&
\&  #### listen with a backlog of 2
\&  if($obj\->listen(2) != 0) {
\&        die "listen error: $!\en";
\&  }
\&
\&  #### register a service
\&  #### $obj must be a open and bound socket
\&  my $service_obj = Net::Bluetooth\->newservice($obj, "1101", "GPS", "GPS Receiver");
\&  unless(defined($service_obj)) {
\&        #### couldn\*(Aqt register service
\&  }
\&
\&  #### accept a client connection
\&  $client_obj = $obj\->accept();
\&  unless(defined($client_obj)) {
\&        die "client accept failed: $!\en";
\&  }
\&
\&  #### get client information
\&  my ($caddr, $port) = $client_obj\->getpeername();
\&
\&  #### create a Perl filehandle for reading and writing
\&  *CLIENT = $client_obj\->perlfh();
\&  print CLIENT "stuff";
\&
\&  #### close client connection
\&  close(CLIENT);
\&  #### stop advertising service
\&  $service_obj\->stopservice();
\&  #### close server connection
\&  $obj\->close();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module creates a Bluetooth interface for Perl.
.PP
Net::Bluetooth works with the BlueZ libs as well as with
Microsoft Windows.
.PP
If you are going to be using a Unix system, the Bluez libs can
be obtained at www.bluez.org. Please make sure these are installed
and working properly before you install the module. Depending on
your system BlueZ maybe already installed, or you may have to build
it yourself and do some configuration. You can verify that BlueZ can
detect devices and services with the utilities that are included with
it (hciconfig, sdptool, hcitool, etc).
.PP
If you are using Windows, please make sure you have Service Pack 2
installed and the Microsoft Platform \s-1SDK.\s0 Also please make sure the
\&\*(L"$win_include\*(R" variable at the top of Makfile.PL is set properly. This
needs to point to the \s-1SDK\s0 include directory for \s-1SP2.\s0 This is where the
module will look for all the Bluetooth header files (ws2bth.h, etc).
.PP
Please check out the samples included in the samples directory for more
general information.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\fBget_remote_devices()\fR" 4
.IX Item "get_remote_devices()"
Searches for remote Bluetooth devices. The search will
take approximately 5 \- 10 seconds (This will be a configurable 
value in the future.). When finished, it will return a hash
reference that contains the device address and name. The
address is the key and the name is the value. Name will be
set to \*(L"[unknown]\*(R" if the name could not be resolved. See the
\&\s-1NOTES\s0 section of this document for more information about this.
.ie n .IP "sdp_search($addr, $uuid, $name)" 4
.el .IP "sdp_search($addr, \f(CW$uuid\fR, \f(CW$name\fR)" 4
.IX Item "sdp_search($addr, $uuid, $name)"
This searches a specific device for service records. The first
argument is the device address which is not optional. The uuid
argument can be a valid uuid or \*(L"0\*(R". The name argument can be a
valid service name or "". It will return services that match
the uuid or service name if supplied, otherwise it will return
all public service records for the device.
.Sp
The return value is a list which contains a hash reference for
each service record found. The key/values for the hash are as follows:
.Sp
\&\f(CW\*(C`SERVICE_NAME\*(C'\fR: Service Name
.Sp
\&\f(CW\*(C`SERVICE_DESC\*(C'\fR: Service Description
.Sp
\&\f(CW\*(C`SERVICE_PROV\*(C'\fR: Service Provider
.Sp
\&\f(CW\*(C`RFCOMM\*(C'\fR: \s-1RFCOMM\s0 Port
.Sp
\&\f(CW\*(C`L2CAP\*(C'\fR: L2CAP Port
.Sp
\&\f(CW\*(C`UNKNOWN\*(C'\fR: Unknown Protocol  Port
.Sp
If any of the values are unavailable, the keys will not exist.
.Sp
If \f(CW$addr\fR is \*(L"localhost\*(R" the call will use the local \s-1SDP\s0 server.
.SH "SOCKET OBJECT"
.IX Header "SOCKET OBJECT"
The bluetooth socket object is used to create bluetooth sockets and
interface with them. There are two types of sockets supported, \s-1RFCOMM\s0 and
L2CAP. The methods are listed below.
.ie n .IP "newsocket(""\s-1RFCOMM""\s0)" 4
.el .IP "newsocket(``\s-1RFCOMM''\s0)" 4
.IX Item "newsocket(RFCOMM)"
This constructs a socket object for a \s-1RFCOMM\s0 socket or L2CAP
socket.
.ie n .IP "connect($addr, $port)" 4
.el .IP "connect($addr, \f(CW$port\fR)" 4
.IX Item "connect($addr, $port)"
This calls the \fBconnect()\fR system call with the address and port you
supply. You can use this to connect to a server. Returns 0 on
success.
.IP "bind($port)" 4
.IX Item "bind($port)"
This calls the \fBbind()\fR system call with the port you provide. 
You can use this to bind to a port if you are creating a server.
Returns 0 on success. As a side note, \s-1RFCOMM\s0 ports can only range
from 1 \- 31.
.IP "listen($backlog)" 4
.IX Item "listen($backlog)"
This calls the \fBlisten()\fR system call with the backlog you provide.
Returns 0 on success.
.IP "\fBaccept()\fR" 4
.IX Item "accept()"
This calls the \fBaccept()\fR system call and creates a new bluetooth
socket object which is returned. On failure it will return undef.
.IP "\fBperlfh()\fR" 4
.IX Item "perlfh()"
This call returns a Perl filehandle for a open socket. You can
use the Perl filehandle as you would any other filehandle, except
with Perl functions that use the socket address structure. This 
provides a easy way to do socket \s-1IO\s0 instead of doing it through the
socket object. Currently this is the only way to do socket \s-1IO,\s0
although soon I will provide read/write calls through the object
interface.
.IP "\fBclose()\fR" 4
.IX Item "close()"
This closes the socket object. This can also be done through the
Perl \fBclose()\fR call on a created Perl filehandle.
.IP "\fBgetpeername()\fR" 4
.IX Item "getpeername()"
This returns the address and name for a open bluetooth socket. (BlueZ only
for now)
.SH "SERVICE OBJECT"
.IX Header "SERVICE OBJECT"
The service object allows you to register a service with your local
\&\s-1SDP\s0 server. The methods are as follows:
.ie n .IP "newservice($obj, $service_uuid, $service_name, $service_desc)" 4
.el .IP "newservice($obj, \f(CW$service_uuid\fR, \f(CW$service_name\fR, \f(CW$service_desc\fR)" 4
.IX Item "newservice($obj, $service_uuid, $service_name, $service_desc)"
This registers a service with your local \s-1SDP\s0 server. The first
argument is a open and bound socket that you created with \fBnewsocket()\fR.
The second argument is the service uuid. The third argument is the
service name. The fourth argument is the service description.
.Sp
The return value is a new service object. This will be undefined
if there was an error.
.IP "\fBstop_service()\fR" 4
.IX Item "stop_service()"
This unregisters your service with the local \s-1SDP\s0 server. The service 
will be unregistered without this call when the application exits.
.SH "NOTES"
.IX Header "NOTES"
All uuids used with this module can either be 128 bit values:
\&\*(L"00000000\-0000\-0000\-0000\-000000000000\*(R" or 16 bit values: \*(L"0000\*(R". All values
must be represented as strings (enclosed in quotes), and must be hexadecimal
values.
.PP
Windows will not immediately return the device name if it is not already
cached. Also there is no mechinism to alert the system when it has acquired
the device name. Therefore you may have to call \fBget_remote_devices()\fR twice
before the name shows up. I'll see if this can be handled better in the
future.
.PP
Currently on Windows the service name and description returned by \fBsdp_search()\fR
are not setting their terminating \s-1NULL\s0 character properly. This can result in
some garbage characters at the end of the string. I am looking at parsing
the raw record to fix this problem.
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
You need BlueZ or Microsoft Service Pack 2 installed and the Microsoft Platform \s-1SDK.\s0
Windows needs at least Perl 5.8.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ian Guthrie
IGuthrie@aol.com
.PP
Copyright (c) 2006 Ian Guthrie. All rights reserved.
               This program is free software; you can redistribute it and/or
               modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1).