// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

[DartPackage="mojo", JavaPackage="org.chromium.mojo.bindings.types"]
module mojo.bindings.types;

import "mojom_types.mojom";

/*
* The structures in this file are intended to be used by the Mojom compiler
* and code generators. The front end of the compiler takes as input a
* .mojom file (or a list of .mojom files) and produces a MojomFileGraph struct.
*
* The backend of the compiler consumes a MojomFileGraph and invokes each of the
* code generators passing them data derived from the MojomFileGraph.
*
* A MojomFile represents the data parsed from a single .mojom file. Mojom
* modules form a directed acyclic graph via the "imports" relation.
* That is, if Module A imports Module B then there is a directed edge in the
* graph from A to B. A MojomFileGraph represents the whole Graph.

* The Mojom structures represented here have been fully resolved, meaning that
* the type references have been associated with their corresponding type
* definitions. This resolved type data is contained in the resolved_types data
* in MojomFileGraph.
*/

// A MojomFile represents the data defined by a single .mojom file, when
// all of the type references to types declared in imported .mojom files
// have been resolved.
struct MojomFile {
  // |file_name| is (derived from) the file name of the corresponding
  // .mojom file. It is the unique identifier for this module within the
  // MojomFileGraph
  string file_name;

  // |specified_file_name| is used to record information about the request that
  // triggered the construction of the |MojomFileGraph| of which this
  // |MojomFile| is a part. This field is populated by some producers (such
  // as the Mojom compiler) but not necessarily all producers of this structure.
  // If this field is null it means it is not supported by the producer.
  //
  // If this field is non-null but empty it means that this |MojomFile|
  // was not explicitly requested but rather is included in the |MojomFileGraph|
  // because it is referenced in the |imports| field of another |MojomFile|
  // in the graph. If this field is non-empty it means that the corresponding
  // .mojom file was explicitly requested, using |specified_file_name|. Note
  // that in this case it is still possible that this file is also referenced
  // in the |imports| field of another |MojomFile|.
  string? specified_file_name;

   // The namespace is the identifier declared via the "module" declaration
   // in the .mojom file.
  string? module_namespace;

  // Attributes declared in the Mojom file at the module level.
  array<Attribute>? attributes;

  // The list of other MojomFiles imported by this one. The elements
  // of the array are the |file_name|s and the associated module may
  // be retrieved from the  MojomFileGraph.
  array<string>? imports;

  // resolved_types and resolved_values in MojomFileGraph contain
  // respectively the types and constants declared in the union of all modules
  // in the graph. This KeysByType selects the keys of the types and constants
  // defined in this module
  KeysByType declared_mojom_objects;

  // The bytes encoding a |RuntimeTypeInfo| struct for this Mojom file,
  // using Mojo message serialization. Some implementations may not include
  // this.
  array<uint8>? serialized_runtime_type_info;
};

// Represents a directed acyclic graph of MojomFiles.
struct MojomFileGraph {
  // All the files in this graph. The keys are |file_name|s.
  map<string, MojomFile> files;

  // All the resolved user-defined types known to this structure. The keys are
  // the |type_key|s.
  map<string, UserDefinedType> resolved_types;

  // All the resolved user-defined values known to this structure. The keys are
  // the |value_key|s.
  map<string, UserDefinedValue> resolved_values;
};

// A KeysByType struct organizes by type all of the type and constant keys known
// to an associated MojomFileGraph.
struct KeysByType {
  // All the type_keys known to the owning MojomFileGraph, organized by
  // type;
  array<string>? interfaces;
  array<string>? structs;
  array<string>? unions;
  array<string>? top_level_enums;
  array<string>? embedded_enums;

  // All the constant_keys known to the owning MojomFileGraph.
  array<string>? top_level_constants;
  array<string>? embedded_constants;
};

// This structure is a component of RuntimeTypeInfo.
// It contains the information necessary to extract the types corresponding
// to a single service. See the comments on RuntimeTypeInfo for a fuller
// explanation.
struct ServiceTypeInfo {
  // The type_key of the top-level interface for the service. This is the
  // type_key of the interface that was annotated with the "ServiceName"
  // annotation.
  string top_level_interface;

  // All of the type_keys of the types in the complete type set of the serive.
  // Note that this set is not restricted to the types from a single .mojom
  // file.
  array<string> complete_type_set;
};

// This structure contains the information necessary for an implementation of
// |ServiceDescription| (see service_describer.mojom), but restricted to a
// single .mojom file and not restricted to a single service. At runtime an
// implementation of |ServiceDescription| needs to merge the |RuntimeTypeInfo|
// from all of the generated modules in the file graph and then filter on only
// those types in the complete type set of a single service.
//
// Note that this structure is not literally a component of a MojomFileGraph.
// Instead, at compile time an instance of this structure is created and
// serialized to an array of bytes that is stored in the
// |serialized_runtime_type_info| field of each |MojomFile|. Then at code
// generation time this array of bytes is written into the generated source
// code as a literal array of bytes. Then at runtime this array of bytes
// is deserialized into an instance of RuntimeTypeInfo that may be used by
// an implementation of |ServiceDescription|.
struct RuntimeTypeInfo {
  // All of the services contained in a single .mojom file. A "service" is an
  // interface that has been annoted with the "ServiceName" annotation.
  // This indicates that it can be returned from
  // ServiceProvider.ProvideService() and its description can be returned
  // from ServiceDescriber.DescribeService(). The keys are the service names
  // (as specified in the "ServiceName" annotation) and the values are instances
  // of |ServiceTypeInfo| for that service.
  //
  // Note that the |type_map| field below is scoped to a single .mojom file and
  // so some of the keys in the |complete_type_set| field of each
  // |ServiceTypeInfo| struct may not occur in |type_map|. At runtime the
  // |type_map|s from multiple files may need to be combined in order to
  // get all of the types listed in the |complete_type_set| of a single service.
  map<string, ServiceTypeInfo> services_by_name;

  // All of the resolved user-defined-types contained in a single .mojom File.
  // The keys are the |type_key|s.
  map<string, UserDefinedType> type_map;
};