Mojom IDL and Bindings Generator

This document is a subset of the .

Contents

Overview

Mojom is the IDL for Mojo bindings interfaces. Given a .mojom file, the  outputs bindings for all supported languages: C++, JavaScript, and Java.

For a trivial example consider the following hypothetical Mojom file we write to //services/widget/public/interfaces/frobinator.mojom:

module widget.mojom;interface Frobinator {  Frobinate();};

This defines a single  named Frobinator in a  named widget.mojom (and thus fully qualified in Mojom as widget.mojom.Frobinator.) Note that many interfaces and/or other types of definitions may be included in a single Mojom file.

If we add a corresponding GN target to //services/widget/public/interfaces/BUILD.gn:

import("mojo/public/tools/bindings/mojom.gni")mojom("interfaces") {  sources = [    "frobinator.mojom",  ]}

and then build this target:

ninja -C out/r services/widget/public/interfaces

we'll find several generated sources in our output directory:

out/r/gen/services/widget/public/interfaces/frobinator.mojom.ccout/r/gen/services/widget/public/interfaces/frobinator.mojom.hout/r/gen/services/widget/public/interfaces/frobinator.mojom.jsout/r/gen/services/widget/public/interfaces/frobinator.mojom.srcjar...

Each of these generated source modules includes a set of definitions representing the Mojom contents within the target language. For more details regarding the generated outputs please see .

Mojom Syntax

Mojom IDL allows developers to define structs, unions, interfaces, constants, and enums, all within the context of a module. These definitions are used to generate code in the supported target languages at build time.

Mojom files 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.

Type	Description
bool	Boolean type (true or false.)
int8, uint8	Signed or unsigned 8-bit integer.
int16, uint16	Signed or unsigned 16-bit integer.
int32, uint32	Signed or unsigned 32-bit integer.
int64, uint64	Signed or unsigned 64-bit integer.
float, double	32- or 64-bit floating point number.
string	UTF-8 encoded string.
array<T>	Array of any Mojom type T; for example, array<uint8> or array<array<string>>.
array<T, N>	Fixed-length array of any Mojom type T. The parameter N must be an integral constant.
map<S, T>	Associated array maping values of type S to values of type T. S may be a string, enum, or numeric type.
handle	Generic Mojo handle. May be any type of handle, including a wrapped native platform handle.
handle<message_pipe>	Generic message pipe handle.
handle<shared_buffer>	Shared buffer handle.
handle<data_pipe_producer>	Data pipe producer handle.
handle<data_pipe_consumer>	Data pipe consumer handle.
InterfaceType	Any user-defined Mojom interface type. This is sugar for a strongly-typed message pipe handle which should eventually be used to make outgoing calls on the interface.
InterfaceType&	An interface request for any user-defined Mojom interface type. This is sugar for a more strongly-typed message pipe handle which is expected to receive request messages and should therefore eventually be bound to an implementation of the interface.
associated InterfaceType	An associated interface handle. See
associated InterfaceType&	An associated interface request. See
T?	An optional (nullable) value. Primitive numeric types (integers, floats, booleans, and enums) are not nullable. All other types are nullable.

Modules

Every Mojom file may optionally specify a single module to which it belongs.

This is used strictly for aggregaging all defined symbols therein within a common Mojom namespace. The specific impact this has on generated binidngs code varies for each target language. For example, if the following Mojom is used to generate bindings:

module business.stuff;interface MoneyGenerator {  GenerateMoney();};

Generated C++ bindings will define a class interface MoneyGenerator in the business::stuff namespace, while Java bindings will define an interface MoneyGenerator in the org.chromium.business.stuff package. JavaScript bindings at this time are unaffected by module declarations.

NOTE: By convention in the Chromium codebase, all Mojom files should declare a module name with at least (and preferrably exactly) one top-level name as well as an inner mojom module suffix. e.g., chrome.mojom, business.mojom, etc.

This convention makes it easy to tell which symbols are generated by Mojom when reading non-Mojom code, and it also avoids namespace collisions in the fairly common scenario where you have a real C++ or Java Foo along with a corresponding Mojom Foo for its serialized representation.

Imports

If your Mojom references definitions from other Mojom files, you must import those files. Import syntax is as follows:

import "services/widget/public/interfaces/frobinator.mojom";

Import paths are always relative to the top-level directory.

Note that circular imports are not supported.

Structs

Structs are defined using the struct keyword, and they provide a way to group related fields together:

struct StringPair {
          string first; string second; };

Struct fields may be comprised of any of the types listed above in the  section.

Default values may be specified as long as they are constant:

struct Request {
          int32 id = -1; string details; };

What follows is a fairly comprehensive example using the supported field types:

struct StringPair {
          string first; string second; }; enum AnEnum { YES, NO }; interface SampleInterface { DoStuff(); }; struct AllTheThings { // Note that these types can never be marked nullable! bool boolean_value; int8 signed_8bit_value = 42; uint8 unsigned_8bit_value; int16 signed_16bit_value; uint16 unsigned_16bit_value; int32 signed_32bit_value; uint32 unsigned_32bit_value; int64 signed_64bit_value; uint64 unsigned_64bit_value; float float_value_32bit; double float_value_64bit; AnEnum enum_value = AnEnum.YES; // Strings may be nullable. string? maybe_a_string_maybe_not; // Structs may contain other structs. These may also be nullable. StringPair some_strings; StringPair? maybe_some_more_strings; // In fact structs can also be nested, though in practice you must always make // such fields nullable -- otherwise messages would need to be infinitely long // in order to pass validation! AllTheThings? more_things; // Arrays may be templated over any Mojom type, and are always nullable: array
       
         numbers; array
        
         ? maybe_more_numbers; // Arrays of arrays of arrays... are fine. array
         
          
           
            >> this_works_but_really_plz_stop; // The element type may be nullable if it's a type which is allowed to be // nullable. array
            
              more_maybe_things; // Fixed-size arrays get some extra validation on the receiving end to ensure // that the correct number of elements is always received. array
             
               uuid; // Maps follow many of the same rules as arrays. Key types may be any // non-handle, non-collection type, and value types may be any supported // struct field type. Maps may also be nullable. map
              
                one_map; map
               
                ? maybe_another_map; map
                
                 ? maybe_a_pretty_weird_but_valid_map; map
                 
                  ?>?>?> ridiculous; // And finally, all handle types are valid as struct fields and may be // nullable. Note that interfaces and interface requests (the "Foo" and // "Foo&" type syntax respectively) are just strongly-typed message pipe // handles. handle generic_handle; handle
                  
                    reader; handle
                   
                    ? maybe_writer; handle