Module OBus_introspect_extSource

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

Sourceval obus_enum : string

The org.ocamlcore.forge.obus.Enum annotation

Sourceval obus_flag : string

The org.ocamlcore.forge.obus.Flag annotation

Sourceval obus_type : string

The org.ocamlcore.forge.obus.Type annotation

Sourceval obus_itype : string

The org.ocamlcore.forge.obus.IType annotation

Sourceval obus_otype : string

The org.ocamlcore.forge.obus.OType annotation

Extended types
Sourcetype 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.

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

Sourceval term : string -> term list -> term

Construct a term

Sourceval tuple : term list -> term

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

Symbols
Sourcetype 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

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

Create an enumeration

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

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

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

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

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

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

An environment, mapping names to symbol

Sourceexception Resolve_error of string

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

Sourceval 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
Sourcetype name = string
Sourcetype annotation = name * string
Sourcetype argument = name option * term
Sourcetype access = OBus_introspect.access =
  1. | Read
  2. | Write
  3. | Read_write
Sourcetype 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
Sourcetype 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