## SwfdecAsValue SwfdecAsValue — exchanging values with the Actionscript engine |

## Synopsis

    #include <swfdec/swfdec.h>

    enum                SwfdecAsValueType;
    typedef             SwfdecAsValue;
    #define             SWFDEC_AS_VALUE_GET_TYPE            (val)
    #define             SWFDEC_AS_VALUE_UNDEFINED
    #define             SWFDEC_AS_VALUE_SET_UNDEFINED       (val)
    #define             SWFDEC_AS_VALUE_FALSE
    #define             SWFDEC_AS_VALUE_TRUE
    #define             SWFDEC_AS_VALUE_FROM_BOOLEAN        (b)
    #define             SWFDEC_AS_VALUE_GET_BOOLEAN         (val)
    gboolean            swfdec_as_value_to_boolean          (SwfdecAsContext *context,
                                                             SwfdecAsValue value);
    #define             SWFDEC_AS_VALUE_SET_BOOLEAN         (val,b)
    #define             SWFDEC_AS_VALUE_GET_NUMBER          (val)
    SwfdecAsValue       swfdec_as_value_from_number         (SwfdecAsContext *context,
                                                             double number);
    double              swfdec_as_value_to_number           (SwfdecAsContext *context,
                                                             SwfdecAsValue value);
    #define             swfdec_as_value_from_integer        (cx, i)
    int                 swfdec_as_value_to_integer          (SwfdecAsContext *context,
                                                             SwfdecAsValue value);
    #define             SWFDEC_AS_VALUE_FROM_STRING         (s)
    #define             SWFDEC_AS_VALUE_GET_STRING          (val)
    const char*         swfdec_as_value_to_string           (SwfdecAsContext *context,
                                                             SwfdecAsValue value);
    #define             SWFDEC_AS_VALUE_SET_STRING          (val,s)
    #define             SWFDEC_AS_VALUE_NULL
    #define             SWFDEC_AS_VALUE_SET_NULL            (val)
    #define             SWFDEC_AS_VALUE_FROM_OBJECT         (o)
    #define             SWFDEC_AS_VALUE_GET_OBJECT          (val)
    SwfdecAsObject*     swfdec_as_value_to_object           (SwfdecAsContext *context,
                                                             SwfdecAsValue value);
    #define             SWFDEC_AS_VALUE_SET_OBJECT          (val,o)
    SwfdecAsValue       swfdec_as_value_to_primitive        (SwfdecAsValue value);
    void                swfdec_as_value_get_variable        (SwfdecAsContext *cx,
                                                             const SwfdecAsValue *value,
                                                             const char *name,
                                                             SwfdecAsValue *ret);
    int                 swfdec_as_double_to_integer         (double d);
    const char*         swfdec_as_double_to_string          (SwfdecAsContext *context,
                                                             double d);
    const char*         swfdec_as_integer_to_string         (SwfdecAsContext *context,
                                                             int i);
    const char*         swfdec_as_str_concat                (SwfdecAsContext *cx,
                                                             const char *s1,
                                                             const char *s2);

## Description

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. SwfdecAsValue 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 `swfdec_as_value_to_string()`. 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.

## Details

### enum SwfdecAsValueType

    typedef enum {
      SWFDEC_AS_TYPE_UNDEFINED = 0,
      SWFDEC_AS_TYPE_NULL = 1,
      SWFDEC_AS_TYPE_BOOLEAN = 2,
      SWFDEC_AS_TYPE_INT = 3,
      SWFDEC_AS_TYPE_NUMBER = 4,
      SWFDEC_AS_TYPE_STRING = 5,
      SWFDEC_AS_TYPE_OBJECT = 6,
      SWFDEC_AS_TYPE_MOVIE = 7
    } SwfdecAsValueType;

These are the possible values the Swfdec Actionscript engine knows about.

