.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::DBus::Binding::Connection 3pm"
.TH Net::DBus::Binding::Connection 3pm "2011-06-30" "perl v5.20.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::DBus::Binding::Connection \- A connection between client and server
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Creating a connection to a server and sending a message
.PP
.Vb 1
\&  use Net::DBus::Binding::Connection;
\&
\&  my $con = Net::DBus::Binding::Connection\->new(address => "unix:path=/path/to/socket");
\&
\&  $con\->send($message);
.Ve
.PP
Registering message handlers
.PP
.Vb 3
\&  sub handle_something {
\&      my $con = shift;
\&      my $msg = shift;
\&
\&      ... do something with the message...
\&  }
\&
\&  $con\->register_message_handler(
\&    "/some/object/path",
\&    \e&handle_something);
.Ve
.PP
Hooking up to an event loop:
.PP
.Vb 1
\&  my $reactor = Net::DBus::Binding::Reactor\->new();
\&
\&  $reactor\->manage($con);
\&
\&  $reactor\->run();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
An outgoing connection to a server, or an incoming connection
from a client. The methods defined on this module have a close
correspondance to the dbus_connection_XXX methods in the C \s-1API,\s0
so for further details on their behaviour, the C \s-1API\s0 documentation
may be of use.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "my $con = Net::DBus::Binding::Connection\->new(address => ""unix:path=/path/to/socket"");" 4
.el .IP "my \f(CW$con\fR = Net::DBus::Binding::Connection\->new(address => ``unix:path=/path/to/socket'');" 4
.IX Item "my $con = Net::DBus::Binding::Connection->new(address => unix:path=/path/to/socket);"
Creates a new connection to the remove server specified by
the parameter \f(CW\*(C`address\*(C'\fR. If the \f(CW\*(C`private\*(C'\fR parameter is
supplied, and set to a True value the connection opened is
private; otherwise a shared connection is opened. A private
connection must be explicitly shutdown with the \f(CW\*(C`disconnect\*(C'\fR
method before the last reference to the object is released.
A shared connection must never be explicitly disconnected.
.ie n .IP "$status = $con\->\fIis_connected()\fR;" 4
.el .IP "\f(CW$status\fR = \f(CW$con\fR\->\fIis_connected()\fR;" 4
.IX Item "$status = $con->is_connected();"
Returns zero if the connection has been disconnected,
otherwise a positive value is returned.
.ie n .IP "$status = $con\->\fIis_authenticated()\fR;" 4
.el .IP "\f(CW$status\fR = \f(CW$con\fR\->\fIis_authenticated()\fR;" 4
.IX Item "$status = $con->is_authenticated();"
Returns zero if the connection has not yet successfully
completed authentication, otherwise a positive value is
returned.
.ie n .IP "$con\->\fIdisconnect()\fR" 4
.el .IP "\f(CW$con\fR\->\fIdisconnect()\fR" 4
.IX Item "$con->disconnect()"
Closes this connection to the remote host. This method
is called automatically during garbage collection (ie
in the \s-1DESTROY\s0 method) if the programmer forgets to
explicitly disconnect.
.ie n .IP "$con\->\fIflush()\fR" 4
.el .IP "\f(CW$con\fR\->\fIflush()\fR" 4
.IX Item "$con->flush()"
Blocks execution until all data in the outgoing data
stream has been sent. This method will not re-enter
the application event loop.
.ie n .IP "$con\->send($message)" 4
.el .IP "\f(CW$con\fR\->send($message)" 4
.IX Item "$con->send($message)"
Queues a message up for sending to the remote host.
The data will be sent asynchronously as the applications
event loop determines there is space in the outgoing
socket send buffer. To force immediate sending of the
data, follow this method will a call to \f(CW\*(C`flush\*(C'\fR. This
method will return the serial number of the message,
which can be used to identify a subsequent reply (if
any).
.ie n .IP "my $reply = $con\->send_with_reply_and_block($msg, $timeout);" 4
.el .IP "my \f(CW$reply\fR = \f(CW$con\fR\->send_with_reply_and_block($msg, \f(CW$timeout\fR);" 4
.IX Item "my $reply = $con->send_with_reply_and_block($msg, $timeout);"
Queues a message up for sending to the remote host
and blocks until it has been sent, and a corresponding
reply received. The return value of this method will
be a \f(CW\*(C`Net::DBus::Binding::Message::MethodReturn\*(C'\fR or \f(CW\*(C`Net::DBus::Binding::Message::Error\*(C'\fR
object.
.ie n .IP "my $pending_call = $con\->send_with_reply($msg, $timeout);" 4
.el .IP "my \f(CW$pending_call\fR = \f(CW$con\fR\->send_with_reply($msg, \f(CW$timeout\fR);" 4
.IX Item "my $pending_call = $con->send_with_reply($msg, $timeout);"
Queues a message up for sending to the remote host
and returns immediately providing a reference to a
\&\f(CW\*(C`Net::DBus::Binding::PendingCall\*(C'\fR object. This object
can be used to wait / watch for a reply. This allows
methods to be processed asynchronously.
.ie n .IP "$con\->dispatch;" 4
.el .IP "\f(CW$con\fR\->dispatch;" 4
.IX Item "$con->dispatch;"
Dispatches any pending messages in the incoming queue
to their message handlers. This method is typically
called on each iteration of the main application event
loop where data has been read from the incoming socket.
.ie n .IP "$message = $con\->borrow_message" 4
.el .IP "\f(CW$message\fR = \f(CW$con\fR\->borrow_message" 4
.IX Item "$message = $con->borrow_message"
Temporarily removes the first message from the incoming
message queue. No other thread may access the message
while it is 'borrowed', so it should be replaced in the
queue with the \f(CW\*(C`return_message\*(C'\fR method, or removed
permanently with th \f(CW\*(C`steal_message\*(C'\fR method as soon as
is practical.
.ie n .IP "$con\->return_message($msg)" 4
.el .IP "\f(CW$con\fR\->return_message($msg)" 4
.IX Item "$con->return_message($msg)"
Replaces a previously borrowed message in the incoming
message queue for subsequent dispatch to registered
message handlers.
.ie n .IP "$con\->steal_message($msg)" 4
.el .IP "\f(CW$con\fR\->steal_message($msg)" 4
.IX Item "$con->steal_message($msg)"
Permanently remove a borrowed message from the incoming
message queue. No registered message handlers will now
be run for this message.
.ie n .IP "$msg = $con\->\fIpop_message()\fR;" 4
.el .IP "\f(CW$msg\fR = \f(CW$con\fR\->\fIpop_message()\fR;" 4
.IX Item "$msg = $con->pop_message();"
Permanently removes the first message on the incoming
message queue, without running any registered message
handlers. If you have hooked the connection up to an
event loop (\f(CW\*(C`Net::DBus::Binding::Reactor\*(C'\fR for example), you probably
don't want to be calling this method.
.ie n .IP "$con\->set_watch_callbacks(\e&add_watch, \e&remove_watch, \e&toggle_watch);" 4
.el .IP "\f(CW$con\fR\->set_watch_callbacks(\e&add_watch, \e&remove_watch, \e&toggle_watch);" 4
.IX Item "$con->set_watch_callbacks(&add_watch, &remove_watch, &toggle_watch);"
Register a set of callbacks for adding, removing & updating
watches in the application's event loop. Each parameter
should be a code reference, which on each invocation, will be
supplied with two parameters, the connection object and the
watch object. If you are using a \f(CW\*(C`Net::DBus::Binding::Reactor\*(C'\fR object
as the application event loop, then the 'manage' method on
that object will call this on your behalf.
.ie n .IP "$con\->set_timeout_callbacks(\e&add_timeout, \e&remove_timeout, \e&toggle_timeout);" 4
.el .IP "\f(CW$con\fR\->set_timeout_callbacks(\e&add_timeout, \e&remove_timeout, \e&toggle_timeout);" 4
.IX Item "$con->set_timeout_callbacks(&add_timeout, &remove_timeout, &toggle_timeout);"
Register a set of callbacks for adding, removing & updating
timeouts in the application's event loop. Each parameter
should be a code reference, which on each invocation, will be
supplied with two parameters, the connection object and the
timeout object. If you are using a \f(CW\*(C`Net::DBus::Binding::Reactor\*(C'\fR object
as the application event loop, then the 'manage' method on
that object will call this on your behalf.
.ie n .IP "$con\->register_object_path($path, \e&handler)" 4
.el .IP "\f(CW$con\fR\->register_object_path($path, \e&handler)" 4
.IX Item "$con->register_object_path($path, &handler)"
Registers a handler for messages whose path matches
that specified in the \f(CW$path\fR parameter. The supplied
code reference will be invoked with two parameters, the
connection object on which the message was received,
and the message to be processed (an instance of the
\&\f(CW\*(C`Net::DBus::Binding::Message\*(C'\fR class).
.ie n .IP "$con\->unregister_object_path($path)" 4
.el .IP "\f(CW$con\fR\->unregister_object_path($path)" 4
.IX Item "$con->unregister_object_path($path)"
Unregisters the handler associated with the object path \f(CW$path\fR. The
handler would previously have been registered with the \f(CW\*(C`register_object_path\*(C'\fR
or \f(CW\*(C`register_fallback\*(C'\fR methods.
.ie n .IP "$con\->register_fallback($path, \e&handler)" 4
.el .IP "\f(CW$con\fR\->register_fallback($path, \e&handler)" 4
.IX Item "$con->register_fallback($path, &handler)"
Registers a handler for messages whose path starts with
the prefix specified in the \f(CW$path\fR parameter. The supplied
code reference will be invoked with two parameters, the
connection object on which the message was received,
and the message to be processed (an instance of the
\&\f(CW\*(C`Net::DBus::Binding::Message\*(C'\fR class).
.ie n .IP "$con\->set_max_message_size($bytes)" 4
.el .IP "\f(CW$con\fR\->set_max_message_size($bytes)" 4
.IX Item "$con->set_max_message_size($bytes)"
Sets the maximum allowable size of a single incoming
message. Messages over this size will be rejected
prior to exceeding this threshold. The message size
is specified in bytes.
.ie n .IP "$bytes = $con\->\fIget_max_message_size()\fR;" 4
.el .IP "\f(CW$bytes\fR = \f(CW$con\fR\->\fIget_max_message_size()\fR;" 4
.IX Item "$bytes = $con->get_max_message_size();"
Retrieves the maximum allowable incoming
message size. The returned size is measured
in bytes.
.ie n .IP "$con\->set_max_received_size($bytes)" 4
.el .IP "\f(CW$con\fR\->set_max_received_size($bytes)" 4
.IX Item "$con->set_max_received_size($bytes)"
Sets the maximum size of the incoming message queue.
Once this threashold is exceeded, no more messages will
be read from wire before one or more of the existing
messages are dispatched to their registered handlers.
The implication is that the message queue can exceed
this threshold by at most the size of a single message.
.ie n .IP "$bytes $con\->\fIget_max_received_size()\fR" 4
.el .IP "\f(CW$bytes\fR \f(CW$con\fR\->\fIget_max_received_size()\fR" 4
.IX Item "$bytes $con->get_max_received_size()"
Retrieves the maximum incoming message queue size.
The returned size is measured in bytes.
.ie n .IP "$con\->add_filter($coderef);" 4
.el .IP "\f(CW$con\fR\->add_filter($coderef);" 4
.IX Item "$con->add_filter($coderef);"
Adds a filter to the connection which will be invoked whenever a
message is received. The \f(CW$coderef\fR should be a reference to a
subroutine, which returns a true value if the message should be
filtered out, or a false value if the normal message dispatch
should be performed.
.ie n .IP "my $msg = $con\->make_raw_message($rawmsg)" 4
.el .IP "my \f(CW$msg\fR = \f(CW$con\fR\->make_raw_message($rawmsg)" 4
.IX Item "my $msg = $con->make_raw_message($rawmsg)"
Creates a new message, initializing it from the low level C message
object provided by the \f(CW$rawmsg\fR parameter. The returned object
will be cast to the appropriate subclass of Net::DBus::Binding::Message.
.ie n .IP "my $msg = $con\->make_error_message( replyto => $method_call, name => $name, description => $description);" 4
.el .IP "my \f(CW$msg\fR = \f(CW$con\fR\->make_error_message( replyto => \f(CW$method_call\fR, name => \f(CW$name\fR, description => \f(CW$description\fR);" 4
.IX Item "my $msg = $con->make_error_message( replyto => $method_call, name => $name, description => $description);"
Creates a new message, representing an error which occurred during
the handling of the method call object passed in as the \f(CW\*(C`replyto\*(C'\fR
parameter. The \f(CW\*(C`name\*(C'\fR parameter is the formal name of the error
condition, while the \f(CW\*(C`description\*(C'\fR is a short piece of text giving
more specific information on the error.
.ie n .IP "my $call = $con\->make_method_call_message( $service_name, $object_path, $interface, $method_name);" 4
.el .IP "my \f(CW$call\fR = \f(CW$con\fR\->make_method_call_message( \f(CW$service_name\fR, \f(CW$object_path\fR, \f(CW$interface\fR, \f(CW$method_name\fR);" 4
.IX Item "my $call = $con->make_method_call_message( $service_name, $object_path, $interface, $method_name);"
Create a message representing a call on the object located at
the path \f(CW$object_path\fR within the client owning the well-known
name given by \f(CW$service_name\fR. The method to be invoked has
the name \f(CW$method_name\fR within the interface specified by the
\&\f(CW$interface\fR parameter.
.ie n .IP "my $msg = $con\->make_method_return_message( replyto => $method_call);" 4
.el .IP "my \f(CW$msg\fR = \f(CW$con\fR\->make_method_return_message( replyto => \f(CW$method_call\fR);" 4
.IX Item "my $msg = $con->make_method_return_message( replyto => $method_call);"
Create a message representing a reply to the method call passed in
the \f(CW\*(C`replyto\*(C'\fR parameter.
.ie n .IP "my $signal = $con\->make_signal_message( object_path => $path, interface => $interface, signal_name => $name);" 4
.el .IP "my \f(CW$signal\fR = \f(CW$con\fR\->make_signal_message( object_path => \f(CW$path\fR, interface => \f(CW$interface\fR, signal_name => \f(CW$name\fR);" 4
.IX Item "my $signal = $con->make_signal_message( object_path => $path, interface => $interface, signal_name => $name);"
Creates a new message, representing a signal [to be] emitted by
the object located under the path given by the \f(CW\*(C`object_path\*(C'\fR
parameter. The name of the signal is given by the \f(CW\*(C`signal_name\*(C'\fR
parameter, and is scoped to the interface given by the
\&\f(CW\*(C`interface\*(C'\fR parameter.
.SH "AUTHOR"
.IX Header "AUTHOR"
Daniel P. Berrange
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2004\-2011 Daniel P. Berrange
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::DBus::Binding::Server, Net::DBus::Binding::Bus, Net::DBus::Binding::Message::Signal, Net::DBus::Binding::Message::MethodCall, Net::DBus::Binding::Message::MethodReturn, Net::DBus::Binding::Message::Error