{"owner":"citizenfx","repo":"fivem","hasSkills":true,"totalSkillsCount":3,"totalTokensCount":6694,"categories":["plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":["code/tools/README.md","vendor/chromium/mojo/public/tools/bindings/README.md","code/tools/dbg/pe_debug/msft_pdb/readme.md"],"skills":{"code/tools/README.md":"# `tools/`\nCitizenFX build infrastructure.\n\n* [**build/**](./build): Premake5 build tool helpers.\n* [**ci/**](./ci): CI scripts. Confused about the build process? Look here.\n* [**dbg/**](./dbg): Wrappers for adding debug info to game clients.\n* [**ext/**](./ext): External data.\n* [**idl/**](./idl): `xpidl` fork.","vendor/chromium/mojo/public/tools/bindings/README.md":"# Mojom Interface Definition Language (IDL)\nThis document is a subset of the [Mojo documentation](/mojo/README.md).\n\n[TOC]\n\n## Overview\n\nMojom is the IDL for Mojo interfaces. Given a `.mojom` file, the\n[bindings\ngenerator](https://cs.chromium.org/chromium/src/mojo/public/tools/bindings/) can\noutput bindings for any supported language: **C++**, **JavaScript**, or\n**Java**.\n\nFor a trivial example consider the following hypothetical Mojom file we write to\n`//services/widget/public/mojom/frobinator.mojom`:\n\n```\nmodule widget.mojom;\n\ninterface Frobinator {\n Frobinate();\n};\n```\n\nThis defines a single [interface](#Interfaces) named `Frobinator` in a\n[module](#Modules) named `widget.mojom` (and thus fully qualified in Mojom as\n`widget.mojom.Frobinator`.) Note that many interfaces and/or other types of\ndefinitions (structs, enums, *etc.*) may be included in a single Mojom file.\n\nIf we add a corresponding GN target to\n`//services/widget/public/mojom/BUILD.gn`:\n\n```\nimport(\"mojo/public/tools/bindings/mojom.gni\")\n\nmojom(\"mojom\") {\n sources = [\n \"frobinator.mojom\",\n ]\n}\n```\n\nand then build this target:\n\n```\nninja -C out/r services/widget/public/mojom\n```\n\nwe'll find several generated sources in our output directory:\n\n```\nout/r/gen/services/widget/public/mojom/frobinator.mojom.cc\nout/r/gen/services/widget/public/mojom/frobinator.mojom.h\nout/r/gen/services/widget/public/mojom/frobinator.mojom-shared.h\netc...\n```\n\nEach of these generated source modules includes a set of definitions\nrepresenting the Mojom contents in C++. You can also build or depend on suffixed\ntarget names to get bindings for other languages. For example,\n\n```\nninja -C out/r services/widget/public/mojom:mojom_js\nninja -C out/r services/widget/public/mojom:mojom_java\n```\n\nwould generate JavaScript and Java bindings respectively, in the same generated\noutput directory.\n\nFor more details regarding the generated\noutputs please see\n[documentation for individual target languages](#Generated-Code-For-Target-Languages).\n\n## Mojom Syntax\n\nMojom IDL allows developers to define **structs**, **unions**, **interfaces**,\n**constants**, and **enums**, all within the context of a **module**. These\ndefinitions are used to generate code in the supported target languages at build\ntime.\n\nMojom files may **import** other Mojom files in order to reference their\ndefinitions.\n\n### Primitive Types\nMojom supports a few basic data types which may be composed into structs or used\nfor message parameters.\n\n| Type | Description\n|-------------------------------|-------------------------------------------------------|\n| `bool` | Boolean type (`true` or `false`.)\n| `int8`, `uint8` | Signed or unsigned 8-bit integer.\n| `int16`, `uint16` | Signed or unsigned 16-bit integer.\n| `int32`, `uint32` | Signed or unsigned 32-bit integer.\n| `int64`, `uint64` | Signed or unsigned 64-bit integer.\n| `float`, `double` | 32- or 64-bit floating point number.\n| `string` | UTF-8 encoded string.\n| `array` | Array of any Mojom type *T*; for example, `array` or `array>`.\n| `array` | Fixed-length array of any Mojom type *T*. The parameter *N* must be an integral constant.\n| `map` | Associated array maping values of type *S* to values of type *T*. *S* may be a `string`, `enum`, or numeric type.\n| `handle` | Generic Mojo handle. May be any type of handle, including a wrapped native platform handle.\n| `handle` | Generic message pipe handle.\n| `handle` | Shared buffer handle.\n| `handle` | Data pipe producer handle.\n| `handle` | Data pipe consumer handle.\n| *`pending_remote`* | 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.\n| *`pending_receiver`* | A pending receiver 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.\n| *`pending_associated_remote`* | An associated interface handle. See [Associated Interfaces](#Associated-Interfaces)\n| *`pending_associated_receiver`* | A pending associated receiver. See [Associated Interfaces](#Associated-Interfaces)\n| *T*? | An optional (nullable) value. Primitive numeric types (integers, floats, booleans, and enums) are not nullable. All other types are nullable.\n\n### Modules\n\nEvery Mojom file may optionally specify a single **module** to which it belongs.\n\nThis is used strictly for aggregaging all defined symbols therein within a\ncommon Mojom namespace. The specific impact this has on generated binidngs code\nvaries for each target language. For example, if the following Mojom is used to\ngenerate bindings:\n\n```\nmodule business.stuff;\n\ninterface MoneyGenerator {\n GenerateMoney();\n};\n```\n\nGenerated C++ bindings will define a class interface `MoneyGenerator` in the\n`business::stuff` namespace, while Java bindings will define an interface\n`MoneyGenerator` in the `org.chromium.business.stuff` package. JavaScript\nbindings at this time are unaffected by module declarations.\n\n**NOTE:** By convention in the Chromium codebase, **all** Mojom files should\ndeclare a module name with at least (and preferrably exactly) one top-level name\nas well as an inner `mojom` module suffix. *e.g.*, `chrome.mojom`,\n`business.mojom`, *etc.*\n\nThis convention makes it easy to tell which symbols are generated by Mojom when\nreading non-Mojom code, and it also avoids namespace collisions in the fairly\ncommon scenario where you have a real C++ or Java `Foo` along with a\ncorresponding Mojom `Foo` for its serialized representation.\n\n### Imports\n\nIf your Mojom references definitions from other Mojom files, you must **import**\nthose files. Import syntax is as follows:\n\n```\nimport \"services/widget/public/mojom/frobinator.mojom\";\n```\n\nImport paths are always relative to the top-level directory.\n\nNote that circular imports are **not** supported.\n\n### Structs\n\nStructs are defined using the **struct** keyword, and they provide a way to\ngroup related fields together:\n\n``` cpp\nstruct StringPair {\n string first;\n string second;\n};\n```\n\nStruct fields may be comprised of any of the types listed above in the\n[Primitive Types](#Primitive-Types) section.\n\nDefault values may be specified as long as they are constant:\n\n``` cpp\nstruct Request {\n int32 id = -1;\n string details;\n};\n```\n\nWhat follows is a fairly\ncomprehensive example using the supported field types:\n\n``` cpp\nstruct StringPair {\n string first;\n string second;\n};\n\nenum AnEnum {\n YES,\n NO\n};\n\ninterface SampleInterface {\n DoStuff();\n};\n\nstruct AllTheThings {\n // Note that these types can never be marked nullable!\n bool boolean_value;\n int8 signed_8bit_value = 42;\n uint8 unsigned_8bit_value;\n int16 signed_16bit_value;\n uint16 unsigned_16bit_value;\n int32 signed_32bit_value;\n uint32 unsigned_32bit_value;\n int64 signed_64bit_value;\n uint64 unsigned_64bit_value;\n float float_value_32bit;\n double float_value_64bit;\n AnEnum enum_value = AnEnum.YES;\n\n // Strings may be nullable.\n string? maybe_a_string_maybe_not;\n\n // Structs may contain other structs. These may also be nullable.\n StringPair some_strings;\n StringPair? maybe_some_more_strings;\n\n // In fact structs can also be nested, though in practice you must always make\n // such fields nullable -- otherwise messages would need to be infinitely long\n // in order to pass validation!\n AllTheThings? more_things;\n\n // Arrays may be templated over any Mojom type, and are always nullable:\n array numbers;\n array? maybe_more_numbers;\n\n // Arrays of arrays of arrays... are fine.\n array>> this_works_but_really_plz_stop;\n\n // The element type may be nullable if it's a type which is allowed to be\n // nullable.\n array more_maybe_things;\n\n // Fixed-size arrays get some extra validation on the receiving end to ensure\n // that the correct number of elements is always received.\n array uuid;\n\n // Maps follow many of the same rules as arrays. Key types may be any\n // non-handle, non-collection type, and value types may be any supported\n // struct field type. Maps may also be nullable.\n map one_map;\n map? maybe_another_map;\n map? maybe_a_pretty_weird_but_valid_map;\n map?>?>?> ridiculous;\n\n // And finally, all handle types are valid as struct fields and may be\n // nullable. Note that interfaces and interface requests (the \"Foo\" and\n // \"Foo&\" type syntax respectively) are just strongly-typed message pipe\n // handles.\n handle generic_handle;\n handle reader;\n handle? maybe_writer;\n handle dumping_ground;\n handle raw_message_pipe;\n pending_remote? maybe_a_sample_interface_client_pipe;\n pending_receiver non_nullable_sample_pending_receiver;\n pending_receiver? nullable_sample_pending_receiver;\n pending_associated_remote associated_interface_client;\n pending_associated_receiver associated_pending_receiver;\n pending_associated_receiver? maybe_another_pending_receiver;\n};\n```\n\nFor details on how all of these different types translate to usable generated\ncode, see\n[documentation for individual target languages](#Generated-Code-For-Target-Languages).\n\n### Unions\n\nMojom supports tagged unions using the **union** keyword. A union is a\ncollection of fields which may taken the value of any single one of those fields\nat a time. Thus they provide a way to represent a variant value type while\nminimizing storage requirements.\n\nUnion fields may be of any type supported by [struct](#Structs) fields. For\nexample:\n\n```cpp\nunion ExampleUnion {\n string str;\n StringPair pair;\n int64 id;\n array guid;\n SampleInterface iface;\n};\n```\n\nFor details on how unions like this translate to generated bindings code, see\n[documentation for individual target languages](#Generated-Code-For-Target-Languages).\n\n### Enumeration Types\n\nEnumeration types may be defined using the **enum** keyword either directly\nwithin a module or nested within the namespace of some struct or interface:\n\n```\nmodule business.mojom;\n\nenum Department {\n SALES = 0,\n DEV,\n};\n\nstruct Employee {\n enum Type {\n FULL_TIME,\n PART_TIME,\n };\n\n Type type;\n // ...\n};\n```\n\nSimilar to C-style enums, individual values may be explicitly assigned within an\nenum definition. By default, values are based at zero and increment by\n1 sequentially.\n\nThe effect of nested definitions on generated bindings varies depending on the\ntarget language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages)\n\n### Constants\n\nConstants may be defined using the **const** keyword either directly within a\nmodule or nested within the namespace of some struct or interface:\n\n```\nmodule business.mojom;\n\nconst string kServiceName = \"business\";\n\nstruct Employee {\n const uint64 kInvalidId = 0;\n\n enum Type {\n FULL_TIME,\n PART_TIME,\n };\n\n uint64 id = kInvalidId;\n Type type;\n};\n```\n\nThe effect of nested definitions on generated bindings varies depending on the\ntarget language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages)\n\n### Interfaces\n\nAn **interface** is a logical bundle of parameterized request messages. Each\nrequest message may optionally define a parameterized response message. Here's\nan example to define an interface `Foo` with various kinds of requests:\n\n```\ninterface Foo {\n // A request which takes no arguments and expects no response.\n MyMessage();\n\n // A request which has some arguments and expects no response.\n MyOtherMessage(string name, array bytes);\n\n // A request which expects a single-argument response.\n MyMessageWithResponse(string command) => (bool success);\n\n // A request which expects a response with multiple arguments.\n MyMessageWithMoarResponse(string a, string b) => (int8 c, int8 d);\n};\n```\n\nAnything which is a valid struct field type (see [Structs](#Structs)) is also a\nvalid request or response argument type. The type notation is the same for both.\n\n### Attributes\n\nMojom definitions may have their meaning altered by **attributes**, specified\nwith a syntax similar to Java or C# attributes. There are a handle of\ninteresting attributes supported today.\n\n**`[Sync]`**\n: The `Sync` attribute may be specified for any interface method which expects\n a response. This makes it so that callers of the method can wait\n synchronously for a response. See\n [Synchronous Calls](/mojo/public/cpp/bindings/README.md#Synchronous-Calls)\n in the C++ bindings documentation. Note that sync calls are not currently\n supported in other target languages.\n\n**`[Extensible]`**\n: The `Extensible` attribute may be specified for any enum definition. This\n essentially disables builtin range validation when receiving values of the\n enum type in a message, allowing older bindings to tolerate unrecognized\n values from newer versions of the enum.\n\n**`[Native]`**\n: The `Native` attribute may be specified for an empty struct declaration to\n provide a nominal bridge between Mojo IPC and legacy `IPC::ParamTraits` or\n `IPC_STRUCT_TRAITS*` macros.\n See\n [Repurposing Legacy IPC Traits](/docs/mojo_ipc_conversion.md#repurposing-and-invocations)\n for more details. Note support for this attribute is strictly limited to C++\n bindings generation.\n\n**`[MinVersion=N]`**\n: The `MinVersion` attribute is used to specify the version at which a given\n field, enum value, interface method, or method parameter was introduced.\n See [Versioning](#Versioning) for more details.\n\n**`[EnableIf=value]`**\n: The `EnableIf` attribute is used to conditionally enable definitions when\n the mojom is parsed. If the `mojom` target in the GN file does not include\n the matching `value` in the list of `enabled_features`, the definition\n will be disabled. This is useful for mojom definitions that only make\n sense on one platform. Note that the `EnableIf` attribute can only be set\n once per definition.\n\n## Generated Code For Target Languages\n\nWhen the bindings generator successfully processes an input Mojom file, it emits\ncorresponding code for each supported target language. For more details on how\nMojom concepts translate to a given target langauge, please refer to the\nbindings API documentation for that language:\n\n* [C++ Bindings](/mojo/public/cpp/bindings/README.md)\n* [JavaScript Bindings](/mojo/public/js/README.md)\n* [Java Bindings](/mojo/public/java/bindings/README.md)\n\n## Message Validation\n\nRegardless of target language, all interface messages are validated during\ndeserialization before they are dispatched to a receiving implementation of the\ninterface. This helps to ensure consitent validation across interfaces without\nleaving the burden to developers and security reviewers every time a new message\nis added.\n\nIf a message fails validation, it is never dispatched. Instead a **connection\nerror** is raised on the binding object (see\n[C++ Connection Errors](/mojo/public/cpp/bindings/README.md#Connection-Errors),\n[Java Connection Errors](/mojo/public/java/bindings/README.md#Connection-Errors),\nor\n[JavaScript Connection Errors](/mojo/public/js/README.md#Connection-Errors) for\ndetails.)\n\nSome baseline level of validation is done automatically for primitive Mojom\ntypes.\n\n### Non-Nullable Objects\n\nMojom fields or parameter values (*e.g.*, structs, interfaces, arrays, *etc.*)\nmay be marked nullable in Mojom definitions (see\n[Primitive Types](#Primitive-Types).) If a field or parameter is **not** marked\nnullable but a message is received with a null value in its place, that message\nwill fail validation.\n\n### Enums\n\nEnums declared in Mojom are automatically validated against the range of legal\nvalues. For example if a Mojom declares the enum:\n\n``` cpp\nenum AdvancedBoolean {\n TRUE = 0,\n FALSE = 1,\n FILE_NOT_FOUND = 2,\n};\n```\n\nand a message is received with the integral value 3 (or anything other than 0,\n1, or 2) in place of some `AdvancedBoolean` field or parameter, the message will\nfail validation.\n\n*** note\nNOTE: It's possible to avoid this type of validation error by explicitly marking\nan enum as [Extensible](#Attributes) if you anticipate your enum being exchanged\nbetween two different versions of the binding interface. See\n[Versioning](#Versioning).\n***\n\n### Other failures\n\nThere are a host of internal validation errors that may occur when a malformed\nmessage is received, but developers should not be concerned with these\nspecifically; in general they can only result from internal bindings bugs,\ncompromised processes, or some remote endpoint making a dubious effort to\nmanually encode their own bindings messages.\n\n### Custom Validation\n\nIt's also possible for developers to define custom validation logic for specific\nMojom struct types by exploiting the\n[type mapping](/mojo/public/cpp/bindings/README.md#Type-Mapping) system for C++\nbindings. Messages rejected by custom validation logic trigger the same\nvalidation failure behavior as the built-in type validation routines.\n\n## Associated Interfaces\n\nAs mentioned in the [Primitive Types](#Primitive-Types) section above, pending_remote\nand pending_receiver fields and parameters may be marked as `associated`. This\nessentially means that they are piggy-backed on some other interface's message\npipe.\n\nBecause individual interface message pipes operate independently there can be no\nrelative ordering guarantees among them. Associated interfaces are useful when\none interface needs to guarantee strict FIFO ordering with respect to one or\nmore other interfaces, as they allow interfaces to share a single pipe.\n\nCurrently associated interfaces are only supported in generated C++ bindings.\nSee the documentation for\n[C++ Associated Interfaces](/mojo/public/cpp/bindings/README.md#Associated-Interfaces).\n\n## Versioning\n\n### Overview\n\n*** note\n**NOTE:** You don't need to worry about versioning if you don't care about\nbackwards compatibility. Specifically, all parts of Chrome are updated\natomically today and there is not yet any possibility of any two Chrome\nprocesses communicating with two different versions of any given Mojom\ninterface.\n***\n\nServices extend their interfaces to support new features over time, and clients\nwant to use those new features when they are available. If services and clients\nare not updated at the same time, it's important for them to be able to\ncommunicate with each other using different snapshots (versions) of their\ninterfaces.\n\nThis document shows how to extend Mojom interfaces in a backwards-compatible\nway. Changing interfaces in a non-backwards-compatible way is not discussed,\nbecause in that case communication between different interface versions is\nimpossible anyway.\n\n### Versioned Structs\n\nYou can use the `MinVersion` [attribute](#Attributes) to indicate from which\nversion a struct field is introduced. Assume you have the following struct:\n\n``` cpp\nstruct Employee {\n uint64 employee_id;\n string name;\n};\n```\n\nand you would like to add a birthday field. You can do:\n\n``` cpp\nstruct Employee {\n uint64 employee_id;\n string name;\n [MinVersion=1] Date? birthday;\n};\n```\n\nBy default, fields belong to version 0. New fields must be appended to the\nstruct definition (*i.e*., existing fields must not change **ordinal value**)\nwith the `MinVersion` attribute set to a number greater than any previous\nexisting versions.\n\n*** note\n**NOTE:** do not change existing fields in versioned structs, as this is\nnot backwards-compatible. Instead, rename the old field to make its\ndeprecation clear and add a new field with the new version number.\n***\n\n**Ordinal value** refers to the relative positional layout of a struct's fields\n(and an interface's methods) when encoded in a message. Implicitly, ordinal\nnumbers are assigned to fields according to lexical position. In the example\nabove, `employee_id` has an ordinal value of 0 and `name` has an ordinal value\nof 1.\n\nOrdinal values can be specified explicitly using `**@**` notation, subject to\nthe following hard constraints:\n\n* For any given struct or interface, if any field or method explicitly specifies\n an ordinal value, all fields or methods must explicitly specify an ordinal\n value.\n* For an *N*-field struct or *N*-method interface, the set of explicitly\n assigned ordinal values must be limited to the range *[0, N-1]*.\n\nYou may reorder fields, but you must ensure that the ordinal values of existing\nfields remain unchanged. For example, the following struct remains\nbackwards-compatible:\n\n``` cpp\nstruct Employee {\n uint64 employee_id@0;\n [MinVersion=1] Date? birthday@2;\n string name@1;\n};\n```\n\n*** note\n**NOTE:** Newly added fields of Mojo object or handle types MUST be nullable.\nSee [Primitive Types](#Primitive-Types).\n***\n\n### Versioned Interfaces\n\nThere are two dimensions on which an interface can be extended\n\n**Appending New Parameters To Existing Methods**\n: Parameter lists are treated as structs internally, so all the rules of\n versioned structs apply to method parameter lists. The only difference is\n that the version number is scoped to the whole interface rather than to any\n individual parameter list.\n\n Please note that adding a response to a message which did not previously\n expect a response is a not a backwards-compatible change.\n\n**Appending New Methods**\n: Similarly, you can reorder methods with explicit ordinal values as long as\n the ordinal values of existing methods are unchanged.\n\nFor example:\n\n``` cpp\n// Old version:\ninterface HumanResourceDatabase {\n AddEmployee(Employee employee) => (bool success);\n QueryEmployee(uint64 id) => (Employee? employee);\n};\n\n// New version:\ninterface HumanResourceDatabase {\n AddEmployee(Employee employee) => (bool success);\n\n QueryEmployee(uint64 id, [MinVersion=1] bool retrieve_finger_print)\n => (Employee? employee,\n [MinVersion=1] array? finger_print);\n\n [MinVersion=1]\n AttachFingerPrint(uint64 id, array finger_print)\n => (bool success);\n};\n```\n\nSimilar to [versioned structs](#Versioned-Structs), when you pass the parameter\nlist of a request or response method to a destination using an older version of\nan interface, unrecognized fields are silently discarded. However, if the method\ncall itself is not recognized, it is considered a validation error and the\nreceiver will close its end of the interface pipe. For example, if a client on\nversion 1 of the above interface sends an `AttachFingerPrint` request to an\nimplementation of version 0, the client will be disconnected.\n\nBindings target languages that support versioning expose means to query or\nassert the remote version from a client handle (*e.g.*, an\n`mojo::Remote` in C++ bindings.)\n\nSee\n[C++ Versioning Considerations](/mojo/public/cpp/bindings/README.md#Versioning-Considerations)\nand\n[Java Versioning Considerations](/mojo/public/java/bindings/README.md#Versioning-Considerations)\n\n### Versioned Enums\n\n**By default, enums are non-extensible**, which means that generated message\nvalidation code does not expect to see new values in the future. When an unknown\nvalue is seen for a non-extensible enum field or parameter, a validation error\nis raised.\n\nIf you want an enum to be extensible in the future, you can apply the\n`[Extensible]` [attribute](#Attributes):\n\n``` cpp\n[Extensible]\nenum Department {\n SALES,\n DEV,\n};\n```\n\nAnd later you can extend this enum without breaking backwards compatibility:\n\n``` cpp\n[Extensible]\nenum Department {\n SALES,\n DEV,\n [MinVersion=1] RESEARCH,\n};\n```\n\n*** note\n**NOTE:** For versioned enum definitions, the use of a `[MinVersion]` attribute\nis strictly for documentation purposes. It has no impact on the generated code.\n***\n\nWith extensible enums, bound interface implementations may receive unknown enum\nvalues and will need to deal with them gracefully. See\n[C++ Versioning Considerations](/mojo/public/cpp/bindings/README.md#Versioning-Considerations)\nfor details.\n\n## Grammar Reference\n\nBelow is the (BNF-ish) context-free grammar of the Mojom language:\n\n```\nMojomFile = StatementList\nStatementList = Statement StatementList | Statement\nStatement = ModuleStatement | ImportStatement | Definition\n\nModuleStatement = AttributeSection \"module\" Identifier \";\"\nImportStatement = \"import\" StringLiteral \";\"\nDefinition = Struct Union Interface Enum Const\n\nAttributeSection = | \"[\" AttributeList \"]\"\nAttributeList = | NonEmptyAttributeList\nNonEmptyAttributeList = Attribute\n | Attribute \",\" NonEmptyAttributeList\nAttribute = Name\n | Name \"=\" Name\n | Name \"=\" Literal\n\nStruct = AttributeSection \"struct\" Name \"{\" StructBody \"}\" \";\"\n | AttributeSection \"struct\" Name \";\"\nStructBody = \n | StructBody Const\n | StructBody Enum\n | StructBody StructField\nStructField = AttributeSection TypeSpec Name Ordinal Default \";\"\n\nUnion = AttributeSection \"union\" Name \"{\" UnionBody \"}\" \";\"\nUnionBody = | UnionBody UnionField\nUnionField = AttributeSection TypeSpec Name Ordinal \";\"\n\nInterface = AttributeSection \"interface\" Name \"{\" InterfaceBody \"}\" \";\"\nInterfaceBody = \n | InterfaceBody Const\n | InterfaceBody Enum\n | InterfaceBody Method\nMethod = AttributeSection Name Ordinal \"(\" ParamterList \")\" Response \";\"\nParameterList = | NonEmptyParameterList\nNonEmptyParameterList = Parameter\n | Parameter \",\" NonEmptyParameterList\nParameter = AttributeSection TypeSpec Name Ordinal\nResponse = | \"=>\" \"(\" ParameterList \")\"\n\nTypeSpec = TypeName \"?\" | TypeName\nTypeName = BasicTypeName\n | Array\n | FixedArray\n | Map\n | InterfaceRequest\nBasicTypeName = Identifier | \"associated\" Identifier | HandleType | NumericType\nNumericType = \"bool\" | \"int8\" | \"uint8\" | \"int16\" | \"uint16\" | \"int32\"\n | \"uint32\" | \"int64\" | \"uint64\" | \"float\" | \"double\"\nHandleType = \"handle\" | \"handle\" \"<\" SpecificHandleType \">\"\nSpecificHandleType = \"message_pipe\"\n | \"shared_buffer\"\n | \"data_pipe_consumer\"\n | \"data_pipe_producer\"\nArray = \"array\" \"<\" TypeSpec \">\"\nFixedArray = \"array\" \"<\" TypeSpec \",\" IntConstDec \">\"\nMap = \"map\" \"<\" Identifier \",\" TypeSpec \">\"\nInterfaceRequest = Identifier \"&\" | \"associated\" Identifier \"&\"\n\nOrdinal = | OrdinalValue\n\nDefault = | \"=\" Constant\n\nEnum = AttributeSection \"enum\" Name \"{\" NonEmptyEnumValueList \"}\" \";\"\n | AttributeSection \"enum\" Name \"{\" NonEmptyEnumValueList \",\" \"}\" \";\"\nNonEmptyEnumValueList = EnumValue | NonEmptyEnumValueList \",\" EnumValue\nEnumValue = AttributeSection Name\n | AttributeSection Name \"=\" Integer\n | AttributeSection Name \"=\" Identifier\n\nConst = \"const\" TypeSpec Name \"=\" Constant \";\"\n\nConstant = Literal | Identifier \";\"\n\nIdentifier = Name | Name \".\" Identifier\n\nLiteral = Integer | Float | \"true\" | \"false\" | \"default\" | StringLiteral\n\nInteger = IntConst | \"+\" IntConst | \"-\" IntConst\nIntConst = IntConstDec | IntConstHex\n\nFloat = FloatConst | \"+\" FloatConst | \"-\" FloatConst\n\n; The rules below are for tokens matched strictly according to the given regexes\n\nIdentifier = /[a-zA-Z_][0-9a-zA-Z_]*/\nIntConstDec = /0|(1-9[0-9]*)/\nIntConstHex = /0[xX][0-9a-fA-F]+/\nOrdinalValue = /@(0|(1-9[0-9]*))/\nFloatConst = ... # Imagine it's close enough to C-style float syntax.\nStringLiteral = ... # Imagine it's close enough to C-style string literals, including escapes.\n```\n\n## Additional Documentation\n\n[Mojom Message Format](https://docs.google.com/document/d/13pv9cFh5YKuBggDBQ1-AL8VReF-IYpFOFpRfvWFrwio/edit)\n: Describes the wire format used by Mojo bindings interfaces over message\n pipes.\n\n[Input Format of Mojom Message Validation Tests](https://docs.google.com/document/d/1-y-2IYctyX2NPaLxJjpJfzVNWCC2SR2MJAD9MpIytHQ/edit)\n: Describes a text format used to facilitate bindings message validation\n tests.\n","code/tools/dbg/pe_debug/msft_pdb/readme.md":"Those files are taken from the official Microsoft PDB repository\n\nhttps://github.com/Microsoft/microsoft-pdb"},"files":{"code/tools/README.md":"# `tools/`\nCitizenFX build infrastructure.\n\n* [**build/**](./build): Premake5 build tool helpers.\n* [**ci/**](./ci): CI scripts. Confused about the build process? Look here.\n* [**dbg/**](./dbg): Wrappers for adding debug info to game clients.\n* [**ext/**](./ext): External data.\n* [**idl/**](./idl): `xpidl` fork.","vendor/chromium/mojo/public/tools/bindings/README.md":"# Mojom Interface Definition Language (IDL)\nThis document is a subset of the [Mojo documentation](/mojo/README.md).\n\n[TOC]\n\n## Overview\n\nMojom is the IDL for Mojo interfaces. Given a `.mojom` file, the\n[bindings\ngenerator](https://cs.chromium.org/chromium/src/mojo/public/tools/bindings/) can\noutput bindings for any supported language: **C++**, **JavaScript**, or\n**Java**.\n\nFor a trivial example consider the following hypothetical Mojom file we write to\n`//services/widget/public/mojom/frobinator.mojom`:\n\n```\nmodule widget.mojom;\n\ninterface Frobinator {\n Frobinate();\n};\n```\n\nThis defines a single [interface](#Interfaces) named `Frobinator` in a\n[module](#Modules) named `widget.mojom` (and thus fully qualified in Mojom as\n`widget.mojom.Frobinator`.) Note that many interfaces and/or other types of\ndefinitions (structs, enums, *etc.*) may be included in a single Mojom file.\n\nIf we add a corresponding GN target to\n`//services/widget/public/mojom/BUILD.gn`:\n\n```\nimport(\"mojo/public/tools/bindings/mojom.gni\")\n\nmojom(\"mojom\") {\n sources = [\n \"frobinator.mojom\",\n ]\n}\n```\n\nand then build this target:\n\n```\nninja -C out/r services/widget/public/mojom\n```\n\nwe'll find several generated sources in our output directory:\n\n```\nout/r/gen/services/widget/public/mojom/frobinator.mojom.cc\nout/r/gen/services/widget/public/mojom/frobinator.mojom.h\nout/r/gen/services/widget/public/mojom/frobinator.mojom-shared.h\netc...\n```\n\nEach of these generated source modules includes a set of definitions\nrepresenting the Mojom contents in C++. You can also build or depend on suffixed\ntarget names to get bindings for other languages. For example,\n\n```\nninja -C out/r services/widget/public/mojom:mojom_js\nninja -C out/r services/widget/public/mojom:mojom_java\n```\n\nwould generate JavaScript and Java bindings respectively, in the same generated\noutput directory.\n\nFor more details regarding the generated\noutputs please see\n[documentation for individual target languages](#Generated-Code-For-Target-Languages).\n\n## Mojom Syntax\n\nMojom IDL allows developers to define **structs**, **unions**, **interfaces**,\n**constants**, and **enums**, all within the context of a **module**. These\ndefinitions are used to generate code in the supported target languages at build\ntime.\n\nMojom files may **import** other Mojom files in order to reference their\ndefinitions.\n\n### Primitive Types\nMojom supports a few basic data types which may be composed into structs or used\nfor message parameters.\n\n| Type | Description\n|-------------------------------|-------------------------------------------------------|\n| `bool` | Boolean type (`true` or `false`.)\n| `int8`, `uint8` | Signed or unsigned 8-bit integer.\n| `int16`, `uint16` | Signed or unsigned 16-bit integer.\n| `int32`, `uint32` | Signed or unsigned 32-bit integer.\n| `int64`, `uint64` | Signed or unsigned 64-bit integer.\n| `float`, `double` | 32- or 64-bit floating point number.\n| `string` | UTF-8 encoded string.\n| `array` | Array of any Mojom type *T*; for example, `array` or `array>`.\n| `array` | Fixed-length array of any Mojom type *T*. The parameter *N* must be an integral constant.\n| `map` | Associated array maping values of type *S* to values of type *T*. *S* may be a `string`, `enum`, or numeric type.\n| `handle` | Generic Mojo handle. May be any type of handle, including a wrapped native platform handle.\n| `handle` | Generic message pipe handle.\n| `handle` | Shared buffer handle.\n| `handle` | Data pipe producer handle.\n| `handle` | Data pipe consumer handle.\n| *`pending_remote`* | 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.\n| *`pending_receiver`* | A pending receiver 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.\n| *`pending_associated_remote`* | An associated interface handle. See [Associated Interfaces](#Associated-Interfaces)\n| *`pending_associated_receiver`* | A pending associated receiver. See [Associated Interfaces](#Associated-Interfaces)\n| *T*? | An optional (nullable) value. Primitive numeric types (integers, floats, booleans, and enums) are not nullable. All other types are nullable.\n\n### Modules\n\nEvery Mojom file may optionally specify a single **module** to which it belongs.\n\nThis is used strictly for aggregaging all defined symbols therein within a\ncommon Mojom namespace. The specific impact this has on generated binidngs code\nvaries for each target language. For example, if the following Mojom is used to\ngenerate bindings:\n\n```\nmodule business.stuff;\n\ninterface MoneyGenerator {\n GenerateMoney();\n};\n```\n\nGenerated C++ bindings will define a class interface `MoneyGenerator` in the\n`business::stuff` namespace, while Java bindings will define an interface\n`MoneyGenerator` in the `org.chromium.business.stuff` package. JavaScript\nbindings at this time are unaffected by module declarations.\n\n**NOTE:** By convention in the Chromium codebase, **all** Mojom files should\ndeclare a module name with at least (and preferrably exactly) one top-level name\nas well as an inner `mojom` module suffix. *e.g.*, `chrome.mojom`,\n`business.mojom`, *etc.*\n\nThis convention makes it easy to tell which symbols are generated by Mojom when\nreading non-Mojom code, and it also avoids namespace collisions in the fairly\ncommon scenario where you have a real C++ or Java `Foo` along with a\ncorresponding Mojom `Foo` for its serialized representation.\n\n### Imports\n\nIf your Mojom references definitions from other Mojom files, you must **import**\nthose files. Import syntax is as follows:\n\n```\nimport \"services/widget/public/mojom/frobinator.mojom\";\n```\n\nImport paths are always relative to the top-level directory.\n\nNote that circular imports are **not** supported.\n\n### Structs\n\nStructs are defined using the **struct** keyword, and they provide a way to\ngroup related fields together:\n\n``` cpp\nstruct StringPair {\n string first;\n string second;\n};\n```\n\nStruct fields may be comprised of any of the types listed above in the\n[Primitive Types](#Primitive-Types) section.\n\nDefault values may be specified as long as they are constant:\n\n``` cpp\nstruct Request {\n int32 id = -1;\n string details;\n};\n```\n\nWhat follows is a fairly\ncomprehensive example using the supported field types:\n\n``` cpp\nstruct StringPair {\n string first;\n string second;\n};\n\nenum AnEnum {\n YES,\n NO\n};\n\ninterface SampleInterface {\n DoStuff();\n};\n\nstruct AllTheThings {\n // Note that these types can never be marked nullable!\n bool boolean_value;\n int8 signed_8bit_value = 42;\n uint8 unsigned_8bit_value;\n int16 signed_16bit_value;\n uint16 unsigned_16bit_value;\n int32 signed_32bit_value;\n uint32 unsigned_32bit_value;\n int64 signed_64bit_value;\n uint64 unsigned_64bit_value;\n float float_value_32bit;\n double float_value_64bit;\n AnEnum enum_value = AnEnum.YES;\n\n // Strings may be nullable.\n string? maybe_a_string_maybe_not;\n\n // Structs may contain other structs. These may also be nullable.\n StringPair some_strings;\n StringPair? maybe_some_more_strings;\n\n // In fact structs can also be nested, though in practice you must always make\n // such fields nullable -- otherwise messages would need to be infinitely long\n // in order to pass validation!\n AllTheThings? more_things;\n\n // Arrays may be templated over any Mojom type, and are always nullable:\n array numbers;\n array? maybe_more_numbers;\n\n // Arrays of arrays of arrays... are fine.\n array>> this_works_but_really_plz_stop;\n\n // The element type may be nullable if it's a type which is allowed to be\n // nullable.\n array more_maybe_things;\n\n // Fixed-size arrays get some extra validation on the receiving end to ensure\n // that the correct number of elements is always received.\n array uuid;\n\n // Maps follow many of the same rules as arrays. Key types may be any\n // non-handle, non-collection type, and value types may be any supported\n // struct field type. Maps may also be nullable.\n map one_map;\n map? maybe_another_map;\n map? maybe_a_pretty_weird_but_valid_map;\n map?>?>?> ridiculous;\n\n // And finally, all handle types are valid as struct fields and may be\n // nullable. Note that interfaces and interface requests (the \"Foo\" and\n // \"Foo&\" type syntax respectively) are just strongly-typed message pipe\n // handles.\n handle generic_handle;\n handle reader;\n handle? maybe_writer;\n handle dumping_ground;\n handle raw_message_pipe;\n pending_remote? maybe_a_sample_interface_client_pipe;\n pending_receiver non_nullable_sample_pending_receiver;\n pending_receiver? nullable_sample_pending_receiver;\n pending_associated_remote associated_interface_client;\n pending_associated_receiver associated_pending_receiver;\n pending_associated_receiver? maybe_another_pending_receiver;\n};\n```\n\nFor details on how all of these different types translate to usable generated\ncode, see\n[documentation for individual target languages](#Generated-Code-For-Target-Languages).\n\n### Unions\n\nMojom supports tagged unions using the **union** keyword. A union is a\ncollection of fields which may taken the value of any single one of those fields\nat a time. Thus they provide a way to represent a variant value type while\nminimizing storage requirements.\n\nUnion fields may be of any type supported by [struct](#Structs) fields. For\nexample:\n\n```cpp\nunion ExampleUnion {\n string str;\n StringPair pair;\n int64 id;\n array guid;\n SampleInterface iface;\n};\n```\n\nFor details on how unions like this translate to generated bindings code, see\n[documentation for individual target languages](#Generated-Code-For-Target-Languages).\n\n### Enumeration Types\n\nEnumeration types may be defined using the **enum** keyword either directly\nwithin a module or nested within the namespace of some struct or interface:\n\n```\nmodule business.mojom;\n\nenum Department {\n SALES = 0,\n DEV,\n};\n\nstruct Employee {\n enum Type {\n FULL_TIME,\n PART_TIME,\n };\n\n Type type;\n // ...\n};\n```\n\nSimilar to C-style enums, individual values may be explicitly assigned within an\nenum definition. By default, values are based at zero and increment by\n1 sequentially.\n\nThe effect of nested definitions on generated bindings varies depending on the\ntarget language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages)\n\n### Constants\n\nConstants may be defined using the **const** keyword either directly within a\nmodule or nested within the namespace of some struct or interface:\n\n```\nmodule business.mojom;\n\nconst string kServiceName = \"business\";\n\nstruct Employee {\n const uint64 kInvalidId = 0;\n\n enum Type {\n FULL_TIME,\n PART_TIME,\n };\n\n uint64 id = kInvalidId;\n Type type;\n};\n```\n\nThe effect of nested definitions on generated bindings varies depending on the\ntarget language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages)\n\n### Interfaces\n\nAn **interface** is a logical bundle of parameterized request messages. Each\nrequest message may optionally define a parameterized response message. Here's\nan example to define an interface `Foo` with various kinds of requests:\n\n```\ninterface Foo {\n // A request which takes no arguments and expects no response.\n MyMessage();\n\n // A request which has some arguments and expects no response.\n MyOtherMessage(string name, array bytes);\n\n // A request which expects a single-argument response.\n MyMessageWithResponse(string command) => (bool success);\n\n // A request which expects a response with multiple arguments.\n MyMessageWithMoarResponse(string a, string b) => (int8 c, int8 d);\n};\n```\n\nAnything which is a valid struct field type (see [Structs](#Structs)) is also a\nvalid request or response argument type. The type notation is the same for both.\n\n### Attributes\n\nMojom definitions may have their meaning altered by **attributes**, specified\nwith a syntax similar to Java or C# attributes. There are a handle of\ninteresting attributes supported today.\n\n**`[Sync]`**\n: The `Sync` attribute may be specified for any interface method which expects\n a response. This makes it so that callers of the method can wait\n synchronously for a response. See\n [Synchronous Calls](/mojo/public/cpp/bindings/README.md#Synchronous-Calls)\n in the C++ bindings documentation. Note that sync calls are not currently\n supported in other target languages.\n\n**`[Extensible]`**\n: The `Extensible` attribute may be specified for any enum definition. This\n essentially disables builtin range validation when receiving values of the\n enum type in a message, allowing older bindings to tolerate unrecognized\n values from newer versions of the enum.\n\n**`[Native]`**\n: The `Native` attribute may be specified for an empty struct declaration to\n provide a nominal bridge between Mojo IPC and legacy `IPC::ParamTraits` or\n `IPC_STRUCT_TRAITS*` macros.\n See\n [Repurposing Legacy IPC Traits](/docs/mojo_ipc_conversion.md#repurposing-and-invocations)\n for more details. Note support for this attribute is strictly limited to C++\n bindings generation.\n\n**`[MinVersion=N]`**\n: The `MinVersion` attribute is used to specify the version at which a given\n field, enum value, interface method, or method parameter was introduced.\n See [Versioning](#Versioning) for more details.\n\n**`[EnableIf=value]`**\n: The `EnableIf` attribute is used to conditionally enable definitions when\n the mojom is parsed. If the `mojom` target in the GN file does not include\n the matching `value` in the list of `enabled_features`, the definition\n will be disabled. This is useful for mojom definitions that only make\n sense on one platform. Note that the `EnableIf` attribute can only be set\n once per definition.\n\n## Generated Code For Target Languages\n\nWhen the bindings generator successfully processes an input Mojom file, it emits\ncorresponding code for each supported target language. For more details on how\nMojom concepts translate to a given target langauge, please refer to the\nbindings API documentation for that language:\n\n* [C++ Bindings](/mojo/public/cpp/bindings/README.md)\n* [JavaScript Bindings](/mojo/public/js/README.md)\n* [Java Bindings](/mojo/public/java/bindings/README.md)\n\n## Message Validation\n\nRegardless of target language, all interface messages are validated during\ndeserialization before they are dispatched to a receiving implementation of the\ninterface. This helps to ensure consitent validation across interfaces without\nleaving the burden to developers and security reviewers every time a new message\nis added.\n\nIf a message fails validation, it is never dispatched. Instead a **connection\nerror** is raised on the binding object (see\n[C++ Connection Errors](/mojo/public/cpp/bindings/README.md#Connection-Errors),\n[Java Connection Errors](/mojo/public/java/bindings/README.md#Connection-Errors),\nor\n[JavaScript Connection Errors](/mojo/public/js/README.md#Connection-Errors) for\ndetails.)\n\nSome baseline level of validation is done automatically for primitive Mojom\ntypes.\n\n### Non-Nullable Objects\n\nMojom fields or parameter values (*e.g.*, structs, interfaces, arrays, *etc.*)\nmay be marked nullable in Mojom definitions (see\n[Primitive Types](#Primitive-Types).) If a field or parameter is **not** marked\nnullable but a message is received with a null value in its place, that message\nwill fail validation.\n\n### Enums\n\nEnums declared in Mojom are automatically validated against the range of legal\nvalues. For example if a Mojom declares the enum:\n\n``` cpp\nenum AdvancedBoolean {\n TRUE = 0,\n FALSE = 1,\n FILE_NOT_FOUND = 2,\n};\n```\n\nand a message is received with the integral value 3 (or anything other than 0,\n1, or 2) in place of some `AdvancedBoolean` field or parameter, the message will\nfail validation.\n\n*** note\nNOTE: It's possible to avoid this type of validation error by explicitly marking\nan enum as [Extensible](#Attributes) if you anticipate your enum being exchanged\nbetween two different versions of the binding interface. See\n[Versioning](#Versioning).\n***\n\n### Other failures\n\nThere are a host of internal validation errors that may occur when a malformed\nmessage is received, but developers should not be concerned with these\nspecifically; in general they can only result from internal bindings bugs,\ncompromised processes, or some remote endpoint making a dubious effort to\nmanually encode their own bindings messages.\n\n### Custom Validation\n\nIt's also possible for developers to define custom validation logic for specific\nMojom struct types by exploiting the\n[type mapping](/mojo/public/cpp/bindings/README.md#Type-Mapping) system for C++\nbindings. Messages rejected by custom validation logic trigger the same\nvalidation failure behavior as the built-in type validation routines.\n\n## Associated Interfaces\n\nAs mentioned in the [Primitive Types](#Primitive-Types) section above, pending_remote\nand pending_receiver fields and parameters may be marked as `associated`. This\nessentially means that they are piggy-backed on some other interface's message\npipe.\n\nBecause individual interface message pipes operate independently there can be no\nrelative ordering guarantees among them. Associated interfaces are useful when\none interface needs to guarantee strict FIFO ordering with respect to one or\nmore other interfaces, as they allow interfaces to share a single pipe.\n\nCurrently associated interfaces are only supported in generated C++ bindings.\nSee the documentation for\n[C++ Associated Interfaces](/mojo/public/cpp/bindings/README.md#Associated-Interfaces).\n\n## Versioning\n\n### Overview\n\n*** note\n**NOTE:** You don't need to worry about versioning if you don't care about\nbackwards compatibility. Specifically, all parts of Chrome are updated\natomically today and there is not yet any possibility of any two Chrome\nprocesses communicating with two different versions of any given Mojom\ninterface.\n***\n\nServices extend their interfaces to support new features over time, and clients\nwant to use those new features when they are available. If services and clients\nare not updated at the same time, it's important for them to be able to\ncommunicate with each other using different snapshots (versions) of their\ninterfaces.\n\nThis document shows how to extend Mojom interfaces in a backwards-compatible\nway. Changing interfaces in a non-backwards-compatible way is not discussed,\nbecause in that case communication between different interface versions is\nimpossible anyway.\n\n### Versioned Structs\n\nYou can use the `MinVersion` [attribute](#Attributes) to indicate from which\nversion a struct field is introduced. Assume you have the following struct:\n\n``` cpp\nstruct Employee {\n uint64 employee_id;\n string name;\n};\n```\n\nand you would like to add a birthday field. You can do:\n\n``` cpp\nstruct Employee {\n uint64 employee_id;\n string name;\n [MinVersion=1] Date? birthday;\n};\n```\n\nBy default, fields belong to version 0. New fields must be appended to the\nstruct definition (*i.e*., existing fields must not change **ordinal value**)\nwith the `MinVersion` attribute set to a number greater than any previous\nexisting versions.\n\n*** note\n**NOTE:** do not change existing fields in versioned structs, as this is\nnot backwards-compatible. Instead, rename the old field to make its\ndeprecation clear and add a new field with the new version number.\n***\n\n**Ordinal value** refers to the relative positional layout of a struct's fields\n(and an interface's methods) when encoded in a message. Implicitly, ordinal\nnumbers are assigned to fields according to lexical position. In the example\nabove, `employee_id` has an ordinal value of 0 and `name` has an ordinal value\nof 1.\n\nOrdinal values can be specified explicitly using `**@**` notation, subject to\nthe following hard constraints:\n\n* For any given struct or interface, if any field or method explicitly specifies\n an ordinal value, all fields or methods must explicitly specify an ordinal\n value.\n* For an *N*-field struct or *N*-method interface, the set of explicitly\n assigned ordinal values must be limited to the range *[0, N-1]*.\n\nYou may reorder fields, but you must ensure that the ordinal values of existing\nfields remain unchanged. For example, the following struct remains\nbackwards-compatible:\n\n``` cpp\nstruct Employee {\n uint64 employee_id@0;\n [MinVersion=1] Date? birthday@2;\n string name@1;\n};\n```\n\n*** note\n**NOTE:** Newly added fields of Mojo object or handle types MUST be nullable.\nSee [Primitive Types](#Primitive-Types).\n***\n\n### Versioned Interfaces\n\nThere are two dimensions on which an interface can be extended\n\n**Appending New Parameters To Existing Methods**\n: Parameter lists are treated as structs internally, so all the rules of\n versioned structs apply to method parameter lists. The only difference is\n that the version number is scoped to the whole interface rather than to any\n individual parameter list.\n\n Please note that adding a response to a message which did not previously\n expect a response is a not a backwards-compatible change.\n\n**Appending New Methods**\n: Similarly, you can reorder methods with explicit ordinal values as long as\n the ordinal values of existing methods are unchanged.\n\nFor example:\n\n``` cpp\n// Old version:\ninterface HumanResourceDatabase {\n AddEmployee(Employee employee) => (bool success);\n QueryEmployee(uint64 id) => (Employee? employee);\n};\n\n// New version:\ninterface HumanResourceDatabase {\n AddEmployee(Employee employee) => (bool success);\n\n QueryEmployee(uint64 id, [MinVersion=1] bool retrieve_finger_print)\n => (Employee? employee,\n [MinVersion=1] array? finger_print);\n\n [MinVersion=1]\n AttachFingerPrint(uint64 id, array finger_print)\n => (bool success);\n};\n```\n\nSimilar to [versioned structs](#Versioned-Structs), when you pass the parameter\nlist of a request or response method to a destination using an older version of\nan interface, unrecognized fields are silently discarded. However, if the method\ncall itself is not recognized, it is considered a validation error and the\nreceiver will close its end of the interface pipe. For example, if a client on\nversion 1 of the above interface sends an `AttachFingerPrint` request to an\nimplementation of version 0, the client will be disconnected.\n\nBindings target languages that support versioning expose means to query or\nassert the remote version from a client handle (*e.g.*, an\n`mojo::Remote` in C++ bindings.)\n\nSee\n[C++ Versioning Considerations](/mojo/public/cpp/bindings/README.md#Versioning-Considerations)\nand\n[Java Versioning Considerations](/mojo/public/java/bindings/README.md#Versioning-Considerations)\n\n### Versioned Enums\n\n**By default, enums are non-extensible**, which means that generated message\nvalidation code does not expect to see new values in the future. When an unknown\nvalue is seen for a non-extensible enum field or parameter, a validation error\nis raised.\n\nIf you want an enum to be extensible in the future, you can apply the\n`[Extensible]` [attribute](#Attributes):\n\n``` cpp\n[Extensible]\nenum Department {\n SALES,\n DEV,\n};\n```\n\nAnd later you can extend this enum without breaking backwards compatibility:\n\n``` cpp\n[Extensible]\nenum Department {\n SALES,\n DEV,\n [MinVersion=1] RESEARCH,\n};\n```\n\n*** note\n**NOTE:** For versioned enum definitions, the use of a `[MinVersion]` attribute\nis strictly for documentation purposes. It has no impact on the generated code.\n***\n\nWith extensible enums, bound interface implementations may receive unknown enum\nvalues and will need to deal with them gracefully. See\n[C++ Versioning Considerations](/mojo/public/cpp/bindings/README.md#Versioning-Considerations)\nfor details.\n\n## Grammar Reference\n\nBelow is the (BNF-ish) context-free grammar of the Mojom language:\n\n```\nMojomFile = StatementList\nStatementList = Statement StatementList | Statement\nStatement = ModuleStatement | ImportStatement | Definition\n\nModuleStatement = AttributeSection \"module\" Identifier \";\"\nImportStatement = \"import\" StringLiteral \";\"\nDefinition = Struct Union Interface Enum Const\n\nAttributeSection = | \"[\" AttributeList \"]\"\nAttributeList = | NonEmptyAttributeList\nNonEmptyAttributeList = Attribute\n | Attribute \",\" NonEmptyAttributeList\nAttribute = Name\n | Name \"=\" Name\n | Name \"=\" Literal\n\nStruct = AttributeSection \"struct\" Name \"{\" StructBody \"}\" \";\"\n | AttributeSection \"struct\" Name \";\"\nStructBody = \n | StructBody Const\n | StructBody Enum\n | StructBody StructField\nStructField = AttributeSection TypeSpec Name Ordinal Default \";\"\n\nUnion = AttributeSection \"union\" Name \"{\" UnionBody \"}\" \";\"\nUnionBody = | UnionBody UnionField\nUnionField = AttributeSection TypeSpec Name Ordinal \";\"\n\nInterface = AttributeSection \"interface\" Name \"{\" InterfaceBody \"}\" \";\"\nInterfaceBody = \n | InterfaceBody Const\n | InterfaceBody Enum\n | InterfaceBody Method\nMethod = AttributeSection Name Ordinal \"(\" ParamterList \")\" Response \";\"\nParameterList = | NonEmptyParameterList\nNonEmptyParameterList = Parameter\n | Parameter \",\" NonEmptyParameterList\nParameter = AttributeSection TypeSpec Name Ordinal\nResponse = | \"=>\" \"(\" ParameterList \")\"\n\nTypeSpec = TypeName \"?\" | TypeName\nTypeName = BasicTypeName\n | Array\n | FixedArray\n | Map\n | InterfaceRequest\nBasicTypeName = Identifier | \"associated\" Identifier | HandleType | NumericType\nNumericType = \"bool\" | \"int8\" | \"uint8\" | \"int16\" | \"uint16\" | \"int32\"\n | \"uint32\" | \"int64\" | \"uint64\" | \"float\" | \"double\"\nHandleType = \"handle\" | \"handle\" \"<\" SpecificHandleType \">\"\nSpecificHandleType = \"message_pipe\"\n | \"shared_buffer\"\n | \"data_pipe_consumer\"\n | \"data_pipe_producer\"\nArray = \"array\" \"<\" TypeSpec \">\"\nFixedArray = \"array\" \"<\" TypeSpec \",\" IntConstDec \">\"\nMap = \"map\" \"<\" Identifier \",\" TypeSpec \">\"\nInterfaceRequest = Identifier \"&\" | \"associated\" Identifier \"&\"\n\nOrdinal = | OrdinalValue\n\nDefault = | \"=\" Constant\n\nEnum = AttributeSection \"enum\" Name \"{\" NonEmptyEnumValueList \"}\" \";\"\n | AttributeSection \"enum\" Name \"{\" NonEmptyEnumValueList \",\" \"}\" \";\"\nNonEmptyEnumValueList = EnumValue | NonEmptyEnumValueList \",\" EnumValue\nEnumValue = AttributeSection Name\n | AttributeSection Name \"=\" Integer\n | AttributeSection Name \"=\" Identifier\n\nConst = \"const\" TypeSpec Name \"=\" Constant \";\"\n\nConstant = Literal | Identifier \";\"\n\nIdentifier = Name | Name \".\" Identifier\n\nLiteral = Integer | Float | \"true\" | \"false\" | \"default\" | StringLiteral\n\nInteger = IntConst | \"+\" IntConst | \"-\" IntConst\nIntConst = IntConstDec | IntConstHex\n\nFloat = FloatConst | \"+\" FloatConst | \"-\" FloatConst\n\n; The rules below are for tokens matched strictly according to the given regexes\n\nIdentifier = /[a-zA-Z_][0-9a-zA-Z_]*/\nIntConstDec = /0|(1-9[0-9]*)/\nIntConstHex = /0[xX][0-9a-fA-F]+/\nOrdinalValue = /@(0|(1-9[0-9]*))/\nFloatConst = ... # Imagine it's close enough to C-style float syntax.\nStringLiteral = ... # Imagine it's close enough to C-style string literals, including escapes.\n```\n\n## Additional Documentation\n\n[Mojom Message Format](https://docs.google.com/document/d/13pv9cFh5YKuBggDBQ1-AL8VReF-IYpFOFpRfvWFrwio/edit)\n: Describes the wire format used by Mojo bindings interfaces over message\n pipes.\n\n[Input Format of Mojom Message Validation Tests](https://docs.google.com/document/d/1-y-2IYctyX2NPaLxJjpJfzVNWCC2SR2MJAD9MpIytHQ/edit)\n: Describes a text format used to facilitate bindings message validation\n tests.\n","code/tools/dbg/pe_debug/msft_pdb/readme.md":"Those files are taken from the official Microsoft PDB repository\n\nhttps://github.com/Microsoft/microsoft-pdb"},"items":[{"name":"readme.md","path":"code/tools/dbg/pe_debug/msft_pdb/readme.md","rawUrl":"https://raw.githubusercontent.com/citizenfx/fivem/HEAD/code/tools/dbg/pe_debug/msft_pdb/readme.md","title":"msft_pdb Documentation","category":"plugin-manifest","format":"markdown","content":"Those files are taken from the official Microsoft PDB repository\n\nhttps://github.com/Microsoft/microsoft-pdb","isInternal":false,"tokens":22,"sizeBytes":108},{"name":"README.md","path":"code/tools/README.md","rawUrl":"https://raw.githubusercontent.com/citizenfx/fivem/HEAD/code/tools/README.md","title":"tools Documentation","category":"plugin-manifest","format":"markdown","content":"# `tools/`\nCitizenFX build infrastructure.\n\n* [**build/**](./build): Premake5 build tool helpers.\n* [**ci/**](./ci): CI scripts. Confused about the build process? Look here.\n* [**dbg/**](./dbg): Wrappers for adding debug info to game clients.\n* [**ext/**](./ext): External data.\n* [**idl/**](./idl): `xpidl` fork.","isInternal":false,"tokens":96,"sizeBytes":313},{"name":"README.md","path":"vendor/chromium/mojo/public/tools/bindings/README.md","rawUrl":"https://raw.githubusercontent.com/citizenfx/fivem/HEAD/vendor/chromium/mojo/public/tools/bindings/README.md","title":"bindings Documentation","category":"plugin-manifest","format":"markdown","content":"# Mojom Interface Definition Language (IDL)\nThis document is a subset of the [Mojo documentation](/mojo/README.md).\n\n[TOC]\n\n## Overview\n\nMojom is the IDL for Mojo interfaces. Given a `.mojom` file, the\n[bindings\ngenerator](https://cs.chromium.org/chromium/src/mojo/public/tools/bindings/) can\noutput bindings for any supported language: **C++**, **JavaScript**, or\n**Java**.\n\nFor a trivial example consider the following hypothetical Mojom file we write to\n`//services/widget/public/mojom/frobinator.mojom`:\n\n```\nmodule widget.mojom;\n\ninterface Frobinator {\n Frobinate();\n};\n```\n\nThis defines a single [interface](#Interfaces) named `Frobinator` in a\n[module](#Modules) named `widget.mojom` (and thus fully qualified in Mojom as\n`widget.mojom.Frobinator`.) Note that many interfaces and/or other types of\ndefinitions (structs, enums, *etc.*) may be included in a single Mojom file.\n\nIf we add a corresponding GN target to\n`//services/widget/public/mojom/BUILD.gn`:\n\n```\nimport(\"mojo/public/tools/bindings/mojom.gni\")\n\nmojom(\"mojom\") {\n sources = [\n \"frobinator.mojom\",\n ]\n}\n```\n\nand then build this target:\n\n```\nninja -C out/r services/widget/public/mojom\n```\n\nwe'll find several generated sources in our output directory:\n\n```\nout/r/gen/services/widget/public/mojom/frobinator.mojom.cc\nout/r/gen/services/widget/public/mojom/frobinator.mojom.h\nout/r/gen/services/widget/public/mojom/frobinator.mojom-shared.h\netc...\n```\n\nEach of these generated source modules includes a set of definitions\nrepresenting the Mojom contents in C++. You can also build or depend on suffixed\ntarget names to get bindings for other languages. For example,\n\n```\nninja -C out/r services/widget/public/mojom:mojom_js\nninja -C out/r services/widget/public/mojom:mojom_java\n```\n\nwould generate JavaScript and Java bindings respectively, in the same generated\noutput directory.\n\nFor more details regarding the generated\noutputs please see\n[documentation for individual target languages](#Generated-Code-For-Target-Languages).\n\n## Mojom Syntax\n\nMojom IDL allows developers to define **structs**, **unions**, **interfaces**,\n**constants**, and **enums**, all within the context of a **module**. These\ndefinitions are used to generate code in the supported target languages at build\ntime.\n\nMojom files may **import** other Mojom files in order to reference their\ndefinitions.\n\n### Primitive Types\nMojom supports a few basic data types which may be composed into structs or used\nfor message parameters.\n\n| Type | Description\n|-------------------------------|-------------------------------------------------------|\n| `bool` | Boolean type (`true` or `false`.)\n| `int8`, `uint8` | Signed or unsigned 8-bit integer.\n| `int16`, `uint16` | Signed or unsigned 16-bit integer.\n| `int32`, `uint32` | Signed or unsigned 32-bit integer.\n| `int64`, `uint64` | Signed or unsigned 64-bit integer.\n| `float`, `double` | 32- or 64-bit floating point number.\n| `string` | UTF-8 encoded string.\n| `array` | Array of any Mojom type *T*; for example, `array` or `array>`.\n| `array` | Fixed-length array of any Mojom type *T*. The parameter *N* must be an integral constant.\n| `map` | Associated array maping values of type *S* to values of type *T*. *S* may be a `string`, `enum`, or numeric type.\n| `handle` | Generic Mojo handle. May be any type of handle, including a wrapped native platform handle.\n| `handle` | Generic message pipe handle.\n| `handle` | Shared buffer handle.\n| `handle` | Data pipe producer handle.\n| `handle` | Data pipe consumer handle.\n| *`pending_remote`* | 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.\n| *`pending_receiver`* | A pending receiver 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.\n| *`pending_associated_remote`* | An associated interface handle. See [Associated Interfaces](#Associated-Interfaces)\n| *`pending_associated_receiver`* | A pending associated receiver. See [Associated Interfaces](#Associated-Interfaces)\n| *T*? | An optional (nullable) value. Primitive numeric types (integers, floats, booleans, and enums) are not nullable. All other types are nullable.\n\n### Modules\n\nEvery Mojom file may optionally specify a single **module** to which it belongs.\n\nThis is used strictly for aggregaging all defined symbols therein within a\ncommon Mojom namespace. The specific impact this has on generated binidngs code\nvaries for each target language. For example, if the following Mojom is used to\ngenerate bindings:\n\n```\nmodule business.stuff;\n\ninterface MoneyGenerator {\n GenerateMoney();\n};\n```\n\nGenerated C++ bindings will define a class interface `MoneyGenerator` in the\n`business::stuff` namespace, while Java bindings will define an interface\n`MoneyGenerator` in the `org.chromium.business.stuff` package. JavaScript\nbindings at this time are unaffected by module declarations.\n\n**NOTE:** By convention in the Chromium codebase, **all** Mojom files should\ndeclare a module name with at least (and preferrably exactly) one top-level name\nas well as an inner `mojom` module suffix. *e.g.*, `chrome.mojom`,\n`business.mojom`, *etc.*\n\nThis convention makes it easy to tell which symbols are generated by Mojom when\nreading non-Mojom code, and it also avoids namespace collisions in the fairly\ncommon scenario where you have a real C++ or Java `Foo` along with a\ncorresponding Mojom `Foo` for its serialized representation.\n\n### Imports\n\nIf your Mojom references definitions from other Mojom files, you must **import**\nthose files. Import syntax is as follows:\n\n```\nimport \"services/widget/public/mojom/frobinator.mojom\";\n```\n\nImport paths are always relative to the top-level directory.\n\nNote that circular imports are **not** supported.\n\n### Structs\n\nStructs are defined using the **struct** keyword, and they provide a way to\ngroup related fields together:\n\n``` cpp\nstruct StringPair {\n string first;\n string second;\n};\n```\n\nStruct fields may be comprised of any of the types listed above in the\n[Primitive Types](#Primitive-Types) section.\n\nDefault values may be specified as long as they are constant:\n\n``` cpp\nstruct Request {\n int32 id = -1;\n string details;\n};\n```\n\nWhat follows is a fairly\ncomprehensive example using the supported field types:\n\n``` cpp\nstruct StringPair {\n string first;\n string second;\n};\n\nenum AnEnum {\n YES,\n NO\n};\n\ninterface SampleInterface {\n DoStuff();\n};\n\nstruct AllTheThings {\n // Note that these types can never be marked nullable!\n bool boolean_value;\n int8 signed_8bit_value = 42;\n uint8 unsigned_8bit_value;\n int16 signed_16bit_value;\n uint16 unsigned_16bit_value;\n int32 signed_32bit_value;\n uint32 unsigned_32bit_value;\n int64 signed_64bit_value;\n uint64 unsigned_64bit_value;\n float float_value_32bit;\n double float_value_64bit;\n AnEnum enum_value = AnEnum.YES;\n\n // Strings may be nullable.\n string? maybe_a_string_maybe_not;\n\n // Structs may contain other structs. These may also be nullable.\n StringPair some_strings;\n StringPair? maybe_some_more_strings;\n\n // In fact structs can also be nested, though in practice you must always make\n // such fields nullable -- otherwise messages would need to be infinitely long\n // in order to pass validation!\n AllTheThings? more_things;\n\n // Arrays may be templated over any Mojom type, and are always nullable:\n array numbers;\n array? maybe_more_numbers;\n\n // Arrays of arrays of arrays... are fine.\n array>> this_works_but_really_plz_stop;\n\n // The element type may be nullable if it's a type which is allowed to be\n // nullable.\n array more_maybe_things;\n\n // Fixed-size arrays get some extra validation on the receiving end to ensure\n // that the correct number of elements is always received.\n array uuid;\n\n // Maps follow many of the same rules as arrays. Key types may be any\n // non-handle, non-collection type, and value types may be any supported\n // struct field type. Maps may also be nullable.\n map one_map;\n map? maybe_another_map;\n map? maybe_a_pretty_weird_but_valid_map;\n map?>?>?> ridiculous;\n\n // And finally, all handle types are valid as struct fields and may be\n // nullable. Note that interfaces and interface requests (the \"Foo\" and\n // \"Foo&\" type syntax respectively) are just strongly-typed message pipe\n // handles.\n handle generic_handle;\n handle reader;\n handle? maybe_writer;\n handle dumping_ground;\n handle raw_message_pipe;\n pending_remote? maybe_a_sample_interface_client_pipe;\n pending_receiver non_nullable_sample_pending_receiver;\n pending_receiver? nullable_sample_pending_receiver;\n pending_associated_remote associated_interface_client;\n pending_associated_receiver associated_pending_receiver;\n pending_associated_receiver? maybe_another_pending_receiver;\n};\n```\n\nFor details on how all of these different types translate to usable generated\ncode, see\n[documentation for individual target languages](#Generated-Code-For-Target-Languages).\n\n### Unions\n\nMojom supports tagged unions using the **union** keyword. A union is a\ncollection of fields which may taken the value of any single one of those fields\nat a time. Thus they provide a way to represent a variant value type while\nminimizing storage requirements.\n\nUnion fields may be of any type supported by [struct](#Structs) fields. For\nexample:\n\n```cpp\nunion ExampleUnion {\n string str;\n StringPair pair;\n int64 id;\n array guid;\n SampleInterface iface;\n};\n```\n\nFor details on how unions like this translate to generated bindings code, see\n[documentation for individual target languages](#Generated-Code-For-Target-Languages).\n\n### Enumeration Types\n\nEnumeration types may be defined using the **enum** keyword either directly\nwithin a module or nested within the namespace of some struct or interface:\n\n```\nmodule business.mojom;\n\nenum Department {\n SALES = 0,\n DEV,\n};\n\nstruct Employee {\n enum Type {\n FULL_TIME,\n PART_TIME,\n };\n\n Type type;\n // ...\n};\n```\n\nSimilar to C-style enums, individual values may be explicitly assigned within an\nenum definition. By default, values are based at zero and increment by\n1 sequentially.\n\nThe effect of nested definitions on generated bindings varies depending on the\ntarget language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages)\n\n### Constants\n\nConstants may be defined using the **const** keyword either directly within a\nmodule or nested within the namespace of some struct or interface:\n\n```\nmodule business.mojom;\n\nconst string kServiceName = \"business\";\n\nstruct Employee {\n const uint64 kInvalidId = 0;\n\n enum Type {\n FULL_TIME,\n PART_TIME,\n };\n\n uint64 id = kInvalidId;\n Type type;\n};\n```\n\nThe effect of nested definitions on generated bindings varies depending on the\ntarget language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages)\n\n### Interfaces\n\nAn **interface** is a logical bundle of parameterized request messages. Each\nrequest message may optionally define a parameterized response message. Here's\nan example to define an interface `Foo` with various kinds of requests:\n\n```\ninterface Foo {\n // A request which takes no arguments and expects no response.\n MyMessage();\n\n // A request which has some arguments and expects no response.\n MyOtherMessage(string name, array bytes);\n\n // A request which expects a single-argument response.\n MyMessageWithResponse(string command) => (bool success);\n\n // A request which expects a response with multiple arguments.\n MyMessageWithMoarResponse(string a, string b) => (int8 c, int8 d);\n};\n```\n\nAnything which is a valid struct field type (see [Structs](#Structs)) is also a\nvalid request or response argument type. The type notation is the same for both.\n\n### Attributes\n\nMojom definitions may have their meaning altered by **attributes**, specified\nwith a syntax similar to Java or C# attributes. There are a handle of\ninteresting attributes supported today.\n\n**`[Sync]`**\n: The `Sync` attribute may be specified for any interface method which expects\n a response. This makes it so that callers of the method can wait\n synchronously for a response. See\n [Synchronous Calls](/mojo/public/cpp/bindings/README.md#Synchronous-Calls)\n in the C++ bindings documentation. Note that sync calls are not currently\n supported in other target languages.\n\n**`[Extensible]`**\n: The `Extensible` attribute may be specified for any enum definition. This\n essentially disables builtin range validation when receiving values of the\n enum type in a message, allowing older bindings to tolerate unrecognized\n values from newer versions of the enum.\n\n**`[Native]`**\n: The `Native` attribute may be specified for an empty struct declaration to\n provide a nominal bridge between Mojo IPC and legacy `IPC::ParamTraits` or\n `IPC_STRUCT_TRAITS*` macros.\n See\n [Repurposing Legacy IPC Traits](/docs/mojo_ipc_conversion.md#repurposing-and-invocations)\n for more details. Note support for this attribute is strictly limited to C++\n bindings generation.\n\n**`[MinVersion=N]`**\n: The `MinVersion` attribute is used to specify the version at which a given\n field, enum value, interface method, or method parameter was introduced.\n See [Versioning](#Versioning) for more details.\n\n**`[EnableIf=value]`**\n: The `EnableIf` attribute is used to conditionally enable definitions when\n the mojom is parsed. If the `mojom` target in the GN file does not include\n the matching `value` in the list of `enabled_features`, the definition\n will be disabled. This is useful for mojom definitions that only make\n sense on one platform. Note that the `EnableIf` attribute can only be set\n once per definition.\n\n## Generated Code For Target Languages\n\nWhen the bindings generator successfully processes an input Mojom file, it emits\ncorresponding code for each supported target language. For more details on how\nMojom concepts translate to a given target langauge, please refer to the\nbindings API documentation for that language:\n\n* [C++ Bindings](/mojo/public/cpp/bindings/README.md)\n* [JavaScript Bindings](/mojo/public/js/README.md)\n* [Java Bindings](/mojo/public/java/bindings/README.md)\n\n## Message Validation\n\nRegardless of target language, all interface messages are validated during\ndeserialization before they are dispatched to a receiving implementation of the\ninterface. This helps to ensure consitent validation across interfaces without\nleaving the burden to developers and security reviewers every time a new message\nis added.\n\nIf a message fails validation, it is never dispatched. Instead a **connection\nerror** is raised on the binding object (see\n[C++ Connection Errors](/mojo/public/cpp/bindings/README.md#Connection-Errors),\n[Java Connection Errors](/mojo/public/java/bindings/README.md#Connection-Errors),\nor\n[JavaScript Connection Errors](/mojo/public/js/README.md#Connection-Errors) for\ndetails.)\n\nSome baseline level of validation is done automatically for primitive Mojom\ntypes.\n\n### Non-Nullable Objects\n\nMojom fields or parameter values (*e.g.*, structs, interfaces, arrays, *etc.*)\nmay be marked nullable in Mojom definitions (see\n[Primitive Types](#Primitive-Types).) If a field or parameter is **not** marked\nnullable but a message is received with a null value in its place, that message\nwill fail validation.\n\n### Enums\n\nEnums declared in Mojom are automatically validated against the range of legal\nvalues. For example if a Mojom declares the enum:\n\n``` cpp\nenum AdvancedBoolean {\n TRUE = 0,\n FALSE = 1,\n FILE_NOT_FOUND = 2,\n};\n```\n\nand a message is received with the integral value 3 (or anything other than 0,\n1, or 2) in place of some `AdvancedBoolean` field or parameter, the message will\nfail validation.\n\n*** note\nNOTE: It's possible to avoid this type of validation error by explicitly marking\nan enum as [Extensible](#Attributes) if you anticipate your enum being exchanged\nbetween two different versions of the binding interface. See\n[Versioning](#Versioning).\n***\n\n### Other failures\n\nThere are a host of internal validation errors that may occur when a malformed\nmessage is received, but developers should not be concerned with these\nspecifically; in general they can only result from internal bindings bugs,\ncompromised processes, or some remote endpoint making a dubious effort to\nmanually encode their own bindings messages.\n\n### Custom Validation\n\nIt's also possible for developers to define custom validation logic for specific\nMojom struct types by exploiting the\n[type mapping](/mojo/public/cpp/bindings/README.md#Type-Mapping) system for C++\nbindings. Messages rejected by custom validation logic trigger the same\nvalidation failure behavior as the built-in type validation routines.\n\n## Associated Interfaces\n\nAs mentioned in the [Primitive Types](#Primitive-Types) section above, pending_remote\nand pending_receiver fields and parameters may be marked as `associated`. This\nessentially means that they are piggy-backed on some other interface's message\npipe.\n\nBecause individual interface message pipes operate independently there can be no\nrelative ordering guarantees among them. Associated interfaces are useful when\none interface needs to guarantee strict FIFO ordering with respect to one or\nmore other interfaces, as they allow interfaces to share a single pipe.\n\nCurrently associated interfaces are only supported in generated C++ bindings.\nSee the documentation for\n[C++ Associated Interfaces](/mojo/public/cpp/bindings/README.md#Associated-Interfaces).\n\n## Versioning\n\n### Overview\n\n*** note\n**NOTE:** You don't need to worry about versioning if you don't care about\nbackwards compatibility. Specifically, all parts of Chrome are updated\natomically today and there is not yet any possibility of any two Chrome\nprocesses communicating with two different versions of any given Mojom\ninterface.\n***\n\nServices extend their interfaces to support new features over time, and clients\nwant to use those new features when they are available. If services and clients\nare not updated at the same time, it's important for them to be able to\ncommunicate with each other using different snapshots (versions) of their\ninterfaces.\n\nThis document shows how to extend Mojom interfaces in a backwards-compatible\nway. Changing interfaces in a non-backwards-compatible way is not discussed,\nbecause in that case communication between different interface versions is\nimpossible anyway.\n\n### Versioned Structs\n\nYou can use the `MinVersion` [attribute](#Attributes) to indicate from which\nversion a struct field is introduced. Assume you have the following struct:\n\n``` cpp\nstruct Employee {\n uint64 employee_id;\n string name;\n};\n```\n\nand you would like to add a birthday field. You can do:\n\n``` cpp\nstruct Employee {\n uint64 employee_id;\n string name;\n [MinVersion=1] Date? birthday;\n};\n```\n\nBy default, fields belong to version 0. New fields must be appended to the\nstruct definition (*i.e*., existing fields must not change **ordinal value**)\nwith the `MinVersion` attribute set to a number greater than any previous\nexisting versions.\n\n*** note\n**NOTE:** do not change existing fields in versioned structs, as this is\nnot backwards-compatible. Instead, rename the old field to make its\ndeprecation clear and add a new field with the new version number.\n***\n\n**Ordinal value** refers to the relative positional layout of a struct's fields\n(and an interface's methods) when encoded in a message. Implicitly, ordinal\nnumbers are assigned to fields according to lexical position. In the example\nabove, `employee_id` has an ordinal value of 0 and `name` has an ordinal value\nof 1.\n\nOrdinal values can be specified explicitly using `**@**` notation, subject to\nthe following hard constraints:\n\n* For any given struct or interface, if any field or method explicitly specifies\n an ordinal value, all fields or methods must explicitly specify an ordinal\n value.\n* For an *N*-field struct or *N*-method interface, the set of explicitly\n assigned ordinal values must be limited to the range *[0, N-1]*.\n\nYou may reorder fields, but you must ensure that the ordinal values of existing\nfields remain unchanged. For example, the following struct remains\nbackwards-compatible:\n\n``` cpp\nstruct Employee {\n uint64 employee_id@0;\n [MinVersion=1] Date? birthday@2;\n string name@1;\n};\n```\n\n*** note\n**NOTE:** Newly added fields of Mojo object or handle types MUST be nullable.\nSee [Primitive Types](#Primitive-Types).\n***\n\n### Versioned Interfaces\n\nThere are two dimensions on which an interface can be extended\n\n**Appending New Parameters To Existing Methods**\n: Parameter lists are treated as structs internally, so all the rules of\n versioned structs apply to method parameter lists. The only difference is\n that the version number is scoped to the whole interface rather than to any\n individual parameter list.\n\n Please note that adding a response to a message which did not previously\n expect a response is a not a backwards-compatible change.\n\n**Appending New Methods**\n: Similarly, you can reorder methods with explicit ordinal values as long as\n the ordinal values of existing methods are unchanged.\n\nFor example:\n\n``` cpp\n// Old version:\ninterface HumanResourceDatabase {\n AddEmployee(Employee employee) => (bool success);\n QueryEmployee(uint64 id) => (Employee? employee);\n};\n\n// New version:\ninterface HumanResourceDatabase {\n AddEmployee(Employee employee) => (bool success);\n\n QueryEmployee(uint64 id, [MinVersion=1] bool retrieve_finger_print)\n => (Employee? employee,\n [MinVersion=1] array? finger_print);\n\n [MinVersion=1]\n AttachFingerPrint(uint64 id, array finger_print)\n => (bool success);\n};\n```\n\nSimilar to [versioned structs](#Versioned-Structs), when you pass the parameter\nlist of a request or response method to a destination using an older version of\nan interface, unrecognized fields are silently discarded. However, if the method\ncall itself is not recognized, it is considered a validation error and the\nreceiver will close its end of the interface pipe. For example, if a client on\nversion 1 of the above interface sends an `AttachFingerPrint` request to an\nimplementation of version 0, the client will be disconnected.\n\nBindings target languages that support versioning expose means to query or\nassert the remote version from a client handle (*e.g.*, an\n`mojo::Remote` in C++ bindings.)\n\nSee\n[C++ Versioning Considerations](/mojo/public/cpp/bindings/README.md#Versioning-Considerations)\nand\n[Java Versioning Considerations](/mojo/public/java/bindings/README.md#Versioning-Considerations)\n\n### Versioned Enums\n\n**By default, enums are non-extensible**, which means that generated message\nvalidation code does not expect to see new values in the future. When an unknown\nvalue is seen for a non-extensible enum field or parameter, a validation error\nis raised.\n\nIf you want an enum to be extensible in the future, you can apply the\n`[Extensible]` [attribute](#Attributes):\n\n``` cpp\n[Extensible]\nenum Department {\n SALES,\n DEV,\n};\n```\n\nAnd later you can extend this enum without breaking backwards compatibility:\n\n``` cpp\n[Extensible]\nenum Department {\n SALES,\n DEV,\n [MinVersion=1] RESEARCH,\n};\n```\n\n*** note\n**NOTE:** For versioned enum definitions, the use of a `[MinVersion]` attribute\nis strictly for documentation purposes. It has no impact on the generated code.\n***\n\nWith extensible enums, bound interface implementations may receive unknown enum\nvalues and will need to deal with them gracefully. See\n[C++ Versioning Considerations](/mojo/public/cpp/bindings/README.md#Versioning-Considerations)\nfor details.\n\n## Grammar Reference\n\nBelow is the (BNF-ish) context-free grammar of the Mojom language:\n\n```\nMojomFile = StatementList\nStatementList = Statement StatementList | Statement\nStatement = ModuleStatement | ImportStatement | Definition\n\nModuleStatement = AttributeSection \"module\" Identifier \";\"\nImportStatement = \"import\" StringLiteral \";\"\nDefinition = Struct Union Interface Enum Const\n\nAttributeSection = | \"[\" AttributeList \"]\"\nAttributeList = | NonEmptyAttributeList\nNonEmptyAttributeList = Attribute\n | Attribute \",\" NonEmptyAttributeList\nAttribute = Name\n | Name \"=\" Name\n | Name \"=\" Literal\n\nStruct = AttributeSection \"struct\" Name \"{\" StructBody \"}\" \";\"\n | AttributeSection \"struct\" Name \";\"\nStructBody = \n | StructBody Const\n | StructBody Enum\n | StructBody StructField\nStructField = AttributeSection TypeSpec Name Ordinal Default \";\"\n\nUnion = AttributeSection \"union\" Name \"{\" UnionBody \"}\" \";\"\nUnionBody = | UnionBody UnionField\nUnionField = AttributeSection TypeSpec Name Ordinal \";\"\n\nInterface = AttributeSection \"interface\" Name \"{\" InterfaceBody \"}\" \";\"\nInterfaceBody = \n | InterfaceBody Const\n | InterfaceBody Enum\n | InterfaceBody Method\nMethod = AttributeSection Name Ordinal \"(\" ParamterList \")\" Response \";\"\nParameterList = | NonEmptyParameterList\nNonEmptyParameterList = Parameter\n | Parameter \",\" NonEmptyParameterList\nParameter = AttributeSection TypeSpec Name Ordinal\nResponse = | \"=>\" \"(\" ParameterList \")\"\n\nTypeSpec = TypeName \"?\" | TypeName\nTypeName = BasicTypeName\n | Array\n | FixedArray\n | Map\n | InterfaceRequest\nBasicTypeName = Identifier | \"associated\" Identifier | HandleType | NumericType\nNumericType = \"bool\" | \"int8\" | \"uint8\" | \"int16\" | \"uint16\" | \"int32\"\n | \"uint32\" | \"int64\" | \"uint64\" | \"float\" | \"double\"\nHandleType = \"handle\" | \"handle\" \"<\" SpecificHandleType \">\"\nSpecificHandleType = \"message_pipe\"\n | \"shared_buffer\"\n | \"data_pipe_consumer\"\n | \"data_pipe_producer\"\nArray = \"array\" \"<\" TypeSpec \">\"\nFixedArray = \"array\" \"<\" TypeSpec \",\" IntConstDec \">\"\nMap = \"map\" \"<\" Identifier \",\" TypeSpec \">\"\nInterfaceRequest = Identifier \"&\" | \"associated\" Identifier \"&\"\n\nOrdinal = | OrdinalValue\n\nDefault = | \"=\" Constant\n\nEnum = AttributeSection \"enum\" Name \"{\" NonEmptyEnumValueList \"}\" \";\"\n | AttributeSection \"enum\" Name \"{\" NonEmptyEnumValueList \",\" \"}\" \";\"\nNonEmptyEnumValueList = EnumValue | NonEmptyEnumValueList \",\" EnumValue\nEnumValue = AttributeSection Name\n | AttributeSection Name \"=\" Integer\n | AttributeSection Name \"=\" Identifier\n\nConst = \"const\" TypeSpec Name \"=\" Constant \";\"\n\nConstant = Literal | Identifier \";\"\n\nIdentifier = Name | Name \".\" Identifier\n\nLiteral = Integer | Float | \"true\" | \"false\" | \"default\" | StringLiteral\n\nInteger = IntConst | \"+\" IntConst | \"-\" IntConst\nIntConst = IntConstDec | IntConstHex\n\nFloat = FloatConst | \"+\" FloatConst | \"-\" FloatConst\n\n; The rules below are for tokens matched strictly according to the given regexes\n\nIdentifier = /[a-zA-Z_][0-9a-zA-Z_]*/\nIntConstDec = /0|(1-9[0-9]*)/\nIntConstHex = /0[xX][0-9a-fA-F]+/\nOrdinalValue = /@(0|(1-9[0-9]*))/\nFloatConst = ... # Imagine it's close enough to C-style float syntax.\nStringLiteral = ... # Imagine it's close enough to C-style string literals, including escapes.\n```\n\n## Additional Documentation\n\n[Mojom Message Format](https://docs.google.com/document/d/13pv9cFh5YKuBggDBQ1-AL8VReF-IYpFOFpRfvWFrwio/edit)\n: Describes the wire format used by Mojo bindings interfaces over message\n pipes.\n\n[Input Format of Mojom Message Validation Tests](https://docs.google.com/document/d/1-y-2IYctyX2NPaLxJjpJfzVNWCC2SR2MJAD9MpIytHQ/edit)\n: Describes a text format used to facilitate bindings message validation\n tests.\n","isInternal":false,"tokens":6576,"sizeBytes":28621}],"systemPromptSnippet":"\n\nThose files are taken from the official Microsoft PDB repository\n\nhttps://github.com/Microsoft/microsoft-pdb\n\n\n# `tools/`\nCitizenFX build infrastructure.\n\n* [**build/**](./build): Premake5 build tool helpers.\n* [**ci/**](./ci): CI scripts. Confused about the build process? Look here.\n* [**dbg/**](./dbg): Wrappers for adding debug info to game clients.\n* [**ext/**](./ext): External data.\n* [**idl/**](./idl): `xpidl` fork.\n\n\n# Mojom Interface Definition Language (IDL)\nThis document is a subset of the [Mojo documentation](/mojo/README.md).\n\n[TOC]\n\n## Overview\n\nMojom is the IDL for Mojo interfaces. Given a `.mojom` file, the\n[bindings\ngenerator](https://cs.chromium.org/chromium/src/mojo/public/tools/bindings/) can\noutput bindings for any supported language: **C++**, **JavaScript**, or\n**Java**.\n\nFor a trivial example consider the following hypothetical Mojom file we write to\n`//services/widget/public/mojom/frobinator.mojom`:\n\n```\nmodule widget.mojom;\n\ninterface Frobinator {\n Frobinate();\n};\n```\n\nThis defines a single [interface](#Interfaces) named `Frobinator` in a\n[module](#Modules) named `widget.mojom` (and thus fully qualified in Mojom as\n`widget.mojom.Frobinator`.) Note that many interfaces and/or other types of\ndefinitions (structs, enums, *etc.*) may be included in a single Mojom file.\n\nIf we add a corresponding GN target to\n`//services/widget/public/mojom/BUILD.gn`:\n\n```\nimport(\"mojo/public/tools/bindings/mojom.gni\")\n\nmojom(\"mojom\") {\n sources = [\n \"frobinator.mojom\",\n ]\n}\n```\n\nand then build this target:\n\n```\nninja -C out/r services/widget/public/mojom\n```\n\nwe'll find several generated sources in our output directory:\n\n```\nout/r/gen/services/widget/public/mojom/frobinator.mojom.cc\nout/r/gen/services/widget/public/mojom/frobinator.mojom.h\nout/r/gen/services/widget/public/mojom/frobinator.mojom-shared.h\netc...\n```\n\nEach of these generated source modules includes a set of definitions\nrepresenting the Mojom contents in C++. You can also build or depend on suffixed\ntarget names to get bindings for other languages. For example,\n\n```\nninja -C out/r services/widget/public/mojom:mojom_js\nninja -C out/r services/widget/public/mojom:mojom_java\n```\n\nwould generate JavaScript and Java bindings respectively, in the same generated\noutput directory.\n\nFor more details regarding the generated\noutputs please see\n[documentation for individual target languages](#Generated-Code-For-Target-Languages).\n\n## Mojom Syntax\n\nMojom IDL allows developers to define **structs**, **unions**, **interfaces**,\n**constants**, and **enums**, all within the context of a **module**. These\ndefinitions are used to generate code in the supported target languages at build\ntime.\n\nMojom files may **import** other Mojom files in order to reference their\ndefinitions.\n\n### Primitive Types\nMojom supports a few basic data types which may be composed into structs or used\nfor message parameters.\n\n| Type | Description\n|-------------------------------|-------------------------------------------------------|\n| `bool` | Boolean type (`true` or `false`.)\n| `int8`, `uint8` | Signed or unsigned 8-bit integer.\n| `int16`, `uint16` | Signed or unsigned 16-bit integer.\n| `int32`, `uint32` | Signed or unsigned 32-bit integer.\n| `int64`, `uint64` | Signed or unsigned 64-bit integer.\n| `float`, `double` | 32- or 64-bit floating point number.\n| `string` | UTF-8 encoded string.\n| `array` | Array of any Mojom type *T*; for example, `array` or `array>`.\n| `array` | Fixed-length array of any Mojom type *T*. The parameter *N* must be an integral constant.\n| `map` | Associated array maping values of type *S* to values of type *T*. *S* may be a `string`, `enum`, or numeric type.\n| `handle` | Generic Mojo handle. May be any type of handle, including a wrapped native platform handle.\n| `handle` | Generic message pipe handle.\n| `handle` | Shared buffer handle.\n| `handle` | Data pipe producer handle.\n| `handle` | Data pipe consumer handle.\n| *`pending_remote`* | 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.\n| *`pending_receiver`* | A pending receiver 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.\n| *`pending_associated_remote`* | An associated interface handle. See [Associated Interfaces](#Associated-Interfaces)\n| *`pending_associated_receiver`* | A pending associated receiver. See [Associated Interfaces](#Associated-Interfaces)\n| *T*? | An optional (nullable) value. Primitive numeric types (integers, floats, booleans, and enums) are not nullable. All other types are nullable.\n\n### Modules\n\nEvery Mojom file may optionally specify a single **module** to which it belongs.\n\nThis is used strictly for aggregaging all defined symbols therein within a\ncommon Mojom namespace. The specific impact this has on generated binidngs code\nvaries for each target language. For example, if the following Mojom is used to\ngenerate bindings:\n\n```\nmodule business.stuff;\n\ninterface MoneyGenerator {\n GenerateMoney();\n};\n```\n\nGenerated C++ bindings will define a class interface `MoneyGenerator` in the\n`business::stuff` namespace, while Java bindings will define an interface\n`MoneyGenerator` in the `org.chromium.business.stuff` package. JavaScript\nbindings at this time are unaffected by module declarations.\n\n**NOTE:** By convention in the Chromium codebase, **all** Mojom files should\ndeclare a module name with at least (and preferrably exactly) one top-level name\nas well as an inner `mojom` module suffix. *e.g.*, `chrome.mojom`,\n`business.mojom`, *etc.*\n\nThis convention makes it easy to tell which symbols are generated by Mojom when\nreading non-Mojom code, and it also avoids namespace collisions in the fairly\ncommon scenario where you have a real C++ or Java `Foo` along with a\ncorresponding Mojom `Foo` for its serialized representation.\n\n### Imports\n\nIf your Mojom references definitions from other Mojom files, you must **import**\nthose files. Import syntax is as follows:\n\n```\nimport \"services/widget/public/mojom/frobinator.mojom\";\n```\n\nImport paths are always relative to the top-level directory.\n\nNote that circular imports are **not** supported.\n\n### Structs\n\nStructs are defined using the **struct** keyword, and they provide a way to\ngroup related fields together:\n\n``` cpp\nstruct StringPair {\n string first;\n string second;\n};\n```\n\nStruct fields may be comprised of any of the types listed above in the\n[Primitive Types](#Primitive-Types) section.\n\nDefault values may be specified as long as they are constant:\n\n``` cpp\nstruct Request {\n int32 id = -1;\n string details;\n};\n```\n\nWhat follows is a fairly\ncomprehensive example using the supported field types:\n\n``` cpp\nstruct StringPair {\n string first;\n string second;\n};\n\nenum AnEnum {\n YES,\n NO\n};\n\ninterface SampleInterface {\n DoStuff();\n};\n\nstruct AllTheThings {\n // Note that these types can never be marked nullable!\n bool boolean_value;\n int8 signed_8bit_value = 42;\n uint8 unsigned_8bit_value;\n int16 signed_16bit_value;\n uint16 unsigned_16bit_value;\n int32 signed_32bit_value;\n uint32 unsigned_32bit_value;\n int64 signed_64bit_value;\n uint64 unsigned_64bit_value;\n float float_value_32bit;\n double float_value_64bit;\n AnEnum enum_value = AnEnum.YES;\n\n // Strings may be nullable.\n string? maybe_a_string_maybe_not;\n\n // Structs may contain other structs. These may also be nullable.\n StringPair some_strings;\n StringPair? maybe_some_more_strings;\n\n // In fact structs can also be nested, though in practice you must always make\n // such fields nullable -- otherwise messages would need to be infinitely long\n // in order to pass validation!\n AllTheThings? more_things;\n\n // Arrays may be templated over any Mojom type, and are always nullable:\n array numbers;\n array? maybe_more_numbers;\n\n // Arrays of arrays of arrays... are fine.\n array>> this_works_but_really_plz_stop;\n\n // The element type may be nullable if it's a type which is allowed to be\n // nullable.\n array more_maybe_things;\n\n // Fixed-size arrays get some extra validation on the receiving end to ensure\n // that the correct number of elements is always received.\n array uuid;\n\n // Maps follow many of the same rules as arrays. Key types may be any\n // non-handle, non-collection type, and value types may be any supported\n // struct field type. Maps may also be nullable.\n map one_map;\n map? maybe_another_map;\n map? maybe_a_pretty_weird_but_valid_map;\n map?>?>?> ridiculous;\n\n // And finally, all handle types are valid as struct fields and may be\n // nullable. Note that interfaces and interface requests (the \"Foo\" and\n // \"Foo&\" type syntax respectively) are just strongly-typed message pipe\n // handles.\n handle generic_handle;\n handle reader;\n handle? maybe_writer;\n handle dumping_ground;\n handle raw_message_pipe;\n pending_remote? maybe_a_sample_interface_client_pipe;\n pending_receiver non_nullable_sample_pending_receiver;\n pending_receiver? nullable_sample_pending_receiver;\n pending_associated_remote associated_interface_client;\n pending_associated_receiver associated_pending_receiver;\n pending_associated_receiver? maybe_another_pending_receiver;\n};\n```\n\nFor details on how all of these different types translate to usable generated\ncode, see\n[documentation for individual target languages](#Generated-Code-For-Target-Languages).\n\n### Unions\n\nMojom supports tagged unions using the **union** keyword. A union is a\ncollection of fields which may taken the value of any single one of those fields\nat a time. Thus they provide a way to represent a variant value type while\nminimizing storage requirements.\n\nUnion fields may be of any type supported by [struct](#Structs) fields. For\nexample:\n\n```cpp\nunion ExampleUnion {\n string str;\n StringPair pair;\n int64 id;\n array guid;\n SampleInterface iface;\n};\n```\n\nFor details on how unions like this translate to generated bindings code, see\n[documentation for individual target languages](#Generated-Code-For-Target-Languages).\n\n### Enumeration Types\n\nEnumeration types may be defined using the **enum** keyword either directly\nwithin a module or nested within the namespace of some struct or interface:\n\n```\nmodule business.mojom;\n\nenum Department {\n SALES = 0,\n DEV,\n};\n\nstruct Employee {\n enum Type {\n FULL_TIME,\n PART_TIME,\n };\n\n Type type;\n // ...\n};\n```\n\nSimilar to C-style enums, individual values may be explicitly assigned within an\nenum definition. By default, values are based at zero and increment by\n1 sequentially.\n\nThe effect of nested definitions on generated bindings varies depending on the\ntarget language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages)\n\n### Constants\n\nConstants may be defined using the **const** keyword either directly within a\nmodule or nested within the namespace of some struct or interface:\n\n```\nmodule business.mojom;\n\nconst string kServiceName = \"business\";\n\nstruct Employee {\n const uint64 kInvalidId = 0;\n\n enum Type {\n FULL_TIME,\n PART_TIME,\n };\n\n uint64 id = kInvalidId;\n Type type;\n};\n```\n\nThe effect of nested definitions on generated bindings varies depending on the\ntarget language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages)\n\n### Interfaces\n\nAn **interface** is a logical bundle of parameterized request messages. Each\nrequest message may optionally define a parameterized response message. Here's\nan example to define an interface `Foo` with various kinds of requests:\n\n```\ninterface Foo {\n // A request which takes no arguments and expects no response.\n MyMessage();\n\n // A request which has some arguments and expects no response.\n MyOtherMessage(string name, array bytes);\n\n // A request which expects a single-argument response.\n MyMessageWithResponse(string command) => (bool success);\n\n // A request which expects a response with multiple arguments.\n MyMessageWithMoarResponse(string a, string b) => (int8 c, int8 d);\n};\n```\n\nAnything which is a valid struct field type (see [Structs](#Structs)) is also a\nvalid request or response argument type. The type notation is the same for both.\n\n### Attributes\n\nMojom definitions may have their meaning altered by **attributes**, specified\nwith a syntax similar to Java or C# attributes. There are a handle of\ninteresting attributes supported today.\n\n**`[Sync]`**\n: The `Sync` attribute may be specified for any interface method which expects\n a response. This makes it so that callers of the method can wait\n synchronously for a response. See\n [Synchronous Calls](/mojo/public/cpp/bindings/README.md#Synchronous-Calls)\n in the C++ bindings documentation. Note that sync calls are not currently\n supported in other target languages.\n\n**`[Extensible]`**\n: The `Extensible` attribute may be specified for any enum definition. This\n essentially disables builtin range validation when receiving values of the\n enum type in a message, allowing older bindings to tolerate unrecognized\n values from newer versions of the enum.\n\n**`[Native]`**\n: The `Native` attribute may be specified for an empty struct declaration to\n provide a nominal bridge between Mojo IPC and legacy `IPC::ParamTraits` or\n `IPC_STRUCT_TRAITS*` macros.\n See\n [Repurposing Legacy IPC Traits](/docs/mojo_ipc_conversion.md#repurposing-and-invocations)\n for more details. Note support for this attribute is strictly limited to C++\n bindings generation.\n\n**`[MinVersion=N]`**\n: The `MinVersion` attribute is used to specify the version at which a given\n field, enum value, interface method, or method parameter was introduced.\n See [Versioning](#Versioning) for more details.\n\n**`[EnableIf=value]`**\n: The `EnableIf` attribute is used to conditionally enable definitions when\n the mojom is parsed. If the `mojom` target in the GN file does not include\n the matching `value` in the list of `enabled_features`, the definition\n will be disabled. This is useful for mojom definitions that only make\n sense on one platform. Note that the `EnableIf` attribute can only be set\n once per definition.\n\n## Generated Code For Target Languages\n\nWhen the bindings generator successfully processes an input Mojom file, it emits\ncorresponding code for each supported target language. For more details on how\nMojom concepts translate to a given target langauge, please refer to the\nbindings API documentation for that language:\n\n* [C++ Bindings](/mojo/public/cpp/bindings/README.md)\n* [JavaScript Bindings](/mojo/public/js/README.md)\n* [Java Bindings](/mojo/public/java/bindings/README.md)\n\n## Message Validation\n\nRegardless of target language, all interface messages are validated during\ndeserialization before they are dispatched to a receiving implementation of the\ninterface. This helps to ensure consitent validation across interfaces without\nleaving the burden to developers and security reviewers every time a new message\nis added.\n\nIf a message fails validation, it is never dispatched. Instead a **connection\nerror** is raised on the binding object (see\n[C++ Connection Errors](/mojo/public/cpp/bindings/README.md#Connection-Errors),\n[Java Connection Errors](/mojo/public/java/bindings/README.md#Connection-Errors),\nor\n[JavaScript Connection Errors](/mojo/public/js/README.md#Connection-Errors) for\ndetails.)\n\nSome baseline level of validation is done automatically for primitive Mojom\ntypes.\n\n### Non-Nullable Objects\n\nMojom fields or parameter values (*e.g.*, structs, interfaces, arrays, *etc.*)\nmay be marked nullable in Mojom definitions (see\n[Primitive Types](#Primitive-Types).) If a field or parameter is **not** marked\nnullable but a message is received with a null value in its place, that message\nwill fail validation.\n\n### Enums\n\nEnums declared in Mojom are automatically validated against the range of legal\nvalues. For example if a Mojom declares the enum:\n\n``` cpp\nenum AdvancedBoolean {\n TRUE = 0,\n FALSE = 1,\n FILE_NOT_FOUND = 2,\n};\n```\n\nand a message is received with the integral value 3 (or anything other than 0,\n1, or 2) in place of some `AdvancedBoolean` field or parameter, the message will\nfail validation.\n\n*** note\nNOTE: It's possible to avoid this type of validation error by explicitly marking\nan enum as [Extensible](#Attributes) if you anticipate your enum being exchanged\nbetween two different versions of the binding interface. See\n[Versioning](#Versioning).\n***\n\n### Other failures\n\nThere are a host of internal validation errors that may occur when a malformed\nmessage is received, but developers should not be concerned with these\nspecifically; in general they can only result from internal bindings bugs,\ncompromised processes, or some remote endpoint making a dubious effort to\nmanually encode their own bindings messages.\n\n### Custom Validation\n\nIt's also possible for developers to define custom validation logic for specific\nMojom struct types by exploiting the\n[type mapping](/mojo/public/cpp/bindings/README.md#Type-Mapping) system for C++\nbindings. Messages rejected by custom validation logic trigger the same\nvalidation failure behavior as the built-in type validation routines.\n\n## Associated Interfaces\n\nAs mentioned in the [Primitive Types](#Primitive-Types) section above, pending_remote\nand pending_receiver fields and parameters may be marked as `associated`. This\nessentially means that they are piggy-backed on some other interface's message\npipe.\n\nBecause individual interface message pipes operate independently there can be no\nrelative ordering guarantees among them. Associated interfaces are useful when\none interface needs to guarantee strict FIFO ordering with respect to one or\nmore other interfaces, as they allow interfaces to share a single pipe.\n\nCurrently associated interfaces are only supported in generated C++ bindings.\nSee the documentation for\n[C++ Associated Interfaces](/mojo/public/cpp/bindings/README.md#Associated-Interfaces).\n\n## Versioning\n\n### Overview\n\n*** note\n**NOTE:** You don't need to worry about versioning if you don't care about\nbackwards compatibility. Specifically, all parts of Chrome are updated\natomically today and there is not yet any possibility of any two Chrome\nprocesses communicating with two different versions of any given Mojom\ninterface.\n***\n\nServices extend their interfaces to support new features over time, and clients\nwant to use those new features when they are available. If services and clients\nare not updated at the same time, it's important for them to be able to\ncommunicate with each other using different snapshots (versions) of their\ninterfaces.\n\nThis document shows how to extend Mojom interfaces in a backwards-compatible\nway. Changing interfaces in a non-backwards-compatible way is not discussed,\nbecause in that case communication between different interface versions is\nimpossible anyway.\n\n### Versioned Structs\n\nYou can use the `MinVersion` [attribute](#Attributes) to indicate from which\nversion a struct field is introduced. Assume you have the following struct:\n\n``` cpp\nstruct Employee {\n uint64 employee_id;\n string name;\n};\n```\n\nand you would like to add a birthday field. You can do:\n\n``` cpp\nstruct Employee {\n uint64 employee_id;\n string name;\n [MinVersion=1] Date? birthday;\n};\n```\n\nBy default, fields belong to version 0. New fields must be appended to the\nstruct definition (*i.e*., existing fields must not change **ordinal value**)\nwith the `MinVersion` attribute set to a number greater than any previous\nexisting versions.\n\n*** note\n**NOTE:** do not change existing fields in versioned structs, as this is\nnot backwards-compatible. Instead, rename the old field to make its\ndeprecation clear and add a new field with the new version number.\n***\n\n**Ordinal value** refers to the relative positional layout of a struct's fields\n(and an interface's methods) when encoded in a message. Implicitly, ordinal\nnumbers are assigned to fields according to lexical position. In the example\nabove, `employee_id` has an ordinal value of 0 and `name` has an ordinal value\nof 1.\n\nOrdinal values can be specified explicitly using `**@**` notation, subject to\nthe following hard constraints:\n\n* For any given struct or interface, if any field or method explicitly specifies\n an ordinal value, all fields or methods must explicitly specify an ordinal\n value.\n* For an *N*-field struct or *N*-method interface, the set of explicitly\n assigned ordinal values must be limited to the range *[0, N-1]*.\n\nYou may reorder fields, but you must ensure that the ordinal values of existing\nfields remain unchanged. For example, the following struct remains\nbackwards-compatible:\n\n``` cpp\nstruct Employee {\n uint64 employee_id@0;\n [MinVersion=1] Date? birthday@2;\n string name@1;\n};\n```\n\n*** note\n**NOTE:** Newly added fields of Mojo object or handle types MUST be nullable.\nSee [Primitive Types](#Primitive-Types).\n***\n\n### Versioned Interfaces\n\nThere are two dimensions on which an interface can be extended\n\n**Appending New Parameters To Existing Methods**\n: Parameter lists are treated as structs internally, so all the rules of\n versioned structs apply to method parameter lists. The only difference is\n that the version number is scoped to the whole interface rather than to any\n individual parameter list.\n\n Please note that adding a response to a message which did not previously\n expect a response is a not a backwards-compatible change.\n\n**Appending New Methods**\n: Similarly, you can reorder methods with explicit ordinal values as long as\n the ordinal values of existing methods are unchanged.\n\nFor example:\n\n``` cpp\n// Old version:\ninterface HumanResourceDatabase {\n AddEmployee(Employee employee) => (bool success);\n QueryEmployee(uint64 id) => (Employee? employee);\n};\n\n// New version:\ninterface HumanResourceDatabase {\n AddEmployee(Employee employee) => (bool success);\n\n QueryEmployee(uint64 id, [MinVersion=1] bool retrieve_finger_print)\n => (Employee? employee,\n [MinVersion=1] array? finger_print);\n\n [MinVersion=1]\n AttachFingerPrint(uint64 id, array finger_print)\n => (bool success);\n};\n```\n\nSimilar to [versioned structs](#Versioned-Structs), when you pass the parameter\nlist of a request or response method to a destination using an older version of\nan interface, unrecognized fields are silently discarded. However, if the method\ncall itself is not recognized, it is considered a validation error and the\nreceiver will close its end of the interface pipe. For example, if a client on\nversion 1 of the above interface sends an `AttachFingerPrint` request to an\nimplementation of version 0, the client will be disconnected.\n\nBindings target languages that support versioning expose means to query or\nassert the remote version from a client handle (*e.g.*, an\n`mojo::Remote` in C++ bindings.)\n\nSee\n[C++ Versioning Considerations](/mojo/public/cpp/bindings/README.md#Versioning-Considerations)\nand\n[Java Versioning Considerations](/mojo/public/java/bindings/README.md#Versioning-Considerations)\n\n### Versioned Enums\n\n**By default, enums are non-extensible**, which means that generated message\nvalidation code does not expect to see new values in the future. When an unknown\nvalue is seen for a non-extensible enum field or parameter, a validation error\nis raised.\n\nIf you want an enum to be extensible in the future, you can apply the\n`[Extensible]` [attribute](#Attributes):\n\n``` cpp\n[Extensible]\nenum Department {\n SALES,\n DEV,\n};\n```\n\nAnd later you can extend this enum without breaking backwards compatibility:\n\n``` cpp\n[Extensible]\nenum Department {\n SALES,\n DEV,\n [MinVersion=1] RESEARCH,\n};\n```\n\n*** note\n**NOTE:** For versioned enum definitions, the use of a `[MinVersion]` attribute\nis strictly for documentation purposes. It has no impact on the generated code.\n***\n\nWith extensible enums, bound interface implementations may receive unknown enum\nvalues and will need to deal with them gracefully. See\n[C++ Versioning Considerations](/mojo/public/cpp/bindings/README.md#Versioning-Considerations)\nfor details.\n\n## Grammar Reference\n\nBelow is the (BNF-ish) context-free grammar of the Mojom language:\n\n```\nMojomFile = StatementList\nStatementList = Statement StatementList | Statement\nStatement = ModuleStatement | ImportStatement | Definition\n\nModuleStatement = AttributeSection \"module\" Identifier \";\"\nImportStatement = \"import\" StringLiteral \";\"\nDefinition = Struct Union Interface Enum Const\n\nAttributeSection = | \"[\" AttributeList \"]\"\nAttributeList = | NonEmptyAttributeList\nNonEmptyAttributeList = Attribute\n | Attribute \",\" NonEmptyAttributeList\nAttribute = Name\n | Name \"=\" Name\n | Name \"=\" Literal\n\nStruct = AttributeSection \"struct\" Name \"{\" StructBody \"}\" \";\"\n | AttributeSection \"struct\" Name \";\"\nStructBody = \n | StructBody Const\n | StructBody Enum\n | StructBody StructField\nStructField = AttributeSection TypeSpec Name Ordinal Default \";\"\n\nUnion = AttributeSection \"union\" Name \"{\" UnionBody \"}\" \";\"\nUnionBody = | UnionBody UnionField\nUnionField = AttributeSection TypeSpec Name Ordinal \";\"\n\nInterface = AttributeSection \"interface\" Name \"{\" InterfaceBody \"}\" \";\"\nInterfaceBody = \n | InterfaceBody Const\n | InterfaceBody Enum\n | InterfaceBody Method\nMethod = AttributeSection Name Ordinal \"(\" ParamterList \")\" Response \";\"\nParameterList = | NonEmptyParameterList\nNonEmptyParameterList = Parameter\n | Parameter \",\" NonEmptyParameterList\nParameter = AttributeSection TypeSpec Name Ordinal\nResponse = | \"=>\" \"(\" ParameterList \")\"\n\nTypeSpec = TypeName \"?\" | TypeName\nTypeName = BasicTypeName\n | Array\n | FixedArray\n | Map\n | InterfaceRequest\nBasicTypeName = Identifier | \"associated\" Identifier | HandleType | NumericType\nNumericType = \"bool\" | \"int8\" | \"uint8\" | \"int16\" | \"uint16\" | \"int32\"\n | \"uint32\" | \"int64\" | \"uint64\" | \"float\" | \"double\"\nHandleType = \"handle\" | \"handle\" \"<\" SpecificHandleType \">\"\nSpecificHandleType = \"message_pipe\"\n | \"shared_buffer\"\n | \"data_pipe_consumer\"\n | \"data_pipe_producer\"\nArray = \"array\" \"<\" TypeSpec \">\"\nFixedArray = \"array\" \"<\" TypeSpec \",\" IntConstDec \">\"\nMap = \"map\" \"<\" Identifier \",\" TypeSpec \">\"\nInterfaceRequest = Identifier \"&\" | \"associated\" Identifier \"&\"\n\nOrdinal = | OrdinalValue\n\nDefault = | \"=\" Constant\n\nEnum = AttributeSection \"enum\" Name \"{\" NonEmptyEnumValueList \"}\" \";\"\n | AttributeSection \"enum\" Name \"{\" NonEmptyEnumValueList \",\" \"}\" \";\"\nNonEmptyEnumValueList = EnumValue | NonEmptyEnumValueList \",\" EnumValue\nEnumValue = AttributeSection Name\n | AttributeSection Name \"=\" Integer\n | AttributeSection Name \"=\" Identifier\n\nConst = \"const\" TypeSpec Name \"=\" Constant \";\"\n\nConstant = Literal | Identifier \";\"\n\nIdentifier = Name | Name \".\" Identifier\n\nLiteral = Integer | Float | \"true\" | \"false\" | \"default\" | StringLiteral\n\nInteger = IntConst | \"+\" IntConst | \"-\" IntConst\nIntConst = IntConstDec | IntConstHex\n\nFloat = FloatConst | \"+\" FloatConst | \"-\" FloatConst\n\n; The rules below are for tokens matched strictly according to the given regexes\n\nIdentifier = /[a-zA-Z_][0-9a-zA-Z_]*/\nIntConstDec = /0|(1-9[0-9]*)/\nIntConstHex = /0[xX][0-9a-fA-F]+/\nOrdinalValue = /@(0|(1-9[0-9]*))/\nFloatConst = ... # Imagine it's close enough to C-style float syntax.\nStringLiteral = ... # Imagine it's close enough to C-style string literals, including escapes.\n```\n\n## Additional Documentation\n\n[Mojom Message Format](https://docs.google.com/document/d/13pv9cFh5YKuBggDBQ1-AL8VReF-IYpFOFpRfvWFrwio/edit)\n: Describes the wire format used by Mojo bindings interfaces over message\n pipes.\n\n[Input Format of Mojom Message Validation Tests](https://docs.google.com/document/d/1-y-2IYctyX2NPaLxJjpJfzVNWCC2SR2MJAD9MpIytHQ/edit)\n: Describes a text format used to facilitate bindings message validation\n tests.\n"}