`SWFDEC_AS_TYPE_UNDEFINED` | the special undefined value
`SWFDEC_AS_TYPE_NULL` | the spaecial null value
`SWFDEC_AS_TYPE_BOOLEAN` | a boolean value - true or false
`SWFDEC_AS_TYPE_INT` | 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.
`SWFDEC_AS_TYPE_NUMBER` | a double value - also used for integer numbers
`SWFDEC_AS_TYPE_STRING` | a string. Strings are garbage-collected and unique.
`SWFDEC_AS_TYPE_OBJECT` | an object - must be of type SwfdecAsObject
`SWFDEC_AS_TYPE_MOVIE` | an internal type used only inside SwfdecPlayer objects. It is not exported in the API.

### SwfdecAsValue

    typedef gsize SwfdecAsValue;

This is the type used to present an opaque value in the Actionscript engine. See SwfdecAsValueType for possible types. It's similar in spirit to GValue. Use the provided macros to access this structure.

### SWFDEC_AS_VALUE_GET_TYPE()

    #define SWFDEC_AS_VALUE_GET_TYPE(val) ((SwfdecAsValueType) ((val) & SWFDEC_AS_VALUE_TYPE_MASK))

Extracts the type from a given value.

`val` : | The value to extract the type from

### SWFDEC_AS_VALUE_UNDEFINED

    #define SWFDEC_AS_VALUE_UNDEFINED SWFDEC_AS_VALUE_COMBINE (NULL, SWFDEC_AS_TYPE_UNDEFINED)

The special "undefined" value. Use `SWFDEC_AS_VALUE_IS_UNDEFINED()` to check if a value equals this value.

### SWFDEC_AS_VALUE_SET_UNDEFINED()

    #define SWFDEC_AS_VALUE_SET_UNDEFINED(val) *(val) = SWFDEC_AS_VALUE_UNDEFINED

Sets `val` to the special undefined value. If you create a temporary value, you can instead use code such as

     SwfdecAsValue val = { 0, };

`val` : | value to set as undefined

### SWFDEC_AS_VALUE_FALSE

    #define SWFDEC_AS_VALUE_FALSE SWFDEC_AS_VALUE_COMBINE(NULL, SWFDEC_AS_TYPE_BOOLEAN)

The boolean value false.

### SWFDEC_AS_VALUE_TRUE

    #define SWFDEC_AS_VALUE_TRUE SWFDEC_AS_VALUE_COMBINE(GSIZE_TO_POINTER (1 << SWFDEC_AS_VALUE_TYPE_BITS), SWFDEC_AS_TYPE_BOOLEAN)

The boolean value true.

### SWFDEC_AS_VALUE_FROM_BOOLEAN()

    #define SWFDEC_AS_VALUE_FROM_BOOLEAN(b) (b ? SWFDEC_AS_VALUE_TRUE : SWFDEC_AS_VALUE_FALSE)

Converts the given value to a boolean SwfdecAsValue. When knowing the value at compile-time, use the static values such as `SWFDEC_AS_VALUE_TRUE` instead of SWFDEC_AS_VALUE_FROM_BOOLEAN(`TRUE`).

`b` : | boolean to convert

### SWFDEC_AS_VALUE_GET_BOOLEAN()

    #define SWFDEC_AS_VALUE_GET_BOOLEAN(val) (SWFDEC_AS_VALUE_GET_VALUE (val) != NULL)

Gets the boolean associated with value. If you are not sure if the value is a boolean, use `swfdec_as_value_to_boolean()` instead.

`val` : | value to get, the value must reference a boolean

### swfdec_as_value_to_boolean ()

    gboolean            swfdec_as_value_to_boolean          (SwfdecAsContext *context,
                                                             SwfdecAsValue value);

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.

`context` : | a SwfdecAsContext
`value` : | value to convert
Returns : | either `TRUE` or `FALSE`.

### SWFDEC_AS_VALUE_SET_BOOLEAN()

    #define             SWFDEC_AS_VALUE_SET_BOOLEAN(val,b)

Sets `val` to the specified boolean value.

