Ubuntu Manpage: Net::DBus::Binding::Connection - A connection between client and server

Provided by: libnet-dbus-perl_1.2.0-2build3_amd64

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

NAME

SYNOPSIS

DESCRIPTION

METHODS

AUTHOR

COPYRIGHT

SEE ALSO