Digimer: Created page with '{{dbtut_header}} = new = Connect to a remote server specified by the 'address'. May also have 'private' set to true (1) in which case a private connection is established. Other…'

2009-10-12T02:43:52Z

Created page with '{{dbtut_header}} = new = Connect to a remote server specified by the 'address'. May also have 'private' set to true (1) in which case a private connection is established. Other…'

Páàjì titun

{{dbtut_header}}

= new =

Connect to a remote server specified by the 'address'. May also have 'private' set to true (1) in which case a private connection is established. Otherwise the connection is shared. If the connection is private, it must be explicitely killed using the 'disconnect' method before releasing the last before the last reference is released. Conversely, a shared connection should never have 'disconnect' called on it.

A private connection is ...? A shared connection is ...?

Usage;
<source lang="perl">
my $address="unix:path=/path/to/socket";
my $connection=Net::DBus::Binding::Connection->new(address => "$address"); # Create a shared connection.
#my $connection=Net::DBus::Binding::Connection->new(address => "$address", private => 1); # Create a private connection.
</source>
:MADI: Confirm this syntax.

= is_connected =

This takes a connection handle and checks if it is still connected to the server, returning '1' if so, '0' if not.

Usage;
<source lang="perl">
my $status=$connection->is_connected();
</perl>

= is_authenticated =

This checks if the connection to the server has completed authenticating against the server, returning '1' if so, '0' if not.

Usage;
<source lang="perl">
my $status=$connection->is_authenticated();
:MADI: Would this be used/useful in a "while (!$connection->is_authenticated()) { &show_progress_bar; }" type method?

= disconnect =

This explicitely disconnects from a remote server. This is automatically called during garbage collection should you forget to call it yourself.

Usage;
<source lang="perl">
$connection->disconnect();
</source>

= flush =

This pauses the program until the data in the current outgoing data stream has been sent. This method will not re-enter the application event loop.
:MADI: What does "not re-enter the application event loop" mean?

Usage;
<source lang="perl">
$connection->flush();
</source>

= send =

This queues up a message for delivery on the message bus, returning the serial number of the message for later identifying a reply, if any. This method is asynchronous by nature. If you do not want to proceed until a reply returns, follow this call with a call to the 'flush' method.

Usage;
<source lang="perl">
my $message_serial_number=$connection->send($message);
# Do other stuff, not knowing if your message has been sent yet.
</source>
OR
<source lang="perl">
my $message_serial_number=$connection->send($message);
$connection->flush();
# Proceed knowing your message was sent.
</source>

= send_with_reply_and_block =

This sends a message and waits for a reply from the remote method before proceeding. The data returned will either be a 'Net::DBus::Binding::Message::MethodReturn' or 'Net::DBus::Binding::Message::Error' object.

Usage;
<source lang="perl">
my $message="what would a valid message be?";
my $timeout=300;
my $reply=$connection->send_with_reply_and_block($message, $timeout);
</source>
:Is '$timeout' specified as a raw integer representing the number of seconds to wait?

= send_with_reply =

This queues a message for sending and returns a reference to a 'Net::DBus::Binding::PendingCall' object which can be used to watch for a reply. This allows you to either wait for a reply or proceed, watching for a matching reply and allowing for asynchronous method processing.

Usage;
<source lang="perl">
my $pending_call=$connection->send_with_reply($msg, $timeout);
</source>
:MADI: What would be an example of waiting on this call vs. reacting to the reply later?

= dispatch =

This tells the program to dispatch any messages sitting in the incoming queue to their respective message handlers. This is generally called whenever the main application event loop is triggered by data on the incoming socket.

Usage;
<source lang="perl">
$connection->dispatch;
</source>

= borrow_message =

This temporarily shifts the first message out of the message queue, making it unavailable to any other thread. Given this, you should replace the message using the 'return_message' method or permanently remove the message using the 'steal_message' method as soon as possible.

Usage;
<source lang="perl">
my $message=$connection->borrow_message;
</source>

= return_message =

This returns a message "borrowed" to the incoming queue that was borrowed via the 'borrow_message' method. Once returned, the message can be dispatched again to the appropriate message handler.

Usage;
<source lang="perl">
my $message=$connection->borrow_message;
# Do work on the message...
$connection->return_message($message);
</source>

= steal_message =

This permanently removes a message from the incoming message queue, preventing it from being dispatched to any message handler.

Usage;
<source lang="perl">
my $message=$connection->borrow_message;
# Do work on the message...
$connection->steal_message($message);
</source>

= pop_message =

This permanently removes the first message from the incoming message queue. This prevents registered message handlers from seeing this message. If you have hooked this connection to an event handler like 'Net::DBus::Binding::Reactor' you probably shouldn't use this method.
:MADI: Why not? What happens if this is called on connection that has a reactor loop on it?

Usage;
<source lang="perl">
my $message=$connection->pop_message();
</source>

= set_watch_callbacks =

This registers a set of methods, as references, that will be called to adding, removing and updating watches in the application's main event loop. Each method will be called with two parameters; the connection object ($connection) and the watch object (??). If you are using the 'Net::DBus::Binding::Reactor' object as the event loop, the 'manage' method is called on your behalf.
:MADI: Talk to Daniel about this... I need to understand why/where this would be used better.

Usage;
<source lang="perl">
$connection->set_watch_callbacks(\&add_watch, \&remove_watch, \&toggle_watch);
</source>

= set_timeout_callbacks =

This registers a set of methods, as references, that will be called to adding, removing and updating timeouts in the application's main event loop. Each method will be called with two parameters; the connection object ($connection) and the watch object (??). If you are using the 'Net::DBus::Binding::Reactor' object as the event loop, the 'manage' method is called on your behalf.

