SwfdecAsObject

SwfdecAsObject — the base object type for scriptable objects

Synopsis




                    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);
void                swfdec_as_object_add                (SwfdecAsObject *object,
                                                         SwfdecAsContext *context,
                                                         gsize size);
void                swfdec_as_object_set_constructor    (SwfdecAsObject *object,
                                                         SwfdecAsObject * const ruct,
                                                         gboolean scripted);
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);
void                swfdec_as_object_set_variable       (SwfdecAsObject *object,
                                                         const char *variable,
                                                         const SwfdecAsValue *value);
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_delete_variable    (SwfdecAsObject *object,
                                                         const char *variable);
gboolean            (*SwfdecAsVariableForeach)          (SwfdecAsObject *object,
                                                         const char *variable,
                                                         SwfdecAsValue *value,
                                                         guint flags,
                                                         gpointer data);
gboolean            swfdec_as_object_foreach            (SwfdecAsObject *object,
                                                         SwfdecAsVariableForeach func,
                                                         gpointer data);
gboolean            swfdec_as_object_has_function       (SwfdecAsObject *object,
                                                         const char *name);
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);
char*               swfdec_as_object_get_debug          (SwfdecAsObject *object);
SwfdecAsObject*     swfdec_as_object_resolve            (SwfdecAsObject *object);

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.

Details

SwfdecAsObject

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

GObject object; do not access

swfdec_as_object_new ()

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.

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.

context : a SwfdecAsContext
Returns : A new SwfdecAsObject adde to context or NULL on OOM.

swfdec_as_object_create ()

void                swfdec_as_object_create             (SwfdecAsFunction *fun,
                                                         guint n_args,
                                                         const SwfdecAsValue *args);

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(). After the constructor has been run, the new object will be pushed to the top of the stack.

fun : constructor
n_args : number of arguments
args : arguments to pass to constructor

swfdec_as_object_add ()

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

swfdec_as_object_set_constructor ()

void                swfdec_as_object_set_constructor    (SwfdecAsObject *object,
                                                         SwfdecAsObject * const ruct,
                                                         gboolean scripted);

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
scripted : TRUE if this object was created by a script. Flash sets the property named "__constructor__" on script-created objects, but "constructor" on native ones.

enum SwfdecAsVariableFlag

typedef enum {
  /* ActionScript flags go here */
  SWFDEC_AS_VARIABLE_DONT_ENUM = (1 << 0),
  SWFDEC_AS_VARIABLE_PERMANENT = (1 << 1),
  SWFDEC_AS_VARIABLE_READONLY = (1 << 2),
  /* internal flags go here */
  SWFDEC_AS_VARIABLE_NATIVE = (1 << 3)
} 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_DONT_ENUM Do not include variable in enumerations and swfdec_as_object_foreach().
SWFDEC_AS_VARIABLE_PERMANENT Do not all swfdec_as_object_delete_variable() to delete this variable.
SWFDEC_AS_VARIABLE_READONLY Do not allow changing the value with swfdec_as_object_set_variable().
SWFDEC_AS_VARIABLE_NATIVE The variable is implemented natively.

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

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

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.

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

void                swfdec_as_object_set_variable       (SwfdecAsObject *object,
                                                         const char *variable,
                                                         const SwfdecAsValue *value);

Sets a variable on object. It is not guaranteed that getting the variable after setting it results in the same value, as some variables can be read-only or require a specific type.

object : a SwfdecAsObject
variable : garbage-collected name of the variable to set
value : value to set the variable to

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.

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.

object : a SwfdecAsObject
variable : the variable to modify
flags : flags to unset

swfdec_as_object_delete_variable ()

gboolean            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 : TRUE if the variable existed. Note that this doesn't mean that the variable was actually removed. Permanent variables for example cannot be removed.

SwfdecAsVariableForeach ()

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

object : a SwfdecAsObject
func : function to call
data : data to pass to func
Returns : TRUE if func always returned TRUE

swfdec_as_object_has_function ()

gboolean            swfdec_as_object_has_function       (SwfdecAsObject *object,
                                                         const char *name);

Convenience function that checks of object has a variable that references a function.

object : a SwfdecAsObject
name : garbage-collected name of th function
Returns : TRUE if object.name is a function.

swfdec_as_object_call ()

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.

swfdec_as_object_add_function ()

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.

swfdec_as_object_get_debug ()

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.

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.

object : a SwfdecAsObject
Returns : a non-internal object