Cef應用程序結構

Application Structure

應用程序結構

Every CEF3 application has the same general structure.

• Provide an entry-point function that initializes CEF and runs either sub-process executable logic or the CEF message loop.
• Provide an implementation of CefApp to handle process-specific callbacks.
• Provide an implementation of CefClient to handle browser-instance-specific callbacks.
• Call CefBrowserHost::CreateBrowser() to create a browser instance and manage the browser life span using CefLifeSpanHandler.

每個CEF3應用程序都是相同的結構

• 提供入口函數，用於初始化CEF、運行子進程執行邏輯或者CEF消息循環。
• 提供CefApp實現，用於處理進程相關的回調。
• 提供CefClient實現，用於處理browser實例相關的回調
• 執行CefBrowserHost::CreateBrowser()創建一個browser實例，使用CefLifeSpanHandler管理browser對象生命週期。

Entry-Point Function

入口函數

As described in the “Processes” section a CEF3 application will run multiple processes. The processes can all use the same executable or a separate executable can be specified for the sub-processes. Execution of the process begins in the entry-point function. Complete platform-specific examples for Windows, Linux and Mac OS-X are available in cefclient_win.cc, cefclient_gtk.cc and cefclient_mac.mm respectively.

像本文中進程章節描述的那樣，一個CEF3應用程序會運行多個進程，這些進程能夠使用同一個執行器或者爲子進程定製的、單獨的執行器。進程的執行從入口函數開始，示例cefclient_win.cc、cefclient_gtk.cc、cefclient_mac.mm分別對應Windows、Linux和Mac OS-X平臺下的實現。

When launching sub-processes CEF will specify configuration information using the command-line that must be passed into the CefExecuteProcess function via the CefMainArgs structure. The definition of CefMainArgs is platform-specific. On Linux and Mac OS X it accepts the argc and argv values which are passed into the main() function.

當執行子進程是，CEF將使用命令行參數指定配置信息，這些命令行參數必須通過CefMainArgs結構體傳入到CefExecuteProcess函數。CefMainArgs的定義與平臺相關，在Linux、Mac OS X平臺下，它接收main函數傳入的argc和argv參數值。

1. CefMainArgs main_args(argc, argv);

On Windows it accepts the instance handle (HINSTANCE) which is passed into the wWinMain() function. The instance handle is also retrievable via GetModuleHandle(NULL).

在Windows平臺下，它接收wWinMain函數傳入的參數：實例句柄（HINSTANCE），這個實例能夠通過函數GetModuleHandle(NULL)獲取。

1. CefMainArgs main_args(hInstance);

Single Executable

單個執行器

When running as a single executable the entry-point function is required to differentiate between the different process types. The single executable structure is supported on Windows and Linux but not on Mac OS X.

當運行單個執行器時，根據不同的進程類型，入口函數有差異。Windows、Linux平臺支持單個執行器架構，Mac OS X平臺則不行。

1. // 程序執行函數
2. int main(int argc, char* argv[]) {
3. // Structure for passing command-line arguments.
4. // The definition of this structure is platform-specific.
5. // 傳遞命令行參數的結構體。
6. // 這個結構體的定義與平臺相關。
7. CefMainArgs main_args(argc, argv);
8.  
9. // Optional implementation of the CefApp interface.
10. // 可選擇地實現CefApp接口
11. CefRefPtr<MyApp> app(new MyApp);
12.  
13. // Execute the sub-process logic, if any. This will either return immediately for the browser
14. // process or block until the sub-process should exit.
15. // 可能會執行子進程邏輯，這個函數的執行在browser進程時會立即返回，在子進程時會堵塞直到退出時返回。
16. int exit_code = CefExecuteProcess(main_args, app.get());
17. if (exit_code >= 0) {
18. // The sub-process terminated, exit now.
19. // 子進程被終結，立即結束。
20. return exit_code;
21. }
22.  
23. // Populate this structure to customize CEF behavior.
24. // 填充這個結構體，用於定製CEF的行爲。
25. CefSettings settings;
26.  
27. // Initialize CEF in the main process.
28. // 在main進程中初始化CEF
29. CefInitialize(main_args, settings, app.get());
30.  
31. // Run the CEF message loop. This will block until CefQuitMessageLoop() is called.
32. // 執行消息循環，此時會堵塞，直到CefQuitMessageLoop()函數被調用。
33. CefRunMessageLoop();
34.  
35. // Shut down CEF.
36. // 退出CEF。
37. CefShutdown();
38.  
39. return 0;
40. }

Separate Sub-Process Executable