`val` : | value to set
`b` : | boolean value to set, must be either `TRUE` or `FALSE`

### SWFDEC_AS_VALUE_GET_NUMBER()

    #define SWFDEC_AS_VALUE_GET_NUMBER(val) (((SwfdecAsDoubleValue *) SWFDEC_AS_VALUE_GET_VALUE(val))->number)

Gets the number associated with `val`. If you are not sure that the value is a valid number value, consider using `swfdec_as_value_to_number()` or `swfdec_as_value_to_int()` instead.

`val` : | value to get, the value must reference a number

### swfdec_as_value_from_number ()

    SwfdecAsValue       swfdec_as_value_from_number         (SwfdecAsContext *context,
                                                             double number);

Creates a garbage-collected value representing `number` and returns it.

`context` : | The context to use
`number` : | double value to set
Returns : | The new value representing `number`

### swfdec_as_value_to_number ()

    double              swfdec_as_value_to_number           (SwfdecAsContext *context,
                                                             SwfdecAsValue value);

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.

`context` : | a SwfdecAsContext
`value` : | a SwfdecAsValue used by context
Returns : | a double value. It can be NaN or +-Infinity. It will not be -0.0.

### swfdec_as_value_from_integer()

    #define swfdec_as_value_from_integer(cx, i) swfdec_as_value_from_number((cx), (int) (i))

Creates a garbage-collected value representing `i` and returns it. Currently this function is a macro that calls `swfdec_as_value_set_number()`, but this may change in future versions of Swfdec.

`cx` : | The context to use
`i` : | integer value to set

### swfdec_as_value_to_integer ()

    int                 swfdec_as_value_to_integer          (SwfdecAsContext *context,
                                                             SwfdecAsValue value);

Converts the given value to an integer. This is done similar to the conversion used by `swfdec_as_value_to_number()`.

`context` : | a SwfdecAsContext
`value` : | value to convert
Returns : | An Integer that can be represented in 32 bits.

### SWFDEC_AS_VALUE_FROM_STRING()

    #define SWFDEC_AS_VALUE_FROM_STRING(s) SWFDEC_AS_VALUE_COMBINE (((guint8 *) (s) - G_STRUCT_OFFSET (SwfdecAsStringValue, string)), SWFDEC_AS_TYPE_STRING)

Converts the given string to a SwfdecAsValue.

`s` : | garbage-collected string to convert

### SWFDEC_AS_VALUE_GET_STRING()

    #define SWFDEC_AS_VALUE_GET_STRING(val) (((SwfdecAsStringValue *) SWFDEC_AS_VALUE_GET_VALUE(val))->string)

Gets the string associated with `val`. If you are not sure that the value is a string value, consider using `swfdec_as_value_to_string()` instead.

`val` : | value to get, the value must reference a string

### swfdec_as_value_to_string ()

    const char*         swfdec_as_value_to_string           (SwfdecAsContext *context,
                                                             SwfdecAsValue value);

Converts `value` to a string according to the rules of Flash. This might cause calling back into the script engine if the `value` is an object. In that case, the object's valueOf function is called.

### Warning

Never use this function for debugging purposes.

`context` : | a SwfdecAsContext
`value` : | value to be expressed as string
Returns : | a garbage-collected string representing `value`. The value will never be `NULL`.

### SWFDEC_AS_VALUE_SET_STRING()

    #define             SWFDEC_AS_VALUE_SET_STRING(val,s)

Sets `val` to the given string value.

`val` : | value to set
`s` : | garbage-collected string to use

### SWFDEC_AS_VALUE_NULL

    #define SWFDEC_AS_VALUE_NULL SWFDEC_AS_VALUE_COMBINE (NULL, SWFDEC_AS_TYPE_NULL)

The special "null" value. Use `SWFDEC_AS_VALUE_IS_NULL()` to check if a value equals this value.

### SWFDEC_AS_VALUE_SET_NULL()

    #define SWFDEC_AS_VALUE_SET_NULL(val) *(val) = SWFDEC_AS_VALUE_NULL

