api-types-cpp is a library providing ergonomic C++ types for data structures used at API (FIDL / banjo) boundaries.

Coding conventions

  • Namespace: All types are defined in the display namespace.

  • Filename: Each type is declared and defined in separate type-name.h / type-name.cc files.

  • Documentation: Each type’s class-level documentation points to the related FIDL / banjo types. This library’s documentation does not duplicate the API contracts specified in the corresponding FIDL / banjo types.

  • One-to-many mapping: One type in this library may correspond to multiple FIDL or banjo types. The type’s documentation points to all related FIDL / banjo types.

  • Data structure naming: The library aims to reuse the FIDL vocabulary for type names and struct member names. FIDL names prevail in naming conflicts between FIDL and banjo. (The long-term conflict resolution is the removal of the banjo types.)

  • Conversion helpers: The library offers conversion helpers between library types and all related FIDL / banjo types. Conversion helpers that produce library types are named ToTypeName(). Conversion helpers that produce FIDL / Banjo types are named ToFidlTypeName() / ToBanjoTypeName().

Type design guidelines

A type defined in api-types-cpp may be an alias of the related FIDL C++ wire type. See AlphaMode for an aliasing example.

The library defines its own types when the code generated by the FIDL C++ wire binding is not sufficiently ergonomic. Some examples of ergonomic gaps in the FIDL generated code:

  • FIDL uses unsigned numeric types for non-negative quantities. This library uses signed types for values that may be involved in arithmetic operations, so we can lean on UBSan for overflow detection. For a concrete example, compare display::Frame with its associated fuchsia.hardware.display.types/Frame FIDL type.

  • No comparison or arithmetics operators. As a minimum bar, this library overloads == and != for all the types it defines. This makes it easy to use the types in googletest assertions.

  • FIDL currently lacks newtype support for non-composite types (numeric and boolean), and the recommended workaround is struct wrappers. This library offers fbl::StrongInt-based types for internal representation, together with conversion helpers for FIDL’s struct wrappers. This is especially useful for the Display stack, which makes extensive use of 64-bit integers as handles for various resources. For a concrete example, compare display::DisplayId with the fuchsia.hardware.display.types/DisplayId FIDL type.

  • Generated binding for FIDL types containing tables or unions require arena allocations.