package obus
Module OBus_connection
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.
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.
val of_addresses :
?switch:Lwt_switch.t ->
?shared:bool ->
OBus_address.t list ->
t Lwt.tof_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.
val loopback : unit -> tCreate a connection with a loopback transport
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
val active : t -> bool React.signalReturns whether a connection is active.
Raised when something wrong happens on the backend transport of the connection
Informations
val name : t -> OBus_name.busReturns 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 "".
val transport : t -> OBus_transport.ttransport connection get the transport associated with a connection
val can_send_basic_type : t -> OBus_value.T.basic -> boolval can_send_single_type : t -> OBus_value.T.single -> boolval can_send_sequence_type : t -> OBus_value.T.sequence -> boolcan_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
val send_message : t -> OBus_message.t -> unit Lwt.tsend_message connection message send a message without expecting a reply.
val send_message_with_reply : t -> OBus_message.t -> OBus_message.t Lwt.tsend_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)
val send_message_keep_serial : t -> OBus_message.t -> unit Lwt.tSame 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.
val send_message_keep_serial_with_reply :
t ->
OBus_message.t ->
OBus_message.t Lwt.tSame 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.
type filter = OBus_message.t -> OBus_message.t optionThe 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
val incoming_filters : t -> filter Lwt_sequence.tFilters applied on incoming messages
val outgoing_filters : t -> filter Lwt_sequence.tFilters 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.
val new_key : unit -> 'a keynew_key () generates a new key.
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
val state : t -> [ `Up | `Down ] React.signalSignal holding the current state of the connection
val set_up : t -> unitSets up the connection if it is not already up
val set_down : t -> unitSets down the connection if it is not already down