Google is committed to advancing racial equity for Black communities. See how.

fuchsia.modular

PROTOCOLS

Agent

Defined in fuchsia.modular/agent.fidl

An agent is a component whose lifecycle is not tied to any Story.

  • An agent is a singleton instance.
  • Components can connect to an Agent using the fuchsia.modular.ComponentContext capability.
  • An agent vends services to components that connect to it over a ServiceProvider.
  • An agent is started when someone wants to connect to it, or when a task it has scheduled has triggered.

This FIDL interface should be implemented by a component that is meant to be run as an Agent.

When an agent application implements the Lifecycle interface, it can receive a signal for when it should stop. An agent may be stopped for the following reasons:

(1) All AgentController connections associated with this agent are closed.

(2) The system wants to optimize for resources.

Once the framework delivers a Lifecycle.Terminate(), the agent application may exit itself, or is killed by framework after a timeout.

For more info see:

  • fuchsia.modular.AgentContext and fuchsia.modular.ComponentContext for capabilities an agent has.
  • fuchsia.modular.Lifecycle for how Components get lifecycle events.

Connect

Called when some component tries to connect to this agent. requestor_url identifies the requesting client. Different client roles are identified differently: * For Module clients in the general case, requestor_url will be the name provided at Module create time (ie, in calls to StoryPuppetMaster's StoryCommand.AddMod/mod_name) with :'s escaped (see below for a complete explanation). * For all other clients (Agents and Shells), requestor_url is set to the requesting component's URL.

services must be connected to an implementation of fuchsia.sys.ServiceProvider offering services specific to the requesting client.

Details on module naming: modules are named hierarchically based on what client created them. This is called a module path. If created by 1) an agent or 2) an existing module, the path is constructed differently.

In the case of (2), the module path is the concatenation of the existing module's path with the new module's name, as provided by the parent module. In the case of (1), the module path is the concatenation of StoryCommand.AddMod/mod_name and StoryCommand.AddMod/surface_relation_parent.

The full path is encoded into requestor_url as escape_colons(module_path).join(':').

Request

NameType
requestor_url string
services request<fuchsia.sys/ServiceProvider>

AgentContext

Defined in fuchsia.modular/agent_context.fidl

An instance of this service is exposed to agents in their namespace.

GetComponentContext

DEPRECATED: ComponentContext is now available in the namespace/environment for Modules.

Request

NameType
request request<ComponentContext>

AgentController

Defined in fuchsia.modular/agent_controller.fidl

This interface is used by the caller of ComponentContext::DeprecatedConnectToAgent() to tell the framework that it is still interested in keeping this Agent running.

The system counts AgentController connections and terminates this Agent if the count goes to zero.

ComponentContext

Defined in fuchsia.modular/component_context.fidl

Provided to all component instances in their respective initialization information by the framework. For example, a Module gets it from its ModuleContext and an Agent gets it from its AgentContext.

DeprecatedConnectToAgent

DEPRECATED: use the component's incoming namespace (for C++, see sys.ComponentContext) to connect to services provided by agents. See /docs/concepts/modular/guide/how_to_write_an_agent_cc.md for an example.

Used to start an agent in the user scope if it isn't already running, and connect to it.

Request

NameType
url string
incoming_services request<fuchsia.sys/ServiceProvider>
controller request<AgentController>

DeprecatedConnectToAgentService

DEPRECATED: use the component's incoming namespace (for C++, see sys.ComponentContext) to connect to services provided by agents. See /docs/concepts/modular/guide/how_to_write_an_agent_cc.md for an example.

Connects to an agent that provides the given request.service_name, and then connects the given request.channel to that service.

If an error is encountered, the request.channel will be closed with a status code, such as:

  • ZX_ERR_NOT_FOUND -- if a request.handler agent URL is not specified, and an agent for the request.service_name is not found
  • ZX_ERR_PEER_CLOSED -- if request.service_name is not available from the agent (either specified or discovered)

Request

NameType
request AgentServiceRequest

FocusController

Defined in fuchsia.modular/focus.fidl

This file has interfaces for 2 pieces of information: (1) The story that is currently in focus and (2) stories that are visible to the user. Names of interfaces follow the usual patterns:

{Focus,VisibleStories}Controller is used by session shell to update information whenever changes take place.

FocusProvider is used by session shell to query and get updates on which story is in focus on which device and visible stories on this device.

Implemented by sessionmgr. Given to session shell through its namespace.

Set

Request

NameType
focused_story_id string?

WatchRequest

Request

NameType
watcher FocusRequestWatcher

FocusProvider

Defined in fuchsia.modular/focus.fidl

Implemented by sessionmgr. Given to session shell and session agents through their namespace. Focus is persisted on the ledger.

Query

Returns the stories that are focused across all devices.

Request

NameType

Response

NameType
focused_stories vector<FocusInfo>

Request

Requests session shell to change focus on this device. If session shell responds to this request, focus shall be taken away from previously focused story and an update will be sent on FocusWatcher.OnFocusChange(). If story_id is NULL, the timeline is brought back into focus.

Request

NameType
story_id string?

Watch

Watches for change in focus on any of the user's devices.

Request

NameType
watcher FocusWatcher

FocusRequestWatcher

Defined in fuchsia.modular/focus.fidl

