swfdecasvalue.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="swfdec-SwfdecAsValue">
<refmeta>
<refentrytitle role="top_of_page">SwfdecAsValue</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>SWFDEC Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>SwfdecAsValue</refname>
<refpurpose>exchanging values with the Actionscript engine</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

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

<synopsis>



enum                <link linkend="SwfdecAsValueType">SwfdecAsValueType</link>;
                    <link linkend="SwfdecAsValue">SwfdecAsValue</link>;
#define             <link linkend="SWFDEC-AS-VALUE-SET-UNDEFINED:CAPS">SWFDEC_AS_VALUE_SET_UNDEFINED</link>       (val)
#define             <link linkend="SWFDEC-AS-VALUE-GET-BOOLEAN:CAPS">SWFDEC_AS_VALUE_GET_BOOLEAN</link>         (val)
<link linkend="gboolean">gboolean</link>            <link linkend="swfdec-as-value-to-boolean">swfdec_as_value_to_boolean</link>          (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         const <link linkend="SwfdecAsValue">SwfdecAsValue</link> *value);
#define             <link linkend="SWFDEC-AS-VALUE-SET-BOOLEAN:CAPS">SWFDEC_AS_VALUE_SET_BOOLEAN</link>         (val,b)
#define             <link linkend="SWFDEC-AS-VALUE-GET-NUMBER:CAPS">SWFDEC_AS_VALUE_GET_NUMBER</link>          (val)
<link linkend="double">double</link>              <link linkend="swfdec-as-value-to-number">swfdec_as_value_to_number</link>           (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         const <link linkend="SwfdecAsValue">SwfdecAsValue</link> *value);
<link linkend="int">int</link>                 <link linkend="swfdec-as-value-to-integer">swfdec_as_value_to_integer</link>          (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         const <link linkend="SwfdecAsValue">SwfdecAsValue</link> *value);
#define             <link linkend="SWFDEC-AS-VALUE-SET-INT:CAPS">SWFDEC_AS_VALUE_SET_INT</link>             (val,d)
#define             <link linkend="SWFDEC-AS-VALUE-SET-NUMBER:CAPS">SWFDEC_AS_VALUE_SET_NUMBER</link>          (val,d)
#define             <link linkend="SWFDEC-AS-VALUE-GET-STRING:CAPS">SWFDEC_AS_VALUE_GET_STRING</link>          (val)
const <link linkend="char">char</link>*         <link linkend="swfdec-as-value-to-string">swfdec_as_value_to_string</link>           (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         const <link linkend="SwfdecAsValue">SwfdecAsValue</link> *value);
#define             <link linkend="SWFDEC-AS-VALUE-SET-STRING:CAPS">SWFDEC_AS_VALUE_SET_STRING</link>          (val,s)
#define             <link linkend="SWFDEC-AS-VALUE-SET-NULL:CAPS">SWFDEC_AS_VALUE_SET_NULL</link>            (val)
#define             <link linkend="SWFDEC-AS-VALUE-GET-OBJECT:CAPS">SWFDEC_AS_VALUE_GET_OBJECT</link>          (val)
<link linkend="SwfdecAsObject">SwfdecAsObject</link>*     <link linkend="swfdec-as-value-to-object">swfdec_as_value_to_object</link>           (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         const <link linkend="SwfdecAsValue">SwfdecAsValue</link> *value);
#define             <link linkend="SWFDEC-AS-VALUE-SET-OBJECT:CAPS">SWFDEC_AS_VALUE_SET_OBJECT</link>          (val,o)
<link linkend="void">void</link>                <link linkend="swfdec-as-value-to-primitive">swfdec_as_value_to_primitive</link>        (<link linkend="SwfdecAsValue">SwfdecAsValue</link> *value);
<link linkend="char">char</link>*               <link linkend="swfdec-as-value-to-debug">swfdec_as_value_to_debug</link>            (const <link linkend="SwfdecAsValue">SwfdecAsValue</link> *value);
const <link linkend="char">char</link>*         <link linkend="swfdec-as-double-to-string">swfdec_as_double_to_string</link>          (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         <link linkend="double">double</link> d);
const <link linkend="char">char</link>*         <link linkend="swfdec-as-str-concat">swfdec_as_str_concat</link>                (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *cx,
                                                         const <link linkend="char">char</link> *s1,
                                                         const <link linkend="char">char</link> *s2);

