For Developers‎ > ‎Design Documents‎ > ‎Mojo‎ > ‎

Mojom Syntax

Overview

Mojom IDL allows developers to define structs, interfaces, constants, and enums, within the context of a module, to be used for bindings code generation at compile time. A mojom file may import other mojom files in order to reference their definitions.

Primitive Types

Mojom supports a few basic data types which may be composed into structs or used for message parameters.

 bool Boolean type
 int8, uint8Signed or unsigned 8-bit integer
 int16, uint16Signed or unsigned 16-bit integer
 int32uint32Signed or unsigned 32-bit integer
 int64uint64Signed or unsigned 64-bit integer
 floatdouble32- or 64-bit floating point number
 stringUnicode string 
 array<T>Array of type T. e.g. array<uint8> or array<array<string>>, etc. T may be any mojom type.
 array<T, N>Fixed-length array of type T. N must be an integer constant. 
 map<S, T>Associative array mapping values of type S to values of type T. Type S may be string or any of the numeric types. T may be any mojom type.
 handleGeneric Mojo handle. May be any type of handle, including a wrapped platform handle. 
 handle<T>Specific handle type. T may be message_pipe, shared_buffer, data_pipe_consumer, or data_pipe_producer
 InterfaceTypeAny user-defined Mojo interface type. This is sugar for a more strongly-typed handle<message_pipe> which will the receiver is expected to use to make calls to a remote interface.
 InterfaceType&An interface request for any user-defined Mojo interface type. This is sugar for a more strongly-typed handle<message_pipe> which the receiver is expected to bind to an implementation of InterfaceType.
T?  A type that may be null. Numerical types (integeral, floating point, boolean, enum) are not nullable. Note that if a Struct/Array/Map/StringTraits specialization is used to convert between a custom type and T, the specialization needs to implement special members IsNull() and SetToNull() to support nullable.

Interfaces

An interface is a logical bundle of parameterized messages. Each message may optionally have a parameterized response. The syntax to define an interface Foo is as follows:

interface Foo {
  MyMessage();
  MyOtherMessage(string name, array<uint8> bytes);
  MyMessageWithResponse(string command) => (bool success);
  MyMessageWithMoarResponse(string a, string b) => (int8 c, int8 d);
};

Notice the use of the => operator to specify a response message.

Structs, Enums and Constants

struct, enum, or constant can be defined in mojom using similar syntax to their familiar C counterparts:

struct StringPair {
  string first;
  string second;
};

enum AdvancedBoolean {
  TRUE = 0,
  FALSE,
  FILE_NOT_FOUND,
};

const uint8 kAnswer = 42;

Note that enum and const definitions may also be be nested within an interface or struct block to limit their visibility accordingly (subject to the constraints of the generated bindings language.)

Modules

Every mojom file may optionally specify exactly one module to which it belongs. This is used strictly for aggregating the defined symbols therein within a common namespace, however that may apply to the generated bindings language. For example, if the following mojom is provided:

module foo.bar.baz;

interface Qux {
  Quux();
};

Generated C++ bindings will define a symbol Qux in the namespace foo::bar::baz, and Java bindings will define a symbol Qux in the package org.chromium.mojom.foo.bar.baz. JavaScript bindings at this time are unaffected by module declarations.

NOTE: As mentioned in the Mojo primer, it is convention in the Chromium codebase for all mojoms to declare a module name with a .mojom suffix (e.g., foo.mojom, foo.bar.baz.mojom, etc.)

Imports

If your mojom must reference symbols defined in other mojom files, you must import those files. Import syntax is as follows:

import "components/foo/public/interfaces/foo.mojom";

Import paths are always relative to the top-level src/ directory. This may be overridden by individual build rule settings, but doing so is strongly discouraged.

Attributes

Mojom definitions may have their meaning altered by attributes, specified with a syntax simliar to Java or C# attributes. There are a handful of interesting attributes supported today.

[Sync]

The Sync attribute may be specified for any interface method which expects a response. This makes it so that callers of the method wait synchronously for a response. See Synchronous Calls for more information.

[Extensible]