Implemented by session shell. OnFocusRequest() gets called whenever there is a new request to change focus on this device. Requests can be made via FocusProvider.Request().

OnFocusRequest

Request

NameType
story_id string

FocusWatcher

Defined in fuchsia.modular/focus.fidl

Implemented by anyone who is interested in getting updates when focus changes.

OnFocusChange

Request

NameType
focus_info FocusInfo?

Lifecycle

Defined in fuchsia.modular/lifecycle.fidl

An interface implemented by applications that wish to terminate gracefully.

Terminate

The client of this application has requested that this application terminate gracefully.

If the application does not terminate itself in a timely manner, the client may forcibly terminate the application.

Request

NameType

ModuleContext

Defined in fuchsia.modular/module_context.fidl

This interface is exposed to all Module instances in a story. It allows to create Link instances and run more Module instances.

RemoveSelfFromStory

When a module calls [RemoveSelfFromStory()] the framework will stop the module and remove it from the story. If there are no more running modules in the story the story will be deleted.

Request

NameType

ModuleController

Defined in fuchsia.modular/module_controller.fidl

This interface is used by the caller of ModuleContext.StartModule() to control the started Module instance.

Closing this connection doesn't affect its Module instance; it just relinquishes the ability of the caller to control the Module instance.

Defocus

Requests that this module be hidden in the story.

Request

NameType

Focus

Requests that this module become the focused module in the story.

Request

NameType

OnStateChange

Called with the current state when it changes. DEPRECATED: Do not use this. ModuleState is a framework-internal concept and should not be exposed outside.

Response

NameType
new_state ModuleState

Stop

Requests the Module instance to stop. The running Module component's Lifecycle::Terminate() method is called, the instance is shut down and state within the framework is cleaned up.

The result callback is called once the Module's runtime has been torn down.

Request

NameType

Response

NameType

OngoingActivity

Defined in fuchsia.modular/module_context.fidl

This interface defines the protocol over which a Module can communicate about an ongoing activity to the framework. It is provided to Modules via ModuleContext.StartOngoingActivity().

PuppetMaster

Defined in fuchsia.modular/puppet_master.fidl

ControlStory

Request

NameType
story_name string
request request<StoryPuppetMaster>

DeleteStory

Request

NameType
story_name string

Response

NameType

GetStories

Request

NameType

Response

NameType
story_names vector<string>

SessionRestartController

Defined in fuchsia.modular/session_restart_controller.fidl

A capability, typically offered from sessionmgr to select child components, allowing them to request the session to be restarted.

Restart

Requests to cleanly terminate and then immediately restart the session.

Request

NameType

SessionShell

Defined in fuchsia.modular/session_shell.fidl

This interface is implemented by a session shell and is used by the sessionmgr to hand to the session shell views of stories, or to notify that the view of a story is about to be closed.

AttachView

Displays the given story view. The story this view belongs to is identified by view_id.story_id. DEPRECATED. For transitional purposes only.

Request

NameType
view_id ViewIdentifier
view_holder_token fuchsia.ui.views/ViewHolderToken

AttachView2

Request

NameType
view_id ViewIdentifier
view_holder_token fuchsia.ui.views/ViewHolderToken

DetachView

Instructs the session shell to detach the view identified by view_id that was previously provided by AttachView() from the UI of the session shell. The view will be closed soon after DetachView() returns, or when a timeout is reached.

It is customary for the session shell to display a placeholder before a view is attached for a given view identifier, or after it was detached.

If the story identified by view_id.story_id is about to be deleted, the Shell will observe a call to StoryProviderWatcher.OnDelete() sometime after DetachView() returns.

If the session for which this session shell is responsible for is being terminated, or the session shell is stopped because it's replaced by another session shell, DetachView() will not be called at all, and the shell will rather observe a call to Lifecycle.Terminate().

Request

NameType
view_id ViewIdentifier

Response

NameType

SessionShellContext

Defined in fuchsia.modular/session_shell.fidl

This interface allows a SessionShell to request capabilities from its creator in a way that is more explicit about the services that are offered than a generic ServiceProvider.

GetComponentContext

Request

NameType
request request<ComponentContext>

GetFocusController

Request

NameType
request request<FocusController>

GetFocusProvider

Request

NameType
request request<FocusProvider>

GetPresentation

Request

NameType
request request<fuchsia.ui.policy/Presentation>

GetStoryProvider

Request

NameType
request request<StoryProvider>

Logout

Deprecated: Equivalent to Restart().

Request

NameType

Restart

Restarts the session.

Request

NameType

SessionShellPresentationProvider

Defined in fuchsia.modular/session_shell.fidl

Session shell provides this service to the framework which may plumb it to different subscribers, such as story shell and intelligence provider.

EXPERIMENTAL Service that allows consumers of a given story to get a connection to a Presentation, and visual state services provided by the user shell. This allows story shell implementations to coordinate event and focus handling. An analog mechanism exists between BaseShell and SessionShell.

GetPresentation

When a StoryShell calls StoryShellContext.GetPresentation(), this request arrives here.

Request

NameType
story_id string
request request<fuchsia.ui.policy/Presentation>

WatchVisualState

When a StoryShell calls StoryShellContext.WatchVisualState(), this request arrives here.

Request

NameType
story_id string
watcher StoryVisualStateWatcher

StoryController

