SwfdecAsObject

SwfdecAsObject — the base object type for scriptable objects

Functions

Types and Values

Includes

#include <swfdec/swfdec.h>

Description

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.

Functions

swfdec_as_object_new ()

SwfdecAsObject *
swfdec_as_object_new (SwfdecAsContext *context,
                      ...);

Allocates a new object and if name is not NULL, runs the constructor. Name is a list of variables to get from the global context as the constructor.

Parameters

context

a SwfdecAsContext

 

...

NULL-terminated list of names of the constructor or NULL for an empty object.

 

Returns

the new object


swfdec_as_object_new_empty ()

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.

Parameters

context

a SwfdecAsContext

 

Returns

A new SwfdecAsObject added to context


swfdec_as_object_create ()

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 runs the constructor.

Parameters

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

 

swfdec_as_object_set_constructor ()

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:

1
object.__proto__ = construct.prototype; ]|

Parameters

object

a SwfdecAsObject

 

construct

the constructor of object

 

swfdec_as_object_get_variable()

#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().

Parameters

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

 

Returns

TRUE if the variable existed, FALSE otherwise


swfdec_as_object_get_variable_and_flags ()

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.

Parameters

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


swfdec_as_object_set_variable()

#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()

Parameters

object

a SwfdecAsObject

 

variable

garbage-collected name of the variable to set

 

value

value to set the variable to

 

swfdec_as_object_set_variable_and_flags ()

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.

Parameters

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.

 

swfdec_as_object_add_variable ()

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.

Parameters

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.

 

swfdec_as_object_set_variable_flags ()

void
swfdec_as_object_set_variable_flags (SwfdecAsObject *object,
                                     const char *variable,
                                     SwfdecAsVariableFlag flags);

Sets the given flags for the given variable.

Parameters

object

a SwfdecAsObject

 

variable

the variable to modify

 

flags

flags to set

 

swfdec_as_object_unset_variable_flags ()

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 .

Parameters

object

a SwfdecAsObject

 

variable

the variable to modify

 

flags

flags to unset

 

swfdec_as_object_has_variable ()

SwfdecAsObject *
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.

Parameters

object

a SwfdecAsObject

 

variable

garbage-collected variable name

 

Returns

the object in the prototype chain that contains variable or NULL if the object does not contain this variable.


swfdec_as_object_delete_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.

Parameters

object

a SwfdecAsObject

 

variable

garbage-collected name of the variable

 

Returns

See SwfdecAsDeleteReturn for details of the return value.


swfdec_as_object_delete_all_variables ()

void
swfdec_as_object_delete_all_variables (SwfdecAsObject *object);

Deletes all user-set variables from the given object.

Parameters

object

a SwfdecAsObject

 

SwfdecAsVariableForeach ()

gboolean
(*SwfdecAsVariableForeach) (SwfdecAsObject *object,
                            const char *variable,
                            SwfdecAsValue *value,
                            guint flags,
                            gpointer data);

Function prototype for the swfdec_as_object_foreach() function.

Parameters

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


swfdec_as_object_foreach ()

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 .

Parameters

object

a SwfdecAsObject

 

func

function to call

 

data

data to pass to func

 

Returns

TRUE if func always returned TRUE


swfdec_as_object_run ()

void
swfdec_as_object_run (SwfdecAsObject *object,
                      SwfdecScript *script);

Executes the given script with object as this pointer.

Parameters

object

a SwfdecAsObject

 

script

script to execute

 

swfdec_as_object_call ()

gboolean
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:

1
@return_value = @object.@name (@argv[0], ..., @argv[argc-1]);

Parameters

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.

 

Returns

TRUE if object had a function with the given name, FALSE otherwise


swfdec_as_object_set_constructor_by_name ()

SwfdecAsObject *
swfdec_as_object_set_constructor_by_name
                               (SwfdecAsObject *object,
                                const char *name,
                                ...);

Sets the constructor of object to be the objet you get when you get the variables given by name and further arguments on the global object. It is equivalent to calling swfdec_as_object_get_variable() with the names first and then calling swfdec_as_object_set_constructor() on object with the final result.

Parameters

object

the object to set a constructor on

 

name

first variable name for getting the constructor

 

...

NULL-terminated list of further variables to get

 

Returns

The actual constructor that was set or NULL on failure


swfdec_as_object_set_constructor_by_namev ()

SwfdecAsObject *
swfdec_as_object_set_constructor_by_namev
                               (SwfdecAsObject *object,
                                const char *name,
                                va_list args);

This is the va_list version of swfdec_as_object_set_constructor_by_name(). See that function for details.

Parameters

object

the object to set a constructor on

 

name

first variable name for getting the constructor

 

args

va_list of further name arguments

 

Returns

The actual constructor that was set or NULL on failure


swfdec_as_object_set_relay ()

void
swfdec_as_object_set_relay (SwfdecAsObject *object,
                            SwfdecAsRelay *relay);

Associates object and relay . This allows you to associate your own data with a given SwfdecAsObject, so you can write native functions making use of this. See SwfdecAsRelay documentation for details about relays.

Parameters

object

The object to set a new relay on

 

relay

The relay to set

 

swfdec_as_object_add_function ()

SwfdecAsFunction *
swfdec_as_object_add_function (SwfdecAsObject *object,
                               const char *name,
                               SwfdecAsNative native);

Adds native as a variable named name to object . The newly added variable will not be enumerated.

Parameters

object

a SwfdecAsObject

 

name

name of the function. The string does not have to be garbage-collected.

 

native

a native function or NULL to just not do anything

 

Returns

the newly created SwfdecAsFunction


swfdec_as_object_resolve ()

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.

Parameters

object

a SwfdecAsObject

 

Returns

a non-internal object

Types and Values

SwfdecAsObject

typedef struct {
} 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.


enum 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().

Members

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.