SwfdecAsContext

## SwfdecAsContext SwfdecAsContext — the main script engine context |

## Synopsis

    #include <swfdec/swfdec.h>

                        SwfdecAsContext;
    void                swfdec_as_context_startup           (SwfdecAsContext *context);
    void                swfdec_as_context_abort             (SwfdecAsContext *context,
                                                             const char *reason);
    gboolean            swfdec_as_context_is_aborted        (SwfdecAsContext *context);
    const char*         swfdec_as_context_get_string        (SwfdecAsContext *context,
                                                             const char *string);
    const char*         swfdec_as_context_give_string       (SwfdecAsContext *context,
                                                             char *string);
    void                swfdec_as_context_use_mem           (SwfdecAsContext *context,
                                                             gsize bytes);
    gboolean            swfdec_as_context_try_use_mem       (SwfdecAsContext *context,
                                                             gsize bytes);
    void                swfdec_as_context_unuse_mem         (SwfdecAsContext *context,
                                                             gsize bytes);
    void                swfdec_as_context_gc                (SwfdecAsContext *context);
    void                swfdec_as_context_maybe_gc          (SwfdecAsContext *context);
    void                swfdec_as_context_throw             (SwfdecAsContext *context,
                                                             const SwfdecAsValue *value);
    gboolean            swfdec_as_context_catch             (SwfdecAsContext *context,
                                                             SwfdecAsValue *value);
    void                swfdec_as_context_get_time          (SwfdecAsContext *context,
                                                             GTimeVal *tv);
    SwfdecAsFrame*      swfdec_as_context_get_frame         (SwfdecAsContext *context);
    gboolean            swfdec_as_context_is_constructing   (SwfdecAsContext *context);

## Object Hierarchy

      GObject
       +----SwfdecAsContext
             +----SwfdecPlayer

## Properties

      "aborted"                  gboolean              : Read
      "debugger"                 SwfdecAsDebugger*     : Read / Write / Construct Only
      "memory-until-gc"          gulong                : Read / Write / Construct
      "random-seed"              guint                 : Write

## Signals

      "trace"                                          : Run Last

## Description

A SwfdecAsContext provides the main execution environment for Actionscript execution. It provides the objects typically available in ECMAScript and manages script execution, garbage collection etc. SwfdecPlayer is a subclass of the context that implements Flash specific objects on top of it. However, it is possible to use the context for completely different functions where a sandboxed scripting environment is needed. An example is the Swfdec debugger.

### Note

The Actionscript engine is similar, but not equal to Javascript. It is not very different, but it is different.

## Details

### SwfdecAsContext

    typedef struct _SwfdecAsContext SwfdecAsContext;

This is the main object ued to hold the state of a script engine. All members are private and should not be accessed.

Subclassing this structure to get scripting support in your own appliation is encouraged.

### swfdec_as_context_startup ()

    void                swfdec_as_context_startup           (SwfdecAsContext *context);

Starts up the context. This function must be called before any Actionscript is called on `context`.

`context` : | a SwfdecAsContext

### swfdec_as_context_abort ()

    void                swfdec_as_context_abort             (SwfdecAsContext *context,
                                                             const char *reason);

Aborts script execution in `context`. Call this functon if the script engine encountered a fatal error and cannot continue. A possible reason for this is an out-of-memory condition.

`context` : | a SwfdecAsContext
`reason` : | a string describing why execution was aborted

### swfdec_as_context_is_aborted ()

    gboolean            swfdec_as_context_is_aborted        (SwfdecAsContext *context);

Determines if the given context is aborted. An aborted context is not able to execute any scripts. Aborting can happen if the script engine detects bad scripts that cause excessive memory usage, infinite loops or other problems. In that case the script engine aborts for safety reasons.

`context` : | a SwfdecAsContext
Returns : | `TRUE` if the player is aborted, `FALSE` if it runs normally.

### swfdec_as_context_get_string ()

    const char*         swfdec_as_context_get_string        (SwfdecAsContext *context,
                                                             const char *string);

Gets the garbage-collected version of `string`. You need to call this function for every not garbage-collected string that you want to use in Swfdecs script interpreter.

`context` : | a SwfdecAsContext
`string` : | a sting that is not garbage-collected
Returns : | the garbage-collected version of `string`

### swfdec_as_context_give_string ()

    const char*         swfdec_as_context_give_string       (SwfdecAsContext *context,
                                                             char *string);

Takes ownership of `string` and returns a refcounted version of the same string. This function is the same as `swfdec_as_context_get_string()`, but takes ownership of `string`.

`context` : | a SwfdecAsContext
`string` : | string to make refcounted
Returns : | A refcounted string

### swfdec_as_context_use_mem ()

    void                swfdec_as_context_use_mem           (SwfdecAsContext *context,
                                                             gsize bytes);

Registers `bytes` additional bytes as in use by the `context`. This function keeps track of the memory that script code consumes. If too much memory is in use, this function may decide to stop the script engine with an out of memory error.

