pub struct ComponentInterface {
    uniffi_version: String,
    types: TypeUniverse,
    namespace: String,
    ffi_namespace: String,
    enums: Vec<Enum>,
    records: Vec<Record>,
    functions: Vec<Function>,
    objects: Vec<Object>,
    callback_interfaces: Vec<CallbackInterface>,
    errors: Vec<Error>,
}
Expand description

The main public interface for this module, representing the complete details of an interface exposed by a rust component and the details of consuming it via an extern-C FFI layer.

Fields

uniffi_version: String

Every ComponentInterface gets tagged with the version of uniffi used to create it. This helps us avoid using a lib compiled with one version together with bindings created using a different version, which might introduce unsafety.

types: TypeUniverse

All of the types used in the interface.

namespace: String

The unique prefix that we’ll use for namespacing when exposing this component’s API.

ffi_namespace: String

The internal unique prefix used to namespace FFI symbols

enums: Vec<Enum>

The high-level API provided by the component.

records: Vec<Record>functions: Vec<Function>objects: Vec<Object>callback_interfaces: Vec<CallbackInterface>errors: Vec<Error>

Implementations

Parse a ComponentInterface from a string containing a WebIDL definition.

The string namespace within which this API should be presented to the caller.

This string would typically be used to prefix function names in the FFI, to build a package or module name for the foreign language, etc.

Get the definitions for every Enum type in the interface.

Get an Enum definition by name, or None if no such Enum is defined.

Get the definitions for every Record type in the interface.

Get a Record definition by name, or None if no such Record is defined.

Get the definitions for every Function in the interface.

Get a Function definition by name, or None if no such Function is defined.

Get the definitions for every Object type in the interface.

Get an Object definition by name, or None if no such Object is defined.

Get the definitions for every Callback Interface type in the interface.

Get a Callback interface definition by name, or None if no such interface is defined.

Get the definitions for every Error type in the interface.

Get an Error definition by name, or None if no such Error is defined.

Get details about all Type::External types

Get details about all Type::Custom types

Iterate over all known types in the interface.

Get a specific type

Iterate over all types contained in the given item.

This method uses iter_types to iterate over the types contained within the given type, but additionally recurses into the definition of user-defined types like records and enums to yield the types that they contain.

Check whether the given item contains any (possibly nested) Type::Object references.

This is important to know in language bindings that cannot integrate object types tightly with the host GC, and hence need to perform manual destruction of objects.

Check whether the given item contains any (possibly nested) unsigned types

Check whether the interface contains any optional types

Check whether the interface contains any sequence types

Check whether the interface contains any map types

Calculate a numeric checksum for this ComponentInterface.

The checksum can be used to guard against accidentally using foreign-language bindings generated from one version of an interface with the compiled Rust code from a different version of that interface. It offers the following properties:

  • Two ComponentIntefaces generated from the same WebIDL file, using the same version of uniffi and the same version of Rust, will always have the same checksum value.
  • Two ComponentInterfaces will, with high probability, have different checksum values if: - They were generated from two different WebIDL files. - They were generated by two different versions of uniffi

The checksum may or may not change depending on the version of Rust used; since we expect consumers to be using the same executable to generate both the scaffolding and the bindings, assuming the same version of Rust seems acceptable.

Note that this is designed to prevent accidents, not attacks, so there is no need for the checksum to be cryptographically secure.

TODO: it’s not clear to me if the derivation of Hash is actually deterministic enough to ensure the guarantees above, or if it might be sensitive to e.g. compiler-driven re-ordering of struct field. Let’s see how it goes…

The namespace to use in FFI-level function definitions.

The value returned by this method is used as a prefix to namespace all UDL-defined FFI functions used in this ComponentInterface.

Since these names are an internal implementation detail that is not typically visible to consumers, we take the opportunity to add an additional safety guard by including a 4-hex-char checksum in each name. If foreign-language bindings attempt to load and use a version of the Rust code compiled from a different UDL definition than the one used for the bindings themselves, then there is a high probability of checksum mismatch and they will fail to link against the compiled Rust code. The result will be an ugly inscrutable link-time error, but that is a lot better than triggering potentially arbitrary memory unsafety!

Builtin FFI function for allocating a new RustBuffer. This is needed so that the foreign language bindings can create buffers in which to pass complex data types across the FFI.

Builtin FFI function for copying foreign-owned bytes This is needed so that the foreign language bindings can create buffers in which to pass complex data types across the FFI.

Builtin FFI function for freeing a RustBuffer. This is needed so that the foreign language bindings can free buffers in which they received complex data types returned across the FFI.

Builtin FFI function for reserving extra space in a RustBuffer. This is needed so that the foreign language bindings can grow buffers used for passing complex data types across the FFI.

List the definitions of all FFI functions in the interface.

The set of FFI functions is derived automatically from the set of higher-level types along with the builtin FFI helper functions.

List all FFI functions definitions for user-defined interfaces

This includes FFI functions for:

  • Top-level functions
  • Object methods
  • Callback interfaces

List all FFI functions definitions for RustBuffer functionality

Resolve a weedle type expression into a Type.

This method uses the current state of our TypeUniverse to turn a weedle type expression into a concrete Type (or error if the type expression is not well defined). It abstracts away the complexity of walking weedle’s type struct heirarchy by dispatching to the TypeResolver trait.

Resolve a weedle ReturnType expression into an optional Type.

This method is similar to resolve_type_expression, but tailored specifically for return types. It can return None to represent a non-existent return value.

Called by APIBuilder impls to add a newly-parsed namespace definition to the ComponentInterface.

Called by APIBuilder impls to add a newly-parsed enum definition to the ComponentInterface.

Called by APIBuilder impls to add a newly-parsed record definition to the ComponentInterface.

Called by APIBuilder impls to add a newly-parsed function definition to the ComponentInterface.

Called by APIBuilder impls to add a newly-parsed object definition to the ComponentInterface.

Called by APIBuilder impls to add a newly-parsed callback interface definition to the ComponentInterface.

Called by APIBuilder impls to add a newly-parsed error definition to the ComponentInterface.

Perform global consistency checks on the declared interface.

This method checks for consistency problems in the declared interface as a whole, and which can only be detected after we’ve finished defining the entire interface.

Automatically derive the low-level FFI functions from the high-level types in the interface.

This should only be called after the high-level types have been completed defined, otherwise the resulting set will be missing some entries.

Trait Implementations

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

ComponentInterface structs can be hashed, but this is mostly a convenient way to produce a checksum of their contents. They’re not really intended to live in a hashtable.

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.