Defined in fuchsia.modular/story_controller.fidl

Used by the clients of StoryProvider (SessionShell) to interact with a single story. Created by StoryProvider.

If StoryController is closed, the StoryState associated with this story does not change.

Annotate

Attach the annotations to the story.

Existing annotations with the same key will be overwritten.

Request

NameType
annotations vector<Annotation>[50]

Response

NameType
result StoryController_Annotate_Result

GetInfo

Gets information associated with the story.

Request

NameType

Response

NameType
info StoryInfo
state StoryState

GetInfo2

For transition purposes only.

Request

NameType

Response

NameType
info StoryInfo2
state StoryState

RequestStart

Requests to run the story controlled by this StoryController instance. When the story starts, if not yet running, the view of the newly started story shell will be passed in a call to SessionShell.AttachView().

Request

NameType

Stop

Requests to stop the story controlled by this StoryController. If Start() requests are pending when this request is issued, the request is queued until the Start() requests complete. Before stopping the story, a snapshot of the story will be taken and saved. Returns when the story is stopped.

Request

NameType

Response

NameType

Watch

Registers a watcher for changes of the story state.

Note that stories can stop themselves at any time and it is advisable for the holder of a StoryController to provide a watcher.

Request

NameType
watcher StoryWatcher

StoryProvider

Defined in fuchsia.modular/story_provider.fidl

Sessionmgr passes a connection to this service to the SessionShell so it can operate on stories for the user.

Closing a StoryProvider connection has no effect on the state of the framework.

GetController

Obtains a controller for a previously created story identified by its story ID. Obtaining the controller doesn't run it yet. If the story doesn't exist, the interface request is closed.

Request

NameType
story_id string
request request<StoryController>

GetStories

Returns a list of existing stories. If watcher is provided, the client will be notified of story changes (new stories, deleted stories, runtime state changes).

Request

NameType
watcher StoryProviderWatcher?

Response

NameType
story_infos vector<StoryInfo>

GetStories2

For transition purposes only.

Request

NameType
watcher StoryProviderWatcher?

Response

NameType
story_infos vector<StoryInfo2>

GetStoryInfo

Requests detailed information about the given story. If the story doesn't exist, returns null.

Request

NameType
story_id string

Response

NameType
story_info StoryInfo?

GetStoryInfo2

For transition purposes only.

Request

NameType
story_id string

Response

NameType
story_info StoryInfo2

Watch

Registers a watcher for changes in the story collection. DEPRECATED: In favor of GetStories().

Request

NameType
watcher StoryProviderWatcher

StoryProviderWatcher

Defined in fuchsia.modular/story_provider.fidl

Implemented by clients of StoryProvider.

OnChange

Called in three different situations:

  • Immediately when a new watcher is registered with one OnChange() invocation with the current infor and state of each story known on the current device.

  • Every time a change to StoryInfo is applied to the record of the story kept on the current device, including a new story created on another device becoming known on this device for the first time.

  • Every time the StoryState of the story changes on this device. The StoryState on another device of a story known on this device is not made known on this device.

  • Every time the StoryVisibilityState of the story changes on this device. The StoryVisibilityState on another device of a story known on this device is not made known on this device.

    I.e. if the story is started or stopped on another device, it does not cause an OnChange() call on this device. Cf. OnDelete() below.

The ID of the story the notifications are about are part of StoryInfo.

story_state is STOPPED if the story was just created or just became known on this device and was not yet started on the current device. It's RUNNING when the story is started on the current device.

story_visibility_state is DEFAULT until a mod on the current device requests for the visibility state to be changed.

Request

NameType
story_info StoryInfo
story_state StoryState
story_visibility_state StoryVisibilityState

OnChange2

For transition purposes only.

Request

NameType
story_info StoryInfo2
story_state StoryState
story_visibility_state StoryVisibilityState

OnDelete

Called when a story record is permanently deleted. The deletion could have originated on this or on another device.

If the story is running on this device at the time it is deleted, OnChange() will not be called first.

Request

NameType
story_id string

StoryPuppetMaster

Defined in fuchsia.modular/puppet_master.fidl

Annotate

Attach the annotations to the story. If the story does not yet exist, it will be created.

Existing annotations with the same key will be overwritten, or deleted if new value is null.

Request

NameType
annotations vector<Annotation>[50]

Response

NameType
result StoryPuppetMaster_Annotate_Result

Enqueue

Request

NameType
commands vector<StoryCommand>

Execute

Request

NameType

Response

NameType
result ExecuteResult

SetStoryInfoExtra

Request

NameType
story_info_extra vector<StoryInfoExtraEntry>

Response

NameType
result StoryPuppetMaster_SetStoryInfoExtra_Result

WatchAnnotations

Returns the annotations attached to this story.

This is a "hanging get" that returns the current annotations on first call, and on subsequent calls returns the full set of annotations once they are updated.

Returns AnnotationError.NOT_FOUND if the story does not exist.

Request

NameType

Response

NameType
result StoryPuppetMaster_WatchAnnotations_Result

StoryShell

Defined in fuchsia.modular/story_shell.fidl

This interface is implemented by a story shell. Dependencies are passed to it in Initialize() on startup. The story shell is also expected to implement Lifecycle in order to receive a Terminate() call on teardown.

