## SwfdecAsObject

SwfdecAsObject — the base object type for scriptable objects

## Synopsis

    #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_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);
    SwfdecAsObject*     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);
    gboolean            swfdec_as_object_call               (SwfdecAsObject *object,
                                                             const char *name,
                                                             guint argc,
                                                             SwfdecAsValue *argv,
                                                             SwfdecAsValue *return_value);
    SwfdecAsObject*     swfdec_as_object_set_constructor_by_name
                                                            (SwfdecAsObject *object,
                                                             const char *name,
                                                             ...);
    SwfdecAsObject*     swfdec_as_object_set_constructor_by_namev
                                                            (SwfdecAsObject *object,
                                                             const char *name,
                                                             va_list args);
    void                swfdec_as_object_set_relay          (SwfdecAsObject *object,
                                                             SwfdecAsRelay *relay);
    SwfdecAsFunction*   swfdec_as_object_add_function       (SwfdecAsObject *object,
                                                             const char *name,
                                                             SwfdecAsNative native);
    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 {
    } 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.

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

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

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

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

     object.constructor = construct;
    object.__proto__ = construct.prototype;

`object` : | a SwfdecAsObject
`construct` : | the constructor of `object`

### enum SwfdecAsVariableFlag

    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.

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

    #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

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

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

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

`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_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.

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

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

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

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

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

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

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

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

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

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

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

`object` : | a SwfdecAsObject
Returns : | a non-internal object