// Copyright (c) 2011 Marshall A. Greenblatt. All rights reserved. // // Redistribution and use in source and binary forms, with or without // modification, are permitted provided that the following conditions are // met: // // * Redistributions of source code must retain the above copyright // notice, this list of conditions and the following disclaimer. // * Redistributions in binary form must reproduce the above // copyright notice, this list of conditions and the following disclaimer // in the documentation and/or other materials provided with the // distribution. // * Neither the name of Google Inc. nor the name Chromium Embedded // Framework nor the names of its contributors may be used to endorse // or promote products derived from this software without specific prior // written permission. // // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. // // --------------------------------------------------------------------------- // // The contents of this file must follow a specific format in order to // support the CEF translator tool. See the translator.README.txt file in the // tools directory for more information. // #ifndef CEF_INCLUDE_CEF_V8_H_ #define CEF_INCLUDE_CEF_V8_H_ #pragma once #include "include/cef_base.h" #include class CefBrowser; class CefFrame; class CefV8Handler; class CefV8Value; /// // 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 // be called on any thread. // // Example JavaScript extension code: //
//   // 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 CefV8Handler::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 CefV8Handler::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 CefV8Handler::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;
//     };
//   })();
// 
// Example usage in the page: //
//   // 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();
// 
/// /*--cef(optional_param=handler)--*/ bool CefRegisterExtension(const CefString& extension_name, const CefString& javascript_code, CefRefPtr handler); /// // Class that encapsulates a V8 context handle. /// /*--cef(source=library)--*/ class CefV8Context : public virtual CefBase { public: /// // Returns the current (top) context object in the V8 context stack. /// /*--cef()--*/ static CefRefPtr GetCurrentContext(); /// // Returns the entered (bottom) context object in the V8 context stack. /// /*--cef()--*/ static CefRefPtr GetEnteredContext(); /// // Returns true if V8 is currently inside a context. /// /*--cef()--*/ static bool InContext(); /// // Returns the browser for this context. /// /*--cef()--*/ virtual CefRefPtr GetBrowser() =0; /// // Returns the frame for this context. /// /*--cef()--*/ virtual CefRefPtr GetFrame() =0; /// // Returns the global object for this context. /// /*--cef()--*/ virtual CefRefPtr GetGlobal() =0; /// // Enter this context. A context must be explicitly entered before creating a // V8 Object, Array or Function asynchronously. Exit() must be called the same // number of times as Enter() before releasing this context. V8 objects belong // to the context in which they are created. Returns true if the scope was // entered successfully. /// /*--cef()--*/ virtual bool Enter() =0; /// // Exit this context. Call this method only after calling Enter(). Returns // true if the scope was exited successfully. /// /*--cef()--*/ virtual bool Exit() =0; /// // Returns true if this object is pointing to the same handle as |that| // object. /// /*--cef()--*/ virtual bool IsSame(CefRefPtr that) =0; }; typedef std::vector > CefV8ValueList; /// // Interface that should be implemented to handle V8 function calls. The methods // of this class will always be called on the UI thread. /// /*--cef(source=client)--*/ class CefV8Handler : public virtual CefBase { public: /// // Handle execution of the function identified by |name|. |object| is the // receiver ('this' object) of the function. |arguments| is the list of // arguments passed to the function. If execution succeeds set |retval| to the // function return value. If execution fails set |exception| to the exception // that will be thrown. Return true if execution was handled. /// /*--cef()--*/ virtual bool Execute(const CefString& name, CefRefPtr object, const CefV8ValueList& arguments, CefRefPtr& retval, CefString& exception) =0; }; /// // Interface that should be implemented to handle V8 accessor calls. Accessor // identifiers are registered by calling CefV8Value::SetValue(). The methods // of this class will always be called on the UI thread. /// /*--cef(source=client)--*/ class CefV8Accessor : public virtual CefBase { public: /// // Handle retrieval the accessor value identified by |name|. |object| is the // receiver ('this' object) of the accessor. If retrieval succeeds set // |retval| to the return value. If retrieval fails set |exception| to the // exception that will be thrown. Return true if accessor retrieval was // handled. /// /*--cef()--*/ virtual bool Get(const CefString& name, const CefRefPtr object, CefRefPtr& retval, CefString& exception) =0; /// // Handle assignment of the accessor value identified by |name|. |object| is // the receiver ('this' object) of the accessor. |value| is the new value // being assigned to the accessor. If assignment fails set |exception| to the // exception that will be thrown. Return true if accessor assignment was // handled. /// /*--cef()--*/ virtual bool Set(const CefString& name, const CefRefPtr object, const CefRefPtr value, CefString& exception) =0; }; /// // Class representing a V8 exception. /// /*--cef(source=library)--*/ class CefV8Exception : public virtual CefBase { public: /// // Returns the exception message. /// /*--cef()--*/ virtual CefString GetMessage() =0; /// // Returns the line of source code that the exception occurred within. /// /*--cef()--*/ virtual CefString GetSourceLine() =0; /// // Returns the resource name for the script from where the function causing // the error originates. /// /*--cef()--*/ virtual CefString GetScriptResourceName() =0; /// // Returns the 1-based number of the line where the error occurred or 0 if the // line number is unknown. /// /*--cef()--*/ virtual int GetLineNumber() =0; /// // Returns the index within the script of the first character where the error // occurred. /// /*--cef()--*/ virtual int GetStartPosition() =0; /// // Returns the index within the script of the last character where the error // occurred. /// /*--cef()--*/ virtual int GetEndPosition() =0; /// // Returns the index within the line of the first character where the error // occurred. /// /*--cef()--*/ virtual int GetStartColumn() =0; /// // Returns the index within the line of the last character where the error // occurred. /// /*--cef()--*/ virtual int GetEndColumn() =0; }; /// // Class representing a V8 value. The methods of this class should only be // called on the UI thread. /// /*--cef(source=library)--*/ class CefV8Value : public virtual CefBase { public: typedef cef_v8_accesscontrol_t AccessControl; typedef cef_v8_propertyattribute_t PropertyAttribute; /// // Create a new CefV8Value object of type undefined. /// /*--cef()--*/ static CefRefPtr CreateUndefined(); /// // Create a new CefV8Value object of type null. /// /*--cef()--*/ static CefRefPtr CreateNull(); /// // Create a new CefV8Value object of type bool. /// /*--cef()--*/ static CefRefPtr CreateBool(bool value); /// // Create a new CefV8Value object of type int. /// /*--cef()--*/ static CefRefPtr CreateInt(int value); /// // Create a new CefV8Value object of type double. /// /*--cef()--*/ static CefRefPtr CreateDouble(double value); /// // Create a new CefV8Value object of type Date. /// /*--cef()--*/ static CefRefPtr CreateDate(const CefTime& date); /// // Create a new CefV8Value object of type string. /// /*--cef(optional_param=value)--*/ static CefRefPtr CreateString(const CefString& value); /// // Create a new CefV8Value object of type object with optional user data and // accessor. This method should only be called from within the scope of a // CefV8ContextHandler, CefV8Handler or CefV8Accessor callback, or in // combination with calling Enter() and Exit() on a stored CefV8Context // reference. /// /*--cef(capi_name=cef_v8value_create_object_with_accessor, optional_param=user_data,optional_param=accessor)--*/ static CefRefPtr CreateObject(CefRefPtr user_data, CefRefPtr accessor); /// // Create a new CefV8Value object of type array. This method should only be // called from within the scope of a CefV8ContextHandler, CefV8Handler or // CefV8Accessor callback, or in combination with calling Enter() and Exit() // on a stored CefV8Context reference. /// /*--cef()--*/ static CefRefPtr CreateArray(); /// // Create a new CefV8Value object of type function. This method should only be // called from within the scope of a CefV8ContextHandler, CefV8Handler or // CefV8Accessor callback, or in combination with calling Enter() and Exit() // on a stored CefV8Context reference. /// /*--cef()--*/ static CefRefPtr CreateFunction(const CefString& name, CefRefPtr handler); /// // True if the value type is undefined. /// /*--cef()--*/ virtual bool IsUndefined() =0; /// // True if the value type is null. /// /*--cef()--*/ virtual bool IsNull() =0; /// // True if the value type is bool. /// /*--cef()--*/ virtual bool IsBool() =0; /// // True if the value type is int. /// /*--cef()--*/ virtual bool IsInt() =0; /// // True if the value type is double. /// /*--cef()--*/ virtual bool IsDouble() =0; /// // True if the value type is Date. /// /*--cef()--*/ virtual bool IsDate() =0; /// // True if the value type is string. /// /*--cef()--*/ virtual bool IsString() =0; /// // True if the value type is object. /// /*--cef()--*/ virtual bool IsObject() =0; /// // True if the value type is array. /// /*--cef()--*/ virtual bool IsArray() =0; /// // True if the value type is function. /// /*--cef()--*/ virtual bool IsFunction() =0; /// // Returns true if this object is pointing to the same handle as |that| // object. /// /*--cef()--*/ virtual bool IsSame(CefRefPtr that) =0; /// // Return a bool value. The underlying data will be converted to if // necessary. /// /*--cef()--*/ virtual bool GetBoolValue() =0; /// // Return an int value. The underlying data will be converted to if // necessary. /// /*--cef()--*/ virtual int GetIntValue() =0; /// // Return a double value. The underlying data will be converted to if // necessary. /// /*--cef()--*/ virtual double GetDoubleValue() =0; /// // Return a Date value. The underlying data will be converted to if // necessary. /// /*--cef()--*/ virtual CefTime GetDateValue() =0; /// // Return a string value. The underlying data will be converted to if // necessary. /// /*--cef()--*/ virtual CefString GetStringValue() =0; // OBJECT METHODS - These methods are only available on objects. Arrays and // functions are also objects. String- and integer-based keys can be used // interchangably with the framework converting between them as necessary. /// // Returns true if the object has a value with the specified identifier. /// /*--cef(capi_name=has_value_bykey)--*/ virtual bool HasValue(const CefString& key) =0; /// // Returns true if the object has a value with the specified identifier. /// /*--cef(capi_name=has_value_byindex,index_param=index)--*/ virtual bool HasValue(int index) =0; /// // Delete the value with the specified identifier. /// /*--cef(capi_name=delete_value_bykey)--*/ virtual bool DeleteValue(const CefString& key) =0; /// // Delete the value with the specified identifier. /// /*--cef(capi_name=delete_value_byindex,index_param=index)--*/ virtual bool DeleteValue(int index) =0; /// // Returns the value with the specified identifier. /// /*--cef(capi_name=get_value_bykey)--*/ virtual CefRefPtr GetValue(const CefString& key) =0; /// // Returns the value with the specified identifier. /// /*--cef(capi_name=get_value_byindex,index_param=index)--*/ virtual CefRefPtr GetValue(int index) =0; /// // Associate a value with the specified identifier. /// /*--cef(capi_name=set_value_bykey)--*/ virtual bool SetValue(const CefString& key, CefRefPtr value, PropertyAttribute attribute) =0; /// // Associate a value with the specified identifier. /// /*--cef(capi_name=set_value_byindex,index_param=index)--*/ virtual bool SetValue(int index, CefRefPtr value) =0; /// // Register an identifier whose access will be forwarded to the CefV8Accessor // instance passed to CefV8Value::CreateObject(). /// /*--cef(capi_name=set_value_byaccessor)--*/ virtual bool SetValue(const CefString& key, AccessControl settings, PropertyAttribute attribute) =0; /// // Read the keys for the object's values into the specified vector. Integer- // based keys will also be returned as strings. /// /*--cef()--*/ virtual bool GetKeys(std::vector& keys) =0; /// // Returns the user data, if any, specified when the object was created. /// /*--cef()--*/ virtual CefRefPtr GetUserData() =0; // ARRAY METHODS - These methods are only available on arrays. /// // Returns the number of elements in the array. /// /*--cef()--*/ virtual int GetArrayLength() =0; // FUNCTION METHODS - These methods are only available on functions. /// // Returns the function name. /// /*--cef()--*/ virtual CefString GetFunctionName() =0; /// // Returns the function handler or NULL if not a CEF-created function. /// /*--cef()--*/ virtual CefRefPtr GetFunctionHandler() =0; /// // Execute the function using the current V8 context. This method should only // be called from within the scope of a CefV8Handler or CefV8Accessor // callback, or in combination with calling Enter() and Exit() on a stored // CefV8Context reference. |object| is the receiver ('this' object) of the // function. |arguments| is the list of arguments that will be passed to the // function. If execution succeeds |retval| will be set to the function return // value. If execution fails |exception| will be set to the exception that was // thrown. If |rethrow_exception| is true any exception will also be re- // thrown. This method returns false if called incorrectly. /// /*--cef(optional_param=object)--*/ virtual bool ExecuteFunction(CefRefPtr object, const CefV8ValueList& arguments, CefRefPtr& retval, CefRefPtr& exception, bool rethrow_exception) =0; /// // Execute the function using the specified V8 context. |object| is the // receiver ('this' object) of the function. |arguments| is the list of // arguments that will be passed to the function. If execution succeeds // |retval| will be set to the function return value. If execution fails // |exception| will be set to the exception that was thrown. If // |rethrow_exception| is true any exception will also be re-thrown. This // method returns false if called incorrectly. /// /*--cef(optional_param=object)--*/ virtual bool ExecuteFunctionWithContext(CefRefPtr context, CefRefPtr object, const CefV8ValueList& arguments, CefRefPtr& retval, CefRefPtr& exception, bool rethrow_exception) =0; }; #endif // CEF_INCLUDE_CEF_V8_H_