In one component instance there can only be one StoryShell service instance. The view token is sent to the separate View service. This way, the story shell may be implemented as a flutter component.

Teardown may occur via the session shell calling StoryController.Stop(), the sessionmgr being terminated, or by the system shutting down.

AddSurface

Adds a new Surface and its corresponding view to be displayed by the StoryShell. More context that allows the story shell to decide how to layout will be added later. Also, interface to influence life cycle and focus is obviously missing. view_connection the new view and the associated Surface ID. surface_info metadata relating to the Surface.

Request

NameType
view_connection ViewConnection
surface_info SurfaceInfo

AddSurface2

DEPRECATED. For transition purposes only.

Request

NameType
view_connection ViewConnection2
surface_info SurfaceInfo

AddSurface3

For transition purposes only.

Request

NameType
view_connection ViewConnection
surface_info SurfaceInfo2

DefocusSurface

Defocuses the surface with surface_id, dismissing it to the background.

Request

NameType
surface_id string

Response

NameType

FocusSurface

Focuses the surface with surface_id, bringing it to the foreground.

Request

NameType
surface_id string

Initialize

Request

NameType
story_shell_context StoryShellContext

OnSurfaceFocused

Notify when a Surface is focused in the story. The focus could be from a user interaction or requested by the framework through StoryController#FocusModule. EXPERIMENTAL

Response

NameType
surface_id string

RemoveSurface

Remove the Surface with surface_id from the StoryShell entirely. This is final. The Surface is removed from the graph. If necessary, the associated Surface is defocused. There is no expectation that DefocusSurface is called before this.

Request

NameType
surface_id string

UpdateSurface

Update the surface This is called when the intent is to update the surface metadata in the story graph in place. Any fields, except for the surface_id can be updated. If no value or null is passed for a field it remains unchanged. This includes the view_holder_token inside the connection.

E.g called when an intent resolves to a module that is known by the caller to already be running, to update associated metadata.

Request

NameType
view_connection ViewConnection
surface_info SurfaceInfo

UpdateSurface2

DEPRECATED. For transition purposes only.

Request

NameType
view_connection ViewConnection2
surface_info SurfaceInfo

UpdateSurface3

For transition purposes only.

Request

NameType
view_connection ViewConnection
surface_info SurfaceInfo2

StoryShellContext

Defined in fuchsia.modular/story_shell.fidl

This interface provides the StoryShell instance with everything it needs to know or be able to do about the Story. Not much right now, but we expect this to increase.

GetPresentation

Requests a Presentation connection from the SessionShell. See SessionShellPresenationProvider in session_shell.fidl.

Request

NameType
request request<fuchsia.ui.policy/Presentation>

RequestView

Requests a view for a Surface. Requests that a view for surface_id is provided through StoryShell.ReconnectView().

Request

NameType
surface_id string

WatchVisualState

Starts watching Story shell's visual state.

Request

NameType
watcher StoryVisualStateWatcher

StoryShellFactory

Defined in fuchsia.modular/story_shell_factory.fidl

StoryShellFactory creates or returns an existing StoryShell for a particular story. This is intended to be implemented by session shells that want to implement StoryShell functionality themselves.

AttachStory

Requests a StoryShell for the story with the given story_id.

Request

NameType
story_id string
story_shell request<StoryShell>

DetachStory

Instructs the session shell to teardown the story shell with the given story_id. This will be called before the story is stopped.

Request

NameType
story_id string

Response

NameType

StoryVisualStateWatcher

Defined in fuchsia.modular/story_shell.fidl

Implemented by StoryShell to get notified about visual state changes.

OnVisualStateChange

Request

NameType
visual_state StoryVisualState

StoryWatcher

Defined in fuchsia.modular/story_controller.fidl

Implemented by the client calling StoryController.Watch().

OnModuleAdded

DEPRECATED

Request

NameType
module_data ModuleData

OnModuleFocused

DEPRECATED

Request

NameType
module_path vector<string>

OnStateChange

Called with the current state right after registration, and subsequently when the state changes.

Request

NameType
new_state StoryState

STRUCTS

AddMod

Defined in fuchsia.modular/story_command.fidl

Adds a mod described by intent to the story with name mod_name. If mod_name already exists in the story, the mod is updated.

NameTypeDescriptionDefault
mod_name vector<string>

The name of the mod within the story. The mod's name acts as the unique ID of the mod, scoped to the story in which it is contained. Since AddMod is reused for observation and mod names are vector inside the framework, they are vector here as well.

Clients should treat the full vector as a single opaque value.

Clients should provide mod_name_transitional instead. If both are provided, mod_name is ignored.

No default
mod_name_transitional string?

The name of the mod within the story. This should be used instead of mod_name. If provided, it is equivalent to passing mod_name with a single item. If both are provided, mod_name is ignored.

No default
intent Intent No default
surface_relation SurfaceRelation

surface_relation defines the visual relationship between this mod and the mod at surface_parent_mod_name.

No default
surface_parent_mod_name vector<string>? No default

Annotation

Defined in fuchsia.modular/annotation.fidl

A user-defined annotation for a story or module.

NameTypeDescriptionDefault
key AnnotationKey

An identfier for this annotation.

No default
value AnnotationValue?

The contents of this annotation.

No default

ExecuteResult

Defined in fuchsia.modular/puppet_master.fidl