</synopsis>
</refsynopsisdiv>









<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>
This section describes how values are handled inside the Actionscript 
engine. Since Actionscript is a dynamically typed language, the variable type 
has to be carried with every value. <link linkend="SwfdecAsValue"><type>SwfdecAsValue</type></link> accomplishes that. Swfdec
allows two possible ways of accessing these values: The common method is to
use the provided functions to explicitly convert the values to a given type
with a function such as <link linkend="swfdec-as-value-to-string"><function>swfdec_as_value_to_string()</function></link>. This is convenient, 
but can be very slow as it can call back into the Actionscript engine when
converting various objects. So it can be unsuitable in some cases.
A different possibiltiy is accessing the values directly using the accessor
macros. You must check the type before doing so though. For setting values,
there only exist macros, since type conversion is not necessary.</para>
<para>

</para>
</refsect1>

<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="SwfdecAsValueType" role="enum"/>enum SwfdecAsValueType</title>
<indexterm><primary>SwfdecAsValueType</primary></indexterm><programlisting>typedef enum {
  SWFDEC_AS_TYPE_UNDEFINED = 0,
  SWFDEC_AS_TYPE_BOOLEAN,
  SWFDEC_AS_TYPE_INT, /* unimplemented, but reserved if someone wants it */
  SWFDEC_AS_TYPE_NUMBER,
  SWFDEC_AS_TYPE_STRING,
  SWFDEC_AS_TYPE_NULL,
  SWFDEC_AS_TYPE_OBJECT
} SwfdecAsValueType;
</programlisting>
<para>
These are the possible values the Swfdec Actionscript engine knows about.</para>
<para>

</para><variablelist role="enum">
<varlistentry>
<term><anchor id="SWFDEC-AS-TYPE-UNDEFINED:CAPS" role="constant"/><literal>SWFDEC_AS_TYPE_UNDEFINED</literal></term>
<listitem><simpara> the special undefined value
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="SWFDEC-AS-TYPE-BOOLEAN:CAPS" role="constant"/><literal>SWFDEC_AS_TYPE_BOOLEAN</literal></term>
<listitem><simpara> a boolean value - true or false
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="SWFDEC-AS-TYPE-INT:CAPS" role="constant"/><literal>SWFDEC_AS_TYPE_INT</literal></term>
<listitem><simpara> reserved value for integers. Should the need arise for
                     performance enhancements - especially on embedded 
                     devices - it might be useful to implement this type.
                     For now, this type will never appear in Swfdec. Using 
                     it will cause Swfdec to crash.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="SWFDEC-AS-TYPE-NUMBER:CAPS" role="constant"/><literal>SWFDEC_AS_TYPE_NUMBER</literal></term>
<listitem><simpara> a double value - also used for integer numbers
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="SWFDEC-AS-TYPE-STRING:CAPS" role="constant"/><literal>SWFDEC_AS_TYPE_STRING</literal></term>
<listitem><simpara> a string. Strings are garbage-collected and unique.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="SWFDEC-AS-TYPE-NULL:CAPS" role="constant"/><literal>SWFDEC_AS_TYPE_NULL</literal></term>
<listitem><simpara> the spaecial null value
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="SWFDEC-AS-TYPE-OBJECT:CAPS" role="constant"/><literal>SWFDEC_AS_TYPE_OBJECT</literal></term>
<listitem><simpara> an object - must be of type <link linkend="SwfdecAsObject"><type>SwfdecAsObject</type></link>
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="SwfdecAsValue" role="struct"/>SwfdecAsValue</title>
<indexterm><primary>SwfdecAsValue</primary></indexterm><programlisting>typedef struct {
  SwfdecAsValueType	type;
} SwfdecAsValue;
</programlisting>
<para>
This is the type used to present an opaque value in the Actionscript 
engine. See <link linkend="SwfdecAsValueType"><type>SwfdecAsValueType</type></link> for possible types. It's similar in 
spirit to <link linkend="GValue"><type>GValue</type></link>. The value held is garbage-collected. Apart from the type 
member, use the provided macros to access this structure.
<note>If you memset a SwfdecAsValue to 0, it is a valid undefined value.</note></para>
<para>

