swfdecascontext.xml

Swfdec is a decoder/renderer for Macromedia Flash animations. The decoding and rendering engine is

<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="SwfdecAsContext">
<refmeta>
<refentrytitle role="top_of_page">SwfdecAsContext</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>SWFDEC Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>SwfdecAsContext</refname>
<refpurpose>the main script engine context</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>



                    <link linkend="SwfdecAsContext-struct">SwfdecAsContext</link>;
<link linkend="void">void</link>                <link linkend="swfdec-as-context-startup">swfdec_as_context_startup</link>           (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         <link linkend="guint">guint</link> version);
<link linkend="void">void</link>                <link linkend="swfdec-as-context-abort">swfdec_as_context_abort</link>             (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         const <link linkend="char">char</link> *reason);
const <link linkend="char">char</link>*         <link linkend="swfdec-as-context-get-string">swfdec_as_context_get_string</link>        (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         const <link linkend="char">char</link> *string);
const <link linkend="char">char</link>*         <link linkend="swfdec-as-context-give-string">swfdec_as_context_give_string</link>       (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         <link linkend="char">char</link> *string);
<link linkend="gboolean">gboolean</link>            <link linkend="swfdec-as-context-use-mem">swfdec_as_context_use_mem</link>           (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         <link linkend="gsize">gsize</link> bytes);
<link linkend="void">void</link>                <link linkend="swfdec-as-context-gc">swfdec_as_context_gc</link>                (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context);
<link linkend="void">void</link>                <link linkend="swfdec-as-context-maybe-gc">swfdec_as_context_maybe_gc</link>          (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context);
<link linkend="void">void</link>                <link linkend="swfdec-as-context-run">swfdec_as_context_run</link>               (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context);
<link linkend="void">void</link>                <link linkend="swfdec-as-context-unuse-mem">swfdec_as_context_unuse_mem</link>         (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         <link linkend="gsize">gsize</link> bytes);
<link linkend="void">void</link>                <link linkend="swfdec-as-context-eval">swfdec_as_context_eval</link>              (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         <link linkend="SwfdecAsObject">SwfdecAsObject</link> *obj,
                                                         const <link linkend="char">char</link> *str,
                                                         <link linkend="SwfdecAsValue">SwfdecAsValue</link> *val);
<link linkend="void">void</link>                <link linkend="swfdec-as-context-eval-set">swfdec_as_context_eval_set</link>          (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         <link linkend="SwfdecAsObject">SwfdecAsObject</link> *obj,
                                                         const <link linkend="char">char</link> *str,
                                                         const <link linkend="SwfdecAsValue">SwfdecAsValue</link> *val);
<link linkend="void">void</link>                <link linkend="swfdec-as-context-get-time">swfdec_as_context_get_time</link>          (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         <link linkend="GTimeVal">GTimeVal</link> *tv);
<link linkend="SwfdecAsFrame">SwfdecAsFrame</link>*      <link linkend="swfdec-as-context-get-frame">swfdec_as_context_get_frame</link>         (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context);
<link linkend="gboolean">gboolean</link>            <link linkend="swfdec-as-context-is-constructing">swfdec_as_context_is_constructing</link>   (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context);

</synopsis>
</refsynopsisdiv>

<refsect1 role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>

  <link linkend="GObject">GObject</link>
   +----SwfdecAsContext
         +----<link linkend="SwfdecPlayer">SwfdecPlayer</link>
</synopsis>

</refsect1>








<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>
A <link linkend="SwfdecAsContext"><type>SwfdecAsContext</type></link> provides the main execution environment for Actionscript
execution. It provides the objects typically available in ECMAScript and
manages script execution, garbage collection etc. <link linkend="SwfdecPlayer"><type>SwfdecPlayer</type></link> 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.</note></para>
<para>

</para>
</refsect1>

<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="SwfdecAsContext-struct" role="struct"/>SwfdecAsContext</title>
<indexterm><primary>SwfdecAsContext</primary></indexterm><programlisting>typedef struct _SwfdecAsContext SwfdecAsContext;</programlisting>
<para>
This is the main object ued to hold the state of a script engine. All members 
are private and should not be accessed.
</para>
<para>
Subclassing this structure to get scripting support in your own appliation is
encouraged.</para>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="swfdec-as-context-startup" role="function"/>swfdec_as_context_startup ()</title>
<indexterm><primary>swfdec_as_context_startup</primary></indexterm><programlisting><link linkend="void">void</link>                swfdec_as_context_startup           (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         <link linkend="guint">guint</link> version);</programlisting>
<para>
Starts up the context. This function must be called before any Actionscript
is called on <parameter>context</parameter>. The version is responsible for deciding which native
functions and properties are available in the context.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="SwfdecAsContext"><type>SwfdecAsContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>version</parameter>&nbsp;:</term>
<listitem><simpara> Flash version to use
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="swfdec-as-context-abort" role="function"/>swfdec_as_context_abort ()</title>
<indexterm><primary>swfdec_as_context_abort</primary></indexterm><programlisting><link linkend="void">void</link>                swfdec_as_context_abort             (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         const <link linkend="char">char</link> *reason);</programlisting>
<para>
Aborts script execution in <parameter>context</parameter>. 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.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="SwfdecAsContext"><type>SwfdecAsContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>reason</parameter>&nbsp;:</term>
<listitem><simpara> a string describing why execution was aborted
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="swfdec-as-context-get-string" role="function"/>swfdec_as_context_get_string ()</title>
<indexterm><primary>swfdec_as_context_get_string</primary></indexterm><programlisting>const <link linkend="char">char</link>*         swfdec_as_context_get_string        (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         const <link linkend="char">char</link> *string);</programlisting>
<para>
Gets the garbage-collected version of <parameter>string</parameter>. You need to call this function
for every not garbage-collected string that you want to use in Swfdecs script
interpreter.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="SwfdecAsContext"><type>SwfdecAsContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> a sting that is not garbage-collected
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the garbage-collected version of <parameter>string</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="swfdec-as-context-give-string" role="function"/>swfdec_as_context_give_string ()</title>
<indexterm><primary>swfdec_as_context_give_string</primary></indexterm><programlisting>const <link linkend="char">char</link>*         swfdec_as_context_give_string       (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         <link linkend="char">char</link> *string);</programlisting>
<para>
Takes ownership of <parameter>string</parameter> and returns a refcounted version of the same 
string. This function is the same as <link linkend="swfdec-as-context-get-string"><function>swfdec_as_context_get_string()</function></link>, but 
takes ownership of <parameter>string</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="SwfdecAsContext"><type>SwfdecAsContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string to make refcounted
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A refcounted string
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="swfdec-as-context-use-mem" role="function"/>swfdec_as_context_use_mem ()</title>
<indexterm><primary>swfdec_as_context_use_mem</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            swfdec_as_context_use_mem           (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         <link linkend="gsize">gsize</link> bytes);</programlisting>
<para>
Registers <parameter>bytes</parameter> additional bytes as in use by the <parameter>context</parameter>. This function
keeps track of the memory that script code consumes. If too many memory is 
in use, this function may decide to stop the script engine with an out of 
memory error.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="SwfdecAsContext"><type>SwfdecAsContext</type></link>
</simpara></listitem></varlistentry>