NameTypeDescriptionDefault
status ExecuteStatus No default
story_id string? No default
error_message string? No default

FocusInfo

Defined in fuchsia.modular/focus.fidl

Specifies the focused story of a device.

NameTypeDescriptionDefault
focused_story_id string?

The id of the focused story. If null, no stories are focused.

No default
last_focus_change_timestamp uint64

The time the focused story on the device device_id was last changed. 0 if no focus has ever been set for device device_id.

No default

FocusMod

Defined in fuchsia.modular/story_command.fidl

Instructs the session shell to focus the mod under mod_name.

NameTypeDescriptionDefault
mod_name vector<string>

The name of the mod within the story.

Clients should provide mod_name_transitional instead. If both are provided, mod_name is ignored.

No default
mod_name_transitional string?

The name of the mod within the story. This should be used instead of mod_name. If provided, it is equivalent to passing mod_name with a single item. If both are provided, mod_name is ignored.

No default

Intent

Defined in fuchsia.modular/intent.fidl

The Intent struct is a runtime descriptor for an abstract action to be initiated in Fuchsia. For details please see docs/intent.md.

NameTypeDescriptionDefault
action string?

The name of the action represented by this Intent.

This is nullable for backwards compatibility.

No default
handler string?

An explicit handler for the Intent. Specified as the component URL of the module.

No default
parameters vector<IntentParameter>?

NON-FUNCTIONAL: parameters is no longer supported but must remain for ABI compatibility.

No default

IntentFilter

Defined in fuchsia.modular/module_manifest.fidl

This struct is used to describe an intent that a module is able to handle.

NameTypeDescriptionDefault
action string

The action this module is able to handle.

No default
parameter_constraints vector<ParameterConstraint>

Includes the name and types of entities for the parameters required to execute specified [action].

No default
action_display ActionDisplay

Defines presentation properties for suggestions of this action.

No default

IntentParameter

Defined in fuchsia.modular/intent.fidl

NON-FUNCTIONAL: IntentParameter is no longer supported but must remain for ABI compatibility. A struct representing a parameter that is passed to the handler of an Intent's Action.

NameTypeDescriptionDefault
name string?

The name of the parameter. The handler (i.e. selected mod) will be provided with the data for this parameter under a link called name.

No default
data IntentParameterData

The data that will be passed to the intent handler.

No default

ModuleManifest

Defined in fuchsia.modular/module_manifest.fidl

Metadata that define the runtime properties of a Module.

NameTypeDescriptionDefault
binary string

The relative path from the root of the package where the Module executable file can be found. TODO(MF-94): Extract a module's URL from its cmx manifest instead of here.

No default
suggestion_headline string?

A human-readable string that can be used when suggesting this Module. DEPRECATED.

No default
intent_filters vector<IntentFilter>?

A list of intents that this module is able to handle.

No default
composition_pattern string?

Identifies the pattern with which to compose this module with others.

No default
placeholder_color string?

Defines the color of the placeholder widget used while the module loads.

No default

ParameterConstraint

Defined in fuchsia.modular/module_manifest.fidl

NameTypeDescriptionDefault
name string No default
type string

The entity type that is valid for this parameter.

No default

RemoveMod

Defined in fuchsia.modular/story_command.fidl

Removes the mod under mod_name from the story.

NameTypeDescriptionDefault
mod_name vector<string>

The name of the mod within the story.

Clients should provide mod_name_transitional instead. If both are provided, mod_name is ignored.

No default
mod_name_transitional string?

The name of the mod within the story. This should be used instead of mod_name. If provided, it is equivalent to passing mod_name with a single item. If both are provided, mod_name is ignored.

No default

SetFocusState

Defined in fuchsia.modular/story_command.fidl

NameTypeDescriptionDefault
focused bool No default

StoryController_Annotate_Response

Defined in fuchsia.modular/story_controller.fidl

NameTypeDescriptionDefault

StoryInfo

Defined in fuchsia.modular/story_info.fidl

Information about a story as provided to the SessionShell.

NameTypeDescriptionDefault
url string?

URL of the first module run in this story. This module is free to run more modules in the story. Used for display purposes only.

No default
id string

The ID of the Story, used to reference it in method arguments.

No default
last_focus_time int64

Wallclock time when the story was last focused. From ZX_CLOCK_UTC, thus nanoseconds since UNIX epoch (1970-01-01 00:00 UTC).

A value of zero means the story has never been focused.

No default
extra vector<StoryInfoExtraEntry>?

Data the SessionShell wants to keep associated with this Story, like title, a color, or a display rank.

No default

StoryInfoExtraEntry

Defined in fuchsia.modular/story_info.fidl

NameTypeDescriptionDefault
key string No default
value string No default

StoryOptions

Defined in fuchsia.modular/story_options.fidl

NameTypeDescriptionDefault
kind_of_proto_story bool

Whether or not the story will be hidden on a call to StoryProvider#GetStories.

No default

StoryPuppetMaster_Annotate_Response

Defined in fuchsia.modular/puppet_master.fidl

NameTypeDescriptionDefault

StoryPuppetMaster_SetStoryInfoExtra_Response

Defined in fuchsia.modular/puppet_master.fidl

NameTypeDescriptionDefault

StoryPuppetMaster_WatchAnnotations_Response

Defined in fuchsia.modular/puppet_master.fidl

