Chromium Embedded Framework (CEF) Translator Tool -- translator.py ------------------------------------------------------------------------------- Document Last Updated: December 7, 2011 OVERVIEW -------- The CEF translator tool automatically generates CEF source code based on the contents of the CEF header file (cef.h). The generated source code includes the main C API header file (cef_capi.h) and all files in the libcef_dll/cpptoc and libcef_dll/ctocpp directories. If any differences are detected between the new translator-generated output and the file that currently exists on disk a backup of the existing file will be created before the new file is written (this behavior can be controlled using a command-line switch -- see 'translator.py -h' for more information). Header files (*.h) are completely generated by the translator and should never be edited by hand. Implementation files (*.cc) may contain user-created content within method and function body blocks. The user-created content is extracted from the existing file and inserted into the new translator-generated file. Any differences between existing method/function prototypes and new method/function prototypes in manually edited implementations will be noted as a warning in new output file. // WARNING - CHANGED ATTRIBUTES // REMOVED: const wchar_t* key // ADDED: int index // WARNING - CHANGED RETURN VALUE // WAS: void // NOW: int #pragma message("Warning: "__FILE__": MyFunction prototype has changed") Auto-generated implementations will be added in the new output file for any methods/functions that exist in the CEF header file but did not exist in the current on-disk implementation file. Each time the translator re-generates the implementation file it will warn if an implementation could not be auto- generated. Delete the indicated portion of the generated code after adding the implementation manually. size_t CEF_CALLBACK frame_new_func(struct _cef_frame_t* self) { // BEGIN DELETE BEFORE MODIFYING // AUTO-GENERATED CONTENT #pragma message("Warning: "__FILE__": frame_new_func is not implemented") // END DELETE BEFORE MODIFYING } If the complete function or method implementation has been auto-generated the body of the function or method will contain the following comment. // AUTO-GENERATED CONTENT - DELETE THIS COMMENT BEFORE MODIFYING If you edit the implementation manually you should remove this comment so that CEF will not discard your changes on the next run of the translator tool. The 'translator.[bat|sh]' file can be used to run the translator tool with command- line arguments that match the default CEF directory structure and output options. Run 'translator.py -h' for a complete list of available command- line arguments. HEADER ATTRIBUTES ----------------- Comment-based attribute tags are added before each function, class and method definition in the CEF header file to provide the translator with additional information about how the output should be generated. The attribute tags must be in the form of a comma-delimited list of name=value pairs. Attribute names and values must contain only alpha-numeric characters, numbers and underscores, and must all exist on a single line. /*--cef(name1=value1,name2=value2,name3=value3)--*/ Supported method/function attributes: capi_name=[string] (Optional) Force a specific output name for the resulting C API function. optional_param=[param] (Optional) Parameter name that will be optional instead of required. index_param=[param] (Optional) Parameter name representing an index value that will be verified as >= 0. default_retval=[string] (Required for enumeration types, Optional for other types) Specify the default return value. count_func=[param:func] (Required for non-const non-string std::vector types) Specify the C++ function that returns the count of elements for a vector parameter. revision_check (Optional) If set a revision check will be added to the CToCpp version of the method/function. Supported class attributes: source=[library|client] (Required) Indicates whether the class implementation is provided by the library or the client. This effects the generation of guard blocks in the cpptoc and ctocpp header files. no_debugct_check (Optional) If set the debug reference count of the object will not be checked on shutdown. TRANSLATION RULES ----------------- All C++ names in the CEF header file are written in CamelCaps format and all C API translations are generated in lowercase_underscore format. Translating Classes and Methods ------------------------------- Class names and global function names must be prefixed with the 'Cef' string. Global function translation C++: void CefShutdown() C API: void cef_shutdown() The translation of a C++ class name to a C API structure name is prefixed with '_' and postfixed with '_t'. A typedef of the C API structure to a value without the prefixed '_' is also provided and may be used interchangeably. Class name translation C++: class CefPostData C API: typedef struct _cef_post_data_t { ... } cef_post_data_t The translation of a C++ virtual class method to a C API member function adds a 'self' structure pointer as the first parameter. This will always be a pointer to the structure that contains the member function. Virtual method translation C++: virtual void SetFocus(bool enable) C API: void set_focus(struct _cef_browser_t* self, int enable) The translation of a C++ static class method to a C API global function is prefixed with 'cef_classname_' where 'classname' is the lowercase_underscore name of the class that contains the static method. Any repeat of 'classname' in the function name is removed. Static method translation C++: static CefRefPtr CreateRequest() C API: struct _cef_request_t* cef_request_create() Implementation of the wrapper method/function body is generally formatted as follows. Static/Global CppToC (without Return): CEF_EXPORT void cef_function(capi_params) { // Parameter Verification (Optional) // Verify the C parameter values. // ... // Parameter Translation (Optional) // Convert C parameter values to C++ parameter values. // ... // Execution CefFunction(cpp_arams); // Parameter Restoration (Optional) // Retore the C parameter values if changed. // ... } Static/Global CppToC (with Return): CEF_EXPORT capi_retval cef_function(capi_params) { // Parameter Verification (Optional) // Verify the C parameter values. // ... // Parameter Translation (Optional) // Convert C parameter values to C++ parameter values. // ... // Execution cpp_retval _rv = CefFunction(cpp_params); // Parameter Restoration (Optional) // Restore the C parameter values if changed. // ... // Return Translation // Convert the C++ return value to a C return value. return ...; } Static/Global CToCpp (without Return): void CefFunction(cpp_params) { // Parameter Verification (Optional) // Verify the C++ parameter values. // ... // Parameter Translation (Optional) // Convert C++ parameter values to C parameter values. // ... // Execution cef_function(capi_params); // Parameter Restoration (Optional) // Restore the C++ parameter values if changed. // ... } Static/Global CToCpp (with Return): cpp_retval CefFunction(cpp_params) { // Parameter Verification (Optional) // Verify the C++ parameter values. // ... // Parameter Translation (Optional) // Convert C++ parameter values to C parameter values. // ... // Execution capi_retval _rv = cef_function(capi_params); // Parameter Restoration (Optional) // Restore the C++ parameter values if changed. // ... // Return Translation // Convert the C return value to a C++ return value. return ...; } Member CppToC (without Return): CEF_CALLBACK void class_function(cef_class_t* self, capi_params) { // Parameter Verification. // Verify the C parameter values. DCHECK(self); DCHECK(...); if (!self || ...) return; // Parameter Translation (Optional) // Convert the C parameter values to C++ parameter values. // ... // Execution CefClassCppToC::Get(self)->CefFunction(cpp_params); // Parameter Restoration (Optional) // Restore the C parameter values if changed. // ... } Member CppToC (with Return): CEF_CALLBACK capi_retval class_function(cef_class_t* self, capi_params) { // Parameter Verification. // Verify the C parameter values. DCHECK(self); DCHECK(...); if (!self || ...) return default_retval; // Configured or defaulted automatically. // Parameter Translation (Optional) // Convert the C parameter values to C++ parameter values. // ... // Execution cpp_retval _rv = CefClassCppToC::Get(self)->CefFunction(cpp_params); // Parameter Restoration (Optional) // Restore the C parameter values if changed. // ... // Return Translation // Convert the C++ return value to a C return value. return ...; } Member CToCpp (without Return): void CefClassCToCpp::Function(cpp_params) { // Structure Verification if (CEF_MEMBER_MISSING(struct_, function)) return; // Parameter Verification (Optional) // Verify the C++ parameter values. // ... // Parameter Translation (Optional) // Convert C++ parameter values to C parameter values. // ... // Execution struct_->class_function(struct_, capi_params); // Parameter Restoration (Optional) // Restore the C++ parameter values if changed. // ... } Member CToCpp (with Return): cpp_retval CefClassCToCpp::Function(cpp_params) { // Structure Verification if (CEF_MEMBER_MISSING(struct_, function)) return default_retval; // Configured or defaulted automatically. // Parameter Verification (Optional) // Verify the C++ parameter values. // ... // Parameter Translation (Optional) // Convert C++ parameter values to C parameter values. // ... // Execution capi_retval _rv = struct_->class_function(struct_, capi_params); // Parameter Restoration (Optional) // Restore the C++ parameter values if changed. // ... // Return Translation // Convert the C return value to a C++ return value. return ...; } Translating Data Types ---------------------- Data types that are available in both C++ and C are left unchanged. This includes the 'double', 'int', 'long', 'size_t' and 'void' basic types. Other data types have differing levels of support as indicated below. The translation tool will terminate with an exception if it encounters a data type that it cannot translate. Parameters: Simple/enumeration type by value (simple_byval): C++: int value C API: int value // CppToC Example CEF_EXPORT void cef_function(int value) { // Execution CefFunction(value); } // CToCpp Example void CefFunction(int value) { // Execution cef_function(value); } Simple/enumeration type by reference (simple_byref): C++: int& value C API: int* value // CppToC Example CEF_EXPORT void cef_function(int* value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation int valueVal = value?*value:0; // Execution CefFunction(valueVal); // Parameter Restoration if (value) *value = valueVal; } // CToCpp Example void CefFunction(int& value) { // Execution cef_function(&value); } Simple/enumeration const type by reference (simple_byref_const): C++: const int& value C API: const int* value // CppToC Example CEF_EXPORT void cef_function(const int* value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation int valueVal = value?*value:0; // Execution CefFunction(valueVal); } // CToCpp Example void CefFunction(const int& value) { // Execution cef_function(&value); } Simple/enumeration type by address (simple_byaddr): C++: int* value C API: int* value // CppToC Example CEF_EXPORT void cef_function(int* value) { // Parameter Verification DHECK(value); if (!value) return; // Execution CefFunction(value); } // CToCpp Example void CefFunction(int* value) { // Parameter Verification DHECK(value); if (!value) return; // Execution cef_function(value); } Boolean type by value (bool_byval): C++: bool value C API: int value // CppToC Example CEF_EXPORT void cef_function(int value) { // Execution CefFunction(value?true:false); } // CToCpp Example void CefFunction(bool value) { // Execution cef_function(value); } Boolean type by reference (bool_byref): C++: bool& value C API: int* value // CppToC Example CEF_EXPORT void cef_function(int* value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation bool valueBool = (value && *value)?true:false; // Execution CefFunction(valueBool); // Parameter Restoration if (value) *value = valueBool?true:false; } // CToCpp Example void CefFunction(bool& value) { // Parameter Translation int valueInt = value; // Execution cef_function(&valueInt); // Parameter Restoration value = valueInt?true:false; } Boolean type by address (bool_byaddr): C++: bool* value C API: int* value // CppToC Example CEF_EXPORT void cef_function(int* value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation bool valueBool = (value && *value)?true:false; // Execution CefFunction(&valueBool); // Parameter Restoration if (value) *value = valueBool?true:false; } // CToCpp Example void CefFunction(bool* value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation int valueInt = value?*value:0; // Execution cef_function(&valueInt); // Parameter Restoration if (value) *value = valueInt?true:false; } Structure const type by reference (struct_byref_const): C++: const CefPopupFeatures& value C API: const cef_popup_features_t* value // CppToC Example CEF_EXPORT void cef_function(const cef_popup_features_t* value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation CefPopupFeatures valueObj; // Reference the existing values instead of copying. if (value) valueObj.Set(*value, false); // Execution CefFunction(valueObj); } // CToCpp Example void CefFunction(const CefPopupFeatures& value) { // Execution cef_function(&value); } Structure non-const type by reference (struct_byref): C++: CefWindowInfo& value C API: cef_window_info_t* value // CppToC Example CEF_EXPORT void cef_function(cef_window_info_t* value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation CefWindowInfo valueObj; // Take ownership of the values. if (value) valueObj.AttachTo(*value); // Execution CefFunction(valueObj); // Parameter Restoration // Return the values to the structure. if (value) valueObj.DetachTo(*value); } // CToCpp Example void CefFunction(CefWindowInfo& value) { // Execution cef_function(&value); } String const type by reference (string_byref_const): C++: const CefString& value C API: const cef_string_t* value // CppToC Example CEF_EXPORT void cef_function(const cef_string_t* value) { // Parameter Verification DHECK(value); if (!value) return; // Execution CefFunction(CefString(value)); } // CToCpp Example void CefFunction(const CefString& value) { // Execution cef_function(value.GetStruct()); } String non-const type by reference (string_byref): C++: CefString& value C API: cef_string_t* value // CppToC Example CEF_EXPORT void cef_function(cef_string_t* value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation CefString valueStr(value); // Execution CefFunction(valueStr); } // CToCpp Example void CefFunction(CefString& value) { // Execution cef_function(value.GetWritableStruct()); } Smart pointer type same boundary side (refptr_same): C++: CefRefPtr value C API: cef_browser_t* value // CppToC Example CEF_EXPORT void cef_function(cef_browser_t* value) { // Parameter Verification DHECK(value); if (!value) return; // Execution CefFunction(CefBrowserCppToC::Unwrap(value)); } // CToCpp Example void CefFunction(CefRefPtr value) { // Execution cef_function(CefBrowserCToCpp::Unwrap(value)); } Smart pointer type same boundary side by reference (refptr_same_byref): C++: CefRefPtr& value C API: cef_client_t** value // CppToC Example CEF_EXPORT void cef_function(cef_client_t** value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation CefRefPtr valuePtr; if (value && *value) valuePtr = CefClientCppToC::Unwrap(*value); CefClient* valueOrig = valuePtr.get(); // Execution CefFunction(valuePtr); // Parameter Restoration if (value) { if (valuePtr.get()) { if (valuePtr.get() != valueOrig) { // The value has been changed. *value = CefClientCppToC::Wrap(valuePtr); } } else { *value = NULL; } } } // CToCpp Example void CefFunction(CefRefPtr& value) { // Parameter Translation cef_client_t* valueStruct = NULL; if(value.get()) valueStruct = CefClientCToCpp::Unwrap(value); cef_client_t* valueOrig = valueStruct; // Execution cef_function(valueStuct); // Parameter Restoration if (valueStruct) { if (valueStruct != valueOrig) { // The value was changed. value = CefClientCToCpp::Wrap(valueStruct); } } else { value = NULL; } } Smart pointer type different boundary side (refptr_diff): C++: CefRefPtr value C API: cef_browser_t* value // CppToC Example CEF_EXPORT void cef_function(cef_browser_t* value) { // Parameter Verification DHECK(value); if (!value) return; // Execution CefFunction(CefBrowserCToCpp::Wrap(value)); } // CToCpp Example void CefFunction(CefRefPtr value) { // Execution cef_function(CefBrowserCppToC::Wrap(value)); } Smart pointer type different boundary side by reference (refptr_diff_byref): C++: CefRefPtr& value C API: cef_client_t** value // CppToC Example CEF_EXPORT void cef_function(cef_client_t** value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation CefRefPtr valuePtr; if (value && *value) valuePtr = CefClientCToCpp::Wrap(*value); CefClient* valueOrig = valuePtr.get(); // Execution CefFunction(valuePtr); // Parameter Restoration if (value) { if (valuePtr.get()) { if (valuePtr.get() != valueOrig) { // The value has been changed. *value = CefClientCToCpp::Unwrap(valuePtr); } } else { *value = NULL; } } } // CToCpp Example void CefFunction(CefRefPtr& value) { // Parameter Translation cef_client_t* valueStruct = NULL; if(value.get()) valueStruct = CefClientCppToC::Wrap(value); cef_client_t* valueOrig = valueStruct; // Execution cef_function(valueStuct); // Parameter Restoration if (valueStruct) { if (valueStruct != valueOrig) { // The value was changed. value = CefClientCppToC::Unwrap(valueStruct); } } else { value = NULL; } } String vector type by reference (string_vec_byref): C++: std::vector& value C API: cef_string_list_t value // CppToC Example CEF_EXPORT void cef_function(cef_string_list_t value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation std::vector valueList; transfer_string_list_contents(value, valueList); // Execution CefFunction(valueList); // Parameter Restoration cef_string_list_clear(value); transfer_string_list_contents(valueList, value); } // CToCpp Example void CefFunction(std::vector& value) { // Parameter Translation cef_string_list_t valueList = cef_string_list_alloc(); DCHECK(valueList); if (valueList) transfer_string_list_contents(value, valueList); // Execution cef_function(valueList); // Parameter Restoration if (valueList) { value.clear(); transfer_string_list_contents(valueList, value); cef_string_list_free(valueList); } } String vector const type by reference (string_vec_byref_const): C++: const std::vector& value C API: cef_string_list_t value // CppToC Example CEF_EXPORT void cef_function(cef_string_list_t value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation std::vector valueList; transfer_string_list_contents(value, valueList); // Execution CefFunction(valueList); } // CToCpp Example void CefFunction(const std::vector& value) { // Parameter Translation cef_string_list_t valueList = cef_string_list_alloc(); DCHECK(valueList); if (valueList) transfer_string_list_contents(value, valueList); // Execution cef_function(valueList); // Parameter Restoration if (valueList) cef_string_list_free(valueList); } String-to-string single map type by reference (string_map_single_byref): C++: std::map& value C API: cef_string_map_t value // CppToC Example CEF_EXPORT void cef_function(cef_string_map_t value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation std::map valueMap; transfer_string_map_contents(value, valueMap); // Execution CefFunction(valueMap); // Parameter Restoration cef_string_map_clear(value); transfer_string_map_contents(valueMap, value); } // CToCpp Example void CefFunction(std::map& value) { // Parameter Translation cef_string_map_t valueMap = cef_string_map_alloc(); DCHECK(valueMap); if (valueMap) transfer_string_map_contents(value, valueMap); // Execution cef_function(valueMap); // Parameter Restoration if (valueMap) { value.clear(); transfer_string_map_contents(valueMap, value); cef_string_map_free(valueMap); } } String-to-string single map const type by reference (string_map_single_byref_const): C++: const std::map& value C API: cef_string_map_t value // CppToC Example CEF_EXPORT void cef_function(cef_string_map_t value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation std::map valueMap; transfer_string_map_contents(value, valueMap); // Execution CefFunction(valueMap); } // CToCpp Example void CefFunction(const std::map& value) { // Parameter Translation cef_string_map_t valueMap = cef_string_map_alloc(); DCHECK(valueMap); if (valueMap) transfer_string_map_contents(value, valueMap); // Execution cef_function(valueMap); // Parameter Restoration if (valueMap) cef_string_map_free(valueMap); } String-to-string multi map type by reference (string_map_multi_byref): C++: std::multimap& value C API: cef_string_multimap_t value // CppToC Example CEF_EXPORT void cef_function(cef_string_multimap_t value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation std::multimap valueMultimap; transfer_string_multimap_contents(value, valueMultimap); // Execution CefFunction(valueMultimap); // Parameter Restoration cef_string_multimap_clear(value); transfer_string_multimap_contents(valueMultimap, value); } // CToCpp Example void CefFunction(std::multimap& value) { // Parameter Translation cef_string_multimap_t valueMultimap = cef_string_multimap_alloc(); DCHECK(valueMultimap); if (valueMultimap) transfer_string_multimap_contents(value, valueMultimap); // Execution cef_function(valueMultimap); // Parameter Restoration if (valueMultimap) { value.clear(); transfer_string_multimap_contents(valueMultimap, value); cef_string_multimap_free(valueMultimap); } } String-to-string multi map const type by reference (string_map_multi_byref_const): C++: const std::multimap& value C API: cef_string_multimap_t value // CppToC Example CEF_EXPORT void cef_function(cef_string_multimap_t value) { // Parameter Verification DHECK(value); if (!value) return; // Parameter Translation std::multimap valueMultimap; transfer_string_multimap_contents(value, valueMultimap); // Execution CefFunction(valueMultimap); } // CToCpp Example void CefFunction(const std::multimap& value) { // Parameter Translation cef_string_multimap_t valueMultimap = cef_string_multimap_alloc(); DCHECK(valueMultimap); if (valueMultimap) transfer_string_multimap_contents(value, valueMultimap); // Execution cef_function(valueMultimap); // Parameter Restoration if (valueMultimap) cef_string_multimap_free(valueMultimap); } Simple/Enumeration vector non-const type by reference (simple_vec_byref): C++: std::vector& value C API: size_t* valueCount, int* value // CppToC Example CEF_EXPORT void cef_function(size_t* valueCount, int* value) { // Parameter Verification DCHECK(valueCount && (*valueCount == 0 || value)); if (!valueCount || (*valueCount > 0 && !value)) return; // Parameter Translation std::vector valueList; if (valueCount && *valueCount > 0 && value) { for (size_t i = 0; i < *valueCount; ++i) valueList.push_back(value[i]); } // Execution CefFunction(valueList); // Parameter Restoration if (valueCount && value) { *valueCount = std::min(valueList.size(), *valueCount); if (*valueCount > 0) { for (size_t i = 0; i < *valueCount; ++i) value[i] = valueList[i]; } } } // CToCpp Example void CefFunction(std::vector& value) { // Parameter Translation // Function identified by the "count_func" method attribute. size_t valueSize = value.size(); size_t valueCount = std::max(GetFunctionCount(), valueSize); int* valueList = NULL; if (valueCount > 0) { valueList = new int[valueCount]; DCHECK(valueList); if (valueList) memset(valueList, 0, sizeof(int)*valueCount); if (valueList && valueSize > 0) { for (size_t i = 0; i < valueSize; ++i) { valueList[i] = value[i]; } } } // Execution cef_function(&valueCount, valueList); // Parameter Restoration value.clear(); if (valueCount > 0 && valueList) { for (size_t i = 0; i < valueCount; ++i) value.push_back(valueList[i]); delete [] valueList; } } Simple/Enumeration vector const type by reference (simple_vec_byref_const): C++: const std::vector& value C API: size_t valueCount, int const* value // CppToC Example CEF_EXPORT void cef_function(size_t valueCount, int const* value) { // Parameter Verification DCHECK(valueCount == 0 || value); if (valueCount > 0 && !value) return; // Parameter Translation std::vector valueList; if (valueCount > 0) { for (size_t i = 0; i < valueCount; ++i) valueList.push_back(value[i]); } // Execution CefFunction(valueList); } // CToCpp Example void CefFunction(const std::vector& value) { // Parameter Translation const size_t valueCount = value.size(); int* valueList = NULL; if (valueCount > 0) { valueList = new int[valueCount]; DCHECK(valueList); if (valueList) { for (size_t i = 0; i < valueCount; ++i) valueList[i] = value[i]; } } // Execution cef_function(valueCount, valueList); } Boolean vector non-const type by reference (bool_vec_byref): C++: std::vector& value C API: size_t* valueCount, int* value // CppToC Example CEF_EXPORT void cef_function(size_t* valueCount, int* value) { // Parameter Verification DCHECK(valueCount && (*valueCount == 0 || value)); if (!valueCount || (*valueCount > 0 && !value)) return; // Parameter Translation std::vector valueList; if (valueCount && *valueCount > 0 && value) { for (size_t i = 0; i < *valueCount; ++i) valueList.push_back(value[i]?true:false); } // Execution CefFunction(valueList); // Parameter Restoration if (valueCount && value) { *valueCount = std::min(valueList.size(), *valueCount); if (*valueCount > 0) { for (size_t i = 0; i < *valueCount; ++i) value[i] = valueList[i]; } } } // CToCpp Example void CefFunction(std::vector& value) { // Parameter Translation // Function identified by the "count_func" method attribute. size_t valueSize = value.size(); size_t valueCount = std::max(GetFunctionCount(), valueSize); int* valueList = NULL; if (valueCount > 0) { valueList = new int[valueCount]; DCHECK(valueList); if (valueList) memset(valueList, 0, sizeof(int)*valueCount); if (valueList && valueSize > 0) { for (size_t i = 0; i < valueSize; ++i) { valueList[i] = value[i]; } } } // Execution cef_function(&valueCount, valueList); // Parameter Restoration value.clear(); if (valueCount > 0 && valueList) { for (size_t i = 0; i < valueCount; ++i) value.push_back(valueList[i]?true:false); delete [] valueList; } } Boolean vector const type by reference (bool_vec_byref_const): C++: const std::vector& value C API: size_t valueCount, int const* value // CppToC Example CEF_EXPORT void cef_function(size_t valueCount, int const* value) { // Parameter Verification DCHECK(valueCount == 0 || value); if (valueCount > 0 && !value) return; // Parameter Translation std::vector valueList; if (valueCount > 0) { for (size_t i = 0; i < valueCount; ++i) valueList.push_back(value[i]?true:false); } // Execution CefFunction(valueList); } // CToCpp Example void CefFunction(const std::vector& value) { // Parameter Translation const size_t valueCount = value.size(); int* valueList = NULL; if (valueCount > 0) { valueList = new int[valueCount]; DCHECK(valueList) if (valueList) { for (size_t i = 0; i < valueCount; ++i) valueList[i] = value[i]; } } // Execution cef_function(valueCount, valueList); } Smart pointer vector non-const type same boundary side by reference (refptr_vec_same_byref): C++: std::vector>& value C API: size_t* valueCount, cef_post_data_element_t** value // CppToC Example CEF_EXPORT void cef_function(size_t* valueCount, cef_post_data_element_t** value) { // Parameter Verification DCHECK(valueCount && (*valueCount == 0 || value)); if (!valueCount || (*valueCount > 0 && !value)) return; // Parameter Translation std::vector> valueList; if (valueCount && *valueCount > 0 && value) { for (size_t i = 0; i < *valueCount; ++i) valueList.push_back(CefPostDataElementCppToC::Unwrap(value[i])); } // Execution CefFunction(valueList); // Parameter Restoration if (valueCount && value) { *valueCount = std::min(valueList.size(), *valueCount); if (*valueCount > 0) { for (size_t i = 0; i < *valueCount; ++i) value[i] = CefPostDataElementCppToC::Wrap(valueList[i]); } } } // CToCpp Example void CefFunction(std::vector& value) { // Parameter Translation // Function identified by the "count_func" method attribute. size_t valueSize = value.size(); size_t valueCount = std::max(GetFunctionCount(), valueSize); cef_post_data_element_t** valueList = NULL; if (valueCount > 0) { valueList = new cef_post_data_element_t*[valueCount]; DCHECK(valueList); if (valueList) memset(valueList, 0, sizeof(cef_post_data_element_t*)*valueCount); if (valueList && valueSize > 0) { for (size_t i = 0; i < valueSize; ++i) { valueList[i] = CefPostDataElementCToCpp::Unwrap(value[i]); } } } // Execution cef_function(&valueCount, valueList); // Parameter Restoration value.clear(); if (valueCount > 0 && valueList) { for (size_t i = 0; i < valueCount; ++i) value.push_back(CefPostDataElementCToCpp::Wrap(valueList[i])); delete [] valueList; } } Smart pointer vector const type same boundary side by reference (refptr_vec_same_byref_const): C++: const std::vector>& value C API: size_t valueCount, const cef_v8value_t** value // CppToC Example CEF_EXPORT void cef_function(size_t valueCount, const cef_v8value_t** value) { // Parameter Verification DCHECK(valueCount == 0 || value); if (valueCount > 0 && !value) return; // Parameter Translation std::vector> valueList; if (valueCount > 0) { for (size_t i = 0; i < valueCount; ++i) valueList.push_back(CefV8ValueCppToC::Unwrap(value[i])); } // Execution CefFunction(valueList); } // CToCpp Example void CefFunction(const std::vector& value) { // Parameter Translation const size_t valueCount = value.size(); cef_v8value_t** valueList = NULL; if (valueCount > 0) { valueList = new int[valueCount]; DCHECK(valueList); if (valueList) { for (size_t i = 0; i < valueCount; ++i) valueList[i] = CefV8ValueCToCpp::Unwrap(value[i]); } } // Execution cef_function(valueCount, valueList); } Smart pointer vector non-const type different boundary side by reference (refptr_vec_diff_byref): C++: std::vector>& value C API: size_t* valueCount, cef_post_data_element_t** value // CppToC Example CEF_EXPORT void cef_function(size_t* valueCount, cef_post_data_element_t** value) { // Parameter Verification DCHECK(valueCount && (*valueCount == 0 || value)); if (!valueCount || (*valueCount > 0 && !value)) return; // Parameter Translation std::vector> valueList; if (valueCount && *valueCount > 0 && value) { for (size_t i = 0; i < *valueCount; ++i) valueList.push_back(CefPostDataElementCToCpp::Wrap(value[i])); } // Execution CefFunction(valueList); // Parameter Restoration if (valueCount && value) { *valueCount = std::min(valueList.size(), *valueCount); if (*valueCount > 0) { for (size_t i = 0; i < *valueCount; ++i) value[i] = CefPostDataElementCToCpp::Unwrap(valueList[i]); } } } // CToCpp Example void CefFunction(std::vector& value) { // Parameter Translation // Function identified by the "count_func" method attribute. size_t valueSize = value.size(); size_t valueCount = std::max(GetFunctionCount(), valueSize); cef_post_data_element_t** valueList = NULL; if (valueCount > 0) { valueList = new cef_post_data_element_t*[valueCount]; DCHECK(valueList); if (valueList) memset(valueList, 0, sizeof(cef_post_data_element_t*)*valueCount); if (valueList && valueSize > 0) { for (size_t i = 0; i < valueSize; ++i) { valueList[i] = CefPostDataElementCppToC::Wrap(value[i]); } } } // Execution cef_function(&valueCount, valueList); // Parameter Restoration value.clear(); if (valueCount > 0 && valueList) { for (size_t i = 0; i < valueCount; ++i) value.push_back(CefPostDataElementCppToC::Unwrap(valueList[i])); delete [] valueList; } } Smart pointer vector const type different boundary side by reference (refptr_vec_diff_byref_const): C++: const std::vector>& value C API: size_t valueCount, const cef_v8value_t** value // CppToC Example CEF_EXPORT void cef_function(size_t valueCount, const cef_v8value_t** value) { // Parameter Verification DCHECK(valueCount == 0 || value); if (valueCount > 0 && !value) return; // Parameter Translation std::vector> valueList; if (valueCount > 0) { for (size_t i = 0; i < valueCount; ++i) valueList.push_back(CefV8ValueCToCpp::Wrap(value[i])); } // Execution CefFunction(valueList); } // CToCpp Example void CefFunction(const std::vector& value) { // Parameter Translation const size_t valueCount = value.size(); cef_v8value_t** valueList = NULL; if (valueCount > 0) { valueList = new int[valueCount]; DCHECK(valueList); if (valueList) { for (size_t i = 0; i < valueCount; ++i) valueList[i] = CefV8ValueCppToC::Wrap(value[i]); } } // Execution cef_function(valueCount, valueList); } Return Values: Simple/Enumeration type (simple): C++: int C API: int // CppToC Example CEF_EXPORT int cef_function() { // Execution int _rv = CefFunction(); // Return Translation return _rv; } // CToCpp Example int CefFunction() { // Execution int _rv = cef_function(); // Return Translation return _rv; } Boolean type (bool): C++: bool C API: int // CppToC Example CEF_EXPORT int cef_function() { // Execution bool _rv = CefFunction(); // Return Translation return _rv; } // CToCpp Example bool CefFunction() { // Execution int _rv = cef_function(); // Return Translation return _rv?true:false; } String non-const by reference type (string): C++: CefString C API: cef_string_userfree_t // CppToC Example CEF_EXPORT cef_string_userfree_t cef_function() { // Execution CefString _rv = CefFunction(); // Return Translation return _rv.DetachToUserFree(); } // CToCpp Example CefString CefFunction() { // Execution cef_string_userfree_t _rv = cef_function(); // Return Translation CefString _rvStr; _rvStr.AttachToUserFree(_rv); return _rvStr; } Smart pointer type same boundary side (refptr_same): C++: CefRefPtr C API: cef_browser_t* // CppToC Example CEF_EXPORT cef_browser_t* cef_function() { // Execution CefRefPtr _rv = CefFunction(); // Return Translation return CefBrowserCppToC::Wrap(_rv); } // CToCpp Example CefString CefFunction() { // Execution cef_browser_t* _rv = cef_function(); // Return Translation return CefBrowserCToCpp::Wrap(_rv); } Smart pointer type different boundary side (refptr_diff): C++: CefRefPtr C API: cef_browser_t* // CppToC Example CEF_EXPORT cef_browser_t* cef_function() { // Execution CefRefPtr _rv = CefFunction(); // Return Translation return CefBrowserCToCpp::Unwrap(_rv); } // CToCpp Example CefString CefFunction() { // Execution cef_browser_t* _rv = cef_function(); // Return Translation return CefBrowserCppToC::Unwrap(_rv); } Translating Comments -------------------- Comments from the CEF header file are reproduced in the C API header file with any referenced C++ types and terminology changed to reflect C API types and terminology. C++: // Create a new CefV8Value object of the specified type. These methods // should only be called from within the JavaScript context -- either in a // CefV8Handler::Execute() callback or a CefHandler::HandleJSBinding() // callback. C API: // Create a new cef_v8value_t object of the specified type. These functions // should only be called from within the JavaScript context -- either in a // cef_v8handler_t::execute() callback or a cef_handler_t::handle_jsbinding() // callback. Situations where the user is responsible for freeing strings allocated and returned by the library are also noted by comments in the C API header file. C API: // The resulting string must be freed by calling cef_string_free(). A comment must occur immediately before the function, class or method that it documents with no extra space in between. Comments may span multiple lines but each line must start with the '//' comment identifier. C++: // Set focus for the browser window. If |enable| is true focus will be set // to the window. Otherwise, focus will be removed. /*--cef()--*/ virtual void SetFocus(bool enable) =0; If two comments are separated by an empty line it will be assumed that the higher comment represents a section header and additional space will be added before it in the translated output. C++: // ARRAY METHODS - These methods are only available on arrays. // Returns the number of elements in the array. /*--cef()--*/ virtual int GetArrayLength() =0; Empty lines and lines with the comment identifier but no content are considered paragraph breaks for the purposes of wrapping the translated text. Any content indented more than one space is reproduced as-is without content translation or wrapping. C++: // 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. // // Example JavaScript extension code: // // // create the 'example' global object if it doesn't already exist. // if (!example) // example = {};