The Extensible attribute may be specified for any enum definition. This attribute disables built-in range validation when receiving values of the modified enum type in a message.

[Native]

The Native attribute may be specified for a struct declaration to provide a nominal bridge between Mojo IPC and legacy IPC ParamTraits. See Using Existing IPC::ParamTraits for more information.

Grammar Reference

Below is the BNF-ish context-free grammar for a mojom file:

MojomFile = StatementList
StatementList = Statement StatementList | Statement
Statement = ModuleStatement | ImportStatement | Definition

ModuleStatement = AttributeSection "module" Identifier ";"
ImportStatement = "import" StringLiteral ";"
Definition = Struct Union Interface Enum Const

AttributeSection = "[" AttributeList "]"
AttributeList = <empty> | NonEmptyAttributeList
NonEmptyAttributeList = Attribute
                      | Attribute "," NonEmptyAttributeList
Attribute = Name
          | Name "=" Name
          | Name "=" Literal

Struct = AttributeSection "struct" Name "{" StructBody "}" ";"
       | AttributeSection "struct" Name ";"
StructBody = <empty>
           | StructBody 
Const
           | StructBody Enum
           | StructBody StructField
StructField = AttributeSection TypeSpec Name Orginal Default ";"

Union = AttributeSection "union" Name "{" UnionBody "}" ";"
UnionBody = <empty> | UnionBody UnionField
UnionField = AttributeSection TypeSpec Name Ordinal ";"

Interface = AttributeSection "interface" Name "{" InterfaceBody "}" ";"
InterfaceBody = <empty>
              | InterfaceBody Const
              | InterfaceBody Enum
              | InterfaceBody Method
Method = AttributeSection Name Ordinal "(" ParamterList ")" Response ";"
ParameterList = <empty> | NonEmptyParameterList
NonEmptyParameterList = Parameter
                      | Parameter "," NonEmptyParameterList
Parameter = AttributeSection TypeSpec Name Ordinal
Response = <empty> | "=>" "(" ParameterList ")"

TypeSpec = TypeName "?" | TypeName
TypeName = BasicTypeName
         | Array
         | FixedArray
         | Map
         | InterfaceRequest
BasicTypeName = Identifier | "associated" Identifier | HandleType
HandleType = "handle" | "handle" "<" SpecificHandleType ">"
SpecificHandleType = "message_pipe"
                   | "shared_buffer"
                   | "data_pipe_consumer"
                   | "data_pipe_producer"
Array = "array" "<" TypeSpec ">"
FixedArray = "array" "<" TypeSpec "," IntConstDec ">"
Map = "map" "<" Identifier "," TypeSpec ">"
InterfaceRequest = Identifier "&" | "associated" Identifier "&"

Ordinal = <empty> | OrdinalValue

Default = <empty> | "=" Constant

Enum = AttributeSection "enum" Name "{" NonEmptyEnumValueList "}" ";"
     | AttributeSection "enum" Name "{" NonEmptyEnumValueList "," "}" ";"
NonEmptyEnumValueList = EnumValue | NonEmptyEnumValueList "," EnumValue
EnumValue = AttributeSection Name
          | AttributeSection Name "=" Integer
          | AttributeSection Name "=" Identifier

Const = "const" TypeSpec Name "=" Constant ";"

Constant = Literal | Identifier ";"

Identifier = Name | Name "." Identifier

Literal = Integer | Float | "true" | "false" | "default" | StringLiteral

Integer = IntConst | "+" IntConst | "-" IntConst
IntConst = IntConstDec | IntConstHex

Float = FloatConst | "+" FloatConst | "-" FloatConst

# The rules below are for tokens matched strictly according to the given regexes

Identifier = /[a-zA-Z_][0-9a-zA-Z_]*/ 
IntConstDec = /0|(1-9[0-9]*)/
IntConstHex = /0[xX][0-9a-fA-F]+/
OrdinalValue = /@(0|(1-9[0-9]*))/
FloatConst = ... # Imagine it's close enough to C-style float syntax.
StringLiteral = ... # Imagine it's close enough to C-style string literals, including escapes.
Comments