package obus
Legend:
Library
Module
Module type
Parameter
Class
Class type

OBus extended introspection

By default, introspection documents do not convey semantical information, such as enumerations or flags. However it is possible to attach information to interfaces and members.

This module implements an extended introspection format, which can be encoded into standard introspection documents by using annotations.

Annotations

The following annotations are used to encode additional informations into D-Bus introspection documents

val obus_enum : string

The org.ocamlcore.forge.obus.Enum annotation

val obus_flag : string

The org.ocamlcore.forge.obus.Flag annotation

val obus_type : string

The org.ocamlcore.forge.obus.Type annotation

val obus_itype : string

The org.ocamlcore.forge.obus.IType annotation

val obus_otype : string

The org.ocamlcore.forge.obus.OType annotation

Extended types
type basic = private
  1. | Byte
  2. | Boolean
  3. | Int16
  4. | Int32
  5. | Int64
  6. | Uint16
  7. | Uint32
  8. | Uint64
  9. | Double
  10. | String
  11. | Signature
  12. | Object_path
  13. | Unix_fd
  14. | Enum of OBus_value.T.basic * (OBus_value.V.basic * string) list
    (*

    An enumeration. The first argument is the real D-Bus type and the second is a list of (constant, keyword).

    For example:

    Enum(OBus_value.T.Uint32,
     [(OBus_value.V.Uint32 1l, "ok");
      (OBus_value.V.Uint32 2l, "fail")])

    Note that the real D-Bus type must be OBus_value.T.basic.Byte or an integer type.

    *)
  15. | Flag of OBus_value.T.basic * (OBus_value.V.basic * string) list
    (*

    A flag. The first argument is the real type and the second is a list of (bits, keyword).

    For example:

    Flag(OBus_value.T.Uint32,
     [(OBus_value.V.Uint32 0x01l, "flag1");
      (OBus_value.V.Uint32 0x02l, "flag2");
      (OBus_value.V.Uint32 0x04l, "flag3")])

    Note that the real D-Bus type must be OBus_value.T.basic.Byte or an integer type.

    *)
type single =
  1. | Basic of basic
  2. | Structure of single list
  3. | Array of single
  4. | Dict of basic * single
  5. | Variant
type sequence = single list
Constructors
val byte : basic
val boolean : basic
val int16 : basic
val int32 : basic
val int64 : basic
val uint16 : basic
val uint32 : basic
val uint64 : basic
val double : basic
val string : basic
val signature : basic
val object_path : basic
val unix_fd : basic
val enum : OBus_value.T.basic -> (OBus_value.V.basic * string) list -> basic
val flag : OBus_value.T.basic -> (OBus_value.V.basic * string) list -> basic
val basic : basic -> single
val structure : single list -> single
val array : single -> single
val dict : basic -> single -> single
val variant : single
Terms
type term = private
  1. | Term of string * term list
    (*

    A term. Arguments are

    • the symbol name, which is either the name of a D-Bus type or a user defined type
    • the arguments taken by the function associated to the symbol
    *)
  2. | Tuple of term list
    (*

    A list of terms, packed into a tuple. Tuples are always mapped to D-Bus structures. Moreover it is ensured that there is never a type of the form Tuple[t].

    *)

A term represent a type, where symbols have not been resolved.

val term : string -> term list -> term

Construct a term

val tuple : term list -> term

Construct a tuple. If the list is of length 1, the type itself is returned.

Symbols
type symbol = private
  1. | Sym_enum of OBus_value.T.basic * (OBus_value.V.basic * string) list
  2. | Sym_flag of OBus_value.T.basic * (OBus_value.V.basic * string) list

Type of user-definable symbols

val sym_enum : OBus_value.T.basic -> (OBus_value.V.basic * string) list -> symbol

Create an enumeration

val sym_flag : OBus_value.T.basic -> (OBus_value.V.basic * string) list -> symbol

Create a flag type

Conversions
Stripping

The following functions remove extension from types.

val strip_basic : basic -> OBus_value.T.basic
val strip_single : single -> OBus_value.T.single
val strip_sequence : sequence -> OBus_value.T.sequence
Projections

The following functions project standard D-Bus types into extended D-Bus types

val project_basic : OBus_value.T.basic -> basic
val project_single : OBus_value.T.single -> single
val project_sequence : OBus_value.T.sequence -> sequence
Types to terms conversions

The following functions returns the term associated to a standard D-Bus type

val term_of_basic : OBus_value.T.basic -> term
val term_of_single : OBus_value.T.single -> term
val term_of_sequence : OBus_value.T.sequence -> term
Symbols resolution
type env = (string * symbol) list

An environment, mapping names to symbol

exception Resolve_error of string

Exception raised when the resolution of symbols of a type fails.

val resolve : env -> term -> single

resolve env term resolves symbols of term using env, and returns the extended type it denotes. It raises Resolve_error if a symbol of term is not found in env.

Extended introspection ast
type name = string
type annotation = name * string
type argument = name option * term
type access = OBus_introspect.access =
  1. | Read
  2. | Write
  3. | Read_write
type member =
  1. | Method of name * argument list * argument list * annotation list
  2. | Signal of name * argument list * annotation list
  3. | Property of name * term * access * annotation list
type interface = name * member list * (string * symbol) list * annotation list
Encoding/decoding

Encode the given interface into a standard one by using annotations

Decode the given standard interface into an extended one by decoding annotations