單獨子進程執行器

When using a separate sub-process executable you need two separate executable projects and two separate entry-point functions.

當使用一個單獨子進程執行器時，你需要2個分開的可執行工程和2個分開的入口函數。

Main application entry-point function:

主程序的入口函數：

1. // Program entry-point function.
2. // 程序入口函數
3. int main(int argc, char* argv[]) {
4. // Structure for passing command-line arguments.
5. // The definition of this structure is platform-specific.
6. // 傳遞命令行參數的結構體。
7. // 這個結構體的定義與平臺相關。
8. CefMainArgs main_args(argc, argv);
9.  
10. // Optional implementation of the CefApp interface.
11. // 可選擇性地實現CefApp接口
12. CefRefPtr<MyApp> app(new MyApp);
13.  
14. // Populate this structure to customize CEF behavior.
15. // 填充這個結構體，用於定製CEF的行爲。
16. CefSettings settings;
17.  
18. // Specify the path for the sub-process executable.
19. // 指定子進程的執行路徑
20. CefString(&settings.browser_subprocess_path).FromASCII(“/path/to/subprocess”);
21.  
22. // Initialize CEF in the main process.
23. // 在主進程中初始化CEF
24. CefInitialize(main_args, settings, app.get());
25.  
26. // Run the CEF message loop. This will block until CefQuitMessageLoop() is called.
27. // 執行消息循環，此時會堵塞，直到CefQuitMessageLoop()函數被調用。
28. CefRunMessageLoop();
29.  
30. // Shut down CEF.
31. // 關閉CEF
32. CefShutdown();
33.  
34. return 0;
35. }

Sub-process application entry-point function: 子進程程序的入口函數：

1. // Program entry-point function.
2. // 程序入口函數
3. int main(int argc, char* argv[]) {
4. // Structure for passing command-line arguments.
5. // The definition of this structure is platform-specific.
6. // 傳遞命令行參數的結構體。
7. // 這個結構體的定義與平臺相關。
8. CefMainArgs main_args(argc, argv);
9.  
10. // Optional implementation of the CefApp interface.
11. // 可選擇性地實現CefApp接口
12. CefRefPtr<MyApp> app(new MyApp);
13.  
14. // Execute the sub-process logic. This will block until the sub-process should exit.
15. // 執行子進程邏輯，此時會堵塞直到子進程退出。
16. return CefExecuteProcess(main_args, app.get());
17. }

Message Loop Integration

集成消息循環

CEF can also integrate with an existing application message loop instead of running its own message loop. There are two ways to do this.

CEF可以不用它自己提供的消息循環，而與已經存在的程序中消息環境集成在一起，有兩種方式可以做到：

1. Call CefDoMessageLoopWork() on a regular basis instead of calling CefRunMessageLoop(). Each call to CefDoMessageLoopWork() will perform a single iteration of the CEF message loop. Caution should be used with this approach. Calling the method too infrequently will starve the CEF message loop and negatively impact browser performance. Calling the method too frequently will negatively impact CPU usage.

2. Set CefSettings.multi_threaded_message_loop = true (Windows only). This will cause CEF to run the browser UI thread on a separate thread from the main application thread. With this approach neither CefDoMessageLoopWork() nor CefRunMessageLoop() need to be called. CefInitialize() and CefShutdown() should still be called on the main application thread. You will need to provide your own mechanism for communicating with the main application thread (see for example the message window usage in cefclient_win.cpp). You can test this mode in cefclient on Windows by running with the “--multi-threaded-message-loop” command-line flag.

3. 週期性執行CefDoMessageLoopWork()函數，替代調用CefRunMessageLoop()。CefDoMessageLoopWork()的每一次調用，都將執行一次CEF消息循環的單次迭代。需要注意的是，此方法調用次數太少時，CEF消息循環會餓死，將極大的影響browser的性能，調用次數太頻繁又將影響CPU使用率。

4. 設置CefSettings.multi_threaded_message_loop=true（Windows平臺下有效），這個設置項將導致CEF運行browser UI運行在單獨的線程上，而不是在主線程上，這種場景下CefDoMessageLoopWork()或者CefRunMessageLoop()都不需要調用，CefInitialze()、CefShutdown()仍然在主線程中調用。你需要提供主程序線程通信的機制（查看cefclient_win.cpp中提供的消息窗口實例）。在Windows平臺下，你可以通過命令行參數“--multi-threaded-message-loop”測試上述消息模型。

CefSettings

CefSettings

The CefSettings structure allows configuration of application-wide CEF settings. Some commonly configured members include:

CefSettings結構體允許定義全局的CEF配置，經常用到的配置項如下：

• single_process Set to true to use a single process for the browser and renderer. Also configurable using the "single-process" command-line switch. See the “Processes” section for more information.
• browser_subprocess_path The path to a separate executable that will be launched for sub-processes. See the “Separate Sub-Process Executable” section for more information.
• multi_threaded_message_loop Set to true to have the browser process message loop run in a separate thread. See the “Message Loop Integration” section for more information.
• command_line_args_disabled Set to true to disable configuration of browser process features using standard CEF and Chromium command-line arguments. See the “Command Line Arguments” section for more information.
• cache_path The location where cache data will be stored on disk. If empty an in-memory cache will be used for some features and a temporary disk cache will be used for others. HTML5 databases such as localStorage will only persist across sessions if a cache path is specified.
• locale The locale string that will be passed to Blink. If empty the default locale of "en-US" will be used. This value is ignored on Linux where locale is determined using environment variable parsing with the precedence order: LANGUAGE, LC_ALL, LC_MESSAGES and LANG. Also configurable using the "lang" command-line switch.
• log_file The directory and file name to use for the debug log. If empty, the default name of "debug.log" will be used and the file will be written to the application directory. Also configurable using the "log-file" command-line switch.
• log_severity The log severity. Only messages of this severity level or higher will be logged. Also configurable using the "log-severity" command-line switch with a value of "verbose", "info", "warning", "error", "error-report" or "disable".
• resources_dir_path The fully qualified path for the resources directory. If this value is empty the cef.pak and/or devtools_resources.pak files must be located in the module directory on Windows/Linux or the app bundle Resources directory on Mac OS X. Also configurable using the "resources-dir-path" command-line switch.
• locales_dir_path The fully qualified path for the locales directory. If this value is empty the locales directory must be located in the module directory. This value is ignored on Mac OS X where pack files are always loaded from the app bundle Resources directory. Also configurable using the "locales-dir-path" command-line switch.

• remote_debugging_port Set to a value between 1024 and 65535 to enable remote debugging on the specified port. For example, if 8080 is specified the remote debugging URL will be http://localhost:8080. CEF can be remotely debugged from any CEF or Chrome browser window. Also configurable using the "remote-debugging-port" command-line switch.

• single_process 設置爲true時，browser和renderer使用一個進程。此項也可以通過命令行參數“single-process”配置。查看本文中“進程”章節獲取更多的信息。

• browser_subprocess_path 設置用於啓動子進程單獨執行器的路徑。參考本文中“單獨子進程執行器”章節獲取更多的信息。
• cache_path 設置磁盤上用於存放緩存數據的位置。如果此項爲空，某些功能將使用內存緩存，多數功能將使用臨時的磁盤緩存。形如本地存儲的HTML5數據庫只能在設置了緩存路徑才能跨session存儲。
• locale 此設置項將傳遞給Blink。如果此項爲空，將使用默認值“en-US”。在Linux平臺下此項被忽略，使用環境變量中的值，解析的依次順序爲：LANGUAE，LC_ALL，LC_MESSAGES和LANG。此項也可以通過命令行參數“lang”配置。
• log_file 此項設置的文件夾和文件名將用於輸出debug日誌。如果此項爲空，默認的日誌文件名爲debug.log，位於應用程序所在的目錄。此項也可以通過命令參數“log-file”配置。
• log_severity 此項設置日誌級別。只有此等級、或者比此等級高的日誌的纔會被記錄。此項可以通過命令行參數“log-severity”配置，可以設置的值爲“verbose”，“info”，“warning”，“error”，“error-report”，“disable”
• resources_dir_path 此項設置資源文件夾的位置。如果此項爲空，Windows平臺下cef.pak、Linux平臺下devtools_resourcs.pak、Mac OS X下的app bundle Resources目錄必須位於組件目錄。此項也可以通過命令行參數“resource-dir-path”配置。
• locales_dir_path 此項設置locale文件夾位置。如果此項爲空，locale文件夾必須位於組件目錄，在Mac OS X平臺下此項被忽略，pak文件從app bundle Resources目錄。此項也可以通過命令行參數“locales-dir-path”配置。
• remote_debugging_port 此項可以設置1024-65535之間的值，用於在指定端口開啓遠程調試。例如，如果設置的值爲8080，遠程調試的URL爲http://localhost:8080。CEF或者Chrome瀏覽器能夠調試CEF。此項也可以通過命令行參數“remote-debugging-port”配置。
• 轉自http://www.cnblogs.com/sld666666/p/4138307.html