Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::DBus::Binding::CoUsertContributed Perl DNet::DBus::Binding::Connection(3)

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.32.0			  2019-02-12 Net::DBus::Binding::Connection(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::DBus::Binding::Connection&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help