SwfdecAsContext

SwfdecAsContext — the main script engine context

Functions

Properties

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

Signals

void trace Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── SwfdecAsContext
        ╰── SwfdecPlayer

Includes

#include <swfdec/swfdec.h>

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.

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

Functions

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

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

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

context

a SwfdecAsConstruct

 

Returns

TRUE if the currently executing frame is a constructor

Types and Values

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.

Property Details

The “aborted” property

  “aborted”                  gboolean

set when the script engine aborts due to an error.

Flags: Read

Default value: FALSE


The “debugger” property

  “debugger”                 SwfdecAsDebugger *

debugger used in this player.

Flags: Read / Write / Construct Only


The “memory-until-gc” property

  “memory-until-gc”          gulong

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

Flags: Read / Write / Construct


The “random-seed” property

  “random-seed”              guint

seed used for calculating random numbers.

Flags: Write

Default value: 0

Signal Details

The “trace” signal

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

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

Parameters

context

the SwfdecAsContext affected

 

text

the debugging string

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

See Also

SwfdecPlayer