Net::D...ection(3pm) User Contributed Perl Documentation Net::D...ection(3pm)
NAME
Net::DBus::Binding::Connection - A connection between client and server
SYNOPSIS
Creating a connection to a server and sending a message
use Net::DBus::Binding::Connection;
my $con = Net::DBus::Binding::Connection->new(address => "unix:path=/path/to/socket");
$con->send($message);
Registering message handlers
sub handle_something {
my $con = shift;
my $msg = shift;
... do something with the message...
}
$con->register_message_handler(
"/some/object/path",
\&handle_something);
Hooking up to an event loop:
my $reactor = Net::DBus::Binding::Reactor->new();
$reactor->manage($con);
$reactor->run();
DESCRIPTION
An outgoing connection to a server, or an incoming connection from a
client. The methods defined on this module have a close correspondence
to the dbus_connection_XXX methods in the C API, so for further details
on their behaviour, the C API documentation may be of use.
METHODS
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 "address". If the "private" 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 "disconnect" method before the last reference to
the object is released. A shared connection must never be
explicitly disconnected.
$status = $con->is_connected();
Returns zero if the connection has been disconnected, otherwise a
positive value is returned.
$status = $con->is_authenticated();
Returns zero if the connection has not yet successfully completed
authentication, otherwise a positive value is returned.
$con->disconnect()
Closes this connection to the remote host. This method is called
automatically during garbage collection (ie in the DESTROY method)
if the programmer forgets to explicitly disconnect.
$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.
$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
"flush". This method will return the serial number of the message,
which can be used to identify a subsequent reply (if any).
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
"Net::DBus::Binding::Message::MethodReturn" or
"Net::DBus::Binding::Message::Error" object.
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
"Net::DBus::Binding::PendingCall" object. This object can be used to
wait / watch for a reply. This allows methods to be processed
asynchronously.
$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.
$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
"return_message" method, or removed permanently with th
"steal_message" method as soon as is practical.
$con->return_message($msg)
Replaces a previously borrowed message in the incoming message queue
for subsequent dispatch to registered message handlers.
$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.
$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 ("Net::DBus::Binding::Reactor"
for example), you probably don't want to be calling this method.
$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 "Net::DBus::Binding::Reactor" object as the application
event loop, then the 'manage' method on that object will call this
on your behalf.
$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 "Net::DBus::Binding::Reactor" object as the application
event loop, then the 'manage' method on that object will call this
on your behalf.
$con->register_object_path($path, \&handler)
Registers a handler for messages whose path matches that specified
in the $path 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
"Net::DBus::Binding::Message" class).
$con->unregister_object_path($path)
Unregisters the handler associated with the object path $path. The
handler would previously have been registered with the
"register_object_path" or "register_fallback" methods.
$con->register_fallback($path, \&handler)
Registers a handler for messages whose path starts with the prefix
specified in the $path 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 "Net::DBus::Binding::Message" class).
$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.
$bytes = $con->get_max_message_size();
Retrieves the maximum allowable incoming message size. The returned
size is measured in bytes.
$con->set_max_received_size($bytes)
Sets the maximum size of the incoming message queue. Once this
threshold 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.
$bytes $con->get_max_received_size()
Retrieves the maximum incoming message queue size. The returned
size is measured in bytes.
$con->add_filter($coderef);
Adds a filter to the connection which will be invoked whenever a
message is received. The $coderef 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.
my $msg = $con->make_raw_message($rawmsg)
Creates a new message, initializing it from the low level C message
object provided by the $rawmsg parameter. The returned object will
be cast to the appropriate subclass of Net::DBus::Binding::Message.
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 "replyto"
parameter. The "name" parameter is the formal name of the error
condition, while the "description" is a short piece of text giving
more specific information on the error.
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 $object_path within the client owning the well-known name given
by $service_name. The method to be invoked has the name $method_name
within the interface specified by the $interface parameter.
my $msg = $con->make_method_return_message( replyto => $method_call);
Create a message representing a reply to the method call passed in
the "replyto" parameter.
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 "object_path" parameter.
The name of the signal is given by the "signal_name" parameter, and
is scoped to the interface given by the "interface" parameter.
AUTHOR
Daniel P. Berrange
COPYRIGHT
Copyright (C) 2004-2011 Daniel P. Berrange
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
perl v5.40.0 2024-10-15 Net::D...ection(3pm)
Generated by dwww version 1.16 on Tue Dec 16 05:52:47 CET 2025.