</para><variablelist role="struct">
<varlistentry>
<term><link linkend="SwfdecAsValueType">SwfdecAsValueType</link>&nbsp;<structfield>type</structfield>;</term>
<listitem><simpara> the type of this value.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="SWFDEC-AS-VALUE-SET-UNDEFINED:CAPS" role="macro"/>SWFDEC_AS_VALUE_SET_UNDEFINED()</title>
<indexterm><primary>SWFDEC_AS_VALUE_SET_UNDEFINED</primary></indexterm><programlisting>#define SWFDEC_AS_VALUE_SET_UNDEFINED(val) (val)-&gt;type = SWFDEC_AS_TYPE_UNDEFINED
</programlisting>
<para>
Sets <parameter>val</parameter> to the special undefined value. If you create a temporary value, 
you can instead use code such as <informalexample><programlisting> SwfdecAsValue val = { 0, }; </programlisting></informalexample></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>val</parameter>&nbsp;:</term>
<listitem><simpara> value to set as undefined
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="SWFDEC-AS-VALUE-GET-BOOLEAN:CAPS" role="macro"/>SWFDEC_AS_VALUE_GET_BOOLEAN()</title>
<indexterm><primary>SWFDEC_AS_VALUE_GET_BOOLEAN</primary></indexterm><programlisting>#define SWFDEC_AS_VALUE_GET_BOOLEAN(val) ((val)-&gt;value.boolean)
</programlisting>
<para>
Gets the boolean associated with value. If you are not sure if the value is
a boolean, use <link linkend="swfdec-as-value-to-boolean"><function>swfdec_as_value_to_boolean()</function></link> instead.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>val</parameter>&nbsp;:</term>
<listitem><simpara> value to get, the value must reference a boolean
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="swfdec-as-value-to-boolean" role="function"/>swfdec_as_value_to_boolean ()</title>
<indexterm><primary>swfdec_as_value_to_boolean</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            swfdec_as_value_to_boolean          (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         const <link linkend="SwfdecAsValue">SwfdecAsValue</link> *value);</programlisting>
<para>
Converts the given value to a boolean according to Flash's rules. Note that
these rules changed significantly for strings between Flash 6 and 7.</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>value</parameter>&nbsp;:</term>
<listitem><simpara> value to convert
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> either <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> or <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="SWFDEC-AS-VALUE-SET-BOOLEAN:CAPS" role="macro"/>SWFDEC_AS_VALUE_SET_BOOLEAN()</title>
<indexterm><primary>SWFDEC_AS_VALUE_SET_BOOLEAN</primary></indexterm><programlisting>#define             SWFDEC_AS_VALUE_SET_BOOLEAN(val,b)</programlisting>
<para>
Sets <parameter>val</parameter> to the specified boolean value.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>val</parameter>&nbsp;:</term>
<listitem><simpara> value to set
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>b</parameter>&nbsp;:</term>
<listitem><simpara> boolean value to set, must be either <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> or <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="SWFDEC-AS-VALUE-GET-NUMBER:CAPS" role="macro"/>SWFDEC_AS_VALUE_GET_NUMBER()</title>
<indexterm><primary>SWFDEC_AS_VALUE_GET_NUMBER</primary></indexterm><programlisting>#define SWFDEC_AS_VALUE_GET_NUMBER(val) ((val)-&gt;value.number)
</programlisting>
<para>
Gets the number associated with <parameter>val</parameter>. If you are not sure that the value is
a valid number value, consider using <link linkend="swfdec-as-value-to-number"><function>swfdec_as_value_to_number()</function></link> or 
<link linkend="swfdec-as-value-to-int"><function>swfdec_as_value_to_int()</function></link> instead.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>val</parameter>&nbsp;:</term>
<listitem><simpara> value to get, the value must reference a number
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="swfdec-as-value-to-number" role="function"/>swfdec_as_value_to_number ()</title>
<indexterm><primary>swfdec_as_value_to_number</primary></indexterm><programlisting><link linkend="double">double</link>              swfdec_as_value_to_number           (<link linkend="SwfdecAsContext">SwfdecAsContext</link> *context,
                                                         const <link linkend="SwfdecAsValue">SwfdecAsValue</link> *value);</programlisting>
<para>
Converts the value to a number according to Flash's conversion routines and
the current Flash version. This conversion routine is similar, but not equal
to ECMAScript. For objects, it can call back into the script engine by 
calling the object's valueOf function.</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>value</parameter>&nbsp;:</term>