# Module OBus_connection

    module OBus_connection: sig .. end

D-Bus connections

This module implement 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 t

Type of D-Bus connections

    val compare : t -> t -> int

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 immediatly call `OBus_bus.register_connection` after the creation.

    val of_addresses : ?switch:Lwt_switch.t ->
           ?shared:bool -> OBus_address.t list -> t Lwt.t

`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.

    val loopback : unit -> t

Creates a connection with a loopback transport

    val close : t -> unit Lwt.t

Close a connection.

All thread waiting for a reply will fail with the exception `OBus_connection.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.signal

Returns whether a connection is active.

    exception Connection_closed

Raise when trying to use a closed connection

    exception Connection_lost

Raised when a connection has been lost

    exception Transport_error of exn

Raised when something wrong happen on the backend transport of the connection

###### Informations

    val name : t -> OBus_name.bus

Returns the unique name of the connection. This is only meaning-full is the other endpoint of the connection is a message bus. If it is not the case it returns `""`.

    val transport : t -> OBus_transport.t

`transport connection` get the transport associated with a connection

    val can_send_basic_type : t -> OBus_value.T.basic -> bool

    val can_send_single_type : t -> OBus_value.T.single -> bool

    val can_send_sequence_type : t -> OBus_value.T.sequence -> bool

`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

    val send_message : t -> OBus_message.t -> unit Lwt.t

`send_message connection message` send a message without expecting a reply.

    val send_message_with_reply : t -> OBus_message.t -> OBus_message.t Lwt.t

`send_message_with_reply connection message` Send a message and return a thread which wait for the reply (which is a method return or an error)

    val send_message_keep_serial : t -> OBus_message.t -> unit Lwt.t

Same as `OBus_connection.send_message` but do 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.t

Same as `OBus_connection.send_message_with_reply` but do 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.t

Calls 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.t

Same as `OBus_connection.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.t

Same as `OBus_connection.method_call` but do not expect a reply

###### General purpose filters

Filters are functions whose 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 option

The result of a filter must be:

- `Some msg` where `msg` is the message given to the filter modified or not, which means that the message is replaced by this one

- `None` which means that the message will be dropped, i.e. not dispatched or not sent

    val incoming_filters : t -> filter Lwt_sequence.t

Filters applied on incomming messages

    val outgoing_filters : t -> filter Lwt_sequence.t

Filters appllied on outgoing messages

###### Connection's local Storage

Connection's local storage allow to attach values to a connection. It is internally used by modules of obus.

    type 'a key

Type of keys. Keys are used to identify a resource attached to a connection.

    val new_key : unit -> 'a key

`new_key ()` generates a new key.

    val get : t -> 'a key -> 'a option

`get connection key` returns the data associated to `key` in connection, if any.

    val set : t -> 'a key -> 'a option -> unit

`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`

    val set_on_disconnect : t -> (exn -> unit Lwt.t) -> unit

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 `OBus_connection.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 -> t

Create 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, expect for connection created with `of_transport`, newly created connection are always up.

When a connection is down, messages will not be dispatched

    val state : t -> [ `Down | `Up ] React.signal

Signal holding the current state of the connection

    val set_up : t -> unit

Sets up the connection if it is not already up

    val set_down : t -> unit

Sets down the connection if it is not already down