1Net::DBus::Binding::ConUnseecrtiCoonn(t3r)ibuted Perl DoNceutm:e:nDtBautsi:o:nBinding::Connection(3)
2
6 Net::DBus::Binding::Connection - A connection between client and server
7
9 Creating a connection to a server and sending a message
10 use Net::DBus::Binding::Connection;
12 my $con = Net::DBus::Binding::Connection->new(address => "unix:path=/path/to/socket");
14 $con->send($message);
16 Registering message handlers
18 sub handle_something {
20 my $con = shift;
21 my $msg = shift;
22 ... do something with the message...
24 }
25 $con->register_message_handler(
27 "/some/object/path",
28 \&handle_something);
29 Hooking up to an event loop:
31 my $reactor = Net::DBus::Binding::Reactor->new();
33 $reactor->manage($con);
35 $reactor->run();
37
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
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 explic‐
51 itly shutdown with the "disconnect" method before the last refer‐
52 ence to the object is released. A shared connection must never be
53 explicitly disconnected.
54 $status = $con->is_connected();
56 Returns zero if the connection has been disconnected, otherwise a
57 positive value is returned.
58 $status = $con->is_authenticated();
60 Returns zero if the connection has not yet successfully completed
61 authentication, otherwise a positive value is returned.
62 $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 $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 $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 immedi‐
77 ate sending of the data, follow this method will a call to "flush".
78 This method will return the serial number of the message, which can
79 be used to identify a subsequent reply (if any).
80 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 "Net::DBus::Binding::Message::Metho‐
85 dReturn" or "Net::DBus::Binding::Message::Error" object.
86 my $pending_call = $con->send_with_reply($msg, $timeout);
88 Queues a message up for sending to the remote host and returns
89 immediately providing a reference to a "Net::DBus::Binding::Pend‐
90 ingCall" object. This object can be used to wait / watch for a
91 reply. This allows methods to be processed asynchronously.
92 $con->dispatch;
94 Dispatches any pending messages in the incoming queue to their mes‐
95 sage handlers. This method is typically called on each iteration of
96 the main application event loop where data has been read from the
97 incoming socket.
98 $message = $con->borrow_message
100 Temporarily removes the first message from the incoming message
101 queue. No other thread may access the message while it is 'bor‐
102 rowed', so it should be replaced in the queue with the "return_mes‐
103 sage" method, or removed permanently with th "steal_message" method
104 as soon as is practical.
105 $con->return_message($msg)
107 Replaces a previously borrowed message in the incoming message
108 queue for subsequent dispatch to registered message handlers.
109 $con->steal_message($msg)
111 Permanently remove a borrowed message from the incoming message
112 queue. No registered message handlers will now be run for this mes‐
113 sage.
114 $msg = $con->pop_message();
116 Permanently removes the first message on the incoming message
117 queue, without running any registered message handlers. If you have
118 hooked the connection up to an event loop ("Net::DBus::Bind‐
119 ing::Reactor" for example), you probably don't want to be calling
120 this method.
121 $con->set_watch_callbacks(\&add_watch, \&remove_watch, \&toggle_watch);
123 Register a set of callbacks for adding, removing & updating watches
124 in the application's event loop. Each parameter should be a code
125 reference, which on each invocation, will be supplied with two
126 parameters, the connection object and the watch object. If you are
127 using a "Net::DBus::Binding::Reactor" object as the application
128 event loop, then the 'manage' method on that object will call this
129 on your behalf.
130 $con->set_timeout_callbacks(\&add_timeout, \&remove_timeout, \&tog‐
132 gle_timeout);
133 Register a set of callbacks for adding, removing & updating time‐
134 outs in the application's event loop. Each parameter should be a
135 code reference, which on each invocation, will be supplied with two
136 parameters, the connection object and the timeout object. If you
137 are using a "Net::DBus::Binding::Reactor" object as the application
138 event loop, then the 'manage' method on that object will call this
139 on your behalf.
140 $con->register_object_path($path, \&handler)
142 Registers a handler for messages whose path matches that specified
143 in the $path parameter. The supplied code reference will be invoked
144 with two parameters, the connection object on which the message was
145 received, and the message to be processed (an instance of the
146 "Net::DBus::Binding::Message" class).
147 $con->unregister_object_path($path)
149 Unregisters the handler associated with the object path $path. The
150 handler would previously have been registered with the "regis‐
151 ter_object_path" or "register_fallback" methods.
152 $con->register_fallback($path, \&handler)
154 Registers a handler for messages whose path starts with the prefix
155 specified in the $path parameter. The supplied code reference will
156 be invoked with two parameters, the connection object on which the
157 message was received, and the message to be processed (an instance
158 of the "Net::DBus::Binding::Message" class).
159 $con->set_max_message_size($bytes)
161 Sets the maximum allowable size of a single incoming message. Mes‐
162 sages over this size will be rejected prior to exceeding this
163 threshold. The message size is specified in bytes.
164 $bytes = $con->get_max_message_size();
166 Retrieves the maximum allowable incoming message size. The returned
167 size is measured in bytes.
168 $con->set_max_received_size($bytes)
170 Sets the maximum size of the incoming message queue. Once this
171 threashold is exceeded, no more messages will be read from wire
172 before one or more of the existing messages are dispatched to their
173 registered handlers. The implication is that the message queue can
174 exceed this threshold by at most the size of a single message.
175 $bytes $con->get_max_received_size()
177 Retrieves the maximum incoming message queue size. The returned
178 size is measured in bytes.
179 $con->add_filter($coderef);
181 Adds a filter to the connection which will be invoked whenever a
182 message is received. The $coderef should be a reference to a sub‐
183 routine, which returns a true value if the message should be fil‐
184 tered out, or a false value if the normal message dispatch should
185 be performed.
186 my $msg = $con->make_raw_message($rawmsg)
188 Creates a new message, initializing it from the low level C message
189 object provided by the $rawmsg parameter. The returned object will
190 be cast to the appropriate subclass of Net::DBus::Binding::Message.
191 my $msg = $con->make_error_message( replyto => $method_call, name =>
193 $name, description => $description);
194 Creates a new message, representing an error which occurred during
195 the handling of the method call object passed in as the "replyto"
196 parameter. The "name" parameter is the formal name of the error
197 condition, while the "description" is a short piece of text giving
198 more specific information on the error.
199 my $call = $con->make_method_call_message( $service_name, $object_path,
201 $interface, $method_name);
202 Create a message representing a call on the object located at the
203 path $object_path within the client owning the well-known name
204 given by $service_name. The method to be invoked has the name
205 $method_name within the interface specified by the $interface
206 parameter.
207 my $msg = $con->make_method_return_message( replyto => $method_call);
209 Create a message representing a reply to the method call passed in
210 the "replyto" parameter.
211 my $signal = $con->make_signal_message( object_path => $path, interface
213 => $interface, signal_name => $name);
214 Creates a new message, representing a signal [to be] emitted by the
215 object located under the path given by the "object_path" parameter.
216 The name of the signal is given by the "signal_name" parameter, and
217 is scoped to the interface given by the "interface" parameter.
218
220 Net::DBus::Binding::Server, Net::DBus::Binding::Bus, Net::DBus::Bind‐
221 ing::Message::Signal, Net::DBus::Binding::Message::MethodCall,
222 Net::DBus::Binding::Message::MethodReturn, Net::DBus::Binding::Mes‐
223 sage::Error
224
226 Daniel Berrange <dan@berrange.com>
227
229 Copyright 2004 by Daniel Berrange
230perl v5.8.8 2008-02-20 Net::DBus::Binding::Connection(3)