bcarrella/cef
1
0
Fork 0
mirror of https://bitbucket.org/chromiumembedded/cef synced 2025-06-05 21:39:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update include/ comments to Doxygen formatting (see issue #3384)

Browse Source 
See related guidelines in the issue.
This commit is contained in:
Marshall Greenblatt
2022-08-31 22:03:04 -04:00
parent 7b352159df
commit d7a153bdd4
235 changed files with 11484 additions and 11274 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
include/wrapper/cef_byte_read_handler.h
View File

@ -42,15 +42,15 @@
#include "include/cef_stream.h"
///
// Thread safe implementation of the CefReadHandler class for reading an
// in-memory array of bytes.
/// Thread safe implementation of the CefReadHandler class for reading an
/// in-memory array of bytes.
///
class CefByteReadHandler : public CefReadHandler {
public:
///
// Create a new object for reading an array of bytes. An optional |source|
// reference can be kept to keep the underlying data source from being
// released while the reader exists.
/// Create a new object for reading an array of bytes. An optional |source|
/// reference can be kept to keep the underlying data source from being
/// released while the reader exists.
///
CefByteReadHandler(const unsigned char* bytes,
size_t size,

96
include/wrapper/cef_closure_task.h
View File

@ -41,63 +41,71 @@
#include "include/cef_task.h"
///
// Helpers for asynchronously executing a base::[Once|Repeating]Closure (bound
// function or method) on a CEF thread. Creation of a
// base::[Once|Repeating]Closure can be facilitated using
// base::Bind[Once|Repeating]. See include/base/cef_callback.h for complete
// usage instructions.
//
// To use these helpers you should include this header and the header that
// defines base::Bind[Once|Repeating].
//
// #include "include/base/cef_callback.h"
// #include "include/wrapper/cef_closure_task.h"
//
// Example of executing a bound function:
//
// // Define a function.
// void MyFunc(int arg) { /* do something with |arg| on the UI thread */ }
//
// // Post a task that will execute MyFunc on the UI thread and pass an |arg|
// // value of 5.
// CefPostTask(TID_UI, base::BindOnce(&MyFunc, 5));
//
// Example of executing a bound method:
//
// // Define a class.
// class MyClass : public CefBaseRefCounted {
// public:
// MyClass() {}
// void MyMethod(int arg) { /* do something with |arg| on the UI thread */ }
// private:
// IMPLEMENT_REFCOUNTING(MyClass);
// };
//
// // Create an instance of MyClass.
// CefRefPtr<MyClass> instance = new MyClass();
//
// // Post a task that will execute MyClass::MyMethod on the UI thread and pass
// // an |arg| value of 5. |instance| will be kept alive until after the task
// // completes.
// CefPostTask(TID_UI, base::BindOnce(&MyClass::MyMethod, instance, 5));
/// \file
/// Helpers for asynchronously executing a base::[Once|Repeating]Closure (bound
/// function or method) on a CEF thread. Creation of a
/// base::[Once|Repeating]Closure can be facilitated using
/// base::Bind[Once|Repeating]. See include/base/cef_callback.h for complete
/// usage instructions.
///
/// To use these helpers you should include this header and the header that
/// defines base::Bind[Once|Repeating].
///
/// <pre>
/// #include "include/base/cef_callback.h"
/// #include "include/wrapper/cef_closure_task.h"
/// </pre>
///
/// Example of executing a bound function:
///
/// <pre>
/// // Define a function.
/// void MyFunc(int arg) { /* do something with |arg| on the UI thread */ }
///
/// // Post a task that will execute MyFunc on the UI thread and pass an |arg|
/// // value of 5.
/// CefPostTask(TID_UI, base::BindOnce(&MyFunc, 5));
/// </pre>
///
/// Example of executing a bound method:
///
/// <pre>
/// // Define a class.
/// class MyClass : public CefBaseRefCounted {
/// public:
/// MyClass() {}
/// void MyMethod(int arg) { /* do something with |arg| on the UI thread */
/// }
/// private:
/// IMPLEMENT_REFCOUNTING(MyClass);
/// };
///
/// // Create an instance of MyClass.
/// CefRefPtr<MyClass> instance = new MyClass();
///
/// // Post a task that will execute MyClass::MyMethod on the UI thread and
/// // pass an |arg| value of 5. |instance| will be kept alive until after the
/// // task completes.
/// CefPostTask(TID_UI, base::BindOnce(&MyClass::MyMethod, instance, 5));
/// </pre>
///
///
// Create a CefTask that wraps a base::[Once|Repeating]Closure. Can be used in
// combination with CefTaskRunner.
/// Create a CefTask that wraps a base::[Once|Repeating]Closure. Can be used in
/// combination with CefTaskRunner.
///
CefRefPtr<CefTask> CefCreateClosureTask(base::OnceClosure closure);
CefRefPtr<CefTask> CefCreateClosureTask(const base::RepeatingClosure& closure);
///
// Post a base::[Once|Repeating]Closure for execution on the specified thread.
/// Post a base::[Once|Repeating]Closure for execution on the specified thread.
///
bool CefPostTask(CefThreadId threadId, base::OnceClosure closure);
bool CefPostTask(CefThreadId threadId, const base::RepeatingClosure& closure);
///
// Post a base::[Once|Repeating]Closure for delayed execution on the specified
// thread.
/// Post a base::[Once|Repeating]Closure for delayed execution on the specified
/// thread.
///
bool CefPostDelayedTask(CefThreadId threadId,
base::OnceClosure closure,

45
include/wrapper/cef_helpers.h
View File

@ -55,26 +55,29 @@
DCHECK(CefCurrentlyOn(TID_FILE_USER_BLOCKING));
#define CEF_REQUIRE_RENDERER_THREAD() DCHECK(CefCurrentlyOn(TID_RENDERER));
// Use this struct in conjuction with refcounted types to ensure that an
// object is deleted on the specified thread. For example:
//
// class Foo : public base::RefCountedThreadSafe<Foo, CefDeleteOnUIThread> {
// public:
// Foo();
// void DoSomething();
//
// private:
// // Allow deletion via scoped_refptr only.
// friend struct CefDeleteOnThread<TID_UI>;
// friend class base::RefCountedThreadSafe<Foo, CefDeleteOnUIThread>;
//
// virtual ~Foo() {}
// };
//
// base::scoped_refptr<Foo> foo = new Foo();
// foo->DoSomething();
// foo = NULL; // Deletion of |foo| will occur on the UI thread.
//
///
/// Use this struct in conjuction with refcounted types to ensure that an
/// object is deleted on the specified thread. For example:
///
/// <pre>
/// class Foo : public base::RefCountedThreadSafe<Foo, CefDeleteOnUIThread> {
/// public:
/// Foo();
/// void DoSomething();
///
/// private:
/// // Allow deletion via scoped_refptr only.
/// friend struct CefDeleteOnThread<TID_UI>;
/// friend class base::RefCountedThreadSafe<Foo, CefDeleteOnUIThread>;
///
/// virtual ~Foo() {}
/// };
///
/// base::scoped_refptr<Foo> foo = new Foo();
/// foo->DoSomething();
/// foo = NULL; /// Deletion of |foo| will occur on the UI thread.
/// </pre>
///
template <CefThreadId thread>
struct CefDeleteOnThread {
template <typename T>
@ -125,7 +128,7 @@ struct CefDeleteOnRendererThread : public CefDeleteOnThread<TID_RENDERER> {};
IMPLEMENT_REFCOUNTING_EX(ClassName, CefDeleteOnIOThread)
///
// Helper class to manage a scoped copy of |argv|.
/// Helper class to manage a scoped copy of |argv|.
///
class CefScopedArgArray {
public:

96
include/wrapper/cef_library_loader.h
View File

@ -40,14 +40,14 @@ extern "C" {
#endif // __cplusplus
///
// Load the CEF library at the specified |path|. Returns true (1) on
// success and false (0) on failure.
/// Load the CEF library at the specified |path|. Returns true (1) on
/// success and false (0) on failure.
///
int cef_load_library(const char* path);
///
// Unload the CEF library that was previously loaded. Returns true (1)
// on success and false (0) on failure.
/// Unload the CEF library that was previously loaded. Returns true (1)
/// on success and false (0) on failure.
///
int cef_unload_library(void);
@ -57,42 +57,46 @@ int cef_unload_library(void);
#if defined(OS_MAC)
///
// Scoped helper for loading and unloading the CEF framework library at
// runtime from the expected location in the app bundle. Loading at runtime
// instead of linking directly is a requirement of the macOS sandbox
// implementation.
//
// Example usage in the main process:
//
// #include "include/wrapper/cef_library_loader.h"
//
// int main(int argc, char* argv[]) {
// // Dynamically load the CEF framework library.
// CefScopedLibraryLoader library_loader;
// if (!library_loader.LoadInMain())
// return 1;
//
// // Continue with CEF initialization...
// }
//
// Example usage in the helper process:
//
// #include "include/cef_sandbox_mac.h"
// #include "include/wrapper/cef_library_loader.h"
//
// int main(int argc, char* argv[]) {
// // Initialize the macOS sandbox for this helper process.
// CefScopedSandboxContext sandbox_context;
// if (!sandbox_context.Initialize(argc, argv))
// return 1;
//
// // Dynamically load the CEF framework library.
// CefScopedLibraryLoader library_loader;
// if (!library_loader.LoadInHelper())
// return 1;
//
// // Continue with CEF initialization...
// }
/// Scoped helper for loading and unloading the CEF framework library at
/// runtime from the expected location in the app bundle. Loading at runtime
/// instead of linking directly is a requirement of the macOS sandbox
/// implementation.
///
/// Example usage in the main process:
///
/// <pre>
/// #include "include/wrapper/cef_library_loader.h"
///
/// int main(int argc, char* argv[]) {
/// // Dynamically load the CEF framework library.
/// CefScopedLibraryLoader library_loader;
/// if (!library_loader.LoadInMain())
/// return 1;
///
/// // Continue with CEF initialization...
/// }
/// </pre>
///
/// Example usage in the helper process:
///
/// <pre>
/// #include "include/cef_sandbox_mac.h"
/// #include "include/wrapper/cef_library_loader.h"
///
/// int main(int argc, char* argv[]) {
/// // Initialize the macOS sandbox for this helper process.
/// CefScopedSandboxContext sandbox_context;
/// if (!sandbox_context.Initialize(argc, argv))
/// return 1;
///
/// // Dynamically load the CEF framework library.
/// CefScopedLibraryLoader library_loader;
/// if (!library_loader.LoadInHelper())
/// return 1;
///
/// // Continue with CEF initialization...
/// }
/// </pre>
///
class CefScopedLibraryLoader {
public:
@ -104,16 +108,16 @@ class CefScopedLibraryLoader {
~CefScopedLibraryLoader();
///
// Load the CEF framework in the main process from the expected app
// bundle location relative to the executable. Returns true if the
// load succeeds.
/// Load the CEF framework in the main process from the expected app
/// bundle location relative to the executable. Returns true if the
/// load succeeds.
///
bool LoadInMain() { return Load(false); }
///
// Load the CEF framework in the helper process from the expected app
// bundle location relative to the executable. Returns true if the
// load succeeds.
/// Load the CEF framework in the helper process from the expected app
/// bundle location relative to the executable. Returns true if the
/// load succeeds.
///
bool LoadInHelper() { return Load(true); }

180
include/wrapper/cef_message_router.h
View File

@ -193,73 +193,79 @@
// 9. Notice that the onSuccess callback is executed in JavaScript.
///
// Used to configure the query router. The same values must be passed to both
// CefMessageRouterBrowserSide and CefMessageRouterRendererSide. If using
// multiple router pairs make sure to choose values that do not conflict.
/// Used to configure the query router. The same values must be passed to both
/// CefMessageRouterBrowserSide and CefMessageRouterRendererSide. If using
/// multiple router pairs make sure to choose values that do not conflict.
///
struct CefMessageRouterConfig {
CefMessageRouterConfig();
// Name of the JavaScript function that will be added to the 'window' object
// for sending a query. The default value is "cefQuery".
///
/// Name of the JavaScript function that will be added to the 'window' object
/// for sending a query. The default value is "cefQuery".
///
CefString js_query_function;
// Name of the JavaScript function that will be added to the 'window' object
// for canceling a pending query. The default value is "cefQueryCancel".
///
/// Name of the JavaScript function that will be added to the 'window' object
/// for canceling a pending query. The default value is "cefQueryCancel".
///
CefString js_cancel_function;
// Messages of size (in bytes) larger than this threshold will be sent via
// shared memory region.
///
/// Messages of size (in bytes) larger than this threshold will be sent via
/// shared memory region.
///
size_t message_size_threshold;
};
///
// Implements the browser side of query routing. The methods of this class may
// be called on any browser process thread unless otherwise indicated.
/// Implements the browser side of query routing. The methods of this class may
/// be called on any browser process thread unless otherwise indicated.
///
class CefMessageRouterBrowserSide
: public base::RefCountedThreadSafe<CefMessageRouterBrowserSide> {
public:
///
// Callback associated with a single pending asynchronous query. Execute the
// Success or Failure method to send an asynchronous response to the
// associated JavaScript handler. It is a runtime error to destroy a Callback
// object associated with an uncanceled query without first executing one of
// the callback methods. The methods of this class may be called on any
// browser process thread.
/// Callback associated with a single pending asynchronous query. Execute the
/// Success or Failure method to send an asynchronous response to the
/// associated JavaScript handler. It is a runtime error to destroy a Callback
/// object associated with an uncanceled query without first executing one of
/// the callback methods. The methods of this class may be called on any
/// browser process thread.
///
class Callback : public CefBaseRefCounted {
public:
///
// Notify the associated JavaScript onSuccess callback that the query has
// completed successfully with the specified |response|.
/// Notify the associated JavaScript onSuccess callback that the query has
/// completed successfully with the specified |response|.
///
virtual void Success(const CefString& response) = 0;
///
// Notify the associated JavaScript onFailure callback that the query has
// failed with the specified |error_code| and |error_message|.
/// Notify the associated JavaScript onFailure callback that the query has
/// failed with the specified |error_code| and |error_message|.
///
virtual void Failure(int error_code, const CefString& error_message) = 0;
};
///
// Implement this interface to handle queries. All methods will be executed on
// the browser process UI thread.
/// Implement this interface to handle queries. All methods will be executed
/// on the browser process UI thread.
///
class Handler {
public:
using Callback = CefMessageRouterBrowserSide::Callback;
///
// Executed when a new query is received. |query_id| uniquely identifies the
// query for the life span of the router. Return true to handle the query
// or false to propagate the query to other registered handlers, if any. If
// no handlers return true from this method then the query will be
// automatically canceled with an error code of -1 delivered to the
// JavaScript onFailure callback. If this method returns true then a
// Callback method must be executed either in this method or asynchronously
// to complete the query.
/// Executed when a new query is received. |query_id| uniquely identifies
/// the query for the life span of the router. Return true to handle the
/// query or false to propagate the query to other registered handlers, if
/// any. If no handlers return true from this method then the query will be
/// automatically canceled with an error code of -1 delivered to the
/// JavaScript onFailure callback. If this method returns true then a
/// Callback method must be executed either in this method or asynchronously
/// to complete the query.
///
virtual bool OnQuery(CefRefPtr<CefBrowser> browser,
CefRefPtr<CefFrame> frame,
@ -271,13 +277,13 @@ class CefMessageRouterBrowserSide
}
///
// Executed when a query has been canceled either explicitly using the
// JavaScript cancel function or implicitly due to browser destruction,
// navigation or renderer process termination. It will only be called for
// the single handler that returned true from OnQuery for the same
// |query_id|. No references to the associated Callback object should be
// kept after this method is called, nor should any Callback methods be
// executed.
/// Executed when a query has been canceled either explicitly using the
/// JavaScript cancel function or implicitly due to browser destruction,
/// navigation or renderer process termination. It will only be called for
/// the single handler that returned true from OnQuery for the same
/// |query_id|. No references to the associated Callback object should be
/// kept after this method is called, nor should any Callback methods be
/// executed.
///
virtual void OnQueryCanceled(CefRefPtr<CefBrowser> browser,
CefRefPtr<CefFrame> frame,
@ -287,80 +293,80 @@ class CefMessageRouterBrowserSide
};
///
// Create a new router with the specified configuration.
/// Create a new router with the specified configuration.
///
static CefRefPtr<CefMessageRouterBrowserSide> Create(
const CefMessageRouterConfig& config);
///
// Add a new query handler. If |first| is true it will be added as the first
// handler, otherwise it will be added as the last handler. Returns true if
// the handler is added successfully or false if the handler has already been
// added. Must be called on the browser process UI thread. The Handler object
// must either outlive the router or be removed before deletion.
/// Add a new query handler. If |first| is true it will be added as the first
/// handler, otherwise it will be added as the last handler. Returns true if
/// the handler is added successfully or false if the handler has already been
/// added. Must be called on the browser process UI thread. The Handler object
/// must either outlive the router or be removed before deletion.
///
virtual bool AddHandler(Handler* handler, bool first) = 0;
///
// Remove an existing query handler. Any pending queries associated with the
// handler will be canceled. Handler::OnQueryCanceled will be called and the
// associated JavaScript onFailure callback will be executed with an error
// code of -1. Returns true if the handler is removed successfully or false
// if the handler is not found. Must be called on the browser process UI
// thread.
/// Remove an existing query handler. Any pending queries associated with the
/// handler will be canceled. Handler::OnQueryCanceled will be called and the
/// associated JavaScript onFailure callback will be executed with an error
/// code of -1. Returns true if the handler is removed successfully or false
/// if the handler is not found. Must be called on the browser process UI
/// thread.
///
virtual bool RemoveHandler(Handler* handler) = 0;
///
// Cancel all pending queries associated with either |browser| or |handler|.
// If both |browser| and |handler| are NULL all pending queries will be
// canceled. Handler::OnQueryCanceled will be called and the associated
// JavaScript onFailure callback will be executed in all cases with an error
// code of -1.
/// Cancel all pending queries associated with either |browser| or |handler|.
/// If both |browser| and |handler| are NULL all pending queries will be
/// canceled. Handler::OnQueryCanceled will be called and the associated
/// JavaScript onFailure callback will be executed in all cases with an error
/// code of -1.
///
virtual void CancelPending(CefRefPtr<CefBrowser> browser,
Handler* handler) = 0;
///
// Returns the number of queries currently pending for the specified |browser|
// and/or |handler|. Either or both values may be empty. Must be called on the
// browser process UI thread.
/// Returns the number of queries currently pending for the specified
/// |browser| and/or |handler|. Either or both values may be empty. Must be
/// called on the browser process UI thread.
///
virtual int GetPendingCount(CefRefPtr<CefBrowser> browser,
Handler* handler) = 0;
// The below methods should be called from other CEF handlers. They must be
// called exactly as documented for the router to function correctly.
/// The below methods should be called from other CEF handlers. They must be
/// called exactly as documented for the router to function correctly.
///
// Call from CefLifeSpanHandler::OnBeforeClose. Any pending queries associated
// with |browser| will be canceled and Handler::OnQueryCanceled will be
// called. No JavaScript callbacks will be executed since this indicates
// destruction of the browser.
/// Call from CefLifeSpanHandler::OnBeforeClose. Any pending queries
/// associated with |browser| will be canceled and Handler::OnQueryCanceled
/// will be called. No JavaScript callbacks will be executed since this
/// indicates destruction of the browser.
///
virtual void OnBeforeClose(CefRefPtr<CefBrowser> browser) = 0;
///
// Call from CefRequestHandler::OnRenderProcessTerminated. Any pending queries
// associated with |browser| will be canceled and Handler::OnQueryCanceled
// will be called. No JavaScript callbacks will be executed since this
// indicates destruction of the context.
/// Call from CefRequestHandler::OnRenderProcessTerminated. Any pending
/// queries associated with |browser| will be canceled and
/// Handler::OnQueryCanceled will be called. No JavaScript callbacks will be
/// executed since this indicates destruction of the context.
///
virtual void OnRenderProcessTerminated(CefRefPtr<CefBrowser> browser) = 0;
///
// Call from CefRequestHandler::OnBeforeBrowse only if the navigation is
// allowed to proceed. If |frame| is the main frame then any pending queries
// associated with |browser| will be canceled and Handler::OnQueryCanceled
// will be called. No JavaScript callbacks will be executed since this
// indicates destruction of the context.
/// Call from CefRequestHandler::OnBeforeBrowse only if the navigation is
/// allowed to proceed. If |frame| is the main frame then any pending queries
/// associated with |browser| will be canceled and Handler::OnQueryCanceled
/// will be called. No JavaScript callbacks will be executed since this
/// indicates destruction of the context.
///
virtual void OnBeforeBrowse(CefRefPtr<CefBrowser> browser,
CefRefPtr<CefFrame> frame) = 0;
///
// Call from CefClient::OnProcessMessageReceived. Returns true if the message
// is handled by this router or false otherwise.
/// Call from CefClient::OnProcessMessageReceived. Returns true if the message
/// is handled by this router or false otherwise.
///
virtual bool OnProcessMessageReceived(
CefRefPtr<CefBrowser> browser,
@ -375,21 +381,21 @@ class CefMessageRouterBrowserSide
};
///
// Implements the renderer side of query routing. The methods of this class must
// be called on the render process main thread.
/// Implements the renderer side of query routing. The methods of this class
/// must be called on the render process main thread.
///
class CefMessageRouterRendererSide
: public base::RefCountedThreadSafe<CefMessageRouterRendererSide> {
public:
///
// Create a new router with the specified configuration.
/// Create a new router with the specified configuration.
///
static CefRefPtr<CefMessageRouterRendererSide> Create(
const CefMessageRouterConfig& config);
///
// Returns the number of queries currently pending for the specified |browser|
// and/or |context|. Either or both values may be empty.
/// Returns the number of queries currently pending for the specified
/// |browser| and/or |context|. Either or both values may be empty.
///
virtual int GetPendingCount(CefRefPtr<CefBrowser> browser,
CefRefPtr<CefV8Context> context) = 0;
@ -398,25 +404,25 @@ class CefMessageRouterRendererSide
// called exactly as documented for the router to function correctly.
///
// Call from CefRenderProcessHandler::OnContextCreated. Registers the
// JavaScripts functions with the new context.
/// Call from CefRenderProcessHandler::OnContextCreated. Registers the
/// JavaScripts functions with the new context.
///
virtual void OnContextCreated(CefRefPtr<CefBrowser> browser,
CefRefPtr<CefFrame> frame,
CefRefPtr<CefV8Context> context) = 0;
///
// Call from CefRenderProcessHandler::OnContextReleased. Any pending queries
// associated with the released context will be canceled and
// Handler::OnQueryCanceled will be called in the browser process.
/// Call from CefRenderProcessHandler::OnContextReleased. Any pending queries
/// associated with the released context will be canceled and
/// Handler::OnQueryCanceled will be called in the browser process.
///
virtual void OnContextReleased(CefRefPtr<CefBrowser> browser,
CefRefPtr<CefFrame> frame,
CefRefPtr<CefV8Context> context) = 0;
///
// Call from CefRenderProcessHandler::OnProcessMessageReceived. Returns true
// if the message is handled by this router or false otherwise.
/// Call from CefRenderProcessHandler::OnProcessMessageReceived. Returns true
/// if the message is handled by this router or false otherwise.
///
virtual bool OnProcessMessageReceived(
CefRefPtr<CefBrowser> browser,

163
include/wrapper/cef_resource_manager.h
View File

@ -48,29 +48,30 @@
#include "include/wrapper/cef_helpers.h"
///
// Class for managing multiple resource providers. For each resource request
// providers will be called in order and have the option to (a) handle the
// request by returning a CefResourceHandler, (b) pass the request to the next
// provider in order, or (c) stop handling the request. See comments on the
// Request object for additional usage information. The methods of this class
// may be called on any browser process thread unless otherwise indicated.
/// Class for managing multiple resource providers. For each resource request
/// providers will be called in order and have the option to (a) handle the
/// request by returning a CefResourceHandler, (b) pass the request to the next
/// provider in order, or (c) stop handling the request. See comments on the
/// Request object for additional usage information. The methods of this class
/// may be called on any browser process thread unless otherwise indicated.
///
class CefResourceManager
: public base::RefCountedThreadSafe<CefResourceManager,
CefDeleteOnIOThread> {
public:
///
// Provides an opportunity to modify |url| before it is passed to a provider.
// For example, the implementation could rewrite |url| to include a default
// file extension. |url| will be fully qualified and may contain query or
// fragment components.
/// Provides an opportunity to modify |url| before it is passed to a provider.
/// For example, the implementation could rewrite |url| to include a default
/// file extension. |url| will be fully qualified and may contain query or
/// fragment components.
///
using UrlFilter =
base::RepeatingCallback<std::string(const std::string& /*url*/)>;
///
// Used to resolve mime types for URLs, usually based on the file extension.
// |url| will be fully qualified and may contain query or fragment components.
/// Used to resolve mime types for URLs, usually based on the file extension.
/// |url| will be fully qualified and may contain query or fragment
/// components.
///
using MimeTypeResolver =
base::RepeatingCallback<std::string(const std::string& /*url*/)>;
@ -91,12 +92,12 @@ class CefResourceManager
public:
///
// Object representing a request. Each request object is used for a single
// call to Provider::OnRequest and will become detached (meaning the callbacks
// will no longer trigger) after Request::Continue or Request::Stop is called.
// A request passed to Provider::OnRequestCanceled will already have been
// detached. The methods of this class may be called on any browser process
// thread.
/// Object representing a request. Each request object is used for a single
/// call to Provider::OnRequest and will become detached (meaning the
/// callbacks will no longer trigger) after Request::Continue or Request::Stop
/// is called. A request passed to Provider::OnRequestCanceled will already
/// have been detached. The methods of this class may be called on any browser
/// process thread.
///
class Request : public base::RefCountedThreadSafe<Request> {
public:
@ -104,54 +105,54 @@ class CefResourceManager
Request& operator=(const Request&) = delete;
///
// Returns the URL associated with this request. The returned value will be
// fully qualified but will not contain query or fragment components. It
// will already have been passed through the URL filter.
/// Returns the URL associated with this request. The returned value will be
/// fully qualified but will not contain query or fragment components. It
/// will already have been passed through the URL filter.
///
std::string url() const { return params_.url_; }
///
// Returns the CefBrowser associated with this request.
/// Returns the CefBrowser associated with this request.
///
CefRefPtr<CefBrowser> browser() const { return params_.browser_; }
///
// Returns the CefFrame associated with this request.
/// Returns the CefFrame associated with this request.
///
CefRefPtr<CefFrame> frame() const { return params_.frame_; }
///
// Returns the CefRequest associated with this request.
/// Returns the CefRequest associated with this request.
///
CefRefPtr<CefRequest> request() const { return params_.request_; }
///
// Returns the current URL filter.
/// Returns the current URL filter.
///
const CefResourceManager::UrlFilter& url_filter() const {
return params_.url_filter_;
}
///
// Returns the current mime type resolver.
/// Returns the current mime type resolver.
///
const CefResourceManager::MimeTypeResolver& mime_type_resolver() const {
return params_.mime_type_resolver_;
}
///
// Continue handling the request. If |handler| is non-NULL then no
// additional providers will be called and the |handler| value will be
// returned via CefResourceManager::GetResourceHandler. If |handler| is NULL
// then the next provider in order, if any, will be called. If there are no
// additional providers then NULL will be returned via CefResourceManager::
// GetResourceHandler.
/// Continue handling the request. If |handler| is non-NULL then no
/// additional providers will be called and the |handler| value will be
/// returned via CefResourceManager::GetResourceHandler. If |handler| is
/// NULL then the next provider in order, if any, will be called. If there
/// are no additional providers then NULL will be returned via
/// CefResourceManager:: GetResourceHandler.
///
void Continue(CefRefPtr<CefResourceHandler> handler);
///
// Stop handling the request. No additional providers will be called and
// NULL will be returned via CefResourceManager::GetResourceHandler.
/// Stop handling the request. No additional providers will be called and
/// NULL will be returned via CefResourceManager::GetResourceHandler.
///
void Stop();
@ -183,25 +184,25 @@ class CefResourceManager
using RequestList = std::list<scoped_refptr<Request>>;
///
// Interface implemented by resource providers. A provider may be created on
// any thread but the methods will be called on, and the object will be
// destroyed on, the browser process IO thread.
/// Interface implemented by resource providers. A provider may be created on
/// any thread but the methods will be called on, and the object will be
/// destroyed on, the browser process IO thread.
///
class Provider {
public:
///
// Called to handle a request. If the provider knows immediately that it
// will not handle the request return false. Otherwise, return true and call
// Request::Continue or Request::Stop either in this method or
// asynchronously to indicate completion. See comments on Request for
// additional usage information.
/// Called to handle a request. If the provider knows immediately that it
/// will not handle the request return false. Otherwise, return true and
/// call Request::Continue or Request::Stop either in this method or
/// asynchronously to indicate completion. See comments on Request for
/// additional usage information.
///
virtual bool OnRequest(scoped_refptr<Request> request) = 0;
///
// Called when a request has been canceled. It is still safe to dereference
// |request| but any calls to Request::Continue or Request::Stop will be
// ignored.
/// Called when a request has been canceled. It is still safe to dereference
/// |request| but any calls to Request::Continue or Request::Stop will be
/// ignored.
///
virtual void OnRequestCanceled(scoped_refptr<Request> request) {}
@ -214,10 +215,10 @@ class CefResourceManager
CefResourceManager& operator=(const CefResourceManager&) = delete;
///
// Add a provider that maps requests for |url| to |content|. |url| should be
// fully qualified but not include a query or fragment component. If
// |mime_type| is empty the MimeTypeResolver will be used. See comments on
// AddProvider for usage of the |order| and |identifier| parameters.
/// Add a provider that maps requests for |url| to |content|. |url| should be
/// fully qualified but not include a query or fragment component. If
/// |mime_type| is empty the MimeTypeResolver will be used. See comments on
/// AddProvider for usage of the |order| and |identifier| parameters.
///
void AddContentProvider(const std::string& url,
const std::string& content,
@ -226,11 +227,11 @@ class CefResourceManager
const std::string& identifier);
///
// Add a provider that maps requests that start with |url_path| to files under
// |directory_path|. |url_path| should include an origin and optional path
// component only. Files will be loaded when a matching URL is requested.
// See comments on AddProvider for usage of the |order| and |identifier|
// parameters.
/// Add a provider that maps requests that start with |url_path| to files
/// under |directory_path|. |url_path| should include an origin and optional
/// path component only. Files will be loaded when a matching URL is
/// requested. See comments on AddProvider for usage of the |order| and
/// |identifier| parameters.
///
void AddDirectoryProvider(const std::string& url_path,
const std::string& directory_path,
@ -238,11 +239,11 @@ class CefResourceManager
const std::string& identifier);
///
// Add a provider that maps requests that start with |url_path| to files
// stored in the archive file at |archive_path|. |url_path| should include an
// origin and optional path component only. The archive file will be loaded
// when a matching URL is requested for the first time. See comments on
// AddProvider for usage of the |order| and |identifier| parameters.
/// Add a provider that maps requests that start with |url_path| to files
/// stored in the archive file at |archive_path|. |url_path| should include an
/// origin and optional path component only. The archive file will be loaded
/// when a matching URL is requested for the first time. See comments on
/// AddProvider for usage of the |order| and |identifier| parameters.
///
void AddArchiveProvider(const std::string& url_path,
const std::string& archive_path,
@ -251,49 +252,49 @@ class CefResourceManager
const std::string& identifier);
///
// Add a provider. This object takes ownership of |provider|. Providers will
// be called in ascending order based on the |order| value. Multiple providers
// sharing the same |order| value will be called in the order that they were
// added. The |identifier| value, which does not need to be unique, can be
// used to remove the provider at a later time.
/// Add a provider. This object takes ownership of |provider|. Providers will
/// be called in ascending order based on the |order| value. Multiple
/// providers sharing the same |order| value will be called in the order that
/// they were added. The |identifier| value, which does not need to be unique,
/// can be used to remove the provider at a later time.
///
void AddProvider(Provider* provider,
int order,
const std::string& identifier);
///
// Remove all providers with the specified |identifier| value. If any removed
// providers have pending requests the Provider::OnRequestCancel method will
// be called. The removed providers may be deleted immediately or at a later
// time.
/// Remove all providers with the specified |identifier| value. If any removed
/// providers have pending requests the Provider::OnRequestCancel method will
/// be called. The removed providers may be deleted immediately or at a later
/// time.
///
void RemoveProviders(const std::string& identifier);
///
// Remove all providers. If any removed providers have pending requests the
// Provider::OnRequestCancel method will be called. The removed providers may
// be deleted immediately or at a later time.
/// Remove all providers. If any removed providers have pending requests the
/// Provider::OnRequestCancel method will be called. The removed providers may
/// be deleted immediately or at a later time.
///
void RemoveAllProviders();
///
// Set the url filter. If not set the default no-op filter will be used.
// Changes to this value will not affect currently pending requests.
/// Set the url filter. If not set the default no-op filter will be used.
/// Changes to this value will not affect currently pending requests.
///
void SetUrlFilter(const UrlFilter& filter);
///
// Set the mime type resolver. If not set the default resolver will be used.
// Changes to this value will not affect currently pending requests.
/// Set the mime type resolver. If not set the default resolver will be used.
/// Changes to this value will not affect currently pending requests.
///
void SetMimeTypeResolver(const MimeTypeResolver& resolver);
// The below methods should be called from other CEF handlers. They must be
// called exactly as documented for the manager to function correctly.
/// The below methods should be called from other CEF handlers. They must be
/// called exactly as documented for the manager to function correctly.
///
// Called from CefRequestHandler::OnBeforeResourceLoad on the browser process
// IO thread.
/// Called from CefRequestHandler::OnBeforeResourceLoad on the browser process
/// IO thread.
///
cef_return_value_t OnBeforeResourceLoad(CefRefPtr<CefBrowser> browser,
CefRefPtr<CefFrame> frame,
@ -301,8 +302,8 @@ class CefResourceManager
CefRefPtr<CefCallback> callback);
///
// Called from CefRequestHandler::GetResourceHandler on the browser process
// IO thread.
/// Called from CefRequestHandler::GetResourceHandler on the browser process
/// IO thread.
///
CefRefPtr<CefResourceHandler> GetResourceHandler(
CefRefPtr<CefBrowser> browser,

46
include/wrapper/cef_scoped_temp_dir.h
View File

@ -42,20 +42,20 @@
#include "include/cef_base.h"
///
// An object representing a temporary / scratch directory that should be cleaned
// up (recursively) when this object goes out of scope. Note that since
// deletion occurs during the destructor, no further error handling is possible
// if the directory fails to be deleted. As a result, deletion is not
// guaranteed by this class.
//
// Multiple calls to the methods which establish a temporary directory
// (CreateUniqueTempDir, CreateUniqueTempDirUnderPath, and Set) must have
// intervening calls to Delete or Take, or the calls will fail.
/// An object representing a temporary / scratch directory that should be
/// cleaned up (recursively) when this object goes out of scope. Note that
/// since deletion occurs during the destructor, no further error handling is
/// possible if the directory fails to be deleted. As a result, deletion is not
/// guaranteed by this class.
///
/// Multiple calls to the methods which establish a temporary directory
/// (CreateUniqueTempDir, CreateUniqueTempDirUnderPath, and Set) must have
/// intervening calls to Delete or Take, or the calls will fail.
///
class CefScopedTempDir {
public:
///
// No directory is owned/created initially.
/// No directory is owned/created initially.
///
CefScopedTempDir();
@ -63,51 +63,51 @@ class CefScopedTempDir {
CefScopedTempDir& operator=(const CefScopedTempDir&) = delete;
///
// Recursively delete path.
/// Recursively delete path.
///
~CefScopedTempDir();
///
// Creates a unique directory in TempPath, and takes ownership of it.
// See file_util::CreateNewTemporaryDirectory.
/// Creates a unique directory in TempPath, and takes ownership of it.
/// See file_util::CreateNewTemporaryDirectory.
///
[[nodiscard]] bool CreateUniqueTempDir();
///
// Creates a unique directory under a given path, and takes ownership of it.
/// Creates a unique directory under a given path, and takes ownership of it.
///
[[nodiscard]] bool CreateUniqueTempDirUnderPath(const CefString& path);
///
// Takes ownership of directory at |path|, creating it if necessary.
// Don't call multiple times unless Take() has been called first.
/// Takes ownership of directory at |path|, creating it if necessary.
/// Don't call multiple times unless Take() has been called first.
///
[[nodiscard]] bool Set(const CefString& path);
///
// Deletes the temporary directory wrapped by this object.
/// Deletes the temporary directory wrapped by this object.
///
[[nodiscard]] bool Delete();
///
// Caller takes ownership of the temporary directory so it won't be destroyed
// when this object goes out of scope.
/// Caller takes ownership of the temporary directory so it won't be destroyed
/// when this object goes out of scope.
///
CefString Take();
///
// Returns the path to the created directory. Call one of the
// CreateUniqueTempDir* methods before getting the path.
/// Returns the path to the created directory. Call one of the
/// CreateUniqueTempDir* methods before getting the path.
///
const CefString& GetPath() const;
///
// Returns true if path_ is empty.
/// Returns true if path_ is empty.
///
bool IsEmpty() const;
///
// Returns true if path_ is non-empty and exists.
/// Returns true if path_ is non-empty and exists.
///
bool IsValid() const;

6
include/wrapper/cef_stream_resource_handler.h
View File

@ -42,17 +42,17 @@
#include "include/cef_stream.h"
///
// Implementation of the CefResourceHandler class for reading from a CefStream.
/// Implementation of the CefResourceHandler class for reading from a CefStream.
///
class CefStreamResourceHandler : public CefResourceHandler {
public:
///
// Create a new object with default response values.
/// Create a new object with default response values.
///
CefStreamResourceHandler(const CefString& mime_type,
CefRefPtr<CefStreamReader> stream);
///
// Create a new object with explicit response values.
/// Create a new object with explicit response values.
///
CefStreamResourceHandler(int status_code,
const CefString& status_text,

98
include/wrapper/cef_xml_object.h
View File

@ -48,27 +48,25 @@
class CefStreamReader;
///
// Thread safe class for representing XML data as a structured object. This
// class should not be used with large XML documents because all data will be
// resident in memory at the same time. This implementation supports a
// restricted set of XML features:
// <pre>
// (1) Processing instructions, whitespace and comments are ignored.
// (2) Elements and attributes must always be referenced using the fully
// qualified name (ie, namespace:localname).
// (3) Empty elements (<a/>) and elements with zero-length values (<a></a>)
// are considered the same.
// (4) Element nodes are considered part of a value if:
// (a) The element node follows a non-element node at the same depth
// (see 5), or
// (b) The element node does not have a namespace and the parent node does.
// (5) Mixed node types at the same depth are combined into a single element
// value as follows:
// (a) All node values are concatenated to form a single string value.
// (b) Entity reference nodes are resolved to the corresponding entity
// value.
// (c) Element nodes are represented by their outer XML string.
// </pre>
/// Thread safe class for representing XML data as a structured object. This
/// class should not be used with large XML documents because all data will be
/// resident in memory at the same time. This implementation supports a
/// restricted set of XML features:
///
/// 1. Processing instructions, whitespace and comments are ignored.
/// 2. Elements and attributes must always be referenced using the fully
/// qualified name (ie, namespace:localname).
/// 3. Empty elements ("<a/>") and elements with zero-length values ("<a></a>")
/// are considered the same.
/// 4. Element nodes are considered part of a value if:
/// 1. The element node follows a non-element node at the same depth
/// (see 5), or
/// 2. The element node does not have a namespace and the parent node does.
/// 5. Mixed node types at the same depth are combined into a single element
/// value as follows:
/// 1. All node values are concatenated to form a single string value.
/// 2. Entity reference nodes are resolved to the corresponding entity value.
/// 3. Element nodes are represented by their outer XML string.
///
class CefXmlObject : public base::RefCountedThreadSafe<CefXmlObject> {
public:
@ -76,8 +74,8 @@ class CefXmlObject : public base::RefCountedThreadSafe<CefXmlObject> {
using AttributeMap = std::map<CefString, CefString>;
///
// Create a new object with the specified name. An object name must always be
// at least one character long.
/// Create a new object with the specified name. An object name must always be
/// at least one character long.
///
explicit CefXmlObject(const CefString& name);
@ -85,8 +83,8 @@ class CefXmlObject : public base::RefCountedThreadSafe<CefXmlObject> {
CefXmlObject& operator=(const CefXmlObject&) = delete;
///
// Load the contents of the specified XML stream into this object. The
// existing children and attributes, if any, will first be cleared.
/// Load the contents of the specified XML stream into this object. The
/// existing children and attributes, if any, will first be cleared.
///
bool Load(CefRefPtr<CefStreamReader> stream,
CefXmlReader::EncodingType encodingType,
@ -94,56 +92,56 @@ class CefXmlObject : public base::RefCountedThreadSafe<CefXmlObject> {
CefString* loadError);
///
// Set the name, children and attributes of this object to a duplicate of the
// specified object's contents. The existing children and attributes, if any,
// will first be cleared.
/// Set the name, children and attributes of this object to a duplicate of the
/// specified object's contents. The existing children and attributes, if any,
/// will first be cleared.
///
void Set(CefRefPtr<CefXmlObject> object);
///
// Append a duplicate of the children and attributes of the specified object
// to this object. If |overwriteAttributes| is true then any attributes in
// this object that also exist in the specified object will be overwritten
// with the new values. The name of this object is not changed.
/// Append a duplicate of the children and attributes of the specified object
/// to this object. If |overwriteAttributes| is true then any attributes in
/// this object that also exist in the specified object will be overwritten
/// with the new values. The name of this object is not changed.
///
void Append(CefRefPtr<CefXmlObject> object, bool overwriteAttributes);
///
// Return a new object with the same name, children and attributes as this
// object. The parent of the new object will be NULL.
/// Return a new object with the same name, children and attributes as this
/// object. The parent of the new object will be NULL.
///
CefRefPtr<CefXmlObject> Duplicate();
///
// Clears this object's children and attributes. The name and parenting of
// this object are not changed.
/// Clears this object's children and attributes. The name and parenting of
/// this object are not changed.
///
void Clear();
///
// Access the object's name. An object name must always be at least one
// character long.
/// Access the object's name. An object name must always be at least one
/// character long.
///
CefString GetName();
bool SetName(const CefString& name);
///
// Access the object's parent. The parent can be NULL if this object has not
// been added as the child on another object.
/// Access the object's parent. The parent can be NULL if this object has not
/// been added as the child on another object.
///
bool HasParent();
CefRefPtr<CefXmlObject> GetParent();
///
// Access the object's value. An object cannot have a value if it also has
// children. Attempting to set the value while children exist will fail.
/// Access the object's value. An object cannot have a value if it also has
/// children. Attempting to set the value while children exist will fail.
///
bool HasValue();
CefString GetValue();
bool SetValue(const CefString& value);
///
// Access the object's attributes. Attributes must have unique names.
/// Access the object's attributes. Attributes must have unique names.
///
bool HasAttributes();
size_t GetAttributeCount();
@ -154,11 +152,11 @@ class CefXmlObject : public base::RefCountedThreadSafe<CefXmlObject> {
void ClearAttributes();
///
// Access the object's children. Each object can only have one parent so
// attempting to add an object that already has a parent will fail. Removing a
// child will set the child's parent to NULL. Adding a child will set the
// child's parent to this object. This object's value, if any, will be cleared
// if a child is added.
/// Access the object's children. Each object can only have one parent so
/// attempting to add an object that already has a parent will fail. Removing
/// a child will set the child's parent to NULL. Adding a child will set the
/// child's parent to this object. This object's value, if any, will be
/// cleared if a child is added.
///
bool HasChildren();
size_t GetChildCount();
@ -169,12 +167,12 @@ class CefXmlObject : public base::RefCountedThreadSafe<CefXmlObject> {
void ClearChildren();
///
// Find the first child with the specified name.
/// Find the first child with the specified name.
///
CefRefPtr<CefXmlObject> FindChild(const CefString& name);
///
// Find all children with the specified name.
/// Find all children with the specified name.
///
size_t FindChildren(const CefString& name, ObjectVector& children);

50
include/wrapper/cef_zip_archive.h
View File

@ -46,35 +46,35 @@
class CefStreamReader;
///
// Thread-safe class for accessing zip archive file contents. This class should
// not be used with large archive files because all data will be resident in
// memory at the same time. This implementation supports a restricted set of zip
// archive features:
// (1) All file names are stored and compared in lower case.
// (2) File ordering from the original zip archive is not maintained. This
// means that files from the same folder may not be located together in the
// file content map.
/// Thread-safe class for accessing zip archive file contents. This class should
/// not be used with large archive files because all data will be resident in
/// memory at the same time. This implementation supports a restricted set of
/// zip archive features:
/// 1. All file names are stored and compared in lower case.
/// 2. File ordering from the original zip archive is not maintained. This means
/// that files from the same folder may not be located together in the file
/// content map.
///
class CefZipArchive : public base::RefCountedThreadSafe<CefZipArchive> {
public:
///
// Class representing a file in the archive. Accessing the file data from
// multiple threads is safe provided a reference to the File object is kept.
/// Class representing a file in the archive. Accessing the file data from
/// multiple threads is safe provided a reference to the File object is kept.
///
class File : public CefBaseRefCounted {
public:
///
// Returns the read-only data contained in the file.
/// Returns the read-only data contained in the file.
///
virtual const unsigned char* GetData() const = 0;
///
// Returns the size of the data in the file.
/// Returns the size of the data in the file.
///
virtual size_t GetDataSize() const = 0;
///
// Returns a CefStreamReader object for streaming the contents of the file.
/// Returns a CefStreamReader object for streaming the contents of the file.
///
virtual CefRefPtr<CefStreamReader> GetStreamReader() const = 0;
};
@ -82,7 +82,7 @@ class CefZipArchive : public base::RefCountedThreadSafe<CefZipArchive> {
using FileMap = std::map<CefString, CefRefPtr<File>>;
///
// Create a new object.
/// Create a new object.
///
CefZipArchive();
@ -90,43 +90,43 @@ class CefZipArchive : public base::RefCountedThreadSafe<CefZipArchive> {
CefZipArchive& operator=(const CefZipArchive&) = delete;
///
// Load the contents of the specified zip archive stream into this object.
// If the zip archive requires a password then provide it via |password|.
// If |overwriteExisting| is true then any files in this object that also
// exist in the specified archive will be replaced with the new files.
// Returns the number of files successfully loaded.
/// Load the contents of the specified zip archive stream into this object.
/// If the zip archive requires a password then provide it via |password|.
/// If |overwriteExisting| is true then any files in this object that also
/// exist in the specified archive will be replaced with the new files.
/// Returns the number of files successfully loaded.
///
size_t Load(CefRefPtr<CefStreamReader> stream,
const CefString& password,
bool overwriteExisting);
///
// Clears the contents of this object.
/// Clears the contents of this object.
///
void Clear();
///
// Returns the number of files in the archive.
/// Returns the number of files in the archive.
///
size_t GetFileCount() const;
///
// Returns true if the specified file exists and has contents.
/// Returns true if the specified file exists and has contents.
///
bool HasFile(const CefString& fileName) const;
///
// Returns the specified file.
/// Returns the specified file.
///
CefRefPtr<File> GetFile(const CefString& fileName) const;
///
// Removes the specified file.
/// Removes the specified file.
///
bool RemoveFile(const CefString& fileName);
///
// Returns the map of all files.
/// Returns the map of all files.
///
size_t GetFiles(FileMap& map) const;