NameTypeDescriptionDefault
annotations vector<Annotation>[100] No default

SurfaceInfo

Defined in fuchsia.modular/story_shell.fidl

Contains metadata for a Surface.

NameTypeDescriptionDefault
parent_id string

ID of the view that is parent of this Surface.

No default
surface_relation SurfaceRelation?

The relationship between the parent Surface and this new Surface. Used for layout optimization.

No default
module_manifest ModuleManifest?

Information about the module populates the view.

No default
module_source ModuleSource

How the Surface was generated. By an action internal to the story or by an external action.

No default

SurfaceRelation

Defined in fuchsia.modular/surface.fidl

Describes the relationship between two Surfaces. Provides information to the StoryShell for layout optimization.

NameTypeDescriptionDefault
arrangement SurfaceArrangement

Advice on arranging these surfaces on the screen together.

SurfaceArrangement.NONE
dependency SurfaceDependency

Advice for dismissal of surfaces to be linked.

SurfaceDependency.NONE
emphasis float32

Relative emphasis of the child surface, relative to the parent. Influences relative areas of surfaces on screen.

1

ViewConnection

Defined in fuchsia.modular/story_shell.fidl

A pair mapping a surface ID to a view (via view_holder_token).

NameTypeDescriptionDefault
surface_id string

The ID for the surface

No default
view_holder_token fuchsia.ui.views/ViewHolderToken

Token for embedding the new view corresponding to the surface.

No default

ViewConnection2

Defined in fuchsia.modular/story_shell.fidl

DEPRECATED, for transition purposes only.

NameTypeDescriptionDefault
surface_id string

The ID for the surface

No default
view_holder_token fuchsia.ui.views/ViewHolderToken

Token for embedding the new view corresponding to the surface.

No default

ViewIdentifier

Defined in fuchsia.modular/session_shell.fidl

Identifies a view provided to a session shell. The values of the story_id field match those used in the StoryProvider interface, allowing identification of the same story across interfaces.

This is a struct rather than a naked string to allow for future evolution of the identifier without changing the SessionShell API itself.

NameTypeDescriptionDefault
story_id string No default

ENUMS

AnnotationError

Type: uint32

Defined in fuchsia.modular/annotation.fidl

Error returned from calls to Annotate().

NameValueDescription
VALUE_TOO_BIG 1

The AnnotationValue.buffer size exceeds the maximum length, MAX_ANNOTATION_VALUE_BUFFER_LENGTH_BYTES.

TOO_MANY_ANNOTATIONS 2

The total number of annotations on the story or module being annotated exceeds MAX_ANNOTATIONS_PER_STORY or MAX_ANNOTATIONS_PER_MODULE.

NOT_FOUND 3

The resource to be annotated was not found and could not be resolved by, for example, waiting, or creating the missing resource automatically. This error may be returned by StoryPuppetMaster.AnnotateModule(), which can wait for a missing Module, but requires the Module's Story exist.

ConfigureStoryError

Type: int32

Defined in fuchsia.modular/puppet_master.fidl

NameValueDescription
ERR_STORY_ALREADY_CREATED 1

The story cannot be (re)configured because it was already created.

ExecuteStatus

Type: uint32

Defined in fuchsia.modular/puppet_master.fidl

NameValueDescription
OK 0
INVALID_COMMAND 1
INVALID_STORY_ID 2
STORY_MUST_HAVE_MODS 3
INVALID_MOD 4
NO_MODULES_FOUND 5
INTERNAL_ERROR 6

ModuleSource

Type: uint32

Defined in fuchsia.modular/module_data.fidl

NameValueDescription
INTERNAL 0

Module that was added to the story from within the story by another module using ModuleContext.AddModuleToStory() or ModuleContext.EmbedModule().

EXTERNAL 1

Module that was added to the story from outside the story using PuppetMaster.

ModuleState

Type: uint32

Defined in fuchsia.modular/module_state.fidl

State used to notify about state transitions of a Module instance. This is very similar to the StoryState, however it's not entirely the same and hence a separate type. A module cannot have an INITIAL state, because it's started as soon as it is created, and it gets deleted as soon as it reaches the STOPPED state, whileas a story can be restarted.

Currently possible state transitions (and the events that cause them) are:

        -> RUNNING     ModuleContext.AddModuleToStory() or
                       ModuleContext.EmbedModule() or
                       StoryController.AddModule()

RUNNING -> STOPPED ModuleController.Stop() or StoryController.Stop() RUNNING -> ERROR application exits

NameValueDescription
RUNNING 2

Module instance was created.

STOPPED 4

Module instance is stopped after Module.Stop(). No further transitions are to be expected.

ERROR 5

Connection to the Module instance was closed without Stop() request. No further transitions are to be expected.

OngoingActivityType

Type: uint32

Defined in fuchsia.modular/module_context.fidl

NameValueDescription
UNSPECIFIED 0
VIDEO 1
AUDIO 2

StoryState

Type: uint32

Defined in fuchsia.modular/story_state.fidl

State of a Story. A story is either running, stopping, or stopped, separately on every device of the user. If it's running, it can also be focused, but that's tracked in a separate service, cf. FocusProvider in focus.fidl.

Possible state transitions are:

STOPPED -> RUNNING RUNNING -> STOPPING STOPPING -> STOPPED

