[Cast Receiver] Update documentation

This CL extends the existing documentation for the cast_receiver
component with details about the code structure.

Bug: 1357171
Change-Id: I03506393286ce06f7c0476b6588e3d429f587cb1
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4324163
Auto-Submit: Ryan Keane <rwkeane@google.com>
Reviewed-by: Vigen Issahhanjan <vigeni@google.com>
Commit-Queue: Ryan Keane <rwkeane@google.com>
Cr-Commit-Position: refs/heads/main@{#1116515}

components/cast_receiver/README.md

@@ -147,7 +147,130 @@ previously throughout the application's lifetime.
 
 # Architecture
 
-TODO(crbug.com/1357171): Add additional documentation.
+## Code Structure
+
+The top-level object with which the embedder will interact is the
+`ContentBrowserClientMixins` class which will be used to
+[create](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/content_browser_client_mixins.h;l=88)
+a `RuntimeApplicationDispatcher` instance. That instance will
+[create](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/runtime_application_dispatcher.h;l=36)
+`RuntimeApplications` instances, either `StreamingRuntimeApplication` or
+`WebRuntimeApplication` instances, and then
+[wrap them](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/runtime_application_dispatcher_impl.h;l=86;drc=790df4d5983e38ad1d1d00fbc10ef941070eed24)
+in an `EmbedderApplication` instance using a factory provided by the embedder.
+The `EmbedderApplication` instance will control the `RuntimeApplication` with
+the following
+[commands](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/runtime_application_dispatcher.h):
+
+*   `Load()`
+*   `Launch()`
+*   `Stop()`
+
+Additionally, the `RuntimeApplication`
+[exposes](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/runtime_application.h;drc=12be03159fe22cd4ef291e9561762531c2589539)
+a number of accessors and ways to set properties of the application, such as
+enabling or disabling touch input. The `EmbedderApplication`
+[exposes](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/embedder_application.h;drc=12be03159fe22cd4ef291e9561762531c2589539)
+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.
+
+![cast_receiver code structure](https://services.google.com/fh/gumdrop/preview/misc/cast_receiver_code_structure.png "cast_receiver code structure")
+
+
+## Common Scenarios
+
+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
+
+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:
+
+1. [Create](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/content_browser_client_mixins.h;l=45;drc=12be03159fe22cd4ef291e9561762531c2589539)
+a new `ContentBrowserClientMixins` instance in the embedder-specific
+`ContentBrowserClient` implementation, and then use that instance to
+[create](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/content_browser_client_mixins.h;l=88;drc=12be03159fe22cd4ef291e9561762531c2589539)
+a `RuntimeApplicationDispatcher`.
+2. Use the `RuntimeApplicationDispatcher` to
+[create](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/runtime_application_dispatcher.h;l=36;drc=1bcc6d9e4af49c462d3b2bee9f00db757084d262)
+a `WebRuntimeApplication` instance, which will then be used to
+[create](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/runtime_application_dispatcher_impl.h;l=86;drc=790df4d5983e38ad1d1d00fbc10ef941070eed24) an instance of the embedder-specific `EmbedderApplication` type.
+3. Call `Load()` on the `RuntimeApplication` instance, and wait for its
+callback.
+4. Call `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.
+5. Call `Launch()` on the `RuntimeApplication` instance, and wait for its
+callback. Various `EmbedderApplication` functions will be called to create the
+necessary resources.
+6. Once the application is no longer needed, close it with `StopApplication()`
+and then
+[destroy](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/runtime_application_dispatcher.h;l=48;drc=1bcc6d9e4af49c462d3b2bee9f00db757084d262)
+the application with the `RuntimeApplicationDispatcher` after the
+`StopApplication()`’s callback returns.
+
+![Web Application code flow](https://services.google.com/fh/gumdrop/preview/misc/webruntimeapplication_flow.png "WebRuntimeApplication structure")
+
+### Streaming
+
+Streaming Applications are used to support the Cast streaming and remoting
+scenarios by making use of the `cast_streaming` component
+
+1. [Create](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/content_browser_client_mixins.h;l=45;drc=12be03159fe22cd4ef291e9561762531c2589539)
+a new `ContentBrowserClientMixins` instance in the embedder-specific
+`ContentBrowserClient` implementation, and then use that instance to
+[create](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/content_browser_client_mixins.h;l=88;drc=12be03159fe22cd4ef291e9561762531c2589539)
+a `RuntimeApplicationDispatcher`.
+2. Use the `RuntimeApplicationDispatcher` to
+[create](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/runtime_application_dispatcher.h;l=36;drc=1bcc6d9e4af49c462d3b2bee9f00db757084d262)
+a `StreamingRuntimeApplication` instance, which will then be used to
+[create](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/runtime_application_dispatcher_impl.h;l=86;drc=790df4d5983e38ad1d1d00fbc10ef941070eed24)
+an instance of the embedder-specific `EmbedderApplication` type.
+3. Call `Load()` on the `RuntimeApplication` instance, and wait for its
+callback.
+4. Call `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](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/streaming_controller_base.cc;l=88;drc=790df4d5983e38ad1d1d00fbc10ef941070eed24)
+to occur for the streaming session to successfully begin, but the order may
+vary:
+    1. Calling of `StartPlaybackAsync()`, which will be called as part of the
+    `Launch()` command before its callback is called.
+    2. The `WebContents` instance associated with this application, as returned
+    by `EmbedderApplication::GetWebContents()`,
+    [loads](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/streaming_controller_base.cc;l=46)
+    the page used for displaying the streaming session.
+    3. The configuration to use for streaming is returned by the
+    embedder-specific `ConfigurationManager` as
+    [provided](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/streaming_config_manager.h;l=25;drc=576992499f3c1488c8f86feafb3a65aee426f784)
+    by `EmbedderApplication::GetStreamingConfigManager()`.
+5. Once streaming has started and a connection has been formed with the Cast
+sender device, a `OnStreamingResolutionChanged()`
+[event](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/streaming_resolution_observer.h;l=29)
+will be fired.
+6. Streaming may be stopped by the embedder as with Web applications.
+Alternatively, if the session is
+[ended](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_streaming/browser/public/receiver_session.h;l=49;drc=7eb26cecf3a3c92e25c68b8ca4f0fc467ea89af7)
+by the remote device, a `NotifyApplicationStopped()` event will be fired to the
+`EmbedderApplication`, at which point the application should be
+[destroyed](https://source.chromium.org/chromium/chromium/src/+/main:components/cast_receiver/browser/public/runtime_application_dispatcher.h;l=48;drc=1bcc6d9e4af49c462d3b2bee9f00db757084d262)
+by the `RuntimeApplicationDispatcher`.
+
+![Streaming Application code flow](https://services.google.com/fh/gumdrop/preview/misc/streamingruntimeapplication_flow.png "StreamingRuntimeApplication structure")
 
 # Known Issues and Limitations