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 correspondance 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.

$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 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.

$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.

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

AUTHOR

Daniel Berrange <dan@berrange.com>

COPYRIGHT

Copyright 2004 by Daniel Berrange