This component provides the shared Cast receiver implementation that is used by various embedders throughout Chromium. It is planned to be used for WebEngine, Chromecast hardware, and others.
The specifics of integrating this component with an existing Chromium embedder are described below. The canonical implementation of this component can be found at //chromecast/cast_core. For specific usages of the below described APIs, see its RuntimeServiceImpl and RuntimeApplicationServiceImpl classes, which use this component to implement a gRPC-defined service.
Integration with an existing Chromium embedder is relateively easy, with only a small number of integration points required:
Browser-side integration has two parts:
The Permissions Manager is used to define the permissions that can be used by a given application. It is integrated into an existing Chromium embedder by calling into the PermissionsManager::GetPermissionsStatus() function from the embedder's implementation of content::PermissionControllerDelegate::GetPermissionStatus().
The remaining integration is done by creating an instance of the ContentBrowserClientMixins class in the ContentBrowserClient implementation for this embedder. For instance, this is currently done in the Cast Core implementation. From there, the OnWebContentsCreated() and CreateURLLoaderThrottles() functions must be called from the ContentBrowserClient functions of the same name.
The embedder may additionally call AddApplicationStateObserver() or AddStreamingResolutionObserver() to subscribe to state change events for the runtime.
Renderer side integration is done very similarly to the runtime hooks for the browser-side integration as described above. Specifically, from the embedder‘s ContentRendererClient implementation, an instance of ContentRendererClientMixins must be created as is currently done in the Cast Core implementation. Then, the functions of this calls must all be called from the appropriate ContentRendererClient functions as outlined in the class’s documentation.
Once the above integration is done, applications can be created by first creating an instance of RuntimeApplicationDispatcher using the ContentBrowserClientMixins::CreateApplicationDispatcher() function, then calling CreateApplication() and providing basic information about the application (such as application id, requested permissions, etc). Note that this requires a template parameter of a type implementing the EmbedderApplication interface.
After creation, an application will always exist in one of the following lifetime states, transitioning between them using functions defined in the RuntimeApplication interface:
RuntimeApplication object has been created, but nothing else has been done.It is expected that the application will be loaded immediately after being created, and then launched shortly after.
When the application is to be destroyed, this can be done through calling RuntimeApplicationDispatcher::DestroyApplication().
Implementing EmbedderApplication is where the majority of the embedder's work is located. Doing so requires the following:
NotifyApplicationStarted(), NotifyApplicationStopped(), and NotifyMediaPlaybackChanged()).GetWebContents() and GetAllBindings()).GetMessagePortService() and GetContentWindowControls()).Implementing this type therefore requires at minimum implementations of the following two embedder-specific classes:
ContentWindowControls: Used for controlling the UX Window associated with this application.MessagePortService: A wrapper around message port functionality, used to handle communication with services outside of this component.When creating an instance of EmbedderApplication through RuntimeApplicationDispatcher, an instance of RuntimeApplication is provided, which can be used for control of this application. Specifically:
Load(), Launch(), and Stop() functions.SetMediaBlocking(), SetVisibility(), SetTouchInputEnabled(), and SetUrlRewriteRules() functions.A pointer to this instance of EmbedderApplication will also be provided to the RuntimeApplicaiton, which will use the callbacks and controls as described previously throughout the application's lifetime.
The top-level object with which the embedder will interact is the ContentBrowserClientMixins class which will be used to create a RuntimeApplicationDispatcher instance. That instance will create RuntimeApplications instances, either StreamingRuntimeApplication or WebRuntimeApplication instances, and then wrap them in an EmbedderApplication instance using a factory provided by the embedder. The EmbedderApplication instance will control the RuntimeApplication with the following commands:
Load()Launch()Stop()Additionally, the RuntimeApplication exposes a number of accessors and ways to set properties of the application, such as enabling or disabling touch input. The EmbedderApplication exposes functions to supply embedder-specific types or commands, such as:
GetAllBindings()GetMessagePortService()GetContentWindowControls()GetStreamingConfigManager()Additionally, it exposes functions by which it may be informed of state changes in the RuntimeApplication instance it owns.
In each of the following diagrams, blue boxes are used to represent embedder-specific infrastructure, while white boxes are part of the component.
This component supports two types of applications: Web Applications and Streaming Applications. Much of the infrastructure for these two application types is shared, but the differences are substantial enough that each will be discussed independently.
Web Applications are used for hosting the majority of applications for a Cast receiver. At a high level, the flow for using a Web Application is:
ContentBrowserClientMixins instance in the embedder-specific ContentBrowserClient implementation, and then use that instance to create a RuntimeApplicationDispatcher.RuntimeApplicationDispatcher to create a WebRuntimeApplication instance, which will then be used to create an instance of the embedder-specific EmbedderApplication type.Load() on the RuntimeApplication instance, and wait for its callback.SetUrlRewriteRules() on the RuntimeApplication. This may be called at any time, but is expected to be called at least once before the Launch() command if such rules are required for the application’s functionality.Launch() on the RuntimeApplication instance, and wait for its callback. Various EmbedderApplication functions will be called to create the necessary resources.StopApplication() and then destroy the application with the RuntimeApplicationDispatcher after the StopApplication()’s callback returns.
Streaming Applications are used to support the Cast streaming and remoting scenarios by making use of the cast_streaming component
ContentBrowserClientMixins instance in the embedder-specific ContentBrowserClient implementation, and then use that instance to create a RuntimeApplicationDispatcher.RuntimeApplicationDispatcher to create a StreamingRuntimeApplication instance, which will then be used to create an instance of the embedder-specific EmbedderApplication type.Load() on the RuntimeApplication instance, and wait for its callback.Launch() on the RuntimeApplication instance, and wait for its callback. Various EmbedderApplication functions will be called to create the necessary resources, which will be used to start the cast_streaming component. Each of the following is expected to occur for the streaming session to successfully begin, but the order may vary:StartPlaybackAsync(), which will be called as part of the Launch() command before its callback is called.WebContents instance associated with this application, as returned by EmbedderApplication::GetWebContents(), loads the page used for displaying the streaming session.ConfigurationManager as provided by EmbedderApplication::GetStreamingConfigManager().OnStreamingResolutionChanged() event will be fired.NotifyApplicationStopped() event will be fired to the EmbedderApplication, at which point the application should be destroyed by the RuntimeApplicationDispatcher.