Checking in the initial version of CEEE (Chrome Extensions Execution

Environment), an optional feature of Chrome Frame that acts as an
adapter layer for a subset of the Chrome Extension APIs. This enables
extensions that stick to the supported subset of APIs to work in the
context of Chrome Frame with minimal or sometimes no changes.

See http://www.chromium.org/developers/design-documents/ceee for an
overview of the design of CEEE.

TEST=unit tests (run ceee/smoke_tests.bat as an administrator on Windows)
BUG=none



git-svn-id: svn://svn.chromium.org/chrome/trunk/src@64712 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 61 insertions, 0 deletions

diff --git a/ceee/ie/broker/broker_docs.h b/ceee/ie/broker/broker_docs.h
new file mode 100644
index 0000000..5cc1220
--- /dev/null
+++ b/ceee/ie/broker/broker_docs.h
@@ -0,0 +1,61 @@
+// Copyright (c) 2010 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+//
+#ifndef CEEE_IE_BROKER_BROKER_DOCS_H_  // Mainly for lint
+#define CEEE_IE_BROKER_BROKER_DOCS_H_
+
+/** @page BrokerDoc Detailed documentation of the Broker process.
+
+@section BrokerIntro Introduction
+
+Since Internet Explorer can have multiple processes and run them at different
+integrity level, we use a separate process to take care of integrity level
+elevation when needed. This Broker process is also used as the sole
+communication point with a Chrome Frame instance for Chrome Extension API
+invocation to be executed in IE as well as events coming from IE and going back
+to Chrome.
+
+@subsection ApiInvocation API Invocation
+
+The Broker must register a Chrome Frame Events sink to receive the private
+messages used to redirect Chrome Extension API Invocations. But this has to be
+done in a non-blocking single threaded way. So we must create a Single Thread
+Apartment (STA) into which an instance of the ChromeFrameHost class will run, so
+it can receive the private messages safely.
+
+Once an API Invocation message is passed to the Broker via the Chrome Frame
+Host, the request is simply added to a global queue of API Invocation, waiting
+to be processed by a worker thread running in the Multi Thread Apartment (MTA).
+
+Running the API invocation mostly likely need to execute code in the IE process,
+but we can't block the STA for those calls, this is why we need to delegate
+these calls to a work thread while the Chrome Frame Host STA can run free.
+
+Once an API invocation is picked up from the queue, and processed (by making
+calls to instances of the CeeeExecutor running in the IE process and managed
+by the ExecutorsManager), then the API response can be sent back to Chrome, via
+the Chrome Frame Host, in the exact same way that we would send Chrome Extension
+Events back to Chrome as described below.
+
+@subsection EventDispatching Event Dispatching
+
+When an event occurs in IE, that Chrome Extension might be interested in, the
+code running in IE fires an event on the ICeeeBroker interface and one of
+the RPC threads, running in the MTA catch it. We process all that is needed
+to fill the event data from the RPC thread, and then add the event to the
+global queue of events that are to be dispatched to Chrome via the Chrome Frame
+Host running in the STA.
+
+So the Chrome Frame Host thread must wake up when events are added to the queue
+and simply pass them to Chrome Frame before going back to sleep. Waiting for
+further API invocations, or more events.
+
+Since the API invocation responses need to go through the Chrome Frame Host
+in the exact same way as the events (except for a different target string), we
+can use the exact same mechanism to send back API invocation response as we do
+for events.
+
+**/
+
+#endif  // CEEE_IE_BROKER_BROKER_DOCS_H_