SwfdecAsValue

SwfdecAsValue — exchanging values with the Actionscript engine

Synopsis


#include <swfdec/swfdec.h>

enum                SwfdecAsValueType;
                    SwfdecAsValue;
#define             SWFDEC_AS_VALUE_SET_UNDEFINED       (val)
#define             SWFDEC_AS_VALUE_GET_BOOLEAN         (val)
gboolean            swfdec_as_value_to_boolean          (SwfdecAsContext *context,
                                                         const SwfdecAsValue *value);
#define             SWFDEC_AS_VALUE_SET_BOOLEAN         (val,b)
#define             SWFDEC_AS_VALUE_GET_NUMBER          (val)
double              swfdec_as_value_to_number           (SwfdecAsContext *context,
                                                         const SwfdecAsValue *value);
int                 swfdec_as_value_to_integer          (SwfdecAsContext *context,
                                                         const SwfdecAsValue *value);
#define             SWFDEC_AS_VALUE_SET_INT             (val,d)
#define             SWFDEC_AS_VALUE_SET_NUMBER          (val,d)
#define             SWFDEC_AS_VALUE_GET_STRING          (val)
const char*         swfdec_as_value_to_string           (SwfdecAsContext *context,
                                                         const SwfdecAsValue *value);
#define             SWFDEC_AS_VALUE_SET_STRING          (val,s)
#define             SWFDEC_AS_VALUE_SET_NULL            (val)
#define             SWFDEC_AS_VALUE_GET_OBJECT          (val)
SwfdecAsObject*     swfdec_as_value_to_object           (SwfdecAsContext *context,
                                                         const SwfdecAsValue *value);
#define             SWFDEC_AS_VALUE_SET_OBJECT          (val,o)
void                swfdec_as_value_to_primitive        (SwfdecAsValue *value);
char*               swfdec_as_value_to_debug            (const SwfdecAsValue *value);
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_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;

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

SWFDEC_AS_TYPE_UNDEFINED

 the special undefined 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_NULL

 the spaecial null value

SWFDEC_AS_TYPE_OBJECT

 an object - must be of type SwfdecAsObject

SwfdecAsValue

typedef struct {
  SwfdecAsValueType	type;
} 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. 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.

SwfdecAsValueType type;

 the type of this value.

SWFDEC_AS_VALUE_SET_UNDEFINED()

#define SWFDEC_AS_VALUE_SET_UNDEFINED(val) (val)->type = SWFDEC_AS_TYPE_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_GET_BOOLEAN()

#define SWFDEC_AS_VALUE_GET_BOOLEAN(val) ((val)->value.boolean)

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,
                                                         const 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) ((val)->value.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_to_number ()

double              swfdec_as_value_to_number           (SwfdecAsContext *context,
                                                         const 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_to_integer ()

int                 swfdec_as_value_to_integer          (SwfdecAsContext *context,
                                                         const 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_SET_INT()

#define SWFDEC_AS_VALUE_SET_INT(val,d) SWFDEC_AS_VALUE_SET_NUMBER(val,(int) (d))

Sets val to the given value. Currently this macro is equivalent to SWFDEC_AS_VALUE_SET_NUMBER(), but this may change in future versions of Swfdec.

val :

 value to set

d :

 integer value to set

SWFDEC_AS_VALUE_SET_NUMBER()

#define             SWFDEC_AS_VALUE_SET_NUMBER(val,d)

Sets val to the given value. If you are sure the value is a valid integer value, use SWFDEC_AS_VALUE_SET_INT() instead.

val :

 value to set

d :

 double value to set

SWFDEC_AS_VALUE_GET_STRING()

#define SWFDEC_AS_VALUE_GET_STRING(val) ((val)->value.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,
                                                         const 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_SET_NULL()

#define SWFDEC_AS_VALUE_SET_NULL(val) (val)->type = SWFDEC_AS_TYPE_NULL

Sets val to the special null value.

val :

 value to set

SWFDEC_AS_VALUE_GET_OBJECT()

#define             SWFDEC_AS_VALUE_GET_OBJECT(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,
                                                         const 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 ()

void                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

swfdec_as_value_to_debug ()

char*               swfdec_as_value_to_debug            (const SwfdecAsValue *value);

Converts the given value to a string in a safe way. It will not call into the scripting engine. Its intended use is for output in debuggers.

value :

 a SwfdecAsValue

Returns :

 a newly allocated string. Free with g_free().

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
Generated by GTK-Doc V1.10