PROTOCOLS
ComponentController
Defined in fuchsia.sys/component_controller.fidl
An interface for controlling components.
Closing this interface implicitly kills the controlled component unless
the Detach method has been called.
If the component exits, this interface will be closed.
Typically obtained via Launcher.CreateComponent.
Detach
Decouples the lifetime of the component from this controller.
After calling Detach, the component will not be implicitly killed when
this interface is closed.
Request
<EMPTY>
Kill
Terminates the component.
This ComponentController connection is closed when the component has terminated.
Request
<EMPTY>
OnDirectoryReady
Event that is triggered when the component's output directory is mounted.
This event will not be triggered for every component, only those that
serve a directory over their PA_DIRECTORY_REQUEST handle.
Response
<EMPTY>
OnTerminated
Event that is triggered when the component is terminated.
This event provides the return code of the process and reason for its termination. The return_code is only valid if the termination reason is EXITED. If the termination reason is not EXITED, the return code is guaranteed not to be 0.
Response
| Name | Type |
|---|---|
return_code |
int64
|
termination_reason |
TerminationReason
|
Environment
Defined in fuchsia.sys/environment.fidl
An interface for managing a set of applications.
Applications run inside environments, which provide ambient services and support for their lifecycle.
CreateNestedEnvironment
Creates a new environment nested inside this environment.
When applications are created inside the nested environment using the
environment's Launcher, the environment requests the
environment services from host_directory before passing those services to
the newly created application in its StartupInfo.
The controller can be used to control the lifecycle of the created
environment. Note that by default the environment will be killed
automatically when the EnvironmentController's interface is closed. You
can use EnvironmentController.Detach to disable this behavior.
label defines the new environment's label/name. It must be unique within
the parent environment (though not globally) and is used for isolating
separate environments. It can also be used for diagnostic purposes. The
label will be truncated if it is longer than kLabelMaxLength.
additional_services, which may be empty, contains a list of services
that the environment provides, which are hosted by
additional_services.host_directory. If options.inherit_parent_services
is false, host_directory must provide a Loader service if it wishes to
allow new components to be loaded in the new environment.
options provides additional options, see EnvironmentOptions for
details.
Request
| Name | Type |
|---|---|
environment |
server_end<Environment>
|
controller |
server_end<EnvironmentController>
|
label |
string
|
additional_services |
ServiceList?
|
options |
EnvironmentOptions
|
GetDirectory
Gets a superset of services provided by this environment's
host_directory.
Request
| Name | Type |
|---|---|
directory_request |
server_end<fuchsia.io/Directory>
|
GetLauncher
Gets the Launcher associated with this environment.
Applications created using this application launcher will be given the
environment services provided by this environment's host_directory.
Request
| Name | Type |
|---|---|
launcher |
server_end<Launcher>
|
GetServices
Gets a superset of services provided by this environment's
host_directory.
Request
| Name | Type |
|---|---|
services |
server_end<ServiceProvider>
|
EnvironmentController
Defined in fuchsia.sys/environment_controller.fidl
An interface for controlling an environment.
Closing this interface implicitly kills the controlled environment unless
the Detach method has been called.
If the environment is destroyed, this interface will be closed.
Typically obtained via Environment.CreateNestedEnvironment.
Detach
Decouples the lifetime of the environment from this controller.
After calling Detach, the environment will not be implicitly killed when
this interface is closed.
Request
<EMPTY>
Kill
Terminates the environment.
When an Environment is terminated, all applications launched
in the environment (and in all transitively nested environments) are also
killed.
Request
<EMPTY>
Response
<EMPTY>
OnCreated
Event that is triggered when the environment is created.
Response
<EMPTY>
JobProvider
Defined in fuchsia.sys/job_provider.fidl
An interface for providing a job handle. Instances of this interface are created in the context of an already-identified realm, so there is no need to explicitly identify the realm below.
GetJob
Gets the root job associated with the realm.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
job |
handle<job>
|
Launcher
Defined in fuchsia.sys/launcher.fidl
An interface for creating component instances.
Typically obtained via Environment.GetLauncher.
CreateComponent
Creates a new instance of the component described by launch_info.
The component instance is created in the Environment
associated with this Launcher. When creating the component,
the environment requests the environment services for this component from
its EnvironmentHost.
The controller can be used to control the lifecycle of the created
component instance. If an ComponentController's interface is
requested, the component instance is killed when the interface is closed.
Request
| Name | Type |
|---|---|
launch_info |
LaunchInfo
|
controller |
server_end<ComponentController>?
|
Loader
Defined in fuchsia.sys/loader.fidl
An interface for loading from packages.
LoadUrl
Load a package by url. The returned package's data VMO handle will
not have ZX_RIGHT_EXECUTE, but the directory field, if present, will
have both the READABLE and EXECUTABLE rights.
Request
| Name | Type |
|---|---|
url |
component_url
|
Response
| Name | Type |
|---|---|
package |
Package?
|
Runner
Defined in fuchsia.sys/runner.fidl
An interface for running components.
Typically exposed by components that provide execution environments for particular classes of programs. For example, the Dart virtual machine exposes this interface to run Dart programs.
StartComponent
Execute the given component.
Upon startup, the component is to be given the information in
startup_info, but the mechanism by which the component receives that
information is up to the component runner.
The controller interface request typically originates from the
Launcher.CreateComponent message that caused this component to be
started.
Request
| Name | Type |
|---|---|
package |
Package
|
startup_info |
StartupInfo
|
controller |
server_end<ComponentController>?
|
ServiceProvider
Defined in fuchsia.sys/service_provider.fidl
An interface through which a client may request services from a host. Instances of this interface are created within the context of an already-identified client and host pair, so there is no need to explicitly identify the client or host in the methods below.
This interface is deprecated. Services should be published as directory entries instead, just like files.
ConnectToService
Asks the host to provide the service identified by service_name through
the channel endpoint supplied by the caller. If the host is not willing
or able to provide the requested service, it should close the channel.
Request
| Name | Type |
|---|---|
service_name |
string
|
channel |
handle<channel>
|
STRUCTS
EnvironmentOptions
Defined in fuchsia.sys/environment.fidl
| Field | Type | Description | Default |
|---|---|---|---|
inherit_parent_services |
bool
|
True if this environment should inherit services provided by the parent environment. |
No default |
use_parent_runners |
bool
|
True if components in this environment will share a runner provided by the parent environment. If false, a new runner will be started in this environment for components. |
No default |
kill_on_oom |
bool
|
True if this environment should be killed first in out of memory
situations by setting the |
No default |
delete_storage_on_death |
bool
|
True if "persistent" storage requested by components in this environment should not actually be persistent, and instead be deleted when this environment is killed. |
No default |
FileDescriptor resource
Defined in fuchsia.sys/launcher.fidl
An FDIO file descriptor.
| Field | Type | Description | Default |
|---|---|---|---|
type0 |
int32
|
The FDIO types of the handle (e.g., |
No default |
type1 |
int32
|
No default | |
type2 |
int32
|
No default | |
handle0 |
handle<handle>?
|
The handles for the file descriptor (e.g., a channel). |
No default |
handle1 |
handle<handle>?
|
No default | |
handle2 |
handle<handle>?
|
No default |
FlatNamespace resource
Defined in fuchsia.sys/flat_namespace.fidl
| Field | Type | Description | Default |
|---|---|---|---|
paths |
vector<string>
|
The mount point for each of the directories below. For example, ["/pkg", "/svc"]. |
No default |
directories |
vector<fuchsia.io/Directory>
|
Added: 10
|
No default |
LaunchInfo resource
Defined in fuchsia.sys/launcher.fidl
Information used to create an instance of a component and obtain services from it.
| Field | Type | Description | Default |
|---|---|---|---|
url |
component_url
|
The location from which to retrieve this component. This field will probably be replaced with a stronger notion of identity, such as an unforgeable token. This field is included in this iteration to ease the transition from the previous component interfaces. |
No default |
arguments |
vector<string>?
|
The arguments to be provided to the component. |
No default |
out |
FileDescriptor?
|
The file descriptor to use for stdout. If null, the component will use the default stdout for the environment. |
No default |
err |
FileDescriptor?
|
The file descriptor to use for stderr. If null, the component will use the default stderr for the environment. |
No default |
directory_request |
server_end<fuchsia.io/Directory>?
|
Added: 10
|
No default |
flat_namespace |
FlatNamespace?
|
A custom namespace that can be appended to the namespace generated by appmgr and provided to this component. Adding a mount point at standard paths like 'pkg' or 'svc' will be ignored. HACK(alhaad): Adding mount points for deprecated default directories like '/data' will override the default. |
No default |
additional_services |
ServiceList?
|
A list of services to be added to this component's svc namespace. These services are in addition to those coming from Environment. |
No default |
Package resource
Defined in fuchsia.sys/runner.fidl
A binary representation of a component.
Typically provided to Runner.StartComponent when starting a component.
| Field | Type | Description | Default |
|---|---|---|---|
data |
fuchsia.mem/Buffer?
|
A read-only binary representation of the component. For example, if the component is intended to run in the Dart virtual machine, this data might contain a dartx package. |
No default |
directory |
fuchsia.io/Directory?
|
Added: 10
|
No default |
resolved_url |
component_url
|
Resolved URL of the component. This is the url specified in
|
No default |
ProgramMetadata
Defined in fuchsia.sys/runner.fidl
Program information about a component.
| Field | Type | Description | Default |
|---|---|---|---|
key |
string
|
Key for program metadata pair. E.g. "binary" for an ELF binary component, or "data" for a flutter/dart component. |
No default |
value |
string
|
Value for program metadata pair. E.g. "bin/app" for a "binary" key, or "data/foo" for a flutter/dart component. |
No default |
ServiceList resource
Defined in fuchsia.sys/launcher.fidl
| Field | Type | Description | Default |
|---|---|---|---|
names |
vector<string>
|
A list of services that can be requested from |
No default |
provider |
ServiceProvider?
|
A service provider to get the services listed in |
No default |
host_directory |
fuchsia.io/Directory?
|
Added: 10
|
No default |
StartupInfo resource
Defined in fuchsia.sys/runner.fidl
Information given to components at startup.
For ELF binaries, this information is provided in the initialization
message given to libc by fuchsia.process.Launcher.
| Field | Type | Description | Default |
|---|---|---|---|
launch_info |
LaunchInfo
|
The launch info for the component to start. |
No default |
flat_namespace |
FlatNamespace
|
The namespace in which to run the component. |
No default |
program_metadata |
vector<ProgramMetadata>?
|
Key string value string map of the component's program metadata, obtained from its component manifest. |
No default |
ENUMS
TerminationReason strict
Type: uint32
Defined in fuchsia.sys/component_controller.fidl
| Name | Value | Description |
|---|---|---|
UNKNOWN |
0 |
The channel closed without giving a termination reason. |
EXITED |
1 |
Component ran and exited with a given return_code. |
URL_INVALID |
2 |
The given URL given to launch was invalid. |
PACKAGE_NOT_FOUND |
3 |
The requested package could not be found. |
INTERNAL_ERROR |
4 |
An internal error happened during the launch process. |
PROCESS_CREATION_ERROR |
5 |
Process creation failed. |
RUNNER_FAILED |
6 |
A Runner failed to start. |
RUNNER_TERMINATED |
7 |
A Runner terminated while attempting to run a component. |
UNSUPPORTED |
8 |
Attempted to use an unsupported feature. |
REALM_SHUTTING_DOWN |
9 |
Attempted to create a component in a realm which is shutting down. |
ACCESS_DENIED |
10 |
Insufficient privilege to start the component. |
CONSTANTS
| Name | Value | Type | Description |
|---|---|---|---|
| MAX_URL_LENGTH |
2083
|
uint16 |
|
| kLabelMaxLength |
32
|
uint32 |
Maximum length for an environment label. |
ALIASES
| Name | Value | Description |
|---|---|---|
| component_url |
string[MAX_URL_LENGTH] |
A URL used to retrieve, launch, and load a component from a specified network location, or to identify a component when connecting to it. |