![]() |
![]() |
![]() |
Swfdec Reference Manual | ![]() |
---|---|---|---|---|
#include <swfdec/swfdec.h> SwfdecAsObject; SwfdecAsObject* swfdec_as_object_new (SwfdecAsContext *context); SwfdecAsObject* swfdec_as_object_new_empty (SwfdecAsContext *context); void swfdec_as_object_create (SwfdecAsFunction *fun, guint n_args, const SwfdecAsValue *args, SwfdecAsValue *return_value); void swfdec_as_object_add (SwfdecAsObject *object, SwfdecAsContext *context, gsize size); void swfdec_as_object_set_constructor (SwfdecAsObject *object, SwfdecAsObject *construct); enum SwfdecAsVariableFlag; #define swfdec_as_object_get_variable (object, variable, value) gboolean swfdec_as_object_get_variable_and_flags (SwfdecAsObject *object, const char *variable, SwfdecAsValue *value, guint *flags, SwfdecAsObject **pobject); #define swfdec_as_object_set_variable (object, variable, value) void swfdec_as_object_set_variable_and_flags (SwfdecAsObject *object, const char *variable, const SwfdecAsValue *value, guint default_flags); void swfdec_as_object_add_variable (SwfdecAsObject *object, const char *variable, SwfdecAsFunction *get, SwfdecAsFunction *set, SwfdecAsVariableFlag default_flags); void swfdec_as_object_set_variable_flags (SwfdecAsObject *object, const char *variable, SwfdecAsVariableFlag flags); void swfdec_as_object_unset_variable_flags (SwfdecAsObject *object, const char *variable, SwfdecAsVariableFlag flags); gboolean swfdec_as_object_has_variable (SwfdecAsObject *object, const char *variable); SwfdecAsDeleteReturn swfdec_as_object_delete_variable (SwfdecAsObject *object, const char *variable); void swfdec_as_object_delete_all_variables (SwfdecAsObject *object); gboolean (*SwfdecAsVariableForeach) (SwfdecAsObject *object, const char *variable, SwfdecAsValue *value, guint flags, gpointer data); gboolean swfdec_as_object_foreach (SwfdecAsObject *object, SwfdecAsVariableForeach func, gpointer data); void swfdec_as_object_run (SwfdecAsObject *object, SwfdecScript *script); void swfdec_as_object_call (SwfdecAsObject *object, const char *name, guint argc, SwfdecAsValue *argv, SwfdecAsValue *return_value); SwfdecAsFunction* swfdec_as_object_add_function (SwfdecAsObject *object, const char *name, GType type, SwfdecAsNative native, guint min_args); SwfdecAsFunction* swfdec_as_object_add_constructor (SwfdecAsObject *object, const char *name, GType type, GType construct_type, SwfdecAsNative native, guint min_args, SwfdecAsObject *prototype); char* swfdec_as_object_get_debug (SwfdecAsObject *object); SwfdecAsObject* swfdec_as_object_resolve (SwfdecAsObject *object);
GObject +----SwfdecAsObject +----SwfdecAsArray +----SwfdecAsFrame +----SwfdecAsFunction
This is the basic object type in Swfdec. Every object used by the script
engine must be a SwfdecAsObject. It handles memory management and assigning
variables to it. Almost all functions that are called on objects require that
the objects have been added to the garbage collector previously. For
custom-created objects, you need to do this using swfdec_as_object_add()
,
built-in functions that create objects do this manually.
Note that you cannot know the lifetime of a SwfdecAsObject, since scripts may assign it as a variable to other objects. So you should not assume to know when an object gets removed.
typedef struct _SwfdecAsObject SwfdecAsObject;
Every object value inside the Swfdec script engine must be a SwfdecAsObject. If you want to add custom objects to your script engine, you need to create a subclass. The class provides a number of virtual functions that you can override to achieve the desired behaviour.
SwfdecAsObject* swfdec_as_object_new (SwfdecAsContext *context);
Allocates a new Object. This does the same as the Actionscript code
"new Object()
".
context : |
a SwfdecAsContext |
Returns : | the new object or NULL on out of memory. |
SwfdecAsObject* swfdec_as_object_new_empty (SwfdecAsContext *context);
Creates an empty object. The prototype and constructor properties of the
returned object will not be set. You probably want to call
swfdec_as_object_set_constructor()
on the returned object yourself.
You may want to use swfdec_as_object_new()
instead.
context : |
a SwfdecAsContext |
Returns : | A new SwfdecAsObject adde to context or NULL on OOM.
|
void swfdec_as_object_create (SwfdecAsFunction *fun, guint n_args, const SwfdecAsValue *args, SwfdecAsValue *return_value);
Creates a new object for the given constructor and pushes the constructor on
top of the stack. To actually run the constructor, you need to call
swfdec_as_context_run()
.
fun : |
constructor |
n_args : |
number of arguments |
args : |
arguments to pass to constructor |
return_value : |
pointer for return value or NULL to push the return value to
the stack
|
void swfdec_as_object_add (SwfdecAsObject *object, SwfdecAsContext *context, gsize size);
Takes over the reference to object
for the garbage collector of context
.
The object may not already be part of a different context. The given size
must have been allocated before with swfdec_as_context_use_mem()
.
Note that after swfdec_as_object_add()
the garbage collector might hold the
only reference to object
.
object : |
SwfdecAsObject to make garbage-collected |
context : |
SwfdecAsContext that should manage the object |
size : |
size the object currently uses |
void swfdec_as_object_set_constructor (SwfdecAsObject *object, SwfdecAsObject *construct);
Sets the constructor variables for object
. Most objects get these
variables set automatically, but for objects you created yourself, you want
to call this function. This is essentially the same as the following script
code:
object.constructor = construct; object.__proto__ = construct.prototype;
object : |
a SwfdecAsObject |
construct : |
the constructor of object
|
typedef enum { SWFDEC_AS_VARIABLE_HIDDEN = (1 << 0), SWFDEC_AS_VARIABLE_PERMANENT = (1 << 1), SWFDEC_AS_VARIABLE_CONSTANT = (1 << 2), SWFDEC_AS_VARIABLE_VERSION_6_UP = (1 << 7), SWFDEC_AS_VARIABLE_VERSION_NOT_6 = (1 << 8), SWFDEC_AS_VARIABLE_VERSION_7_UP = (1 << 10), SWFDEC_AS_VARIABLE_VERSION_8_UP = (1 << 12), SWFDEC_AS_VARIABLE_VERSION_9_UP = (1 << 13), } SwfdecAsVariableFlag;
These flags are used to describe various properties of a variable inside
Swfdec. You can manually set them with swfdec_as_object_set_variable_flags()
.
SWFDEC_AS_VARIABLE_HIDDEN |
Do not include variable in enumerations and
swfdec_as_object_foreach() .
|
SWFDEC_AS_VARIABLE_PERMANENT |
Do not allow swfdec_as_object_delete_variable()
to delete this variable.
|
SWFDEC_AS_VARIABLE_CONSTANT |
Do not allow changing the value with
swfdec_as_object_set_variable() .
|
SWFDEC_AS_VARIABLE_VERSION_6_UP |
This symbol is only visible in version 6 and above. |
SWFDEC_AS_VARIABLE_VERSION_NOT_6 |
This symbols is visible in all versions but version 6. |
SWFDEC_AS_VARIABLE_VERSION_7_UP |
This symbol is only visible in version 7 and above. |
SWFDEC_AS_VARIABLE_VERSION_8_UP |
This symbol is only visible in version 8 and above. |
SWFDEC_AS_VARIABLE_VERSION_9_UP |
This symbol is only visible in version 9 and above. |
#define swfdec_as_object_get_variable(object, variable, value)
Gets the value of the given variable
on object
. It walks the prototype
chain. This is a shortcut macro for
swfdec_as_object_get_variable_and_flags()
.
object : |
a SwfdecAsObject |
variable : |
a garbage-collected string containing the name of the variable |
value : |
pointer to a SwfdecAsValue that takes the return value or NULL
|
gboolean swfdec_as_object_get_variable_and_flags (SwfdecAsObject *object, const char *variable, SwfdecAsValue *value, guint *flags, SwfdecAsObject **pobject);
Looks up variable
on object
. It also walks the object's prototype chain.
If the variable exists, its value, flags and the real object containing the
variable will be set and TRUE
will be returned.
object : |
a SwfdecAsObject |
variable : |
a garbage-collected string containing the name of the variable |
value : |
pointer to a SwfdecAsValue that takes the return value or NULL
|
flags : |
pointer to a guint taking the variable's flags or NULL
|
pobject : |
pointer to set to the object that really holds the property or
NULL
|
Returns : | TRUE if the variable exists, FALSE otherwise
|
#define swfdec_as_object_set_variable(object, variable, value)
Sets a variable on object
. It is not guaranteed that getting the variable
after setting it results in the same value. This is a mcaro that calls
swfdec_as_object_set_variable_and_flags()
object : |
a SwfdecAsObject |
variable : |
garbage-collected name of the variable to set |
value : |
value to set the variable to |
void swfdec_as_object_set_variable_and_flags (SwfdecAsObject *object, const char *variable, const SwfdecAsValue *value, guint default_flags);
Sets a variable on object
. It is not guaranteed that getting the variable
after setting it results in the same value, because various mechanisms (like
the Actionscript Object.addProperty function or constant variables) can
avoid this.
object : |
a SwfdecAsObject |
variable : |
garbage-collected name of the variable to set |
value : |
value to set the variable to |
default_flags : |
flags to use if creating the variable anew - the flags will be ignored if the property already exists. |
void swfdec_as_object_add_variable (SwfdecAsObject *object, const char *variable, SwfdecAsFunction *get, SwfdecAsFunction *set, SwfdecAsVariableFlag default_flags);
Adds a variable to object
in the same way as the Actionscript code
"object.addProperty()
" would do. Accessing the variable will from now on be
handled by calling the get
or set
functions. A previous value of the
variable or a previous call to this function will be overwritten.
object : |
a SwfdecAsObject |
variable : |
name of the variable |
get : |
getter function to call when reading the variable |
set : |
setter function to call when writing the variable or NULL if read-only
|
default_flags : |
flags to use if creating the variable anew - the flags will be ignored if the property already exists. |
void swfdec_as_object_set_variable_flags (SwfdecAsObject *object, const char *variable, SwfdecAsVariableFlag flags);
Sets the given flags for the given variable.
object : |
a SwfdecAsObject |
variable : |
the variable to modify |
flags : |
flags to set |
void swfdec_as_object_unset_variable_flags (SwfdecAsObject *object, const char *variable, SwfdecAsVariableFlag flags);
Unsets the given flags for the given variable. The variable must exist in
object
.
object : |
a SwfdecAsObject |
variable : |
the variable to modify |
flags : |
flags to unset |
gboolean swfdec_as_object_has_variable (SwfdecAsObject *object, const char *variable);
Checks if a user-set variable
with the given name exists on object
. This
function does not check variables that are available via an overwritten get
function of the object's class.
object : |
a SwfdecAsObject |
variable : |
garbage-collected variable name |
Returns : | TRUE if the object contains the given variable
|
SwfdecAsDeleteReturn swfdec_as_object_delete_variable (SwfdecAsObject *object, const char *variable);
Deletes the given variable if possible. If the variable is protected from deletion, it will not be deleted.
object : |
a SwfdecAsObject |
variable : |
garbage-collected name of the variable |
Returns : | See SwfdecAsDeleteReturn for details of the return value. |
void swfdec_as_object_delete_all_variables (SwfdecAsObject *object);
Deletes all user-set variables from the given object.
object : |
a SwfdecAsObject |
gboolean (*SwfdecAsVariableForeach) (SwfdecAsObject *object, const char *variable, SwfdecAsValue *value, guint flags, gpointer data);
Function prototype for the swfdec_as_object_foreach()
function.
object : |
The object this function is run on |
variable : |
garbage-collected name of the current variables |
value : |
value of the current variable |
flags : |
Flags associated with the current variable |
data : |
User data passed to swfdec_as_object_foreach()
|
Returns : | TRUE to continue running the foreach function, FALSE to stop
|
gboolean swfdec_as_object_foreach (SwfdecAsObject *object, SwfdecAsVariableForeach func, gpointer data);
Calls func
for every variable of object
or until func
returns FALSE
. The
variables of object
must not be modified by func
.
object : |
a SwfdecAsObject |
func : |
function to call |
data : |
data to pass to func
|
Returns : | TRUE if func always returned TRUE
|
void swfdec_as_object_run (SwfdecAsObject *object, SwfdecScript *script);
Executes the given script
with object
as this pointer.
object : |
a SwfdecAsObject |
script : |
script to execute |
void swfdec_as_object_call (SwfdecAsObject *object, const char *name, guint argc, SwfdecAsValue *argv, SwfdecAsValue *return_value);
Calls the function named name
on the given object. This function is
essentially equal to the folloeing Actionscript code:
@return_value = @object.@name (@argv[0], ..., @argv[argc-1]);
object : |
a SwfdecAsObject |
name : |
garbage-collected string naming the function to call. |
argc : |
number of arguments to provide to function |
argv : |
arguments or NULL when argc is 0
|
return_value : |
location to take the return value of the call or NULL to
ignore the return value.
|
SwfdecAsFunction* swfdec_as_object_add_function (SwfdecAsObject *object, const char *name, GType type, SwfdecAsNative native, guint min_args);
Adds native
as a variable named name
to object
. The newly added variable
will not be enumerated.
object : |
a SwfdecAsObject |
name : |
name of the function. The string does not have to be garbage-collected. |
type : |
the required type of the this Object to make this function execute. May be 0 to accept any type. |
native : |
a native function or NULL to just not do anything
|
min_args : |
minimum number of arguments to pass to native
|
Returns : | the newly created SwfdecAsFunction or NULL on error.
|
SwfdecAsFunction* swfdec_as_object_add_constructor (SwfdecAsObject *object, const char *name, GType type, GType construct_type, SwfdecAsNative native, guint min_args, SwfdecAsObject *prototype);
Adds native
as a constructor named name
to object
. The newly added variable
will not be enumerated.
object : |
a SwfdecAsObject |
name : |
name of the function. The string does not have to be garbage-collected. |
type : |
the required type of the this Object to make this function execute. May be 0 to accept any type. |
construct_type : |
type used when using this function as a constructor. May be 0 to use the default type. |
native : |
a native function or NULL to just not do anything
|
min_args : |
minimum number of arguments to pass to native
|
prototype : |
An optional object to be set as the "prototype" property of the new function. The prototype will be hidden and constant. |
Returns : | the newly created SwfdecAsFunction or NULL on error.
|
char* swfdec_as_object_get_debug (SwfdecAsObject *object);
Gets a representation string suitable for debugging. This function is
guaranteed to not modify the state of the script engine, unlike
swfdec_as_value_to_string()
for example.
object : |
a SwfdecAsObject |
Returns : | A newly allocated string. Free it with g_free() after use.
|
SwfdecAsObject* swfdec_as_object_resolve (SwfdecAsObject *object);
Resolves the object to its real object. Some internal objects should not be exposed to scripts, for example SwfdecAsFrame objects. If an object you want to expose might be internal, call this function to resolve it to an object that is safe to expose.
object : |
a SwfdecAsObject |
Returns : | a non-internal object |