Net::DBus::Binding::Connection Methods

AN!Tools :: Net::DBus Binding Tutorial :: Net::DBus::Binding::Connection Methods

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;

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.

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;

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();

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;

$connection->flush();

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;

my $message_serial_number=$connection->send($message);
# Do other stuff, not knowing if your message has been sent yet.

OR

my $message_serial_number=$connection->send($message);
$connection->flush();
# Proceed knowing your message was sent.

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;

my $message="what would a valid message be?";
my $timeout=300;
my $reply=$connection->send_with_reply_and_block($message, $timeout);

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;

my $pending_call=$connection->send_with_reply($msg, $timeout);

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;

$connection->dispatch;

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;

my $message=$connection->borrow_message;

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;

my $message=$connection->borrow_message;
# Do work on the message...
$connection->return_message($message);

steal_message

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

Usage;

my $message=$connection->borrow_message;
# Do work on the message...
$connection->steal_message($message);

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;

my $message=$connection->pop_message();

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;

$connection->set_watch_callbacks(\&add_watch, \&remove_watch, \&toggle_watch);

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;

$connection->set_timeout_callbacks(\&add_watch, \&remove_watch, \&toggle_watch);

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;

$connection->register_object_path($path, \&handler);

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;

$connection->unregister_object_path($path, \&handler);

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;

$connection->register_fallback($path, \&handler);

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;

my $bytes=4096;
$connection->set_max_message_size($bytes);

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;

my $bytes=$connection->get_max_message_size();

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;

my $bytes=1048576;
$connection->set_max_received_size($bytes);

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;

my $bytes=$connection->get_max_received_size($bytes);

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;

my $coderef=\&filter_messages;
$connection->add_filter($coderef);

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;

my $rawmsg="what are valid options? the typing key words?";
my $message=$connection->make_raw_message($rawmsg);

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;

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
);

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;

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);

make_method_return_message

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

Usage;

my $method_call="??";
my $message=$connection->make_method_return_message(replyto => $method_call);

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;

my $path="??";
my $interface="??";
my $name="??";
my $signal=$connection->make_signal_message(
        object_path => $path,
        interface   => $interface,
        signal_name => $name
);

 

Any questions, feedback, advice, complaints or meanderings are welcome.
Alteeve's Niche!	Enterprise Support: Alteeve Support	Community Support
© Alteeve's Niche! Inc. 1997-2024		Anvil! "Intelligent Availability®" Platform
legal stuff: All info is provided "As-Is". Do not use anything here unless you are willing and able to take responsibility for your own actions.