SwfdecAsValue

SwfdecAsValue — exchanging values with the Actionscript engine

Functions

Types and Values

Includes

#include <swfdec/swfdec.h>

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.

Functions

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.

Parameters

val

The value to extract the type from

 

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, }; ]|

Parameters

val

value to set as undefined

 

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).

Parameters

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.

Parameters

val

value to get, the value must reference a boolean

 

Returns

TRUE or FALSE


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.

Parameters

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.

Parameters

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.

Parameters

val

value to get, the value must reference a number

 

Returns

a double. It can be NaN or +-Infinity, but not -0.0


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.

Parameters

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.

Parameters

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.

Parameters

cx

The context to use

 

i

integer value to set

 

Returns

The new value representing i


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().

Parameters

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.

Parameters

s

garbage-collected string to convert

 

Returns

a SwfdecAsValue representing the given string


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.

Parameters

val

value to get, the value must reference a string

 

Returns

a garbage-collected 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.

Never use this function for debugging purposes.

Parameters

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.

Parameters

val

value to set

 

s

garbage-collected string to use

 

SWFDEC_AS_VALUE_SET_NULL()

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

Sets val to the special null value.

Parameters

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.

Parameters

o

the SwfdecAsObject to convert

 

Returns

a SwfdecAsValue representing the given object


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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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().

Parameters

cx

a SwfdecAsContext

 

s1

first string

 

s2

second string

 

Returns

A new garbage-collected string

Types and Values

enum SwfdecAsValueType

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

Members

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_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_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_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.