/usr/lib/ocaml/obus/oBus_peer.mli is in libobus-ocaml-dev 1.1.5-3build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 | (*
* oBus_peer.mli
* -------------
* Copyright : (c) 2008, Jeremie Dimino <jeremie@dimino.org>
* Licence : BSD3
*
* This file is a part of obus, an ocaml implementation of D-Bus.
*)
(** D-Bus peers *)
(** A D-Bus peer represent an application which can be reach though a
D-Bus connection. It is the application at the end-point of the
connection or, if the end-point is a message bus, any application
connected to it. *)
type t = {
connection : OBus_connection.t;
(** Connection used to reach the peer. *)
name : OBus_name.bus;
(** Name of the peer. This only make sense if the connection is a
connection to a message bus. *)
}
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]. *)
val connection : t -> OBus_connection.t
(** [connection] projection *)
val name : t -> OBus_name.bus
(** [name] projection *)
(** Note that it is possible to use either a unique connection name or
a bus name as peer name.
Both possibility have advantages and drawbacks:
- using bus names such as "org.freedesktop.DBus.Hal" avoid the
need to resolve the name. When doing the first method call the bus
will automatically start the service if available. Also if the
service restart the peer will still be valid.
One drawback is that the owner may change over the time, and
method calls may not be made on the same peer.
- using unique name, which can be retreived with bus functions
(see {!OBus_bus}), ensure that the peer won't change over time.
By the way if the service exit, or another application replace it
and we want to always use the default one, we have to write the
code to handle owner change.
So, one good strategy is to use bus name when calls do not involve
side-effect on the service such as object creation, and use unique
name for object create on our demand. Basically you can stick to
this rule:
Always use bus name for a well-known objects, such as
"/org/freedesktop/Hal/Manager" on "org.freedesktop.Hal.Manager"
and use unique name for objects for which the path is retreived
from a method call.
*)
val make : connection : OBus_connection.t -> name : OBus_name.bus -> t
(** [make connection name] make a named peer *)
val anonymous : OBus_connection.t -> t
(** [anonymous connection] make an anonymous peer *)
val ping : t -> t Lwt.t
(** Ping a peer, and return the peer which really respond to the
ping.
For example, the fastest way to get the the peer owning a bus
name, and start it if not running is:
[ping (OBus_peer.make bus "well.known.name")] *)
val get_machine_id : t -> OBus_uuid.t Lwt.t
(** Return the id of the machine the peer is running on *)
val wait_for_exit : t -> unit Lwt.t
(** [wait_for_exit peer] wait until [peer] exit. If [peer] is not
running then it returns immediatly. Raises [Invalid_argument] if
the peer has no name. *)
(** {6 Private peers} *)
type peer = t
(** Minimal interface of private peers *)
module type Private = sig
type t = private peer
external of_peer : peer -> t = "%identity"
external to_peer : t -> peer = "%identity"
end
(** Minimal implementation of private peers *)
module Private : sig
type t = peer
external of_peer : peer -> t = "%identity"
external to_peer : t -> peer = "%identity"
end
|