Click or drag to resize
CfxRuntime Class

[This is preliminary documentation and is subject to change.]

Collection of global static CEF functions.
Inheritance Hierarchy
SystemObject
  ChromiumCfxRuntime

Namespace: Chromium
Assembly: ChromiumFX (in ChromiumFX.dll)
Syntax
public static class CfxRuntime

The CfxRuntime type exposes the following members.

Properties
  NameDescription
Public propertyStatic memberLibCefDirPath
Set the path to the directory containing the libcef library. If left blank the default locations are searched.
Public propertyStatic memberLibCfxDirPath
Set the path to the directory containing the libcfx library. If left blank the default locations are searched.
Public propertyStatic memberLibrariesLoaded
True if the native libraries are loaded.
Public propertyStatic memberPlatformArch
The system architecture ChromiumFX is currently running on.
Public propertyStatic memberPlatformOS
The operating system ChromiumFX is currently running on.
Top
Methods
  NameDescription
Public methodStatic memberAddCrossOriginWhitelistEntry
Add an entry to the cross-origin access whitelist. The same-origin policy restricts how scripts hosted from different origins (scheme + domain + port) can communicate. By default, scripts can only access resources with the same origin. Scripts hosted on the HTTP and HTTPS schemes (but no other schemes) can use the "Access-Control-Allow-Origin" header to allow cross-origin requests. For example, https://source.example.com can make XMLHttpRequest requests on http://target.example.com if the http://target.example.com request returns an "Access-Control-Allow-Origin: https://source.example.com" response header. Scripts in separate frames or iframes and hosted from the same protocol and domain suffix can execute cross-origin JavaScript if both pages set the document.domain value to the same domain suffix. For example, scheme://foo.example.com and scheme://bar.example.com can communicate using JavaScript if both domains set document.domain="example.com". This function is used to allow access to origins that would otherwise violate the same-origin policy. Scripts hosted underneath the fully qualified |sourceOrigin| URL (like http://www.example.com) will be allowed access to all resources hosted on the specified |targetProtocol| and |targetDomain|. If |targetDomain| is non-NULL and |allowTargetSubdomains| if false (0) only exact domain matches will be allowed. If |targetDomain| contains a top- level domain component (like "example.com") and |allowTargetSubdomains| is true (1) sub-domain matches will be allowed. If |targetDomain| is NULL and |allowTargetSubdomains| if true (1) all domains and IP addresses will be allowed. This function cannot be used to bypass the restrictions on local or display isolated schemes. See the comments on CfxRegisterCustomScheme for more information. This function may be called on any thread. Returns false (0) if |sourceOrigin| is invalid or the whitelist cannot be accessed.
Public methodStatic memberApiHash
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
Public methodStatic memberBase64Decode
Decodes the base64 encoded string |data|. The returned value will be NULL if the decoding fails.
Public methodStatic memberBase64Encode
Encodes |data| as a base64 string.
Public methodStatic memberBeginTracing
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.
Public methodStatic memberClearCrossOriginWhitelist
Remove all entries from the cross-origin access whitelist. Returns false (0) if the whitelist cannot be accessed.
Public methodStatic memberClearSchemeHandlerFactories
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().
Public methodStatic memberCrashReportingEnabled
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.
Public methodStatic memberCreateContextShared
Creates a new context object that shares storage with |other| and uses an optional |handler|.
Public methodStatic memberCreateDirectory
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.
Public methodStatic memberCreateNewTempDirectory
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.
Public methodStatic memberCreateTempDirectoryInDirectory
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.
Public methodStatic memberCreateUrl
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.
Public methodStatic memberCurrentlyOn
Returns true (1) if called on the specified thread. Equivalent to using CfxTaskRunner.GetForThread(threadId).BelongsToCurrentThread().
Public methodStatic memberDeleteFile
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.
Public methodStatic memberDirectoryExists
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.
Public methodStatic memberDoMessageLoopWork
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.
Public methodStatic memberEnableHighDpiSupport
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.
Public methodStatic memberEndTracing
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.
Public methodStatic memberExecuteProcess
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.
Public methodStatic memberExecuteProcess(CfxApp)
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.
Public methodStatic memberFormatUrlForSecurityDisplay
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.
Public methodStatic memberGetCefVersion
Public methodStatic memberGetChromeVersion
Public methodStatic memberGetExtensionsForMimeType
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.
Public methodStatic memberGetGeolocation
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.
Public methodStatic memberGetMimeType
Returns the mime type for the specified file extension or an NULL string if unknown.
Public methodStatic memberGetPath
Retrieve the path associated with the specified |key|. Returns true (1) on success. Can be called on any thread in the browser process.
Public methodStatic memberGetTempDirectory
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).
Public methodStatic memberInitialize(CfxSettings, CfxApp)
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.
Public methodStatic memberInitialize(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.
Public methodStatic memberIsCertStatusError
Returns true (1) if the certificate status has any error, major or minor.
Public methodStatic memberIsCertStatusMinorError
Returns true (1) if the certificate status represents only minor errors (e.g. failure to verify certificate revocation).
Public methodStatic memberIsWebPluginUnstable
Query if a plugin is unstable. Can be called on any thread in the browser process.
Public methodStatic memberLaunchProcess
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.)
Public methodStatic memberNowFromSystemTraceTime
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.
Public methodStatic memberParseJson
Parses the specified |jsonString| and returns a dictionary or list representation. If JSON parsing fails this function returns NULL.
Public methodStatic memberParseJsonAndReturnError
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.
Public methodStatic memberParseUrl
Parse the specified |url| into its component parts. Returns false (0) if the URL is NULL or invalid.
Public methodStatic memberPostDelayedTask
Post a task for delayed execution on the specified thread. Equivalent to using CfxTaskRunner.GetForThread(threadId).PostDelayedTask(task, delay_ms).
Public methodStatic memberPostTask
Post a task for execution on the specified thread. Equivalent to using CfxTaskRunner.GetForThread(threadId).PostTask(task).
Public methodStatic memberQuitMessageLoop
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.
Public methodStatic memberRefreshWebPlugins
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.
Public methodStatic memberRegisterExtension
Register a new V8 extension with the specified JavaScript extension code and handler. Functions implemented by the handler are prototyped using the keyword 'native'. The calling of a native function is restricted to the scope in which the prototype of the native function is defined. This function may only be called on the render process main thread. Example JavaScript extension code: <pre> // create the 'example' global object if it doesn't already exist. if (!example) example = {}; // create the 'example.test' global object if it doesn't already exist. if (!example.test) example.test = {}; (function() { // Define the function 'example.test.myfunction'. example.test.myfunction = function() { // Call CfxV8Handler.Execute() with the function name 'MyFunction' // and no arguments. native function MyFunction(); return MyFunction(); }; // Define the getter function for parameter 'example.test.myparam'. example.test.__defineGetter__('myparam', function() { // Call CfxV8Handler.Execute() with the function name 'GetMyParam' // and no arguments. native function GetMyParam(); return GetMyParam(); }); // Define the setter function for parameter 'example.test.myparam'. example.test.__defineSetter__('myparam', function(b) { // Call CfxV8Handler.Execute() with the function name 'SetMyParam' // and a single argument. native function SetMyParam(); if(b) SetMyParam(b); }); // Extension definitions can also contain normal JavaScript variables // and functions. var myint = 0; example.test.increment = function() { myint += 1; return myint; }; })(); </pre> Example usage in the page: <pre> // Call the function. example.test.myfunction(); // Set the parameter. example.test.myparam = value; // Get the parameter. value = example.test.myparam; // Call another function. example.test.increment(); </pre>
Public methodStatic memberRegisterSchemeHandlerFactory
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().
Public methodStatic memberRegisterWebPluginCrash
Register a plugin crash. Can be called on any thread in the browser process but will be executed on the IO thread.
Public methodStatic memberRegisterWidevineCdm
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. "1.4.8.903"). 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.
Public methodStatic memberRemoveCrossOriginWhitelistEntry
Remove an entry from the cross-origin access whitelist. Returns false (0) if |sourceOrigin| is invalid or the whitelist cannot be accessed.
Public methodStatic memberRunMessageLoop
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.
Public methodStatic memberSetCrashKeyValue
Sets or clears a specific key-value pair from the crash metadata.
Public methodStatic memberSetOsModalLoop
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.
Public methodStatic memberShutdown
This function should be called on the main application thread to shut down the CEF browser process before the application exits.
Public methodStatic memberUnregisterInternalWebPlugin
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.
Public methodStatic memberUriDecode
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.
Public methodStatic memberUriEncode
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.
Public methodStatic memberVersionInfo
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
Public methodStatic memberVisitWebPluginInfo
Visit web plugin information. Can be called on any thread in the browser process.
Public methodStatic memberWriteJson
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.
Public methodStatic memberZipDirectory
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.
Top
See Also