Sets `val` to the special null value.

`val` : | value to set

### SWFDEC_AS_VALUE_FROM_OBJECT()

    #define SWFDEC_AS_VALUE_FROM_OBJECT(o) SWFDEC_AS_VALUE_COMBINE (o, SWFDEC_AS_TYPE_OBJECT)

Converts the given object to a SwfdecAsValue.

`o` : | the SwfdecAsObject to convert

### SWFDEC_AS_VALUE_GET_OBJECT()

    #define SWFDEC_AS_VALUE_GET_OBJECT(val) ((SwfdecAsObject *) SWFDEC_AS_VALUE_GET_VALUE (val))

Gets the object associated with `val`. If you are not sure that the value is an object value, consider using `swfdec_as_value_to_object()` instead.

`val` : | value to get, the value must reference an object
Returns : | a SwfdecAsObject

### swfdec_as_value_to_object ()

    SwfdecAsObject*     swfdec_as_value_to_object           (SwfdecAsContext *context,
                                                             SwfdecAsValue value);

Converts a given value to its representation as an object. The object representation for primitive types is a wrapper object of the corresponding class (Number for numbers, String for strings, Boolean for bools). If the value does not have an object representing it, such as undefined and null values, `NULL` is returned.

`context` : | a SwfdecAsContext
`value` : | value to convert
Returns : | object representing `value` or `NULL`.

### SWFDEC_AS_VALUE_SET_OBJECT()

    #define             SWFDEC_AS_VALUE_SET_OBJECT(val,o)

Sets `val` to the given object. The object must have been added to the garbage collector via `swfdec_as_object_add()` previously.

`val` : | value to set
`o` : | garbage-collected SwfdecAsObject to use

### swfdec_as_value_to_primitive ()

    SwfdecAsValue       swfdec_as_value_to_primitive        (SwfdecAsValue value);

Tries to convert the given `value` inline to its primitive value. Primitive values are values that are not objects. If the value is an object, the object's valueOf function is called. If the result of that function is still an object, it is returned nonetheless.

`value` : | value to convert
Returns : | The primitive value for &value

### swfdec_as_value_get_variable ()

    void                swfdec_as_value_get_variable        (SwfdecAsContext *cx,
                                                             const SwfdecAsValue *value,
                                                             const char *name,
                                                             SwfdecAsValue *ret);

Gets a variable from the given `value`. This function is a shortcut for converting to a SwfdecAsObject and then calling `swfdec_As_object_get_variable()`. When the `value` cannot be converted to an object, `ret` is set to undefined.

`cx` : | the context
`value` : | the value to get the variable from
`name` : | name of the variable to get
`ret` : | The return value to set. May be identical to the passed in `value`.

### swfdec_as_double_to_integer ()

    int                 swfdec_as_double_to_integer         (double d);

Converts the given double to an integer using the same rules as the Flash player.

`d` : | any double
Returns : | an integer

### swfdec_as_double_to_string ()

    const char*         swfdec_as_double_to_string          (SwfdecAsContext *context,
                                                             double d);

Converts `d` into a string using the same conversion algorithm as the official Flash player.

`context` : | a SwfdecAsContext
`d` : | a double
Returns : | a garbage-collected string

### swfdec_as_integer_to_string ()

    const char*         swfdec_as_integer_to_string         (SwfdecAsContext *context,
                                                             int i);

Converts `d` into a string using the same conversion algorithm as the official Flash player.

`context` : | a SwfdecAsContext
`i` : | an integer that fits into 32 bits
Returns : | a garbage-collected string

### swfdec_as_str_concat ()

    const char*         swfdec_as_str_concat                (SwfdecAsContext *cx,
                                                             const char *s1,
                                                             const char *s2);

Convenience function to concatenate two garbage-collected strings. This function is equivalent to `g_strconcat()`.

`cx` : | a SwfdecAsContext
`s1` : | first string
`s2` : | second string
Returns : | A new garbage-collected string