/**
* @file webvm.h
*
* Copyright 2007-2010 Aplix Corporation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* @htmlonly
* You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
* @endhtmlonly
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* Changes:
*
* - 0.4:
* -
* - removed WVMModuleFuncs->getProperty, introduced WVMGetProperty instead
*
* - 0.5:
* -
* - removed WVMCallbackFuncs->destroyObjectRef, use WVMCallbackFunc->derefObject instead
*
- 0.6:
* -
* - added get and set to WVMFieldSpec
* - changed STRING_TO_WVMVARIANT to take extra release argument
* - added WVMCallbackFuncs->getClassSpecForName
*
* - 0.7:
* -
* - added WVMCallbackFuncs->getFieldValue and WVMCallbackFuncs->setFieldValue
*
* - 0.8:
* -
* - added WVMArrayFuncs to WVMCallbackFuncs->createObjectRef and WVMClassSpec
*
* - 0.9:
* -
* - added "features" parameter to WVMAttach. In WVMPermissionQuery,
* changed permission to feature, a pointer into the features array.
* - Added WVMStringsToAtomsPtr and WVMReleaseAtomsPtr.
*
* - 0.10:
* -
* - changed init so module can specify default root object name.
* - In checkPermission/WVMPermissionQuery, changed getProperty to
* getParam, now taking a user pointer and an atom.
*
* - 0.11:
* -
* Several major and minor API changes including:
* - added superClasses and childClasses to WVMClassSpec to allow inheritance
* - added VariantType_Date in order to support JavaScript type Date
* - added getMapEntryForKey convenience method
* - changed various structs and signatures in order to remove explicit counts,
* it is expected now to use NULL-terminated arrays everywhere in this API
* - renamed WVMValue.count into WVMValue.length
* - removed count argument in WVMCallbackFuncs->getAtomsForStrings
* - removed count argument in WVMCallbackFuncs->releaseAtoms
* - removed classSpecCount argument in WVMModuleFuncs->init
* - removed OBJECTREFARRAY and VariantType_ObjectRefArray, use WVMArrayFuncs instead
* - removed WVMCallType from WVMClassSpec, that's an constructor argument in the future
* - extended WVMClassSpec with WVMClassFuncs in order to provide support for new/delete
* - extended createObjectRef with overrides for methods/fields, which is necessary for
* inheritance
* - extended createObjectRef with callType (replaces WVMClassSpec.callType)
*
* - 0.12:
* -
* - removed WVMError, introduced WVMVariant->isError instead
*
* - 0.13:
* -
* - introduced getFieldValue and setFieldValue
*
* - 0.14:
* -
* - re-introduced OBJECTREFARRAY and VariantType_ObjectRefArray for field access
*
*
*
* Last change: 2010/01/15 dev@webvm.net
*/
#pragma once
#ifdef __cplusplus
extern "C" {
#endif
/**
* @defgroup WVM_General General
* @{
*/
/** @defgroup Common_Enum Common Enumerations */
/** @defgroup WebVM_Error_Code Error Code */
/** @defgroup WebVM_Primitive_Type Primitive Type */
/** @defgroup WebVM_Common_Type General Type */
/** @defgroup WVM_Variant_Operation WVMVariant Operation Macro */
/** @} */
/**
* @defgroup WebVM_Native_Module WebVM Native Module Interface
* Interfaces to be exported by a WebVM native module.
*
* The implementations of the function types defined here must be thread-safe.
* @{
*/
/** @defgroup WebVM_Mudule_Registration Module Registration */
/** @defgroup WebVM_Module_Function Module Instance Lifecycle Control */
/** @} */
/**
* @defgroup WebVM_Callback_Function WebVM Interface
* WebVM service function interface definitions.
* The interface functions pointers are provided by
* WebVM in a #WVMCallbackFuncs struct and can be called at any time in between
* WVMAttach() and WVMDetach().
*
* The implementations of the function types defined here are thread-safe.
* @{
*/
/** @defgroup WebVM_Object_Management Object */
/** @defgroup WebVM_Security_Check Security */
/** @defgroup WebVM_Atom_Management Atom */
/** @defgroup WebVM_Map_Access Map */
/** @defgroup WebVM_Module_State Module State */
/** @defgroup WebVM_Property WebVM Property */
/** @defgroup WebVM_Foreign_Class_Access Foreign Class */
/** @} */
/**
* @defgroup WebVM_Class_Specification Object Interface
* Defines a JavaScript object.
*
* Object access functions must be thread-safe.
* @{
*/
/** @defgroup Class_Instance_Constructor_Destructor Instance Constructor Destructor */
/** @defgroup Class_Field_Access Field Access */
/** @defgroup Class_Method_Invocation Method Invocation */
/** @} */
/**
* @defgroup Array_Access Array Interface
*/
/****************************************************************************
* macros
****************************************************************************/
#define WEBVM_TYPES
#define WEBVM_VERSION_MAJOR 0
#define WEBVM_VERSION_MINOR 14
/**
* @addtogroup WVM_Variant_Operation
* @{
*/
/**
* Begins a macro processing block.
*/
#define WVM_BEGIN_MACRO do {
/**
* Terminates a macro processing block.
*/
#define WVM_END_MACRO } while (0)
/**
* @name Variant type checker
* @{
*/
/**
* Checks if the variant is of void type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_VOID(x) ((x)->type == VariantType_Void)
/**
* Checks if the variant is of boolean type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_BOOL(x) ((x)->type == VariantType_Bool)
/**
* Checks if the variant is of char type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_CHAR(x) ((x)->type == VariantType_Char)
/**
* Checks if the variant is of byte type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_BYTE(x) ((x)->type == VariantType_Byte)
/**
* Checks if the variant is of 32 bit integer type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_INT32(x) ((x)->type == VariantType_Int32)
/**
* Checks if the variant is of 64 bit integer type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_INT64(x) ((x)->type == VariantType_Int64)
/**
* Checks if the variant is of double type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_DOUBLE(x) ((x)->type == VariantType_Double)
/**
* Checks if the variant is of string type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_STRING(x) ((x)->type == VariantType_String)
/**
* Checks if the variant is of date type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_DATE(x) ((x)->type == VariantType_Date)
/**
* Checks if the variant is of map type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_MAP(x) ((x)->type == VariantType_Map)
/**
* Checks if the variant is of value type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_VALUETYPE(x) ((x)->type == VariantType_Value)
/**
* Checks if the variant is of object reference type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_OBJECTREF(x) ((x)->type == VariantType_ObjectRef)
/**
* Checks if the variant represents an error.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_ERROR(x) ((x)->isError)
/**
* Checks if the variant is of function type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_FUNCTION(x) ((x)->type == VariantType_Function)
/**
* Checks if the variant is of byte array type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_BYTEARRAY(x) ((x)->type == VariantType_ByteArray)
/**
* Checks if the variant is of 32 bit integer type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_INT32ARRAY(x) ((x)->type == VariantType_Int32Array)
/**
* Checks if the variant is of 64 bit integer type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_INT64ARRAY(x) ((x)->type == VariantType_Int64Array)
/**
* Checks if the variant is of double array type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_DOUBLEARRAY(x) ((x)->type == VariantType_DoubleArray)
/**
* Checks if the variant is of value array type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_VALUEARRAY(x) ((x)->type == VariantType_ValueArray)
/**
* Checks if the variant is of variant array type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_VARIANTARRAY(x) ((x)->type == VariantType_VariantArray)
/**
* Checks if the variant is of object reference array type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_OBJECTREFARRAY(x) ((x)->type == VariantType_ObjectRefArray)
/**
* Checks if the variant is of null type.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_IS_NULL(x) ((x)->type == VariantType_Null)
/** @} */
/**
* @name Variant value getter
* @{
*/
/**
* The boolean value of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_BOOL(x) ((x)->value.boolValue)
/**
* The 32 bit integer value of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_INT32(x) ((x)->value.int32Value)
/**
* The 64 bit integer value of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_INT64(x) ((x)->value.int64Value)
/**
* The double value of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_DOUBLE(x) ((x)->value.doubleValue)
/**
* Pointer to the UTF-8 string of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_STRING(x) ((x)->value.arr.elements.utf8Elements)
/**
* The date value of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_DATE(x) ((x)->value.dateValue)
/**
* The object reference value of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_OBJECTREF(x) ((x)->value.refValue)
/**
* The function pointer value of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_FUNCTION(x) ((x)->value.refValue)
/**
* The byte array of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_BYTEARRAY(x) ((x)->value.arr.elements.byteElements)
/**
* The 32 bit integer array of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_INT32ARRAY(x) ((x)->value.arr.elements.int32Elements)
/**
* The double array of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_DOUBLEARRAY(x) ((x)->value.arr.elements.doubleElements)
/**
* The value array of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_VALUEARRAY(x) ((x)->value.arr.elements.varElements)
/**
* The variant array of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_VARIANTARRAY(x) ((x)->value.arr.elements.varElements)
/**
* The object reference array of a variant.
* @param x pointer to a #_WVMVariant
*/
#define WVMVARIANT_TO_OBJECTREFARRAY(x) ((x)->value.arr.elements.varElements)
/**
* Retrieves an element of the byte array of a variant.
* @param x pointer to a #_WVMVariant
* @param i index of the element
*/
#define WVMARRAY_GET_BYTE(x, i) ((x)->value.arr.elements.byteElements[(i)])
/**
* Retrieves an element of the 32 bit integer array of a variant.
* @param x pointer to a #_WVMVariant
* @param i index of the element
*/
#define WVMARRAY_GET_INT32(x, i) ((x)->value.arr.elements.int32Elements[(i)])
/**
* Retrieves an element of the 64 bit integer array of a variant.
* @param x pointer to a #_WVMVariant
* @param i index of the element
*/
#define WVMARRAY_GET_INT64(x, i) ((x)->value.arr.elements.int64Elements[(i)])
/**
* Retrieves an element of the double array of a variant.
* @param x pointer to a #_WVMVariant
* @param i index of the element
*/
#define WVMARRAY_GET_DOUBLE(x, i) ((x)->value.arr.elements.doubleElements[(i)])
/**
* Retrieves an element of the variant array of a variant.
* @param x pointer to a #_WVMVariant
* @param i index of the element
*/
#define WVMARRAY_GET_VARIANT(x, i) ((x)->value.arr.elements.varElements[(i)])
/**
* Retrieves an element of the object reference array of a variant.
* @param x pointer to a #_WVMVariant
* @param i index of the element
*/
#define WVMARRAY_GET_OBJECTREF(x, i) ((x)->value.arr.elements.varElements[(i)].value.refValue)
/**
* Retrieves an element of UTF-8 string array of a variant.
* @param x pointer to a #_WVMVariant
* @param i index of the element
*/
#define WVMARRAY_GET_STRING(x, i) ((x)->value.arr.elements.varElements[(i)].value.arr.elements.utf8Elements)
/** @} */
/**
* @name Variant setter
* @{
*/
/**
* Sets a value to an element of the byte array of a variant.
* @param _val value to set
* @param x pointer to a #_WVMVariant
* @param i index of the element
*/
#define WVMARRAY_SET_BYTE(_val, x, i) \
WVM_BEGIN_MACRO \
(x)->value.arr.elements.byteElements[(i)] = (_val); \
WVM_END_MACRO
/**
* Sets a value to an element of the 32 bit integer array of a variant.
* @param _val value to set
* @param x pointer to a #_WVMVariant
* @param i index of the element
*/
#define WVMARRAY_SET_INT32(_val, x, i) \
WVM_BEGIN_MACRO \
(x)->value.arr.elements.int32Elements[(i)] = (_val); \
WVM_END_MACRO
/**
* Sets a value to an element of the 64 bit integer array of a variant.
* @param _val value to set
* @param x pointer to a #_WVMVariant
* @param i index of the element
*/
#define WVMARRAY_SET_INT64(_val, x, i) \
WVM_BEGIN_MACRO \
(x)->value.arr.elements.int64Elements[(i)] = (_val); \
WVM_END_MACRO
/**
* Sets a value to an element of the double array of a variant.
* @param _val value to set
* @param x pointer to a #_WVMVariant
* @param i index of the element
*/
#define WVMARRAY_SET_DOUBLE(_val, x, i) \
WVM_BEGIN_MACRO \
(x)->value.arr.elements.doubleElements[(i)] = (_val); \
WVM_END_MACRO
/**
* Sets a value to an element of the variant array of a variant.
* @param _val value to set
* @param x pointer to a #_WVMVariant
* @param i index of the element
* Use this for #VariantType_ValueArray and #VariantType_VariantArray.
*/
#define WVMARRAY_SET_VARIANT(_val, x, i) \
WVM_BEGIN_MACRO \
(x)->value.arr.elements.varElements[(i)] = (_val); \
WVM_END_MACRO
/**
* Sets a variant as Null type.
* @param x pointer to a #_WVMVariant
*/
#define NULL_TO_WVMVARIANT(x) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_Null; \
(x)->isError = 0; \
WVM_END_MACRO
/**
* Sets a variant as void type.
* @param x pointer to a #_WVMVariant
*/
#define VOID_TO_WVMVARIANT(x) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_Void; \
(x)->isError = 0; \
WVM_END_MACRO
/**
* Sets a boolean value to a variant.
* @param _val the value
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define BOOL_TO_WVMVARIANT(_val, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_Bool; \
(x)->length = 0; \
(x)->release = 0; \
(x)->value.boolValue = !!(_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a char value to a variant.
* @param _val the value
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define CHAR_TO_WVMVARIANT(_val, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_Char; \
(x)->length = 0; \
(x)->release = 0; \
(x)->value.int32Value = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a byte value to a variant.
* @param _val the value
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define BYTE_TO_WVMVARIANT(_val, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_Byte; \
(x)->length = 0; \
(x)->release = 0; \
(x)->value.int32Value = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a 32 bit integer value to a variant.
* @param _val the value
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define INT32_TO_WVMVARIANT(_val, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_Int32; \
(x)->length = 0; \
(x)->release = 0; \
(x)->value.int32Value = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a 64 bit integer value to a variant.
* @param _val the value
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define INT64_TO_WVMVARIANT(_val, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_Int64; \
(x)->length = 0; \
(x)->release = 0; \
(x)->value.int64Value = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a double value to a variant.
* @param _val the value
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define DOUBLE_TO_WVMVARIANT(_val, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_Double; \
(x)->length = 0; \
(x)->release = 0; \
(x)->value.doubleValue = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a string value to a variant.
* @param _val the UTF-8 string value
* @param _release the release function pointer
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define STRING_TO_WVMVARIANT(_val, _release, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_String; \
(x)->length = (UInt32)strlen(_val); \
(x)->release = (_release); \
(x)->value.arr.elements.utf8Elements = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a date value to a variant.
* @param _val the date value
* @param _release the release function pointer
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define DATE_TO_WVMVARIANT(_val, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_Date; \
(x)->length = 0; \
(x)->release = NULL; \
(x)->value.dateValue = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets an object reference to a variant.
* @param _val the reference value
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define OBJECTREF_TO_WVMVARIANT(_val, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_ObjectRef; \
(x)->length = 0; \
(x)->release = 0; \
(x)->value.refValue = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a map to a variant.
* @param _val the map value
* @param _size the map size
* @param _release the release function pointer
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define MAP_TO_WVMVARIANT(_val, _size, _release, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_Map; \
(x)->length = (_size); \
(x)->release = (_release); \
(x)->value.arr.elements.mapElements = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a byte array to a variant.
* @param _val the array
* @param _len the array length
* @param _release the release function pointer
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define BYTEARRAY_TO_WVMVARIANT(_val, _len, _release, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_ByteArray; \
(x)->length = (_len); \
(x)->release = (_release); \
(x)->value.arr.elements.byteElements = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a 32 bit integer array to a variant.
* @param _val the array
* @param _len the array length
* @param _release the release function pointer
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define INT32ARRAY_TO_WVMVARIANT(_val, _len, _release, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_Int32Array; \
(x)->length = (_len); \
(x)->release = (_release); \
(x)->value.arr.elements.int32Elements = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a 64 bit integer array to a variant.
* @param _val the array
* @param _len the array length
* @param _release the release function pointer
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define INT64ARRAY_TO_WVMVARIANT(_val, _len, _release, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_Int64Array; \
(x)->length = (_len); \
(x)->release = (_release); \
(x)->value.arr.elements.int64Elements = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a double array to a variant.
* @param _val the array
* @param _len the array length
* @param _release the release function pointer
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define DOUBLEARRAY_TO_WVMVARIANT(_val, _len, _release, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_DoubleArray; \
(x)->length = (_len); \
(x)->release = (_release); \
(x)->value.arr.elements.doubleElements = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a variant array to a variant.
* @param _val the array
* @param _len the array length
* @param _release the release function pointer
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define VARIANTARRAY_TO_WVMVARIANT(_val, _len, _release, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_VariantArray; \
(x)->length = (_len); \
(x)->release = (_release); \
(x)->value.arr.elements.varElements = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets an object reference array to a variant.
* @param _val the array
* @param _len the array length
* @param _release the release function pointer
* @param x pointer to a object reference array
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define OBJECTREFARRAY_TO_WVMVARIANT(_val, _len, _release, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_ObjectRefArray; \
(x)->length = (_len); \
(x)->release = (_release); \
(x)->value.arr.elements.varElements = (_val); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/**
* Sets a value array to a variant.
* @param _val the array
* @param _cs the class spec of the values
* @param _len the array length
* @param _release the release function pointer
* @param x pointer to a #_WVMVariant
* @param _isError
* a flag indicating whether the variant is an error. (0: not an error; 1: an error)
*/
#define VALUETYPE_TO_WVMVARIANT(_val, _cs, _len, _release, x, _isError) \
WVM_BEGIN_MACRO \
(x)->type = VariantType_Value; \
(x)->length = (_len); \
(x)->release = (_release); \
(x)->value.arr.elements.varElements = (_val); \
(x)->classSpec = (_cs); \
(x)->isError = !!(_isError); \
WVM_END_MACRO
/** @} */
/**
* Releases a variant.
* @param x pointer to a #_WVMVariant
*/
#define RELEASE_WVMVARIANT(x) \
WVM_BEGIN_MACRO \
if((x)->release) { \
(x)->release((x)); \
} \
WVM_END_MACRO
/** @} */
/****************************************************************************
* enums and typedefs
****************************************************************************/
/**
* @addtogroup WebVM_Primitive_Type
* @{
*/
/** Byte */
typedef unsigned char byte;
/** 8 bit unsigned integer */
typedef unsigned char UInt8;
/** 16 bit unsigned integer */
typedef unsigned short UInt16;
/** 32 bit unsigned integer */
typedef unsigned long int UInt32;
/** 64 bit unsigned integer */
typedef unsigned long long UInt64;
/** 16 bit signed integer */
typedef short Int16;
/** 32 bit signed integer */
typedef long int Int32;
/** 63 bit signed integer */
typedef long long Int64;
/** Date data type */
typedef unsigned long long WVMDate;
/* @} */
/**
* @addtogroup WebVM_Common_Type
* @{
*/
/**
* WebVM status data type.
* A value of this data type contains a value of the #WVMState enumeration.
*/
typedef int WVMStatus;
/**
* WebVM reason data type
*/
typedef UInt16 WVMReason;
/**
* WebVM boolean data type
*/
typedef int WVMBool;
/**
* WebVM object data type
*/
typedef void * WVMObject;
/**
* WebVM class reference data type
*/
typedef UInt16 WVMClassReference;
/**
* WebVM object reference data type
*/
typedef UInt64 WVMObjectReference;
/**
* WebVM atom data type
*/
typedef struct _WVMAtom * WVMAtom;
/**
* WebVM variant data type
*/
typedef struct _WVMVariant WVMVariant;
/**
* WebVM class specification
*/
typedef struct _WVMClassSpec WVMClassSpec;
/**
* WebVM map entry
*/
typedef struct _WVMMapEntry WVMMapEntry;
/**
* WebVM method specification
*/
typedef struct _WVMMethodSpec WVMMethodSpec;
/**
* The structure type for containing WebVM module instance data.
*/
typedef struct {
/** module private data. */
void *mData;
/** WebVM private data. */
void *wData;
} WVM;
/* @} */
/**
* @addtogroup WebVM_Error_Code
* @{
*/
enum {
/** ok, no error at all */
Error_NoError = 0,
/** unknown error */
Error_Unspecified = -1,
/** internal error loading native module */
Error_Native = -2,
/** unsupported version */
Error_Unsupported = -3,
/** memory allocation failure */
Error_Mem = -4,
/** type conversion error */
Error_Type = -5,
/** requested item not found */
Error_NotFound = -6,
/** permission denied */
Error_PermDenied = -7,
/** invalid argument */
Error_InvalidArg = -8,
/** use this error code as offset in WebVM internal errors */
Error_Webvm = -32,
/** use this error code as offset in extensions */
Error_Ext = -64,
/** internal error, unknown, fatal */
Error_Internal = -127,
Error_Max = -254
};
/* @} */
/**
* @addtogroup Class_Method_Invocation
* Interface for invoking methods of an object.
* The implementations of the function types defined here must be thread-safe.
* @{
*/
/**
* Invokes a module method.
*
* Each module method must follow this signature.
*
* @param instance
* [in] a WebVM instance handle for private data in the module.
* @param ref
* [in] the object reference of this invocation.
* The value created by the #WVCCreateObjectRefPtr function is passed.
* @param vArgs
* [in] input argument variant.
* $review The number of arguments must follow the value of the
* {@link _WVMMethodSpec#signature signature} member of the #_WVMMethodSpec
* struct to which this function pointer belongs via the
* {@link _WVMMethodSpec#invoke invoke} member. $endreview
* @param vResultArgs
* [out] $review return value variant for the result. $endreview
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.1
* Modified: 0.2 (added WVMObjectReference ref argument)
*/
typedef WVMStatus (*WVMInvokePtr) (WVM *instance,
WVMObjectReference ref,
WVMVariant *vArgs,
WVMVariant *vResultArgs);
/* @} */
/**
* @addtogroup Class_Field_Access
* Interface for accessing fields of an object.
* The implementations of the function types defined here must be thread-safe.
* @{
*/
/**
* Module field access type.
*
* Each module field getter must follow this signature.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param ref
* [in] the object reference of this field access.
* The value created by the #WVCCreateObjectRefPtr function is passed.
* @param vResultArgs
* [out] output argument variant for the result
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.6
*/
typedef WVMStatus (*WVMFieldGetPtr) (WVM *instance,
WVMObjectReference ref,
WVMVariant *vResultArgs);
/**
* Module field access type.
*
* Each module field setter must follow this signature.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param ref
* [in] the object reference of this field access.
* The value created by the #WVCCreateObjectRefPtr function is passed.
* @param vArgs
* [in] input argument variant for the new value
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.6
*
*/
typedef WVMStatus (*WVMFieldSetPtr) (WVM *instance,
WVMObjectReference ref,
WVMVariant *vArgs);
/** @} */
/**
* @addtogroup Array_Access
* @{
*/
/**
* Array element length.
*
* Each array implementation must follow this signature.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param ref
* [in] the object reference of this array access.
* The value created by the #WVCCreateObjectRefPtr function is passed.
* @param length
* [out] output argument variant for the result
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.7
*
*/
typedef WVMStatus (*WVMArrayGetLengthPtr) (WVM *instance,
WVMObjectReference ref,
UInt16 *length);
/**
* Array element getter.
*
* Each array implementation must follow this signature.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param ref
* [in] the object reference of this field access.
* The value created by the #WVCCreateObjectRefPtr function is passed.
* @param index
* [in] [CHECK] the index of the first element of the sub-array the function gets
* @param vResultArgs
* [out] output argument variant for the elements value
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.7
*
*/
typedef WVMStatus (*WVMArrayGetElementPtr) (WVM *instance,
WVMObjectReference ref,
UInt16 index,
WVMVariant *vResultArgs);
/**
* Array element setter.
*
* Each array implementation must follow this signature.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param ref
* [in] the object reference of this field access.
* The value created by the #WVCCreateObjectRefPtr function is passed.
* @param index
* [in] [CHECK] the index of the first element of the sub-array the function sets
* @param vArgs
* [in] input argument variant for the new value
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.7
*
*/
typedef WVMStatus (*WVMArraySetElementPtr) (WVM *instance,
WVMObjectReference ref,
UInt16 index,
WVMVariant *vArgs);
/** @} */
/**
* @addtogroup Class_Instance_Constructor_Destructor
* Interface for instantiation and destruction of an object.
* The implementations of the function types defined here must be thread-safe.
* @{
*/
/**
* Object constructor.
*
* In order to construct a class instance, this method is called when the 'new'
* keyword is used or if a foreign class requests construction.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param classSpec
* [in] the classSpec reference to create an object for.
* @param ref
* [out] output object reference of the class instance.
* $review This function need to call the #WVCCreateObjectRefPtr function to create an object
* reference and pass its result via this parameter. $endreview
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.11
*
*/
typedef WVMStatus (*WVMConstructPtr) (WVM *instance,
WVMClassSpec *classSpec,
WVMObjectReference *ref);
/**
* Object destructor.
*
* In order to destroy a class instance, this method is called when the last
* reference to the underlying object disappears.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param ref
* [in] input object reference of the class instance.
* The object reference created by the the #WVCCreateObjectRefPtr function is passed.
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.11
*
*/
typedef WVMStatus (*WVMDestructPtr) (WVM *instance,
WVMObjectReference *ref);
/** @} */
/**
* @addtogroup Common_Enum Common Enumerations
* @{
*/
/** Variant type */
typedef enum {
/** Void */
VariantType_Void,
/** Bool */
VariantType_Bool,
/** Char */
VariantType_Char,
/** Byte */
VariantType_Byte,
/** 32 bit integer */
VariantType_Int32,
/** 64 bit integer */
VariantType_Int64,
/** Double */
VariantType_Double,
/** String */
VariantType_String,
/** Map */
VariantType_Map,
/** Value */
VariantType_Value,
/** Function */
VariantType_Function,
/** Object reference */
VariantType_ObjectRef,
/** Error */
VariantType_Error,
/** Byte array */
VariantType_ByteArray,
/** 32 bit integer array */
VariantType_Int32Array,
/** 64 bit integer array */
VariantType_Int64Array,
/** Double array */
VariantType_DoubleArray,
/** Variant array */
VariantType_VariantArray,
/** Variant */
VariantType_Variant,
/** Value array */
VariantType_ValueArray,
/** Null. Never use as type */
VariantType_Null,
/**
* Date
* @par History
* added in 0.11
*/
VariantType_Date,
/**
* Date
* @par History
* re-added in 0.14
*/
VariantType_ObjectRefArray,
VariantType_Max,
} WVMVariantType;
/** WebVM native module instance state */
typedef enum {
/** Created */
State_InstanceCreated,
/** Initialized */
State_InstanceInitialised,
/** Loading */
State_InstanceLoading,
/** Loaded */
State_InstanceLoaded,
/** Starting */
State_InstanceStarting,
/** Started */
State_InstanceStarted,
/** Exited */
State_InstanceExited,
/** Aborted */
State_InstanceAborted,
/** Failed */
State_InstanceFailed,
/** Denied */
State_InstanceDenied,
State_Max,
} WVMState;
/** Protocol type */
typedef enum {
/** HTTP */
Protocol_HTTP,
/** HTTPS */
Protocol_HTTPS,
/** File */
Protocol_File,
/** Data */
Protocol_Data,
/** JAR */
Protocol_JAR,
/** Widget */
Protocol_Widget,
Protocol_Max,
} WVMProtocol;
/** Decision */
typedef enum {
/** Permit */
Decision_Permit,
/** Deny */
Decision_Deny,
Decision_Max,
} WVMDecision;
/** Property type */
typedef enum {
/** String */
PropertyType_String,
/** URI */
PropertyType_Uri,
PropertyType_Max,
} WVMPropertyType;
/** Call type */
typedef enum {
/** Call by reference */
CallType_ByReference,
/** Call by value */
CallType_ByValue,
} WVMCallType;
/** @} */
/**
* @addtogroup Array_Access
* @{
*/
/**
* The structure type for containing array access functions.
*/
typedef struct {
/**
* Array length retrieval function.
*/
WVMArrayGetLengthPtr getLength;
/**
* Array element getter function.
*/
WVMArrayGetElementPtr getElement;
/**
* Array element setter function.
*/
WVMArraySetElementPtr setElement;
} WVMArrayFuncs;
/** @} */
/**
* @addtogroup Class_Instance_Constructor_Destructor
* @{
*/
/**
* The structure type for containing constructor and destructor of a class.
*/
typedef struct {
/**
* Constructor
*/
WVMConstructPtr construct;
/**
* Desctructor
*/
WVMDestructPtr destruct;
} WVMClassFuncs;
/** @} */
/**
* @addtogroup Class_Field_Access
* @{
*/
/**
* The structure type for representing a field.
*/
typedef struct {
/**
* Type of field.
*/
WVMVariantType type;
/**
* Class of field.
*
* $review Valid when the type member is #VariantType_ObjectRef; NULL otherwise. $endreview
* @par History:
* added in 0.5
*/
WVMClassSpec *classSpec;
/**
* Name of field.
*/
const char *name;
/**
* $review Getter function.\ $endreview
* @par History:
* added in 0.6
*/
WVMFieldGetPtr get;
/**
* $review Setter function.\ $endreview
*/
WVMFieldSetPtr set;
} WVMFieldSpec;
/** @} **/
/**
* @addtogroup Class_Method_Invocation
* @{
*/
/**
* The structure type for representing an argument.
*/
typedef struct {
/**
* Type of the argument.
*/
WVMVariantType type;
/**
* Class of the argument.
*
* $review Valid when the type member is #VariantType_ObjectRef; NULL otherwise. $endreview
*/
WVMClassSpec *classSpec;
} WVMArgSpec;
/**
* The structure type for representing a signature.
*/
typedef struct {
/**
* $review NULL-terminated array of pointers to input arguments.\ $endreview
*/
WVMArgSpec **inputArgs;
/**
* $review Return argument.\ $endreview
*/
WVMArgSpec *returnArg;
} WVMSignature;
/**
* The structure type for representing a method specification.
*/
struct _WVMMethodSpec {
/**
* Name of the method.
*/
const char *name;
/**
* Signature of the method.
*/
WVMSignature *signature;
/**
* Invoke function pointer (entrypoint) of the method.
*/
WVMInvokePtr invoke;
};
/** @} **/
/**
* @addtogroup WebVM_Class_Specification
* @{
*/
/**
* The structure type for representing a class specification.
*/
struct _WVMClassSpec {
/**
* $review Name of class.\ $endreview
*/
const char *name;
/**
* $review NULL-terminated array of pointers to fields.\ $endreview
*/
WVMFieldSpec **fields;
/**
* $review NULL-terminated array of pointers to methods.\ $endreview
*/
WVMMethodSpec **methods;
/**
* $review Class functions.\ $endreview
* @par History
* added in 0.11
*/
WVMClassFuncs *classFuncs;
/**
* $review NULL-terminated array of pointers to super classes.\ $endreview
*/
WVMClassSpec **superClasses;
/**
* $review NULL-terminated array of pointers to child classes.\ $endreview
*/
WVMClassSpec **childClasses;
};
/** @} */
/**
* @addtogroup WebVM_Common_Type
* @{
*/
/**
* struct WVMUri contains an array of pointer-length pairs, one for
* each part of the URI. The enum is used as the index into the array.
*/
enum WVMUriPartIdx {
/** scheme: always present, terminating ':' not included */
WVMUriScheme,
/** userinfo: NULL if no authority or userinfo omitted;
* terminating '@' not included */
WVMUriUserInfo,
/** host: NULL if no authority */
WVMUriHost,
/** port: NULL if no port; initial ':' not included */
WVMUriPort,
/** path: always present; initial '/' (if any) included */
WVMUriPath,
/** query: NULL if no query; initial '?' not included */
WVMUriQuery,
/** segment: NULL if no segment; initial '#' not included */
WVMUriSegment,
/** The number of URI parts */
WVMUriPartCount
};
/**
* The structure type for representing a URI part.
*/
struct WVMUriPart {
/**
* $review A non-NUL-terminated string containing the part.\ $endreview
*/
const char *s;
/**
* $review The length in bytes of the string indicated by the s member.\ $endreview
*/
unsigned int len;
};
/**
* The structure type for representing a URI.
*/
typedef struct WVMUri {
/** Array of URI parts */
struct WVMUriPart parts[WVMUriPartCount];
} WVMUri;
/**
* The structure type for representing a property.
*/
typedef struct {
/**
* The property type.
*/
WVMPropertyType type;
/**
* The property value
*/
union {
/** UTF-8 string containing the value */
const char *utf8string;
/** $review URI to acquire the property value.\ $endreview */
const WVMUri *uri;
} propValue;
} WVMProperty;
/**
* The structure type for representing a feature.
*/
typedef struct _WVMFeature {
/**
* API feature. A NUL-terminated string.
*/
const char *apiFeature;
/**
* Required device capability. A NUL-terminated string.
*/
const char *deviceCap;
} WVMFeature;
/**
* The structure type for representing a permission query.
@see WVCCheckPermissionPtr
*/
typedef struct _WVMPermissionQuery {
/**
* The feature for which a query is to be made.
*/
const WVMFeature *feature;
/**
* Retrieves parameter string on the permission check.
* @param user
* [in] the user data pointer passed in the userptr parameter to the #WVCCheckPermissionPtr function.
* @param param
* [in] device-capabilities parameter.
* The name of the parameter for a device-capability defined by BONDI.
* @return
* The parameter value corresponding to param for permission check.
*
* $review This function is called multiple times for the number of parameters defined for the device capability.
* For example, for the "messaging.email.send" capability, it is called twice passing "recipients" and "inContacts"
* in param respectively in each call. $endreview
*/
const WVMProperty *(*getParam)(void *user, WVMAtom param);
} WVMPermissionQuery;
/**
* The structure type for representing a value.
*
* It is not recommended to dealing with WVMValue structs directly.
* Use @ref WVM_Variant_Operation "WVMARRAY_XXXX macros" instead.
*/
typedef union {
/**
* Boolean value
*/
WVMBool boolValue;
/**
* 32 bit integer
*/
Int32 int32Value;
/**
* 64 bit integer
*/
Int64 int64Value;
/**
* Double
*/
double doubleValue;
/**
* Object reference
*/
WVMObjectReference refValue;
/**
* Internal use only.
*/
WVMObject objValue;
/**
* Date
*/
WVMDate dateValue;
/**
* Array type values
*/
struct {
/**
* Internal use only.
*/
WVMObject handle;
/**
* Array elements
*/
union {
/** UTF-8 character array */
char *utf8Elements;
/** Byte array */
byte *byteElements;
/** 32 bit integer array */
Int32 *int32Elements;
/** 64 bit integer array */
Int64 *int64Elements;
/** Double array */
double *doubleElements;
/** Map array */
WVMMapEntry *mapElements;
/** Variant array */
WVMVariant *varElements;
} elements;
} arr;
} WVMValue;
/**
* The structure type for representing a variant.
*/
struct _WVMVariant {
/**
* Type of the variant.
*/
WVMVariantType type;
/**
* $review The number of the elements of the array {@link WVMValue#arr value.arr} if type is of an array. $endreview
*/
UInt32 length;
/**
* Value of this variant.
*/
WVMValue value;
/**
* Ignore this.
* @deprecated This will be removed in the near future.
*
* @par History:
* added in 0.7 to support VariantType_ValueArray
*/
WVMClassReference classRef;
/**
* Release function entry for this variant.
* $review This must be set when the variant data is dynamically allocated and needs deallocation
* when it becomes no longer used; NULL otherwise. $endreview
*/
void (*release)(WVMVariant *);
/**
* Object pointer.
* $review This must be set when the type member is #VariantType_ObjectRef; NULL otherwise. $endreview
*/
void *userdata;
/**
* The class of this variant.
* $review Valid when the type member is #VariantType_ObjectRef; NULL otherwise. $endreview
*/
WVMClassSpec *classSpec;
/**
* A flag whether the variant represents an error.
* A value of 0 means that the variant is not an error;
* $review a value of 1 means that an error has occurred and the variant,
* which may represent an Error object, should be thrown
* to the JavaScript script if this error has occurred in a synchronous method call. $endreview
*
* @par History:
* added in 0.12, reflecting if WVMVariant represents an error
*/
WVMBool isError;
};
/**
* The structure type for representing a map entry.
*/
struct _WVMMapEntry {
/**
* The atom assigned to the name of this map entry.
*/
WVMAtom id;
/**
* The value of this map entry.
*/
WVMVariant varValue;
};
/** @} */
/**
* @addtogroup WebVM_Object_Management
* @{
*/
/**
* Creates a WebVM object reference.\ [mandatory]
*
* The function type to be set in {@link WVMCallbackFuncs#createObjectRef WVMCallbackFuncs\#createObjectRef}.
*
* A module calls this function in order to retrieve a valid object
* reference for each object of a class specification it intends to provide as
* an API into JavaScript. This is mandatory for the module's default
* scriptable object, and may be used for further objects that the module
* needs to create. Typically, during the #WVMStartPtr call, this function is
* called then #WVCSetScriptableObjectPtr is called on its object reference
* result to expose the object's API to Javascript.
*
* @param instance
* [in] a WebVM instance handle for private data in the module.
* @param classSpec
* [in] pointer to the particular class specification.
* @param callType
* [in] the call type of the object to be created. This is reserved for future use.
* $review Pass #CallType_ByReference always for the time being. $endreview
* @param arrFuncs
* [in] if not NULL the class spec is created as array result.
* @param overrideFields
* [in] overridden fields in this instantiation, usually in
* inheritance cases, should be NULL if classSpec fields
* should be used.
* @param overrideMethods
* [in] overridden methods in this instantiation, usually in
* inheritance cases, should be NULL if classSpec methods
* should be used.
* @param userData
* [in] auxiliary pointer to the modules object representation.
* $review You can retrieve this value via the #WVCGetObjectForRefPtr function
* passing the object reference passed from this function. $endreview
* @param objectRef
* [out] pointer to the created object reference.
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.1
* Modified: 0.7, introduced arrFuncs argument in order to provide
* array object instantiation.
* Modified: 0.11, introduced overrides for fieldSpecs and classSpecs,
* which can be used in the case of inheritance,
* also introduced the callType argument (replaces prior
* WVMClassSpec field)
*/
typedef WVMStatus (*WVCCreateObjectRefPtr) (WVM *instance,
WVMClassSpec *classSpec,
WVMCallType callType,
WVMArrayFuncs *arrFuncs,
WVMFieldSpec **overrideFields,
WVMMethodSpec **overrideMethods,
WVMObject userData,
WVMObjectReference *objectRef);
/**
* Increases reference count of a WebVM object reference by one.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#refObjectRef WVMCallbackFuncs\#refObjectRef}.
*
* A module calls this function in order to retain an object reference
* for future use. This is mandatory for JavaScript event objects which
* are intended to be used in subsequent invocations. You need to call
* #WVCDerefObjectRefPtr after calling this function in order to free all resources
* correctly.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param objectRef
* [in] pointer to the particular class specification
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.4
* Modified: 0.5, renamed to refObjectRef, changed second argument
*/
typedef WVMStatus (*WVCRefObjectRefPtr) (WVM *instance,
WVMObjectReference objectRef);
/**
* Decreases the reference count of a WebVM object reference by one.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#derefObjectRef WVMCallbackFuncs\#derefObjectRef}.
*
* A module calls this function in order to release an event object reference
* again. This is mandatory for objects which have been referenced using the
* #WVCRefObjectRefPtr call.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param objectRef
* [in] pointer to the particular class specification
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.4
* Modified: 0.5, renamed to derefObjectRef, changed second argument
*/
typedef WVMStatus (*WVCDerefObjectRefPtr) (WVM *instance,
WVMObjectReference objectRef);
/**
* Exposes default scriptable object API for the module.\ [mandatory]
*
* The function type to be set in {@link WVMCallbackFuncs#setScriptableObject WVMCallbackFuncs\#setScriptableObject}.
*
* A module must call this function to provide a default API to WebVM and the
* browser application. Calling this function results in an implicit state
* change of this module to #State_InstanceStarted. If this function is not used, the
* module will not provide any API other than providing properties and allowing
* invocations into WebVM using #WVCInvokePtr.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param objectRef
* [in] the object reference.
* Pass the value created by the #WVCCreateObjectRefPtr function.
*
* @retval #Error_NoError if the function succeeds.
* This means the module is in a #State_InstanceStarted state.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.1
*/
typedef WVMStatus (*WVCSetScriptableObjectPtr) (WVM *instance,
WVMObjectReference objectRef);
/** @} WebVM_Object_Management */
/**
* @addtogroup WebVM_Module_State
* @{
*/
/**
* Gets the module's WebVM state.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#getState WVMCallbackFuncs\#getState}.
*
* A module calls this function to retrieve the modules state in WebVM.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param state
* [out] the state of this module
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.1
*/
typedef WVMStatus (*WVCGetStatePtr) (WVM *instance,
WVMState *state);
/**
* Sets the module's WebVM state.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#setState WVMCallbackFuncs\#setState}.
*
* A module may call this function to set its WebVM state to a particular
* value. For example, if a module cannot be started for some reason, it could
* explicitly set its state to #State_InstanceFailed. It is highly recommended to use
* this function if the native module fails at any point.
*
* $review
* The use of this function is to reflect problems in a module, for
* example if it can't recover from some internal erroneous state anymore.
* If one of the following state is set, WebVM will call any #WVMReleasePtr functions,
* #WVMStopPtr functions and finally WVMDetach().
* - State_InstanceAborted Aborted.
* - State_InstanceFailed Failed.
* - State_InstanceDenied Denied.
* .
* $endreview
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param state
* [in] the new state of the module
* @param reason
* [in] the reason for the state change (not specified yet)
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.1
*/
typedef WVMStatus (*WVCSetStatePtr) (WVM *instance,
WVMState state,
WVMReason reason);
/** @} WebVM_Module_State */
/**
* @addtogroup WebVM_Property
* @{
*/
/**
* Gets a WebVM property value.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#getProperty WVMCallbackFuncs\#getProperty}.
*
* FIXME: This doesn't return the value!
* This function retrieves a WebVM property. No WebVM properties are defined
* yet.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param key
* [in] a short name for the exception
* @param value
* [out] the value pointer
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.1
*/
typedef WVMStatus (*WVCGetPropertyPtr) (WVM *instance,
const char *key,
const char **value);
/** @} WebVM_Property */
/**
* @addtogroup WebVM_Object_Management
* @{
*/
/**
* Invokes a method on a WebVM object.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#invoke WVMCallbackFuncs\#invoke}.
*
* This function allows the caller to invoke a method on a WebVM object for
* which it has a valid reference (from a parameter passed into a module
* method). Such an object might be a JavaScript object that WebVM has
* wrapped, or a WebVM object from another module.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param objectRef
* [in] the object reference on which to perform a method call.
* Pass the value created by the #WVCCreateObjectRefPtr function.
* @param methodIdx
* [in] the method index on this module
* @param vArgs
* [in] the variant arguments to the method
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.1
*/
typedef WVMStatus (*WVCInvokePtr) (WVM *instance,
WVMObjectReference objectRef,
UInt16 methodIdx,
WVMVariant *vArgs);
/** @} WebVM_Object_Management */
/**
* @addtogroup WebVM_Security_Check
* @{
*/
/**
* Checks permission.\ [recommended]
*
* The function type to be set in {@link WVMCallbackFuncs#checkPermission WVMCallbackFuncs\#checkPermission}.
*
* A module should use this function to check permission before performing any
* privacy- or security-related action such as providing access to third party
* components to the host OS environment or accessing privacy-related data such
* as the contact database for example. This function returns the
* permission query result in the decision argument.
*
* The {@link WVMPermissionQuery#feature query->feature}
* field points to the
* applicable API feature and device capability string pair in the features
* array returned from the module's WVMAttach() function.
* {@link WVMPermissionQuery#feature query->feature} must point
* within this array.
*
* During the function call, WebVM will use the supplied
* {@link WVMPermissionQuery#getParam query->getParam} callback
* field to retrieve parameters on the permission check
* as requested by the security policy, for example "location" (corresponding
* to the resource attribute "param:location" in the security policy)
* when checking the device capability "io.file.read".
*
* After this function returns WebVM will not perform further {@link WVMPermissionQuery#getParam query->getParam}
* callbacks.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param query
* [in] the permission query object
* @param userptr
* [in] the user pointer passed to the
* {@link WVMPermissionQuery#getParam query->getParam} callback function.
* @param diecision
* [out] the decision of this permission query
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.1
* Modified: 0.10
*/
typedef WVMStatus (*WVCCheckPermissionPtr) (WVM *instance,
WVMPermissionQuery *query,
void *userptr,
WVMDecision *decision);
/** @} WebVM_Security_Check */
/**
* @addtogroup WebVM_Atom_Management
* @{
*/
/**
* Returns/creates an atom for the given string.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#getAtomForString WVMCallbackFuncs\#getAtomForString}.
*
* A module calls this function in order to retrieve an atom reference for a string.
* If a module uses #WVMMapEntry's this is mandatory in order to address map entries
* in maps retrieved from JavaScript or passed to JavaScript.
* Note that WebVM creates #WVMMapEntry atoms if they are input values.
*
* @param instance
* [in] a WebVM instance handle for private data in the module.
* @param prop
* [in] the particular string you want an atom for.
* @param prop_len
* [in] length in bytes of the string prop.
* @param id
* [out] the atom reference of the string prop.
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.2
*/
typedef WVMStatus (*WVCGetAtomForStringPtr) (WVM *instance,
const char *prop,
UInt32 prop_len,
WVMAtom *id);
/**
* Returns the string property for the given atom.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#getStringForAtom WVMCallbackFuncs\#getStringForAtom}.
*
* A module can use this function to retrieve the string property for the given atom.
* This is mandatory to determine the property key of maps.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param id
* [in] the atom
* @param prop
* [out] pointer to the property result
* @param prop_len
* [out] length of the property string
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.2
* Modified: 0.4 - introduced prop_len return argument
*/
typedef WVMStatus (*WVCGetStringForAtomPtr) (WVM *instance,
WVMAtom id,
const char **prop,
UInt32 *prop_len);
/**
* Releases the given atom.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#releaseAtom WVMCallbackFuncs\#releaseAtom}.
*
* A module can use this function to release the given atom.
*
* This function is expected to be called in the #WVMDeinitPtr function
* under the assumption that the module registered several atoms for
* specific strings during the call to the #WVMInitPtr function.
* It is recommended to call this function, though WebVM will release unreleased
* atoms anyways when an instance disappears.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param id
* [in] the atom
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.2
*/
typedef WVMStatus (*WVCReleaseAtomPtr) (WVM *instance,
WVMAtom id);
/** @} WebVM_Atom_Management */
/**
* @addtogroup WebVM_Map_Access
* @{
*/
/**
* Retrieves the map entry of the given atom as a specific type.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#getMapEntry WVMCallbackFuncs\#getMapEntry}.
*
* A module can use this function to retrieve map entries as a specific type
* conveniently. Different JavaScript engines treat types differently, it is highly
* recommended to use this function for map entry accesses.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param map
* [in] the map variant, must be of type #VariantType_Map.
* @param id
* [in] the atom
* @param type
* [in] the type of the entry
* @param result
* [out] the variant containing the map entry.
*
* @retval #Error_NoError if the function succeeds.
* @retval #Error_Type if a type conversion error occurs.
* @retval "Another negative value" if another {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.2
* Modified: 0.5 (changed WVMArgType into WVMVariantType)
*/
typedef WVMStatus (*WVCGetMapEntryPtr) (WVM *instance,
WVMVariant *map,
WVMAtom id,
WVMVariantType type,
WVMVariant *result);
/**
* Retrieves the map entry of the given key as a specific type.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#getMapEntryForKey WVMCallbackFuncs\#getMapEntryForKey}.
*
* This function is slightly slower than #WVCGetMapEntryPtr, because it'll retrieve a
* #WVMAtom internally for the given key in order to lookup for the map entry.
* If you frequently query for map entries with the same keys it is recommended
* to use #WVCGetMapEntryPtr. This function is intended to be used for convenience
* reasons only.
*
* A module can use this function to retrieve map entries as a specific type
* conveniently. Different JavaScript engines treat types differently, it is highly
* recommended to use this function for map entry accesses.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param map
* [in] the map variant, must be of type #VariantType_Map.
* @param key
* [in] the key
* @param type
* [in] the type of the entry
* @param result
* [out] the variant containing the map entry.
*
* @retval #Error_NoError if the function succeeds.
* @retval #Error_Type if a type conversion error occurs.
* @retval "Another negative value" if another {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.11
*/
typedef WVMStatus (*WVCGetMapEntryForKeyPtr) (WVM *instance,
WVMVariant *map,
const char *key,
WVMVariantType type,
WVMVariant *result);
/** @} WebVM_Map_Access */
/**
* @addtogroup WebVM_Object_Management
* @{
*/
/**
* Returns the object for the given reference.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#getObjectForRef WVMCallbackFuncs\#getObjectForRef}.
*
* For an object reference which has been created by the #WVCCreateObjectRefPtr
* function, you can retrieve the object pointer passed in the
* userData parameter to that function.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param objectRef
* [in] the object reference created by the #WVCCreateObjectRefPtr function.
* @param object
* [out] the object pointer.
*
* @retval #Error_NoError
* if the function succeeds. This means the given reference is known and
* the object has been set.
* @retval #Error_NotFound
* if the function fails because the reference is unknown and the object cannot
* be returned.
* @retval "Another negative value" if another {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.2
*/
typedef WVMStatus (*WVCGetObjectForRefPtr) (WVM *instance,
WVMObjectReference objectRef,
WVMObject *object);
/** @} WebVM_Object_Management */
/**
* @addtogroup WebVM_Foreign_Class_Access
* @{
*/
/**
* Returns a already known (foreign) class specification with for the given name.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#getClassSpecForName WVMCallbackFuncs\#getClassSpecForName}.
*
* A module can use this function to retrieve foreign class specification
* provided by other modules, subject that they have been instanced already.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param name
* [in] name of the class spec
* @param classSpec
* [out] the foreign class spec
*
* @retval #Error_NoError
* if the function succeeds. This means the given class spec is known and
* the classSpec has been set.
* @retval #Error_NotFound
* if the function fails because the class spec is unknown and cannot be returned.
* @retval "Another negative value" if another {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.6
*/
typedef WVMStatus (*WVCGetClassSpecForNamePtr) (WVM *instance,
const char *name,
WVMClassSpec **classSpec);
/** @} WebVM_Foreign_Class_Access */
/**
* @addtogroup WebVM_Object_Management
* @{
*/
/**
* Retrieves the value of the given field index on the object reference.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#getFieldValue WVMCallbackFuncs\#getFieldValue}.
*
* A module can use this function to retrieve a field value for
* the given index of the object reference.
*
* @param instance
* [in] a WebVM instance handle for private data in the module.
* @param ref
* [in] the object reference of this field access.
* Pass the value created by the #WVCCreateObjectRefPtr function.
* @param fieldIdx
* [in] the field index
* @param vResultArgs
* [out] output argument variant for the result
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.7
*/
typedef WVMStatus (*WVCGetFieldValuePtr) (WVM *instance,
WVMObjectReference ref,
UInt16 fieldIdx,
WVMVariant *vResultArgs);
/**
* Sets the value of the given field index on the object reference.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#setFieldValue WVMCallbackFuncs\#setFieldValue}.
*
* A module can use this function to set a field value for
* the given index of the object reference.
*
* @param instance
* [in] a WebVM instance handle for private data in the module.
* @param ref
* [in] the object reference of this field access.
* Pass the value created by the #WVCCreateObjectRefPtr function.
* @param fieldIdx
* [in] the field index.
* @param vArgs
* [in] input argument variant for the value.
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.7
*/
typedef WVMStatus (*WVCSetFieldValuePtr) (WVM *instance,
WVMObjectReference ref,
UInt16 fieldIdx,
WVMVariant *vArgs);
/** @} WebVM_Object_Management */
/**
* @addtogroup WebVM_Atom_Management
* @{
*/
/**
* Returns/creates an atom for each element in the given array of strings.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#getAtomsForStrings WVMCallbackFuncs\#getAtomsForStrings}.
*
* A module calls this function in order to retrieve an atom reference for
* each string in an array. It can be used as an alternative to calling
* #WVCGetAtomForStringPtr multiple times. The array of strings needs to be NULL
* terminated.
*
* @param instance
* [in] a WebVM instance handle for private data in the module.
* @param strings
* [in] array of pointers to NUL-terminated strings. The array must be NULL-terminated.
* @param ids
* [out] NULL-terminated array to store atoms in.
* The array must have enough room to contain the number of atoms for the requested strings.
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* On failure, no atoms have been created, but the contents of the array
* pointed to by ids are undefined.
*
* @par History:
* First appeared: 0.9
* Modified: 0.11 removed count argument, expects NULL terminated strings array
*/
typedef WVMStatus (*WVCGetAtomsForStringsPtr)(WVM *instance,
const char *const *strings,
WVMAtom *ids);
/**
* Releases the atoms in the given array.\ [optional]
*
* The function type to be set in {@link WVMCallbackFuncs#releaseAtoms WVMCallbackFuncs\#releaseAtoms}.
*
* A module calls this function to release the atoms in the given
* NULL-terminated array. It is an alternative to calling #WVCReleaseAtomPtr multiple
* times.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param atoms
* [in] an array of atoms. The array must be NULL-terminated.
*
* @retval #Error_NoError if the function succeeds.
* @retval "A negative value" if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.9
* Modified: 0.11 removed count argument, expects NULL terminated atoms array
*/
typedef WVMStatus (*WVCReleaseAtomsPtr)(WVM *instance,
const WVMAtom *atoms);
/** @} WebVM_Atom_Management */
/**
* @addtogroup WebVM_Callback_Function
* @{
*/
/**
* The structure type for containing the variables and pointers to functions of WebVM.
*/
typedef struct {
/**
* $review Size in bytes of this structure. $endreview
*/
UInt16 size;
/**
* Version of this callback function structure.
*/
struct {
/** Major version */
UInt16 major;
/** Minor version */
UInt16 minor;
} version;
/**
* Function pointer: Creates a WebVM object reference.
*/
WVCCreateObjectRefPtr createObjectRef;
/**
* Function pointer: Exposes default scriptable object API for the module.
*/
WVCSetScriptableObjectPtr setScriptableObject;
/**
* Function pointer: Gets the module's WebVM state.
*/
WVCGetStatePtr getState;
/**
* Function pointer: Sets the module's WebVM state.
*/
WVCSetStatePtr setState;
/**
* Function pointer: Gets a WebVM property value.
*/
WVCGetPropertyPtr getProperty;
/**
* Function pointer: Invokes a method on a WebVM object.
*/
WVCInvokePtr invoke;
/**
* Function pointer: Checks permission.
*/
WVCCheckPermissionPtr checkPermission;
/**
* Function pointer: Returns/creates an atom for the given string.
*/
WVCGetAtomForStringPtr getAtomForString;
/**
* Function pointer: Returns the string property for the given atom.
*/
WVCGetStringForAtomPtr getStringForAtom;
/**
* Function pointer: Releases the given atom.
*/
WVCReleaseAtomPtr releaseAtom;
/**
* Function pointer: Retrieves the map entry of the given atom as a specific type.
*/
WVCGetMapEntryPtr getMapEntry;
/**
* Function pointer: Returns the object for the given reference.
*/
WVCGetObjectForRefPtr getObjectForRef;
/**
* Function pointer: Increases reference count of a WebVM object reference by one.
* @par History:
* extension in 0.4
* renamed in 0.5
*/
WVCRefObjectRefPtr refObjectRef;
/**
* Function pointer: Decreases the reference count of a WebVM object reference by one.
* @par History:
* renamed in 0.5
*/
WVCDerefObjectRefPtr derefObjectRef;
/**
* Function pointer: Returns a already known (foreign) class specification with for the given name.
* @par History:
* extensions in 0.6
*/
WVCGetClassSpecForNamePtr getClassSpecForName;
/**
* Function pointer: Retrieves the value of the given field index on the object reference.
* @par History:
* extensions in 0.7
*/
WVCGetFieldValuePtr getFieldValue;
/**
* Function pointer: Sets the value of the given field index on the object reference.
* @par History:
* extensions in 0.7
*/
WVCSetFieldValuePtr setFieldValue;
/**
* Function pointer: Returns/creates an atom for each element in the given array of strings.
* @par History:
* extension in 0.9
*/
WVCGetAtomsForStringsPtr getAtomsForStrings;
/**
* Function pointer: Releases the atoms in the given array.
* @par History:
* extension in 0.9
*/
WVCReleaseAtomsPtr releaseAtoms;
/**
* Function pointer: Retrieves the map entry of the given key as a specific type.
* @par History:
* extension in 0.11
*/
WVCGetMapEntryForKeyPtr getMapEntryForKey;
} WVMCallbackFuncs;
/** @} end of WebVM Callback Function */
/**
* @addtogroup WebVM_Module_Function
* Module interface functions definitions.
* The interface functions need to be provided by a
* module in a #WVMModuleFuncs struct for use by WebVM.
*
* The implementations of the function types defined here must be thread-safe.
* @{
*/
/**
* @name WVMModuleFuncs function type
* @{
*/
/**
* Initializes the module.\ [mandatory]
*
* The function type to be set in {@link WVMModuleFuncs#init WVMModuleFuncs\#init}.
*
* WebVM calls this function after a successful WVMAttach() call to instruct the
* module to initialize its data structures and allocate any resources it needs
* in order to be started later on.
*
* @param instance
* [in] a WebVM instance handle for private data in the module.
* @param classSpecs
* [out] NULL-terminated array of class specifications provided by this module.
* @param defaultRootName
* [out] NUL-terminated default name to assign to root object.
* Defaults to NULL if not set, meaning that there is
* no default name.
*
* @retval #Error_NoError if the function succeeds.
* @retval #Error_Native if an {@link #Error_Unspecified error} occurs.
*
* @par Future use:
* It might be valid in the future to set the classSpecCount and classSpecs
* to nil if use cases appear where the classSpecs supported by a module
* aren't known at initialization time.
*
* @par History:
* First appeared: 0.1
* Modified: 0.10 (added defaultRootName parameter)
* Modified: 0.11 removed classSpecCount argument
*/
typedef WVMStatus (*WVMInitPtr) (WVM *instance,
WVMClassSpec ***classSpecs,
const char **defaultRootName);
/**
* Deinitializes the module.\ [mandatory]
*
* The function type to be set in {@link WVMModuleFuncs#deinit WVMModuleFuncs\#deinit}.
*
* WebVM calls this function when it is about to be unloaded, to instruct
* the module to free resources and deinitialize.
*
* @param instance
* [in] a WebVM instance handle for private data in the module.
*
* @par History:
* First appeared: 0.1
*/
typedef void (*WVMDeinitPtr) (WVM *instance);
/**
* Starts the module.\ [mandatory]
*
* The function type to be set in {@link WVMModuleFuncs#start WVMModuleFuncs\#start}.
*
* WebVM calls this function to start the module, after a successful call
* to the module's #WVMInitPtr function.
*
* The module should be prepared to have its method calls invoked once this
* function succeeds.
*
* This function is expected to call the #WVCCreateObjectRefPtr function to create
* an object reference for its top-level class and call the
* #WVCSetScriptableObjectPtr function to set it as the module's default scriptable
* object.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
*
* @retval #Error_NoError if the function succeeds.
* @retval #Error_Native if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.1
*/
typedef WVMStatus (*WVMStartPtr) (WVM *instance);
/**
* Stops the module.\ [mandatory]
*
* The function type to be set in {@link WVMModuleFuncs#stop WVMModuleFuncs\#stop}.
*
* WebVM calls this function to signal that no more invocation of module
* method calls will occur. It is called just before calling the
* #WVMDeinitPtr function.
*
* The function is expected to call the
* #WVCDerefObjectRefPtr function to destroy any object created in the #WVMStartPtr function,
* including the default scriptable object.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
*
* @retval #Error_NoError if the function succeeds.
* @retval #Error_Native if an {@link #Error_Unspecified error} occurs.
*
* @par History:
* First appeared: 0.1
*/
typedef WVMStatus (*WVMStopPtr) (WVM *instance);
/**
* Releases the associated object of the given object reference.\ [mandatory]
*
* The function type to be set in {@link WVMModuleFuncs#release WVMModuleFuncs\#release}.
*
* WebVM calls this function to signal that no more references of
* the object are kept and that the native module must free the object.
*
* This function is expected being called during or after a call to
* the #WVCDerefObjectRefPtr function for an object reference
* which has been created by the native module. It is illegal
* to retrieve the object from WebVM when this function is called, because
* WebVM will not reference it anymore.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
* @param object
* [in] the object pointer held in WebVM.
* The value passed in the userData parameter to the #WVCCreateObjectRefPtr function is pased.
* @param objectRef
* [in] the object reference.
* The value created by the #WVCCreateObjectRefPtr function is pased.
*
* @par History:
* First appeared: 0.5
*/
typedef void (*WVMReleasePtr) (WVM *instance,
WVMObject *object,
WVMObjectReference objectRef);
/** @} */
/**
* The structure type for containing the module variables and pointers to module functions.
*/
typedef struct {
/**
* to be filled later
*/
UInt16 size;
/**
* The version.
*/
struct {
/** Major version. */
UInt16 major;
/** Minor version. */
UInt16 minor;
} version;
/**
* Initialize function.\ [mandatory]
* @par History:
* modified in 0.11
*/
WVMInitPtr init;
/**
* De-initialize function.\ [mandatory]
*/
WVMDeinitPtr deinit;
/**
* Start function.\ [mandatory]
*/
WVMStartPtr start;
/**
* Stop function.\ [mandatory]
*/
WVMStopPtr stop;
/**
* Release function.\ [mandatory]
* @par History:
* version 0.5
*/
WVMReleasePtr release;
} WVMModuleFuncs;
/** @} end of WebVM Module Function */
/**
* @addtogroup WebVM_Mudule_Registration Module Registration
* Module entry/exit functions. These need to be exported by the module
* library.
*
* The implementations of the function types defined here must be thread-safe.
* @{
*/
/**
* Attaches a module.\ [mandatory]
*
* WebVM calls this function as the module is loaded.
* $review The module is loaded when a Web page or Widget requests use of the feature
* implemented in the module and it is approved by WebVM according to the security policy.
* This implies that multiple instance of a module can be attached concurrently. $endreview
*
* A #WVMFeature struct
* contains two pointers each to a NUL-terminated string.
* Where a single API feature uses more than one
* device capability, it should appear in that many #WVMFeature
* structs in the array passed via features. A pointer to a particular
* #WVMFeature struct in the array is then passed by the
* module to calls to #WVCCheckPermissionPtr as the
* {@link WVMPermissionQuery#feature WVMPermissionQuery\#feature} field of the query parameter.
*
* @param instance
* [in] a WebVM instance handle for private data in the module.
* @param wvcFuncs
* [in] pointer to WebVM callback functions called by the module.
* @param wvmFuncs
* [out] pointer to the module functions called by WebVM.
* @param features
* [out] pointer to an array of #WVMFeature structs describing
* the (BONDI security model) API features and device
* capabilities used by the module. $review The array must be terminated by
* a 0-filled #WVMFeature struct. $endreview
*
* @retval #Error_NoError
* if the function succeeds.
* @retval #Error_Unsupported
* if the version in wvcFuncs isn't supported.
* @retval #Error_Native
* if another error occurs.
*
* @par History:
* First appeared: 0.1
* Modified: 0.9
*/
WVMStatus WVMAttach(WVM *instance,
WVMCallbackFuncs *wvcFuncs,
WVMModuleFuncs **wvmFuncs,
const WVMFeature **features);
/**
* Detaches a module.\ [mandatory]
*
* WebVM calls this function as the module is unloaded.
*
* @param instance
* [in] a WebVM instance handle for private data in the module
*
* @par History:
* First appeared: 0.1
*/
void WVMDetach(WVM *instance);
/**
* Gets a static module property.\ [optional]
*
* WebVM calls this function to get the value of a property from this
* module. It can be called at any time, even prior to WVMAttach() or after
* WVMDetach().
*
* A module might provide some properties about the version, vendor,
* description, etc. in the future.
*
* @param key
* [in] a property key
* @return
* the value of the property or NULL if the property does not exist.
*
* @par History:
* First appeared: 0.1 as WVMModuleFunction
* Modified: 0.4 as a library function
*/
const char *WVMGetProperty(const char *key);
/** @} end of WebVM Module Registration */
#ifdef __cplusplus
} /* extern "C" */
#endif