NameValueDescription
RUNNING 1

Story was started using StoryController.Start().

STOPPING 2

Story is in the middle of stopping after StoryController.Stop() was called.

STOPPED 3

Story was not yet run, or Story was stopped after StoryController.Stop() was called.

StoryVisibilityState

Type: uint32

Defined in fuchsia.modular/story_visibility_state.fidl

Visibility state of a Story within the session shell. This state describes how a story should be displayed within the session shell, regardless of whether the story is in focus or not. Focus state and visibility state are orthogonal concepts. E.g A story can be out-of-focus and be in IMMERSIVE state at the same time if a user was playing a video, exits, then re-enters the story. The expectation in this scenario is that the story is in IMMERSIVE state upon re-enter.

All state transitions are possible.

NameValueDescription
DEFAULT 1

Default state for a story.

IMMERSIVE 2

Full-screen user experience, e.g. playing a video.

StoryVisualState

Type: uint32

Defined in fuchsia.modular/story_shell.fidl

Defines the visual state of the Story shell.

NameValueDescription
MINIMIZED 0
MAXIMIZED 1
MAXIMIZED_OVERLAYED 2

SurfaceArrangement

Type: uint32

Defined in fuchsia.modular/surface.fidl

Expresses arrangement type.

NameValueDescription
NONE 0

No arrangement specified.

COPRESENT 1

Desire to present simultaneously.

SEQUENTIAL 2

The parent prefers to not be presented simultaneously with its child. (The child may still become part of a simultaneous presentation depending on the relationships between it and subsequently added surfaces).

ONTOP 3

Place this surface on top of and obscuring the parent surface. This is a complete replacement, not a modal or inset presentation.

SurfaceDependency

Type: uint32

Defined in fuchsia.modular/surface.fidl

Links surface dismissal.

NameValueDescription
NONE 0

No dependency specified.

DEPENDENT 1

Child is dependent on parent. If parent is dismissed, child is dismissed as well.

TABLES

ActionDisplay

Defined in fuchsia.modular/module_manifest.fidl

Defines how a suggestion of an action will be presented.

OrdinalNameTypeDescription
1 display_info DisplayInfo

Defines presentation fields for a suggestion. The string fields might be templated and will be filled from data in parameter_mapping. For example: "Listen to $artistName"

2 parameter_mapping vector<ParameterMapping>

Fields to be replaced in the given display_info templated strings. In the example above, we would map name=artistName to the intent field artist.name where artist is the intent parameter name and name a field of it.

AgentServiceRequest

Defined in fuchsia.modular/component_context.fidl

Used by ComponentContext.ConnectToAgentService

OrdinalNameTypeDescription
1 service_name string

The name of the requested service.

2 channel handle<channel>

The channel that will be used to communicate with the requested service.

3 handler fuchsia.sys/component_url

The component URL of the Agent that is to provide the specified service. If no handler is specified, the framework will perform resolution to find an appropriate handler.

4 agent_controller request<AgentController>

The AgentController handle is optional. If provided, the channel will be kept open until the agent providing service_name is terminated.

DisplayInfo

Defined in fuchsia.modular/module_manifest.fidl

Presentation information about the suggestion.

OrdinalNameTypeDescription
1 title string

The title of the suggestion.

2 subtitle string

A subtitle for the suggestion.

3 icon string

A url from which to fetch the icon of the suggestion.

ModuleData

Defined in fuchsia.modular/module_data.fidl

Information about a Module instance in a story.

OrdinalNameTypeDescription
1 module_url string

The URL of the Module binary.

2 module_path vector<string>

The named path leading up to this Module instance. The last name in this array is the name by which the Module was started by the parent Module instance calling StartModule().

3
4 module_source ModuleSource

The way in which this Module instance was first started in the story, either by request from another Module instance (INTERNAL) or by request from outside the story (i.e. by suggestion from an agent - EXTERNAL).

5 surface_relation SurfaceRelation

The surface_relation that was used to start this Module instance with. The same is used when re-inflating the Module instance when the story is resumed. A SurfaceRelation value of null represents an embedded Module instance (started by EmbedModule()) that is not managed by the story shell.

6 module_deleted bool

True if this module was removed from its story either through ModuleController.Stop() or ModuleContext.RemoveSelfFromStory().

7 intent Intent

The intent that was issued to start add this Module instance to the story. Some Module instances may have been added not by an Intent, for example as the initial module of a story. For those the field may be null.

TODO(thatguy,mesch): This field should now always be set, so make it required once the framework is cleaned up enough to guarantee this statement.

8 is_embedded bool

If true, this module was started by a parent module using ModuleContext.EmbedModule(), and its view is not managed by the StoryShell.

9 annotations vector<Annotation>[100]

Collection of user-defined key-value attributes that describe this surface (module).

The Annotation.value field of each Annotation is always set.

ParameterMapping

Defined in fuchsia.modular/module_manifest.fidl

Defines pairs that will be replaced in the DisplayInfo.

OrdinalNameTypeDescription
1 name string

The name of the variable to be replaced in the template.

2 parameter_property string

The path in the intent parameter to get that name. PARAMETER_PROPERTY = string | string . PARAMETER_PROPERTY The first string in the dot-separated string is the name of the intent parameter and the following are nested subfields.

StoryInfo2