`context` : | a SwfdecAsContext
`bytes` : | number of bytes to use

### swfdec_as_context_try_use_mem ()

    gboolean            swfdec_as_context_try_use_mem       (SwfdecAsContext *context,
                                                             gsize bytes);

Tries to register `bytes` additional bytes as in use by the `context`. This function keeps track of the memory that script code consumes. The scripting engine won't be stopped, even if there wasn't enough memory left.

`context` : | a SwfdecAsContext
`bytes` : | number of bytes to use
Returns : | `TRUE` if the memory could be allocated. `FALSE` on OOM.

### swfdec_as_context_unuse_mem ()

    void                swfdec_as_context_unuse_mem         (SwfdecAsContext *context,
                                                             gsize bytes);

Releases a number of bytes previously allocated using `swfdec_as_context_use_mem()`. See that function for details.

`context` : | a SwfdecAsContext
`bytes` : | number of bytes to release

### swfdec_as_context_gc ()

    void                swfdec_as_context_gc                (SwfdecAsContext *context);

Calls the Swfdec Gargbage collector and reclaims any unused memory. You should call this function or `swfdec_as_context_maybe_gc()` regularly.

### Warning

Calling the GC during execution of code or initialization is not allowed.

`context` : | a SwfdecAsContext

### swfdec_as_context_maybe_gc ()

    void                swfdec_as_context_maybe_gc          (SwfdecAsContext *context);

Calls the garbage collector if necessary. It's a good idea to call this function regularly instead of `swfdec_as_context_gc()` as it only does collect garage as needed. For example, SwfdecPlayer calls this function after every frame advancement.

`context` : | a SwfdecAsContext

### swfdec_as_context_throw ()

    void                swfdec_as_context_throw             (SwfdecAsContext *context,
                                                             const SwfdecAsValue *value);

Throws a new exception in the `context` using the given `value`. This function can only be called if the `context` is not already throwing an exception.

`context` : | a SwfdecAsContext
`value` : | a SwfdecAsValue to be thrown

### swfdec_as_context_catch ()

    gboolean            swfdec_as_context_catch             (SwfdecAsContext *context,
                                                             SwfdecAsValue *value);

Removes the currently thrown exception from `context` and sets `value` to the thrown value

`context` : | a SwfdecAsContext
`value` : | a SwfdecAsValue to be thrown
Returns : | `TRUE` if an exception was catched, `FALSE` otherwise

### swfdec_as_context_get_time ()

    void                swfdec_as_context_get_time          (SwfdecAsContext *context,
                                                             GTimeVal *tv);

This function queries the time to be used inside this context. By default, this is the same as `g_get_current_time()`, but it may be overwriten to allow things such as slower or faster playback.

`context` : | a SwfdecAsContext
`tv` : | a GTimeVal to be set to the context's time

### swfdec_as_context_get_frame ()

    SwfdecAsFrame*      swfdec_as_context_get_frame         (SwfdecAsContext *context);

This is a debugging function. It gets the topmost stack frame that is currently executing. If no function is executing, `NULL` is returned. You can easily get a backtrace with code like this:

    for (frame = swfdec_as_context_get_frame (context); frame != NULL;
        frame = swfdec_as_frame_get_next (frame)) {
      char *s = swfdec_as_object_get_debug (SWFDEC_AS_OBJECT (frame));
      g_print ("%s\n", s);
      g_free (s);
    }

`context` : | a SwfdecAsContext
Returns : | the currently executing frame or `NULL` if none

### swfdec_as_context_is_constructing ()

    gboolean            swfdec_as_context_is_constructing   (SwfdecAsContext *context);

Determines if the contexxt is currently constructing. This information is used by various constructors to do different things when they are constructing and when they are not. The Boolean, Number and String functions for example setup the newly constructed objects when constructing but only cast the provided argument when being called.

`context` : | a SwfdecAsConstruct
Returns : | `TRUE` if the currently executing frame is a constructor

## Property Details

### The `"aborted"` property

      "aborted"                  gboolean              : Read

set when the script engine aborts due to an error.

Default value: FALSE

### The `"debugger"` property

      "debugger"                 SwfdecAsDebugger*     : Read / Write / Construct Only

debugger used in this player.

### The `"memory-until-gc"` property

      "memory-until-gc"          gulong                : Read / Write / Construct

amount of bytes that need to be allocated before garbage collection triggers.

### The `"random-seed"` property

      "random-seed"              guint                 : Write

seed used for calculating random numbers.

Default value: 0

## Signal Details

### The `"trace"` signal

    void                user_function                      (SwfdecAsContext *context,
                                                            gchar           *text,
                                                            gpointer         user_data)      : Run Last

Emits a debugging string while running. The effect of calling any swfdec functions on the emitting `context` is undefined.

`context` : | the SwfdecAsContext affected
`text` : | the debugging string
`user_data` : | user data set when the signal handler was connected.

## See Also

SwfdecPlayer