package obus
Module OBus_connectionSource
D-Bus connections
This module implements manipulation of a D-Bus connection. A D-Bus connection is a channel opened with another application which also implement the D-Bus protocol. It is used to exchange D-Bus messages.
Type of D-Bus connections
Same as Pervasives.compare. It allows this module to be used as argument to the functors Set.Make and Map.Make.
Creation
The following functions will return a connection which is ready to send and receive messages. You should use them only for direct connection to another application without passing through a message bus.
Otherwise you should use OBus_bus or immediately call OBus_bus.register_connection after the creation.
of_addresses ?switch ?shared addresses try to get a working D-Bus connection from a list of addresses. The server must be accessible from at least one of these addresses.
If shared is true and a connection to the same server is already open, then it is used instead of transport. This is the default behaviour.
Close a connection.
All thread waiting for a reply will fail with the exception Connection_closed.
Notes:
- when a connection is closed, the transport it use is closed too
- if the connection is already closed, it does nothing
Raised when trying to use a closed connection
Raised when a connection has been lost
Raised when something wrong happens on the backend transport of the connection
Informations
Returns the unique name of the connection. This is only meaningful is the other endpoint of the connection is a message bus. If it is not the case it returns "".
transport connection get the transport associated with a connection
can_send_*_type connection typ returns whether values of the given type can be sent through the given connection.
Sending messages
These functions are the low-level functions for sending messages. They take and return a complete message description
send_message connection message send a message without expecting a reply.
send_message_with_reply connection message Send a message and return a thread which waits for the reply (which is a method return or an error)
Same as send_message but does not generate a serial for the message.
Warning: this is for implementing a D-Bus daemon only, not for casual use.
Same as send_message_with_reply but does not generate a serial for the message.
Warning: this is for implementing a D-Bus daemon only, not for casual use.
Helpers for calling methods
val method_call :
connection:t ->
?destination:OBus_name.bus ->
path:OBus_path.t ->
?interface:OBus_name.interface ->
member:OBus_name.member ->
i_args:'a OBus_value.C.sequence ->
o_args:'b OBus_value.C.sequence ->
'a ->
'b Lwt.tCalls a method using the given parameters, and waits for its reply.
val method_call_with_message :
connection:t ->
?destination:OBus_name.bus ->
path:OBus_path.t ->
?interface:OBus_name.interface ->
member:OBus_name.member ->
i_args:'a OBus_value.C.sequence ->
o_args:'b OBus_value.C.sequence ->
'a ->
(OBus_message.t * 'b) Lwt.tSame as method_call, but also returns the reply message so you can extract informations from it.
val method_call_no_reply :
connection:t ->
?destination:OBus_name.bus ->
path:OBus_path.t ->
?interface:OBus_name.interface ->
member:OBus_name.member ->
i_args:'a OBus_value.C.sequence ->
'a ->
unit Lwt.tSame as method_call but does not expect a reply
General purpose filters
Filters are functions that are applied on all incoming and outgoing messages.
For incoming messages they are called before dispatching, for outgoing ones, they are called just before being sent.
The result of a filter must be:
Some msgwheremsgis the message given to the filter modified or not, which means that the message is replaced by this one
Nonewhich means that the message will be dropped, i.e. not dispatched or not sent
Filters applied on incoming messages
Filters appllied on outgoing messages
Connection local Storage
Connection local storage allows to attach values to a connection. It is internally used by modules of obus.
Type of keys. Keys are used to identify a resource attached to a connection.
get connection key returns the data associated to key in connection, if any.
set connection key value attach value to connection under the key key. set connection key None will remove any occurence of key from connection.
Errors handling
Note: when a filter/signal handler/method_call handler raise an exception, it is just dropped. If OBus_info.debug is set then a message is printed on stderr
Sets the function called when a fatal error happen or when the conection is lost.
Notes:
- the default function does nothing
- it is not called when the connection is closed using
close - if the connection is closed, it does nothing
Low-level
val of_transport :
?switch:Lwt_switch.t ->
?guid:OBus_address.guid ->
?up:bool ->
OBus_transport.t ->
tCreate a D-Bus connection on the given transport. If guid is provided the connection will be shared.
up tell whether the connection is initially up or down, default is true.
A connection can be up or down. Except for connections created with of_transport, newly created connections are always up.
When a connection is down, messages will not be dispatched
Signal holding the current state of the connection