Defined in fuchsia.modular/story_info.fidl

Information about a story as provided to the SessionShell. For transition purposes only.

OrdinalNameTypeDescription
1 id string

The ID of the Story, used to reference it in method arguments.

2 last_focus_time int64

Wallclock time when the story was last focused. From ZX_CLOCK_UTC, thus nanoseconds since UNIX epoch (1970-01-01 00:00 UTC).

A value of zero means the story has never been focused.

3 annotations vector<Annotation>[100]

Collection of user-defined key-value attributes that describe this story.

The Annotation.value field of each Annotation is always set.

SurfaceInfo2

Defined in fuchsia.modular/story_shell.fidl

Contains metadata for a Surface.

OrdinalNameTypeDescription
1 parent_id string

ID of the view that is parent of this Surface.

2 surface_relation SurfaceRelation

The relationship between the parent Surface and this new Surface. Used for layout optimization.

3 module_manifest ModuleManifest

Information about the module populates the view.

4 module_source ModuleSource

How the Surface was generated. By an action internal to the story or by an external action.

5 annotations vector<Annotation>[100]

Collection of user-defined key-value attributes that describe this surface (module).

The Annotation.value field of each Annotation is always set.

6 view_ref fuchsia.ui.views/ViewRef

The view ref associated with the surface, if one is present.

UNIONS

AnnotationValue

Defined in fuchsia.modular/annotation.fidl

The value of a Annotation.

The actual field used depends on the type of annotation, which is user-defined, and not enforced by the framework.

The size of buffer is limited to MAX_ANNOTATION_VALUE_BUFFER_LENGTH_BYTES bytes.

NameTypeDescription
text string[1024]
bytes vector<uint8>[1024]
buffer fuchsia.mem/Buffer

IntentParameterData

Defined in fuchsia.modular/intent.fidl

NON-FUNCTIONAL: IntentParameterData is no longer supported but must remain defined for IntentParameter's ABI compatibility.

NameTypeDescription
entity_reference string

Set this if you already have an Entity reference at runtime. Entity.getTypes() will be used to set the constraints for this noun during resolution.

json fuchsia.mem/Buffer

Set this if you have structured JSON data. Values typically are a JSON object with a "@type" attribute and other associated data. TODO(thatguy): We need to decide if we want to keep this in place, or deprecate this eventually and move entirely to using Entity references.

DEPRECATED: Use entity_reference.

entity_type vector<string>

Set this if you want to explicitly define this noun's allowed types. This is also useful in the cases where the noun has a 'direction' of type 'output', and you wish to set the allowable output types from the Module (see docs/modular/manifests/action_template.md for a definition of 'direction').

Only one entry in entity_type must match the constraint specified by the Module for the constraint to be considered satisfied.

StoryCommand

Defined in fuchsia.modular/story_command.fidl

StoryCommands are POD structures that describe the set of operations that can be performed on a story by components outside the modular framework. All commands are:

(1) Scoped to a single story (2) Idempotent: issuing the same command twice yields the same result (3) Symmetrical with observation: the same structures are used to describe operations to watchers of a story (through SessionWatcher) as are used to control a story.

NameTypeDescription
set_focus_state SetFocusState

Sets the focus state of the story to set_focus_state.focused.

add_mod AddMod

Adds a Mod.

remove_mod RemoveMod

Removes an existing Mod.

focus_mod FocusMod

Brings focus to a mod.

StoryController_Annotate_Result

Defined in fuchsia.modular/story_controller.fidl

NameTypeDescription
response StoryController_Annotate_Response
err AnnotationError

StoryPuppetMaster_Annotate_Result

Defined in fuchsia.modular/puppet_master.fidl

NameTypeDescription
response StoryPuppetMaster_Annotate_Response
err AnnotationError

StoryPuppetMaster_SetStoryInfoExtra_Result

Defined in fuchsia.modular/puppet_master.fidl

NameTypeDescription
response StoryPuppetMaster_SetStoryInfoExtra_Response
err ConfigureStoryError

StoryPuppetMaster_WatchAnnotations_Result

Defined in fuchsia.modular/puppet_master.fidl

NameTypeDescription
response StoryPuppetMaster_WatchAnnotations_Response
err AnnotationError

CONSTANTS

NameValueTypeDescription
MAX_ANNOTATIONS_PER_MODULE 100 uint32

Maximum number of annotations on a single module.

MAX_ANNOTATIONS_PER_STORY 100 uint32

Maximum number of annotations on a single story.

MAX_ANNOTATIONS_PER_UPDATE 50 uint32

Maximum number of annotations that can be passed to either method Annotate() AnnotateModule() in fuchsia.modular protocols that support annotations.

MAX_ANNOTATION_KEY_LENGTH 256 uint32

Maximum length of AnnotationKey.

MAX_ANNOTATION_VALUE_BUFFER_LENGTH_BYTES 102400 uint32

Maximum length of the AnnotationValue.buffer field, in bytes.

Does not apply to other fields; see MAX_ANNOTATION_VALUE_LENGTH.

MAX_ANNOTATION_VALUE_LENGTH 1024 uint32

Maximum length of AnnotationValue fields: text and bytes.

TYPE ALIASES

NameValueDescription
AnnotationKey string[MAX_ANNOTATION_KEY_LENGTH]

An identifier for an Annotation.