Net::DBus::Binding::Connection(3pm)

1Net::DBus::Binding::ConUnseecrtiCoonn(t3r)ibuted Perl DoNceutm:e:nDtBautsi:o:nBinding::Connection(3)
2
3
4

NAME

6       Net::DBus::Binding::Connection - A connection between client and server
7

SYNOPSIS

9       Creating a connection to a server and sending a message
10
11         use Net::DBus::Binding::Connection;
12
13         my $con = Net::DBus::Binding::Connection->new(address => "unix:path=/path/to/socket");
14
15         $con->send($message);
16
17       Registering message handlers
18
19         sub handle_something {
20             my $con = shift;
21             my $msg = shift;
22
23             ... do something with the message...
24         }
25
26         $con->register_message_handler(
27           "/some/object/path",
28           \&handle_something);
29
30       Hooking up to an event loop:
31
32         my $reactor = Net::DBus::Binding::Reactor->new();
33
34         $reactor->manage($con);
35
36         $reactor->run();
37

DESCRIPTION

39       An outgoing connection to a server, or an incoming connection from a
40       client. The methods defined on this module have a close correspondance
41       to the dbus_connection_XXX methods in the C API, so for further details
42       on their behaviour, the C API documentation may be of use.
43

METHODS

45       my $con = Net::DBus::Binding::Connection->new(address =>
46       "unix:path=/path/to/socket");
47           Creates a new connection to the remove server specified by the
48           parameter "address". If the "private" parameter is supplied, and
49           set to a True value the connection opened is private; otherwise a
50           shared connection is opened. A private connection must be
51           explicitly shutdown with the "disconnect" method before the last
52           reference to the object is released.  A shared connection must
53           never be explicitly disconnected.
54
55       $status = $con->is_connected();
56           Returns zero if the connection has been disconnected, otherwise a
57           positive value is returned.
58
59       $status = $con->is_authenticated();
60           Returns zero if the connection has not yet successfully completed
61           authentication, otherwise a positive value is returned.
62
63       $con->disconnect()
64           Closes this connection to the remote host. This method is called
65           automatically during garbage collection (ie in the DESTROY method)
66           if the programmer forgets to explicitly disconnect.
67
68       $con->flush()
69           Blocks execution until all data in the outgoing data stream has
70           been sent. This method will not re-enter the application event
71           loop.
72
73       $con->send($message)
74           Queues a message up for sending to the remote host.  The data will
75           be sent asynchronously as the applications event loop determines
76           there is space in the outgoing socket send buffer. To force
77           immediate sending of the data, follow this method will a call to
78           "flush". This method will return the serial number of the message,
79           which can be used to identify a subsequent reply (if any).
80
81       my $reply = $con->send_with_reply_and_block($msg, $timeout);
82           Queues a message up for sending to the remote host and blocks until
83           it has been sent, and a corresponding reply received. The return
84           value of this method will be a
85           "Net::DBus::Binding::Message::MethodReturn" or
86           "Net::DBus::Binding::Message::Error" object.
87
88       my $pending_call = $con->send_with_reply($msg, $timeout);
89           Queues a message up for sending to the remote host and returns
90           immediately providing a reference to a
91           "Net::DBus::Binding::PendingCall" object. This object can be used
92           to wait / watch for a reply. This allows methods to be processed
93           asynchronously.
94
95       $con->dispatch;
96           Dispatches any pending messages in the incoming queue to their
97           message handlers. This method is typically called on each iteration
98           of the main application event loop where data has been read from
99           the incoming socket.
100
101       $message = $con->borrow_message
102           Temporarily removes the first message from the incoming message
103           queue. No other thread may access the message while it is
104           'borrowed', so it should be replaced in the queue with the
105           "return_message" method, or removed permanently with th
106           "steal_message" method as soon as is practical.
107
108       $con->return_message($msg)
109           Replaces a previously borrowed message in the incoming message
110           queue for subsequent dispatch to registered message handlers.
111
112       $con->steal_message($msg)
113           Permanently remove a borrowed message from the incoming message
114           queue. No registered message handlers will now be run for this
115           message.
116
117       $msg = $con->pop_message();
118           Permanently removes the first message on the incoming message
119           queue, without running any registered message handlers. If you have
120           hooked the connection up to an event loop
121           ("Net::DBus::Binding::Reactor" for example), you probably don't
122           want to be calling this method.
123
124       $con->set_watch_callbacks(\&add_watch, \&remove_watch, \&toggle_watch);
125           Register a set of callbacks for adding, removing & updating watches
126           in the application's event loop. Each parameter should be a code
127           reference, which on each invocation, will be supplied with two
128           parameters, the connection object and the watch object. If you are
129           using a "Net::DBus::Binding::Reactor" object as the application
130           event loop, then the 'manage' method on that object will call this
131           on your behalf.
132
133       $con->set_timeout_callbacks(\&add_timeout, \&remove_timeout,
134       \&toggle_timeout);
135           Register a set of callbacks for adding, removing & updating
136           timeouts in the application's event loop. Each parameter should be
137           a code reference, which on each invocation, will be supplied with
138           two parameters, the connection object and the timeout object. If
139           you are using a "Net::DBus::Binding::Reactor" object as the
140           application event loop, then the 'manage' method on that object
141           will call this on your behalf.
142
143       $con->register_object_path($path, \&handler)
144           Registers a handler for messages whose path matches that specified
145           in the $path parameter. The supplied code reference will be invoked
146           with two parameters, the connection object on which the message was
147           received, and the message to be processed (an instance of the
148           "Net::DBus::Binding::Message" class).
149
150       $con->unregister_object_path($path)
151           Unregisters the handler associated with the object path $path. The
152           handler would previously have been registered with the
153           "register_object_path" or "register_fallback" methods.
154
155       $con->register_fallback($path, \&handler)
156           Registers a handler for messages whose path starts with the prefix
157           specified in the $path parameter. The supplied code reference will
158           be invoked with two parameters, the connection object on which the
159           message was received, and the message to be processed (an instance
160           of the "Net::DBus::Binding::Message" class).
161
162       $con->set_max_message_size($bytes)
163           Sets the maximum allowable size of a single incoming message.
164           Messages over this size will be rejected prior to exceeding this
165           threshold. The message size is specified in bytes.
166
167       $bytes = $con->get_max_message_size();
168           Retrieves the maximum allowable incoming message size. The returned
169           size is measured in bytes.
170
171       $con->set_max_received_size($bytes)
172           Sets the maximum size of the incoming message queue.  Once this
173           threashold is exceeded, no more messages will be read from wire
174           before one or more of the existing messages are dispatched to their
175           registered handlers.  The implication is that the message queue can
176           exceed this threshold by at most the size of a single message.
177
178       $bytes $con->get_max_received_size()
179           Retrieves the maximum incoming message queue size.  The returned
180           size is measured in bytes.
181
182       $con->add_filter($coderef);
183           Adds a filter to the connection which will be invoked whenever a
184           message is received. The $coderef should be a reference to a
185           subroutine, which returns a true value if the message should be
186           filtered out, or a false value if the normal message dispatch
187           should be performed.
188
189       my $msg = $con->make_raw_message($rawmsg)
190           Creates a new message, initializing it from the low level C message
191           object provided by the $rawmsg parameter. The returned object will
192           be cast to the appropriate subclass of Net::DBus::Binding::Message.
193
194       my $msg = $con->make_error_message( replyto => $method_call, name =>
195       $name, description => $description);
196           Creates a new message, representing an error which occurred during
197           the handling of the method call object passed in as the "replyto"
198           parameter. The "name" parameter is the formal name of the error
199           condition, while the "description" is a short piece of text giving
200           more specific information on the error.
201
202       my $call = $con->make_method_call_message( $service_name, $object_path,
203       $interface, $method_name);
204           Create a message representing a call on the object located at the
205           path $object_path within the client owning the well-known name
206           given by $service_name. The method to be invoked has the name
207           $method_name within the interface specified by the $interface
208           parameter.
209
210       my $msg = $con->make_method_return_message( replyto => $method_call);
211           Create a message representing a reply to the method call passed in
212           the "replyto" parameter.
213
214       my $signal = $con->make_signal_message( object_path => $path, interface
215       => $interface, signal_name => $name);
216           Creates a new message, representing a signal [to be] emitted by the
217           object located under the path given by the "object_path" parameter.
218           The name of the signal is given by the "signal_name" parameter, and
219           is scoped to the interface given by the "interface" parameter.
220

AUTHOR

222       Daniel P. Berrange
223

COPYRIGHT

225       Copyright (C) 2004-2011 Daniel P. Berrange
226

NAME

SYNOPSIS

DESCRIPTION

METHODS

AUTHOR

COPYRIGHT

SEE ALSO