[This is preliminary documentation and is subject to change.]
Thetype exposes the following members.
Set the path to the directory containing the libcef library. If left blank the default locations are searched.
Set the path to the directory containing the libcfx library. If left blank the default locations are searched.
True if the native libraries are loaded.
The system architecture ChromiumFX is currently running on.
The operating system ChromiumFX is currently running on.
Returns CEF API hashes for the libcef library. The returned string is owned by the library and should not be freed. The |entry| parameter describes which hash value will be returned: 0 - CEF_API_HASH_PLATFORM 1 - CEF_API_HASH_UNIVERSAL 2 - CEF_COMMIT_HASH
Decodes the base64 encoded string |data|. The returned value will be NULL if the decoding fails.
Encodes |data| as a base64 string.
Start tracing events on all processes. Tracing is initialized asynchronously and |callback| will be executed on the UI thread after initialization is complete. If CfxBeginTracing was called previously, or if a CfxEndTracingAsync call is pending, CfxBeginTracing will fail and return false (0). |categories| is a comma-delimited list of category wildcards. A category can have an optional '-' prefix to make it an excluded category. Having both included and excluded categories in the same list is not supported. Example: "test_MyTest*" Example: "test_MyTest*,test_OtherStuff" Example: "-excluded_category1,-excluded_category2" This function must be called on the browser process UI thread.
Remove all entries from the cross-origin access whitelist. Returns false (0) if the whitelist cannot be accessed.
Clear all scheme handler factories registered with the global request context. Returns false (0) on error. This function may be called on any thread in the browser process. Using this function is equivalent to calling c ef_request_tContext::cef_request_context_get_global_context()->clear_scheme_h andler_factories().
Crash reporting is configured using an INI-style config file named "crash_reporter.cfg". On Windows and Linux this file must be placed next to the main application executable. On macOS this file must be placed in the top-level app bundle Resources directory (e.g. "<appname>.app/Contents/Resources"). File contents are as follows: # Comments start with a hash character and must be on their own line. [Config] ProductName=<Value of the "prod" crash key; defaults to "cef"> ProductVersion=<Value of the "ver" crash key; defaults to the CEF version> AppName=<Windows only; App-specific folder name component for storing crash information; default to "CEF"> ExternalHandler=<Windows only; Name of the external handler exe to use instead of re-launching the main exe; default to empty> BrowserCrashForwardingEnabled=<macOS only; True if browser process crashes should be forwarded to the system crash reporter; default to false> ServerURL=<crash server URL; default to empty> RateLimitEnabled=<True if uploads should be rate limited; default to true> MaxUploadsPerDay=<Max uploads per 24 hours, used if rate limit is enabled; default to 5> MaxDatabaseSizeInMb=<Total crash report disk usage greater than this value will cause older reports to be deleted; default to 20> MaxDatabaseAgeInDays=<Crash reports older than this value will be deleted; default to 5> [CrashKeys] my_key1=<small|medium|large> my_key2=<small|medium|large> Config section: If "ProductName" and/or "ProductVersion" are set then the specified values will be included in the crash dump metadata. On macOS if these values are set to NULL then they will be retrieved from the Info.plist file using the "CFBundleName" and "CFBundleShortVersionString" keys respectively. If "AppName" is set on Windows then crash report information (metrics, database and dumps) will be stored locally on disk under the "C:\Users\[CurrentUser]\AppData\Local\[AppName]\User Data" folder. On other platforms the CfxSettings.UserDataPath value will be used. If "ExternalHandler" is set on Windows then the specified exe will be launched as the crashpad-handler instead of re-launching the main process exe. The value can be an absolute path or a path relative to the main exe directory. On Linux the CfxSettings.BrowserSubprocessPath value will be used. On macOS the existing subprocess app bundle will be used. If "BrowserCrashForwardingEnabled" is set to true (1) on macOS then browser process crashes will be forwarded to the system crash reporter. This results in the crash UI dialog being displayed to the user and crash reports being logged under "~/Library/Logs/DiagnosticReports". Forwarding of crash reports from non-browser processes and Debug builds is always disabled. If "ServerURL" is set then crashes will be uploaded as a multi-part POST request to the specified URL. Otherwise, reports will only be stored locally on disk. If "RateLimitEnabled" is set to true (1) then crash report uploads will be rate limited as follows: 1. If "MaxUploadsPerDay" is set to a positive value then at most the specified number of crashes will be uploaded in each 24 hour period. 2. If crash upload fails due to a network or server error then an incremental backoff delay up to a maximum of 24 hours will be applied for retries. 3. If a backoff delay is applied and "MaxUploadsPerDay" is > 1 then the "MaxUploadsPerDay" value will be reduced to 1 until the client is restarted. This helps to avoid an upload flood when the network or server error is resolved. Rate limiting is not supported on Linux. If "MaxDatabaseSizeInMb" is set to a positive value then crash report storage on disk will be limited to that size in megabytes. For example, on Windows each dump is about 600KB so a "MaxDatabaseSizeInMb" value of 20 equates to about 34 crash reports stored on disk. Not supported on Linux. If "MaxDatabaseAgeInDays" is set to a positive value then crash reports older than the specified age in days will be deleted. Not supported on Linux. CrashKeys section: Any number of crash keys can be specified for use by the application. Crash key values will be truncated based on the specified size (small = 63 bytes, medium = 252 bytes, large = 1008 bytes). The value of crash keys can be set from any thread or process using the CfxSetCrashKeyValue function. These key/value pairs will be sent to the crash server along with the crash dump file. Medium and large values will be chunked for submission. For example, if your key is named "mykey" then the value will be broken into ordered chunks and submitted using keys named "mykey-1", "mykey-2", etc.
Creates a new context object that shares storage with |other| and uses an optional |handler|.
Creates a directory and all parent directories if they don't already exist. Returns true (1) on successful creation or if the directory already exists. The directory is only readable by the current user. Calling this function on the browser process UI or IO threads is not allowed.
Creates a new directory. On Windows if |prefix| is provided the new directory name is in the format of "prefixyyyy". Returns true (1) on success and sets |newTempPath| to the full path of the directory that was created. The directory is only readable by the current user. Calling this function on the browser process UI or IO threads is not allowed.
Creates a directory within another directory. Extra characters will be appended to |prefix| to ensure that the new directory does not have the same name as an existing directory. Returns true (1) on success and sets |newDir| to the full path of the directory that was created. The directory is only readable by the current user. Calling this function on the browser process UI or IO threads is not allowed.
Creates a URL from the specified |parts|, which must contain a non-NULL spec or a non-NULL host and path (at a minimum), but not both. Returns false (0) if |parts| isn't initialized as described.
Returns true (1) if called on the specified thread. Equivalent to using CfxTaskRunner.GetForThread(threadId).BelongsToCurrentThread().
Deletes the given path whether it's a file or a directory. If |path| is a directory all contents will be deleted. If |recursive| is true (1) any sub- directories and their contents will also be deleted (equivalent to executing "rm -rf", so use with caution). On POSIX environments if |path| is a symbolic link then only the symlink will be deleted. Returns true (1) on successful deletion or if |path| does not exist. Calling this function on the browser process UI or IO threads is not allowed.
Returns true (1) if the given path exists and is a directory. Calling this function on the browser process UI or IO threads is not allowed.
Perform a single iteration of CEF message loop processing. This function is provided for cases where the CEF message loop must be integrated into an existing application message loop. Use of this function is not recommended for most users; use either the cef_run_message_loop() function or CfxSettings.MultiThreadedMessageLoop if possible. When using this function care must be taken to balance performance against excessive CPU usage. It is recommended to enable the CfxSettings.ExternalMessagePump option when using this function so that CfxBrowserProcessHandler.OnScheduleMessagePumpWork() callbacks can facilitate the scheduling process. This function should only be called on the main application thread and only if cef_initialize() is called with a CfxSettings.MultiThreadedMessageLoop value of false (0). This function will not block.
Call during process startup to enable High-DPI support on Windows 7 or newer. Older versions of Windows should be left DPI-unaware because they do not support DirectWrite and GDI fonts are kerned very badly.
Stop tracing events on all processes. This function will fail and return false (0) if a previous call to CfxEndTracingAsync is already pending or if CfxBeginTracing was not called. |tracingFile| is the path at which tracing data will be written and |callback| is the callback that will be executed once all processes have sent their trace data. If |tracingFile| is NULL a new temporary file path will be used. If |callback| is NULL no trace data will be written. This function must be called on the browser process UI thread.
This function should be called from the application entry point function to execute a secondary process. It can be used to run secondary processes from the browser client executable (default behavior) or from a separate executable specified by the CefSettings.browser_subprocess_path value. If called for the browser process (identified by no "type" command-line value) it will return immediately with a value of -1. If called for a recognized secondary process it will block until the process should exit and then return the process exit code. If the browser process was initialized with a valid render process startup callback, the render main thread will be redirected through the remoting interface into the browser process. The browser process' render process startup callback routine is then responsible for calling CfrRuntime.ExecuteProcess(). The chromium sandbox is currently not supported within ChromiumFX.
This function should be called from the application entry point function to execute a secondary process. It can be used to run secondary processes from the browser client executable (default behavior) or from a separate executable specified by the CefSettings.browser_subprocess_path value. If called for the browser process (identified by no "type" command-line value) it will return immediately with a value of -1. If called for a recognized secondary process it will block until the process should exit and then return the process exit code. The |application| parameter may be NULL. If the browser process was initialized with a valid render process startup callback, the render main thread will be redirected through the remoting interface into the browser process. The browser process' render process startup callback routine is then responsible for calling CfrRuntime.ExecuteProcess() and the |application| parameter will be ignored. The chromium sandbox is currently not supported within ChromiumFX.
This is a convenience function for formatting a URL in a concise and human- friendly way to help users make security-related decisions (or in other circumstances when people need to distinguish sites, origins, or otherwise- simplified URLs from each other). Internationalized domain names (IDN) may be presented in Unicode if the conversion is considered safe. The returned value will (a) omit the path for standard schemes, excepting file and filesystem, and (b) omit the port if it is the default for the scheme. Do not use this for URLs which will be parsed or sent to other applications.
Get the extensions associated with the given mime type. This should be passed in lower case. There could be multiple extensions for a given mime type, like "html,htm" for "text/html", or "txt,text,html,..." for "text/*". Any existing elements in the provided vector will not be erased.
Request a one-time geolocation update. This function bypasses any user permission checks so should only be used by code that is allowed to access location information.
Returns the mime type for the specified file extension or an NULL string if unknown.
Retrieve the path associated with the specified |key|. Returns true (1) on success. Can be called on any thread in the browser process.
Get the temporary directory provided by the system. WARNING: In general, you should use the temp directory variants below instead of this function. Those variants will ensure that the proper permissions are set so that other users on the system can't edit them while they're open (which could lead to security issues).
This function should be called on the main application thread to initialize the CEF browser process. The |application| parameter may be NULL. A return value of true (1) indicates that it succeeded and false (0) indicates that it failed. The chromium sandbox is currently not supported within ChromiumFX.
|Initialize(CfxSettings, CfxApp, CfxRenderProcessMainDelegate)|
This function should be called on the main application thread to initialize the CEF browser process with support for the remote interface to the render process. The |application| parameter may be NULL. A return value of true (1) indicates that it succeeded and false (0) indicates that it failed. If |renderProcessMain| is provided, then every newly created render process main thread will be redirected through this callback and the callee is responsible for calling CfrRuntime.ExecuteProcess() from within the scope of this callback. The chromium sandbox is currently not supported within ChromiumFX.
Returns true (1) if the certificate status has any error, major or minor.
Returns true (1) if the certificate status represents only minor errors (e.g. failure to verify certificate revocation).
Query if a plugin is unstable. Can be called on any thread in the browser process.
Launches the process specified via |commandLine|. Returns true (1) upon success. Must be called on the browser process TID_PROCESS_LAUNCHER thread. Unix-specific notes: - All file descriptors open in the parent process will be closed in the child process except for stdin, stdout, and stderr. - If the first argument on the command line does not contain a slash, PATH will be searched. (See man execvp.)
Returns the current system trace time or, if none is defined, the current high-res time. Can be used by clients to synchronize with the time information in trace events.
Parses the specified |jsonString| and returns a dictionary or list representation. If JSON parsing fails this function returns NULL.
Parses the specified |jsonString| and returns a dictionary or list representation. If JSON parsing fails this function returns NULL and populates |errorCodeOut| and |errorMsgOut| with an error code and a formatted error message respectively.
Parse the specified |url| into its component parts. Returns false (0) if the URL is NULL or invalid.
Post a task for delayed execution on the specified thread. Equivalent to using CfxTaskRunner.GetForThread(threadId).PostDelayedTask(task, delay_ms).
Post a task for execution on the specified thread. Equivalent to using CfxTaskRunner.GetForThread(threadId).PostTask(task).
Quit the CEF message loop that was started by calling cef_run_message_loop(). This function should only be called on the main application thread and only if cef_run_message_loop() was used.
Cause the plugin list to refresh the next time it is accessed regardless of whether it has already been loaded. Can be called on any thread in the browser process.
Register a scheme handler factory with the global request context. An NULL |domainName| value for a standard scheme will cause the factory to match all domain names. The |domainName| value will be ignored for non-standard schemes. If |schemeName| is a built-in scheme and no handler is returned by |factory| then the built-in scheme handler factory will be called. If |schemeName| is a custom scheme then you must also implement the CfxApp.OnRegisterCustomSchemes() function in all processes. This function may be called multiple times to change or remove the factory that matches the specified |schemeName| and optional |domainName|. Returns false (0) if an error occurs. This function may be called on any thread in the browser process. Using this function is equivalent to calling CfxRequestCo ntext::cef_request_context_get_global_context()->register_scheme_handler_fact ory().
Register a plugin crash. Can be called on any thread in the browser process but will be executed on the IO thread.
Register the Widevine CDM plugin. The client application is responsible for downloading an appropriate platform-specific CDM binary distribution from Google, extracting the contents, and building the required directory structure on the local machine. The CfxBrowserHost.StartDownload function and CfxZipArchive structure can be used to implement this functionality in CEF. Contact Google via https://www.widevine.com/contact.html for details on CDM download. |path| is a directory that must contain the following files: 1. manifest.json file from the CDM binary distribution (see below). 2. widevinecdm file from the CDM binary distribution (e.g. widevinecdm.dll on on Windows, libwidevinecdm.dylib on OS X, libwidevinecdm.so on Linux). 3. widevidecdmadapter file from the CEF binary distribution (e.g. widevinecdmadapter.dll on Windows, widevinecdmadapter.plugin on OS X, libwidevinecdmadapter.so on Linux). If any of these files are missing or if the manifest file has incorrect contents the registration will fail and |callback| will receive a |result| value of CEF_CDM_REGISTRATION_ERROR_INCORRECT_CONTENTS. The manifest.json file must contain the following keys: A. "os": Supported OS (e.g. "mac", "win" or "linux"). B. "arch": Supported architecture (e.g. "ia32" or "x64"). C. "x-cdm-module-versions": Module API version (e.g. "4"). D. "x-cdm-interface-versions": Interface API version (e.g. "8"). E. "x-cdm-host-versions": Host API version (e.g. "8"). F. "version": CDM version (e.g. "22.214.171.1243"). G. "x-cdm-codecs": List of supported codecs (e.g. "vp8,vp9.0,avc1"). A through E are used to verify compatibility with the current Chromium version. If the CDM is not compatible the registration will fail and |callback| will receive a |result| value of CEF_CDM_REGISTRATION_ERROR_INCOMPATIBLE. |callback| will be executed asynchronously once registration is complete. On Linux this function must be called before cef_initialize() and the registration cannot be changed during runtime. If registration is not supported at the time that cef_register_widevine_cdm() is called then |callback| will receive a |result| value of CEF_CDM_REGISTRATION_ERROR_NOT_SUPPORTED.
Remove an entry from the cross-origin access whitelist. Returns false (0) if |sourceOrigin| is invalid or the whitelist cannot be accessed.
Run the CEF message loop. Use this function instead of an application- provided message loop to get the best balance between performance and CPU usage. This function should only be called on the main application thread and only if cef_initialize() is called with a CfxSettings.MultiThreadedMessageLoop value of false (0). This function will block until a quit message is received by the system.
Sets or clears a specific key-value pair from the crash metadata.
Set to true (1) before calling Windows APIs like TrackPopupMenu that enter a modal message loop. Set to false (0) after exiting the modal message loop.
This function should be called on the main application thread to shut down the CEF browser process before the application exits.
Unregister an internal plugin. This may be undone the next time cef_refresh_web_plugins() is called. Can be called on any thread in the browser process.
Unescapes |text| and returns the result. Unescaping consists of looking for the exact pattern "%XX" where each X is a hex digit and converting to the character with the numerical value of those digits (e.g. "i%20=%203%3b" unescapes to "i = 3;"). If |convertToUtf8| is true (1) this function will attempt to interpret the initial decoded result as UTF-8. If the result is convertable into UTF-8 it will be returned as converted. Otherwise the initial decoded result will be returned. The |unescapeRule| parameter supports further customization the decoding process.
Escapes characters in |text| which are unsuitable for use as a query parameter value. Everything except alphanumerics and -_.!~*'() will be converted to "%XX". If |usePlus| is true (1) spaces will change to "+". The result is basically the same as encodeURIComponent in Javacript.
Returns CEF version information for the libcef library. The |entry| parameter describes which version component will be returned: 0 - CEF_VERSION_MAJOR 1 - CEF_COMMIT_NUMBER 2 - CHROME_VERSION_MAJOR 3 - CHROME_VERSION_MINOR 4 - CHROME_VERSION_BUILD 5 - CHROME_VERSION_PATCH
Visit web plugin information. Can be called on any thread in the browser process.
Generates a JSON string from the specified root |node| which should be a dictionary or list value. Returns an NULL string on failure. This function requires exclusive access to |node| including any underlying data.
Writes the contents of |srcDir| into a zip archive at |destFile|. If |includeHiddenFiles| is true (1) files starting with "." will be included. Returns true (1) on success. Calling this function on the browser process UI or IO threads is not allowed.