Usage;
<source lang="perl">
$connection->set_timeout_callbacks(\&add_watch, \&remove_watch, \&toggle_watch);
</source>

= register_object_path =

This registers a handler for messages whose specific path matches that specified in the '$path' variable. The supplied code reference is called with two parameters; the connection object that the message was received on ($connection) and the message to be processed, which is a 'Net::DBus::Binding::Message' class.
:MADI: What does "'Net::DBus::Binding::Message' class" mean?

Using TLE-BU as a reference, this would be called when a client successfully connects to the server.

Usage;
<source lang="perl">
$connection->register_object_path($path, \&handler);
</source>

= unregister_object_path =

This removes a handler associated with a specific '$path' from the referenced handler method previously set by the 'register_object_path' method.

Using TLE-BU as a reference, this would be called when a client disconnects from the server.

Usage;
<source lang="perl">
$connection->unregister_object_path($path, \&handler);
</source>

= register_fallback =

This registers a handler for messages whose path starts with the path set in the '$path' variable. The supplied code reference is called with two parameters; the connection object that the message was received on ($connection) and the message to be processed, which is a 'Net::DBus::Binding::Message' class.

Think of this method as a "fallback" for messages that don't specifically match a handler previously defined by the 'register_object_path' method.

Usage;
<source lang="perl">
$connection->register_fallback($path, \&handler);
</source>

= set_max_message_size =

This specifies, in [[bytes]], the maximum size that a message can be. Messages larger than this size will be rejected before they can exceed this size.

Usage;
<source lang="perl">
my $bytes=4096;
$connection->set_max_message_size($bytes);
</source>
:MADI: What is a reasonable size to use in this document? Is there a way to set no limit (ie: 0)?

= get_max_message_size =

This reads the maximum size that a message is allowed to be, in [[bytes]].

Usage;
<source lang="perl">
my $bytes=$connection->get_max_message_size();
</source>

= set_max_received_size =

This sets the maximum size, in [[bytes]], that the incoming message queue can grow to. Once the messages in the queue are equal to or larger than this size, no more messages will be accepted by the queue until space is freed up by dispatching some messages to their respective handlers.

Please note, this actual size of the data in the queue can exceed this limit. The full contents of the last message to make it into the queue will be stored. If you have a hard limit you cannot exceed, set this value to your maximum size minus the maximum message size as set via the 'set_max_message_size' method.

Usage;
<source lang="perl">
my $bytes=1048576;
$connection->set_max_received_size($bytes);
</source>
:MADI: What is a reasonable size to use in this document? Is there a way to set no limit (ie: 0)?

= get_max_received_size =

This reads the maximum size of the incoming message queue, as set by the 'set_max_received_size' method. Please see that method's notes for an important caveat!

Usage;
<source lang="perl">
my $bytes=$connection->get_max_received_size($bytes);
</source>

= add_filter =

This takes a reference to a subrouting that acts as a filter on the connection. When a message is received, it is passed to the references subroutine. This expects the referenced subroutine to return only true (1) or false (0). If true, the message is filtered out of the incoming queue. If false, the message is passed on to the appropriate message handler.
:MADI: Does the referenced subroutine get passed the usual connection object followed by the message object?

Usage;
<source lang="perl">
my $coderef=\&filter_messages;
$connection->add_filter($coderef);
</source>

= make_raw_message =

This creates a new message object based on the '$rawmsg' parameter using the matching low-level C message object. The returned message will be an appropriate 'Net::DBus::Binding::Message' subclass.
:MADI: Ask Daniel to clarify this.

Usage;
<source lang="perl">
my $rawmsg="what are valid options? the typing key words?";
my $message=$connection->make_raw_message($rawmsg);
</source>

= make_error_message =

This creates a new message, representing an error which occurred during the handling of a message, represented by the 'replyto' variable. The 'name' is the formal name of the error and the 'description' is a short bit of plain text describing the error.

Usage;
<source lang="perl">
my $method_call="what?";
my $name="what are the valid error names";
my $description="This error is generally the result of ...";
my $message=$connection->make_error_message(
replyto => $method_call,
name => $name,
description => $description
);
</source>
:MADI: Get examples of valid 'method_call' and 'name' values.

= make_method_call_message =

Create a message that represents a call (?) on the object located at the path '$object_path'. This is performed withing the client owning the well-known (?) service name '$service_name'. The method (method) to be invoked has the name '$method_name' (remote method or a local coderef?) within the interface specified by the '$interface' parameter.

Usage;
<source lang="perl">
my $service_name="??";
my $object_path="??";
my $interface="??";
my $method_name="??";
my $call=$connection->make_method_call_message($service_name, $object_path, $interface, $method_name);
</source>

= make_method_return_message =

Create a message representing a reply to the method call passed in the 'replyto' variable.

Usage;
<source lang="perl">
my $method_call="??";
my $message=$connection->make_method_return_message(replyto => $method_call);
</source>

= make_signal_message =

This prepares a message that will be emitted by the object specified by the '$path' variable. The signal will have the name specified in the 'signal_name' variable and will be emitted onto the interface specified by the 'interface' variable.

Usage;
<source lang="perl">
my $path="??";
my $interface="??";
my $name="??";
my $signal=$connection->make_signal_message(
object_path => $path,
interface => $interface,
signal_name => $name
);
</source>

{{footer}}

Net::DBus::Binding::Connection Methods - Revision history

Digimer: Created page with '{{dbtut_header}} = new = Connect to a remote server specified by the 'address'. May also have 'private' set to true (1) in which case a private connection is established. Other…'