WIP: Migrate Wiki content over to src/docs

docs/embedded_browser_framework.md

+**This document is obsolete.  Please visit the chromium embedded framework project page at http://code.google.com/p/chromiumembedded/**

[Bons, 2015/08/20 20:16:50]

propose deletion based on this comment

+
+# Introduction
+
+The embedded browser framework will provide standard implementations for the browser window, message loop and default functionality (printing, context menus, resource loading, etc), allowing us to offer similar functionality and semantics for embedded clients on different platforms and technologies (ActiveX, MFC, ObjC, wxWidgets, etc).  The embedded client can customize the default functionality and handle browser notifications by registering delegate interfaces.  The user will be completely insulated from the underlying chromium layer, similar to how the chromium layer insulates users from WebKit objects.
+
+# Details
+
+A fully functional embedded chrome window using this framework might be easily created as follows:
+```
+// Define an instance of our CefHandler implementation.
+CefRefPtr<CefHandler> handler(new MyHandler());
+
+// Provide information about the parent window, client rectangle, etc.
+CefWindowInfo info = {...};
+
+// Create the new browser window object, which eventually results in a call to
+// MyHandler::HandleAfterCreated().
+CefBrowser::CreateBrowser(info, false, handler);
+
+// In the MyHandler::HandleAfterCreated() implementation, navigate to a URL.
+RetVal MyHandler::HandleAfterCreated(CefRefPtr<CefBrowser> browser)
+{
+  browser->LoadURL("http://www.google.com");
+  return RV_CONTINUE;
+}
+```
+
+
+## Browser Notifications
+
+Browser notifications are delivered from the browser to the client via registered delegate interfaces(CefHandler and CefJSHandler).
+
+  * Before Popup. The application can cancel the creation of a popup window.
+  * Before Browse. The application can cancel navigation. Information provided with this event includes the URL, post data and request headers.
+  * Load Start. The browser is about to begin loading a URL.
+  * Load End. The browser has finished loading a URL.
+  * Resource Start.  The browser is about to begin loading a resource. The application can provide an alternate data source (in-memory buffer, for instance) or cancel the load.  The default behavior of the browser implementation is to load the resource in the same manner as test\_shell.
+  * Resource End. The browser has finished loading a resource.
+  * Update Address Bar.  Change the address bar to the specified string.  This is sent after navigation is committed and before the page has begun loading.
+  * Update Title.  Change the title to the specified string.  This is sent while the page is loading.
+  * Before Menu.  The browser is about to show a context menu. The application can either cancel the menu or show a custom menu in its place.  The default behavior of the browser implementation is to show a basic context menu based on the disposition type.
+  * Get Menu Label.  Called one time for each item in a default context menu before that menu is displayed.  The application can change the text from the English default to something else (a different language, for instance).
+  * Get Print Header & Footer.  Called after the web view is rendered to the print context but before the page is ended.  The application can insert a custom header/footer string at any of six predefined locations (top left, top center, top right, bottom left, bottom center, bottom right) or do custom drawing on the print context.  Information provided with this event includes the current URL, title, page number, total pages, print context, page bounding box and DPI scale factor.
+  * Execute JavaScript. A method has been executed on the "window.embed" object.  All JavaScript arguments are provided with this event and the application can specify a return value or cause a JavaScript "no method found" error to be generated.
+
+## Browser Events
+
+Browser events are delivered to the browser by the client via host class methods (CefBrowser).
+
+  * Back, Forward, Reload and Stop Load. Control navigation of the target frame.
+  * Undo, Redo, Cut, Copy, Paste, Delete, Select All.  Control selection on the target frame.
+  * Print.  Print the target frame.
+  * View Source. Save the target frame's HTML source to a temporary file and open it in the default text viewing application.
+  * Load URL.  Load the specified URL into an optionally specified target frame.
+  * Load String. Load the specified string into the main browser frame with an optionally specified dummy URL.
+  * Execute JavaScript.  Execute an arbitrary JavaScript command.
+
+## Future Capabilities
+
+The following advanced capabilities will be added to the framework at a later time.
+
+  * Support "themes" for customizing user interface elements such as buttons, scroll bars, etc.
+  * Provide access to and support manipulation of the DOM structure.
+  * Design an easy way to dynamically mix application-provided windows with web content in the browser window.
+  * Provide a method to add objects and functions to the V8 engine.
+
+
+# Framework Class Definition
+
+All classes that belong to the Chromium Embedded Framework will be prefixed with "Cef".
+
+## Framework Setup and Tear Down
+
+The UI message loop will be hosted in a single thread created by the framework.  The client is responsible for setting up and shutting down this thread for each process that uses the framework by calling CefInitialize() and CefShutdown() respectively.
+
+```
+// This function should only be called once when the application is started.
+// Create the thread to host the UI message loop.  A return value of true
+// indicates that it succeeded and false indicates that it failed.
+bool CefInitialize();
+
+// This function should only be called once before the application exits.
+// Shut down the thread hosting the UI message loop and destroy any created
+// windows.
+void CefShutdown();
+```
+
+## Reference Counting
+
+All framework classes will implement the CefBase interface and all instance pointers will be handled using the CefRefPtr smart pointer implementation.
+
+```
+// Interface defining the the reference count implementation methods. All
+// framework classes must implement the CefBase class.
+class CefBase
+{
+public:
+  // The AddRef method increments the reference count for the object. It should
+  // be called for every new copy of a pointer to a given object. The resulting
+  // reference count value is returned and should be used for diagnostic/testing
+  // purposes only.
+  virtual int AddRef() =0;
+
+  // The Release method decrements the reference count for the object. If the
+  // reference count on the object falls to 0, then the object should free
+  // itself from memory.  The resulting reference count value is returned and
+  // should be used for diagnostic/testing purposes only.
+  virtual int Release() =0;
+};
+
+
+// Smart pointer implementation borrowed from base/ref_counted.h
+//
+// A smart pointer class for reference counted objects.  Use this class instead
+// of calling AddRef and Release manually on a reference counted object to
+// avoid common memory leaks caused by forgetting to Release an object
+// reference.  Sample usage:
+//
+//   class MyFoo : public CefBase {
+//    ...
+//   };
+//
+//   void some_function() {
+//     // The MyFoo object that |foo| represents starts with a single
+//     // reference.
+//     CefRefPtr<MyFoo> foo = new MyFoo();
+//     foo->Method(param);
+//     // |foo| is released when this function returns
+//   }
+//
+//   void some_other_function() {
+//     CefRefPtr<MyFoo> foo = new MyFoo();
+//     ...
+//     foo = NULL;  // explicitly releases |foo|
+//     ...
+//     if (foo)
+//       foo->Method(param);
+//   }
+//
+// The above examples show how CefRefPtr<T> acts like a pointer to T.
+// Given two CefRefPtr<T> classes, it is also possible to exchange
+// references between the two objects, like so:
+//
+//   {
+//     CefRefPtr<MyFoo> a = new MyFoo();
+//     CefRefPtr<MyFoo> b;
+//
+//     b.swap(a);
+//     // now, |b| references the MyFoo object, and |a| references NULL.
+//   }
+//
+// To make both |a| and |b| in the above example reference the same MyFoo
+// object, simply use the assignment operator:
+//
+//   {
+//     CefRefPtr<MyFoo> a = new MyFoo();
+//     CefRefPtr<MyFoo> b;
+//
+//     b = a;
+//     // now, |a| and |b| each own a reference to the same MyFoo object.
+//     // the reference count of the underlying MyFoo object will be 2.
+//   }
+//
+// Reference counted objects can also be passed as function parameters and
+// used as function return values:
+//
+//   void some_func_with_param(CefRefPtr<MyFoo> param) {
+//     // A reference is added to the MyFoo object that |param| represents
+//     // during the scope of some_func_with_param() and released when
+//     // some_func_with_param() goes out of scope.
+//   }
+//
+//   CefRefPtr<MyFoo> some_func_with_retval() {
+//     // The MyFoo object that |foox| represents starts with a single
+//     // reference.
+//     CefRefPtr<MyFoo> foox = new MyFoo();
+//
+//     // Creating the return value adds an additional reference.
+//     return foox;
+//
+//     // When some_func_with_retval() goes out of scope the original |foox|
+//     // reference is released.
+//   }
+//
+//   void and_another_function() {
+//     CefRefPtr<MyFoo> foo = new MyFoo();
+//
+//     // pass |foo| as a parameter.
+//     some_function(foo);
+//
+//     CefRefPtr<MyFoo> foo2 = some_func_with_retval();
+//     // Now, since we kept a reference to the some_func_with_retval() return
+//     // value, |foo2| is the only class pointing to the MyFoo object created
+//     in some_func_with_retval(), and it has a reference count of 1.
+//
+//     some_func_with_retval();
+//     // Now, since we didn't keep a reference to the some_func_with_retval()
+//     // return value, the MyFoo object created in some_func_with_retval()
+//     // will automatically be released.
+//   }
+//
+// And in standard containers:
+//
+//   {
+//      // Create a vector that holds MyFoo objects.
+//      std::vector<CefRefPtr<MyFoo> > MyFooVec;
+//
+//     // The MyFoo object that |foo| represents starts with a single
+//     // reference.
+//     CefRefPtr<MyFoo> foo = new MyFoo();
+//
+//     // When the MyFoo object is added to |MyFooVec| the reference count
+//     // is increased to 2.
+//     MyFooVec.push_back(foo);
+//   }
+//
+template <class T>
+class CefRefPtr {
+ public:
+  CefRefPtr() : ptr_(NULL) {
+  }
+
+  CefRefPtr(T* p) : ptr_(p) {
+    if (ptr_)
+      ptr_->AddRef();
+  }
+
+  CefRefPtr(const CefRefPtr<T>& r) : ptr_(r.ptr_) {
+    if (ptr_)
+      ptr_->AddRef();
+  }
+
+  ~CefRefPtr() {
+    if (ptr_)
+      ptr_->Release();
+  }
+
+  T* get() const { return ptr_; }
+  operator T*() const { return ptr_; }
+  T* operator->() const { return ptr_; }
+
+  CefRefPtr<T>& operator=(T* p) {
+    // AddRef first so that self assignment should work
+    if (p)
+      p->AddRef();
+    if (ptr_ )
+      ptr_ ->Release();
+    ptr_ = p;
+    return *this;
+  }
+
+  CefRefPtr<T>& operator=(const CefRefPtr<T>& r) {
+    return *this = r.ptr_;
+  }
+
+  void swap(T** pp) {
+    T* p = ptr_;
+    ptr_ = *pp;
+    *pp = p;
+  }
+
+  void swap(CefRefPtr<T>& r) {
+    swap(&r.ptr_);
+  }
+
+ private:
+  T* ptr_;
+};
+```
+
+## Platform Dependant Types
+
+The framework will define a set of implementation-neutral interfaces and typedef's that wrap platform-dependent behavior.
+
+```
+#ifdef _WIN32
+#include <windows.h>
+
+// Structure representing create window parameters for MS Windows.
+struct _CefWindowInfoWin
+{
+  // Standard parameters required by CreateWindowEx()
+  DWORD dwExStyle;
+  std::wstring className;
+  std::wstring windowName;
+  DWORD dwStyle;
+  int x;
+  int y;
+  int nWidth;
+  int nHeight;
+  HWND hWndParent;
+  HMENU hMenu;
+  HINSTANCE hInstance;
+
+  // Handle for the new browser window.
+  HWND hWnd;
+
+  // A parameter that can be used to store client-specific information.
+  CefRefPtr<CefBase> clientInfo;
+};
+
+// Use the correct create info structure for the operating system.
+typedef struct _CefWindowInfoWin CefWindowInfo;
+
+// Structure representing print context parameters for MS Windows.
+struct _CefPrintInfoWin
+{
+  HDC hdc;
+  RECT rect;
+  double scale;
+};
+
+// Use the correct print info structure for the operating system.
+typedef struct _CefPrintInfoWind CefPrintInfo;
+#endif // _WIN32
+```
+
+## Thread Safety
+
+All implementations of framework interfaces must be safe for access from multiple threads.  The CefThreadSafeBase template provides atomic AddRef() and Release() implementations.  It also provides Lock() and Unlock() methods for synchronizing access to blocks of code.
+
+```
+#ifdef _WIN32
+// Atomic increment and decrement for MS Windows
+#define CefAtomicIncrement(p) InterlockedIncrement(p)
+#define CefAtomicDecrement(p) InterlockedDecrement(p)
+
+// Critical section wrapper for MS Windows
+class CefCriticalSection
+{
+public:
+  CefCriticalSection()
+  {
+    memset(&m_sec, 0, sizeof(CRITICAL_SECTION));
+    InitializeCriticalSection(&m_sec);
+  }
+  ~CefCriticalSection()
+  {
+    DeleteCriticalSection(&m_sec);
+  }
+  void Lock()
+  {
+    EnterCriticalSection(&m_sec);
+  }
+  void Unlock()
+  {
+    LeaveCriticalSection(&m_sec);
+  }
+
+  CRITICAL_SECTION m_sec;
+};
+#endif // _WIN32
+
+// Template that provides atomic implementations of AddRef() and Release()
+// along with Lock() and Unlock() methods to protect critical sections of
+// code from simultaneous access by multiple threads.
+//
+// The below example demonstrates how to use the CefThreadSafeBase template.
+//
+// class MyHandler : public CefThreadSafeBase<CefHandler>
+// {
+//    std::wstring m_title;
+//
+//    virtual RetVal HandleTitleChange(const std::wstring& title)
+//    {
+//       Lock();   // Begin protecting code
+//       m_title = title;
+//       Unlock(); // Done protecting code
+//       return RV_HANDLED;
+//    }
+//    ...
+// }
+//
+template <class ClassName>
+class CefThreadSafeBase : public ClassName
+{
+public:
+  CefThreadSafeBase()
+  {
+    m_dwRef = 0L;
+  }
+  ~CefThreadSafeBase()
+  {
+  }
+
+  // Atomic reference increment.
+  int AddRef()
+  {
+    return CefAtomicIncrement(&m_dwRef);
+  }
+
+  // Atomic reference decrement.  Delete this object when no references remain.
+  int Release()
+  {
+    int retval = CefAtomicDecrement(&m_dwRef);
+    if(retval == 0)
+      delete this;
+    return retval;
+  }
+
+  // Use the Lock() and Unlock() methods to protect a section of code from
+  // simultaneous access by multiple threads.
+  void Lock() { m_critsec.Lock(); }
+  void Unlock() { m_critsec.Unlock(); }
+
+protected:
+  long m_dwRef;
+  CefCriticalSection m_critsec;
+};
+```
+
+## Framework Interfaces
+
+And, finally, we have the framework interfaces.
+
+  * **CefBrowser** is the main browser window host class. A new browser window is created by calling the static CefBrowser::CreateBrowser() method.
+  * **CefHandler** is the main browser delegate interface passed into the CefBrowser::CreateBrowser() method.
+  * **CefRequest** represents request data such as url, method, post data and headers.
+  * **CefPostData** and **CefPostDataElement** represent the post data that may be part of a request.
+  * **CefStreamReader** and **CefStreamWriter** are simple interfaces for reading and writing data respectively.
+  * **CefJSHandler** and **CefVariant** are used to implement external JavaScript objects provided by the client.  JS handlers are assigned via a call to CefBrowser::AddJSHandler().
+
+```
+class CefHandler;
+class CefRequest;
+class CefStreamReader;
+class CefStreamWriter;
+class CefPostData;
+class CefPostDataElement;
+class CefJSHandler;
+class CefVariant;
+
+
+// Class used to represent a browser window.  All methods exposed by this
+// class should be thread safe.
+class CefBrowser : public CefBase
+{
+public:
+  // Create a new browser window using the creation parameters specified
+  // by |createInfo|. All values will be copied internally and the actual
+  // window will be created on the UI thread.  The |popup| parameter should
+  // be true if the new window is a popup window. This method call will not
+  // block.
+  static void CreateBrowser(CefWindowInfo& createInfo, bool popup,
+                            CefRefPtr<CefHandler> handler);
+
+  // Returns true if the browser can navigate backwards.
+  virtual bool CanGoBack() =0;
+  // Navigate backwards.
+  virtual void GoBack() =0;
+  // Returns true if the browser can navigate forwards.
+  virtual bool CanGoForward() =0;
+  // Navigate backwards.
+  virtual void GoForward() =0;
+  // Reload the current page.
+  virtual void Reload() =0;
+  // Stop loading the page.
+  virtual void StopLoad() =0;
+
+  // Define frame target types. Using TF_FOCUSED will target the focused
+  // frame and using TF_MAIN will target the main frame.
+  enum TargetFrame
+  {
+    TF_FOCUSED   = 0,
+    TF_MAIN      = 1
+  };
+
+  // Execute undo in the target frame.
+  virtual void Undo(TargetFrame targetFrame) =0;
+  // Execute redo in the target frame.
+  virtual void Redo(TargetFrame targetFrame) =0;
+  // Execute cut in the target frame.
+  virtual void Cut(TargetFrame targetFrame) =0;
+  // Execute copy in the target frame.
+  virtual void Copy(TargetFrame targetFrame) =0;
+  // Execute paste in the target frame.
+  virtual void Paste(TargetFrame targetFrame) =0;
+  // Execute delete in the target frame.
+  virtual void Delete(TargetFrame targetFrame) =0;
+  // Execute select all in the target frame.
+  virtual void SelectAll(TargetFrame targetFrame) =0;
+
+  // Execute printing in the target frame.  The user will be prompted with
+  // the print dialog appropriate to the operating system.
+  virtual void Print(TargetFrame targetFrame) =0;
+
+  // Save the target frame's HTML source to a temporary file and open it in
+  // the default text viewing application.
+  virtual void ViewSource(TargetFrame targetFrame) =0;
+
+  // Returns the target frame's HTML source as a string.
+  virtual std::wstring GetSource(TargetFrame targetFrame) =0;
+
+  // Returns the target frame's display text as a string.
+  virtual std::wstring GetText(TargetFrame targetFrame) =0;
+
+  // Load the request represented by the |request| object.
+  virtual void LoadRequest(CefRefPtr<CefRequest> request) =0;
+
+  // Convenience method for loading the specified |url| in the optional target
+  // |frame|.
+  virtual void LoadURL(const std::wstring& url, const std::wstring& frame) =0;
+  
+  // Load the contents of |string| with the optional dummy target |url|.
+  virtual void LoadString(const std::wstring& string,
+                          const std::wstring& url) =0;
+
+  // Load the contents of |stream| with the optional dummy target |url|.
+  virtual void LoadStream(CefRefPtr<CefStreamReader> stream,
+                          const std::wstring& url) =0;
+
+  // Returns true if a JS handler with the specified |name| is currently
+  // registered.
+  virtual bool HasJSHandler(const std::wstring& name) =0;
+
+  // Register a new handler tied to the specified JS object |name|. Returns
+  // true if the handler is registered successfully.
+  virtual bool AddJSHandler(const std::wstring& name,
+                            CefRefPtr<CefJSHandler> handler) =0;
+  
+  // Unregister the JS handler registered with the specified |name|.  Returns
+  // true if the handler is unregistered successfully.
+  virtual bool RemoveJSHandler(const std::wstring& name) =0;
+
+  // Returns the JS handler registered with the specified |name|.
+  virtual CefRefPtr<CefJSHandler> GetJSHandler(const std::wstring& name) =0;
+
+  // Retrieve the window information for this browser.
+  virtual void GetWindowInfo(CefWindowInfo& info) =0;
+
+  // Returns true if the window is a popup window.
+  virtual bool IsPopup() =0;
+
+  // Returns the handler for this browser.
+  virtual CefRefPtr<CefHandler> GetHandler() =0;
+};
+
+
+// Interface that should be implemented to handle events generated by the
+// browser window.  All methods exposed by this class should be thread safe.
+// Each method in the interface returns a RetVal value.
+class CefHandler : public CefBase
+{
+public:
+  // Define handler return value types. Returning RV_HANDLED indicates
+  // that the implementation completely handled the method and that no further
+  // processing is required.  Returning RV_CONTINUE indicates that the
+  // implementation did not handle the method and that the default handler
+  // should be called.
+  enum RetVal
+  {
+    RV_HANDLED   = 0,
+    RV_CONTINUE  = 1
+  };
+
+  // Event called before a new window is created. The |parentBrowser| parameter
+  // will point to the parent browser window, if any. The |popup| parameter
+  // will be true if the new window is a popup window. If you create the window
+  // yourself you should populate the window handle member of |createInfo| and
+  // return RV_HANDLED.  Otherwise, return RV_CONTINUE and the framework will
+  // create the window.  By default, a newly created window will recieve the
+  // same handler as the parent window.  To change the handler for the new
+  // window modify the object that |handler| points to.
+  virtual RetVal HandleBeforeCreated(CefRefPtr<CefBrowser> parentBrowser,
+                                     CefWindowInfo& createInfo, bool popup,
+                                     CefRefPtr<CefHandler>& handler) =0;
+
+  // Event called after a new window is created. The return value is currently
+  // ignored.
+  virtual RetVal HandleAfterCreated(CefRefPtr<CefBrowser> browser) =0;
+
+  // Event called when the address bar changes. The return value is currently
+  // ignored.
+  virtual RetVal HandleAddressChange(CefRefPtr<CefBrowser> browser,
+                                     const std::wstring& url) =0;
+
+  // Event called when the page title changes. The return value is currently
+  // ignored.
+  virtual RetVal HandleTitleChange(CefRefPtr<CefBrowser> browser,
+                                   const std::wstring& title) =0;
+
+  // Various browser navigation types supported by chrome.
+  enum NavType
+  {
+    NAVTYPE_LINKCLICKED = 0,
+    NAVTYPE_FORMSUBMITTED,
+    NAVTYPE_BACKFORWARD,
+    NAVTYPE_RELOAD,
+    NAVTYPE_FORMRESUBMITTED,
+    NAVTYPE_OTHER
+  };
+
+  // Event called before browser navigation. The client has an opportunity to
+  // modify the |request| object if desired.  Return RV_HANDLED to cancel
+  // navigation.
+  virtual RetVal HandleBeforeBrowse(CefRefPtr<CefBrowser> browser,
+                                    CefRefPtr<CefRequest> request,
+                                    NavType navType, bool isRedirect) =0;
+
+  // Event called when the browser begins loading a page.  The return value is
+  // currently ignored.
+  virtual RetVal HandleLoadStart(CefRefPtr<CefBrowser> browser) =0;
+
+  // Event called when the browser is done loading a page.  The return value is
+  // currently ignored.
+  virtual RetVal HandleLoadEnd(CefRefPtr<CefBrowser> browser) =0;
+
+  // Event called before a resource is loaded.  To allow the resource to load
+  // normally return RV_CONTINUE. To redirect the resource to a new url
+  // populate the |redirectUrl| value and return RV_CONTINUE.  To specify
+  // data for the resource return a CefStream object in |resourceStream| and
+  // return RV_CONTINUE.  To cancel loading of the resource return RV_HANDLED.
+  virtual RetVal HandleBeforeResourceLoad(CefRefPtr<CefBrowser> browser,
+                                          CefRefPtr<CefRequest> request,
+                                          std::wstring& redirectUrl,
+                                          CefRefPtr<CefStreamReader> resourceStream,
+                                          int resource_flags) =0;
+
+  // Event called when the browser begins loading a resource.  The return value is
+  // currently ignored.
+  virtual RetVal HandleResourceLoadStart(CefRefPtr<CefBrowser> browser) =0;
+
+  // Event called when the browser is done loading a resource.  The return value is
+  // currently ignored.
+  virtual RetVal HandleResourceLoadEnd(CefRefPtr<CefBrowser> browser) =0;
+
+  // Various context menu types supported by chrome.
+  enum MenuType
+  {
+    MENUTYPE_NONE = 0,
+    MENUTYPE_PAGE,
+    MENUTYPE_FRAME,
+    MENUTYPE_LINK,
+    MENUTYPE_IMAGE,
+    MENUTYPE_IMAGE_LINK,
+    MENUTYPE_SELECTION,
+    MENUTYPE_EDITABLE
+  };
+
+  // Event called before a context menu is displayed.  To cancel display of the
+  // default context menu return RV_HANDLED.
+  virtual RetVal HandleBeforeMenu(CefRefPtr<CefBrowser> browser,
+                                  MenuType menuType, int x, int y,
+                                  const std::wstring& linkUrl,
+                                  const std::wstring& imageUrl,
+                                  const std::wstring& pageUrl,
+                                  const std::wstring& frameUrl,
+                                  const std::wstring& selectionText,
+                                  int editFlags) =0;
+
+
+  // Event called to optionally override the default text for a context menu
+  // item.  |label| contains the default text and may be modified to substitute
+  // alternate text.  The return value is currently ignored.
+  virtual RetVal HandleGetMenuLabel(CefRefPtr<CefBrowser> browser,
+                                    int menuId, std::wstring& label) =0;
+
+  // Event called to format print headers and footers.  |printInfo| contains
+  // platform-specific information about the printer context.  |url| is the
+  // URL if the currently printing page, |title| is the title of the currently
+  // printing page, |currentPage| is the current page number and |maxPages| is
+  // the total number of pages.  Six default header locations are provided
+  // by the implementation: top left, top center, top right, bottom left,
+  // bottom center and bottom right.  To use one of these default locations
+  // just assign a string to the appropriate variable.  To draw the header
+  // and footer yourself return RV_HANDLED.  Otherwise, populate the approprate
+  // variables and return RV_CONTINUE.
+  virtual RetVal HandlePrintHeaderFooter(CefRefPtr<CefBrowser> browser,
+                                         CefPrintInfo& printInfo,
+                                         const std::wstring& url,
+                                         const std::wstring& title,
+                                         int currentPage, int maxPages,
+                                         std::wstring& topLeft,
+                                         std::wstring& topCenter,
+                                         std::wstring& topRight,
+                                         std::wstring& bottomLeft,
+                                         std::wstring& bottomCenter,
+                                         std::wstring& bottomRight) =0;
+};
+
+
+// Class used to represent a web request.
+class CefRequest : public CefBase
+{
+  typedef std::map<std::wstring, std::wstring> HeaderMap;
+
+public:
+  // Create a new CefRequest object.
+  static CefRefPtr<CefRequest> CreateRequest();
+
+  // Fully qualified URL to load.
+  virtual std::wstring GetURL() =0;
+  virtual void SetURL(const std::wstring& url) =0;
+
+  // Optional name of the target frame.
+  virtual std::wstring GetFrame() =0;
+  virtual void SetFrame(const std::wstring& url) =0;
+
+  // Optional request method type, defaulting to POST if post data is provided
+  // and GET otherwise.
+  virtual std::wstring GetMethod() =0;
+  virtual void SetMethod(const std::wstring& url) =0;
+
+  // Optional post data.
+  virtual CefRefPtr<CefPostData> GetPostData() =0;
+  virtual void SetPostData(CefRefPtr<CefPostData> postData) =0;
+
+  // Optional header values.
+  virtual HeaderMap GetHeaderMap() =0;
+  virtual void SetHeaderMap(const HeaderMap& headerMap) =0;
+
+  // Set all values at one time.
+  virtual void Set(const std::wstring& url,
+                   const std::wstring& frame,
+                   const std::wstring& method,
+                   CefRefPtr<CefPostData> postData,
+                   const HeaderMap& headerMap) =0;
+};
+
+
+// Class used to represent post data for a web request.
+class CefPostData : public CefBase
+{
+  typedef std::vector<CefRefPtr<CefPostDataElement> > ElementVector;
+
+public:
+  // Create a new CefPostData object.
+  static CefRefPtr<CefPostData> CreatePostData();
+
+  // Returns the number of existing post data elements.
+  virtual size_t GetElementCount() =0;
+
+  // Return the post data elements.
+  virtual ElementVector GetElements() =0;
+
+  // Remove the specified post data element.  Returns true if the removal
+  // succeeds.
+  virtual bool RemoveElement(CefRefPtr<CefPostDataElement> element) =0;
+
+  // Add the specified post data element.  Returns true if the add
+  // succeeds.
+  virtual bool AddElement(CefRefPtr<CefPostDataElement> element) =0;
+};
+
+
+// Class used to represent a single element in the request post data.
+class CefPostDataElement : public CefBase
+{
+public:
+  // Post data elements may represent either bytes or files.
+  enum Type
+  {
+    TYPE_BYTES  = 0,
+    TYPE_FILE   = 1
+  };
+
+  // Create a new CefPostDataElement object.
+  static CefRefPtr<CefPostDataElement> CreatePostDataElement();
+
+  // The post data element will represent a file.
+  virtual void SetToFile(std::wstring& fileName) =0;
+
+  // The post data element will represent bytes.  The bytes passed
+  // in will be copied.
+  virtual void SetToBytes(size_t size, void* bytes) =0;
+
+  // Return the type of this post data element.
+  virtual Type GetType() =0;
+
+  // Return the file name.
+  virtual std::wstring GetFile() =0;
+
+  // Return the number of bytes.
+  virtual size_t GetBytesCount() =0;
+
+  // Read up to |size| bytes into |bytes| and return the number of bytes
+  // actually read.
+  virtual size_t GetBytes(size_t size, void *bytes) =0;
+};
+
+
+// Class used to read data from a stream.
+class CefStreamReader : public CefBase
+{
+public:
+  // Read raw binary data.
+  virtual size_t Read(void *ptr, size_t size, size_t n) =0;
+        
+  // Seek to the specified offset position. |whence| may be any one of
+  // SEEK_CUR, SEEK_END or SEEK_SET.
+  virtual int Seek(long offset, int whence) =0;
+        
+  // Return the current offset position.
+  virtual long Tell() =0;
+};
+
+
+// Class used to write data to a stream.
+class CefStreamWriter : public CefBase
+{
+public:
+  // Write raw binary data.
+  virtual size_t Write(const void *ptr, size_t size, size_t n) =0;
+        
+  // Seek to the specified offset position. |whence| may be any one of
+  // SEEK_CUR, SEEK_END or SEEK_SET.
+  virtual int Seek(long offset, int whence) =0;
+        
+  // Return the current offset position.
+  virtual long Tell() =0;
+};
+
+
+// Class for implementing external JavaScript objects.
+class CefJSHandler : public CefBase
+{
+  typedef std::vector<CefRefPtr<CefVariant> > VariantVector;
+
+public:
+  // Returns true if the specified method exists.
+  virtual bool HasMethod(CefRefPtr<CefBrowser> browser,
+                         const std::wstring& name) =0;
+  
+  // Returns true if the specified property exists.
+  virtual bool HasProperty(CefRefPtr<CefBrowser> browser,
+                           const std::wstring& name) =0;
+
+  // Set the property value. Returns true if the property is set
+  // successfully.
+  virtual bool SetProperty(CefRefPtr<CefBrowser> browser,
+                           const std::wstring& name,
+                           CefRefPtr<CefVariant> value) =0;
+  
+  // Get the property value.
+  virtual CefRefPtr<CefVariant> GetProperty(CefRefPtr<CefBrowser> browser,
+                                            const std::wstring& name) =0;
+
+  // Execute a method with the specified argument vector.  Returns the method
+  // return value.
+  virtual CefRefPtr<CefVariant> ExecuteMethod(CefRefPtr<CefBrowser> browser,
+                                              const std::wstring& name,
+                                              const VariantVector& args) =0;
+};
+
+
+// Class that represents multiple data types as a single object.
+class CefVariant : public CefBase
+{
+public:
+  enum Type
+  {
+    TYPE_NULL = 0,
+    TYPE_BOOL,
+    TYPE_INT,
+    TYPE_DOUBLE,
+    TYPE_STRING,
+    TYPE_BOOL_ARRAY,
+    TYPE_INT_ARRAY,
+    TYPE_DOUBLE_ARRAY,
+    TYPE_STRING_ARRAY
+  };
+
+  // Create a new CefVariant object.
+  static CefRefPtr<CefVariant> CreateVariant();
+
+  // Return the variant data type.
+  virtual Type GetType() =0;
+
+  // Assign various data types.
+  virtual void SetNull() =0;
+  virtual void SetBool(bool val) =0;
+  virtual void SetInt(int val) =0;
+  virtual void SetDouble(double val) =0;
+  virtual void SetString(const std::wstring& val) =0;
+  virtual void SetBoolArray(const std::vector<bool>& val) =0;
+  virtual void SetIntArray(const std::vector<int>& val) =0;
+  virtual void SetDoubleArray(const std::vector<double>& val) =0;
+  virtual void SetStringArray(const std::vector<std::wstring>& val) =0;
+
+  // Retrieve various data types.
+  virtual bool GetBool() =0;
+  virtual int GetInt() =0;
+  virtual double GetDouble() =0;
+  virtual std::wstring GetString() =0;
+  virtual void GetBoolArray(std::vector<bool>& val) =0;
+  virtual void GetIntArray(std::vector<int>& val) =0;
+  virtual void GetDoubleArray(std::vector<double>& val) =0;
+  virtual void GetStringArray(std::vector<std::wstring>& val) =0;
+};
+```