SwfdecAsFunction

## SwfdecAsFunction SwfdecAsFunction — script objects that can be executed |

## Synopsis

    #include <swfdec/swfdec.h>

                        SwfdecAsFunction;
    void                (*SwfdecAsNative)                   (SwfdecAsContext *context,
                                                             SwfdecAsObject *thisp,
                                                             guint argc,
                                                             SwfdecAsValue *argv,
                                                             SwfdecAsValue *retval);
                        SwfdecAsNativeFunction;
    #define             swfdec_as_function_call             (function, thisp, n_args, args, return_value)
    void                swfdec_as_function_call_full        (SwfdecAsFunction *function,
                                                             SwfdecAsObject *thisp,
                                                             gboolean construct,
                                                             SwfdecAsObject *super_reference,
                                                             guint n_args,
                                                             const SwfdecAsValue *args,
                                                             SwfdecAsValue *return_value);
    SwfdecAsFunction*   swfdec_as_native_function_new       (SwfdecAsContext *context,
                                                             const char *name,
                                                             SwfdecAsNative native,
                                                             SwfdecAsObject *prototype);
    void                swfdec_as_native_function_set_construct_type
                                                            (SwfdecAsNativeFunction *function,
                                                             GType type);
    gboolean            swfdec_as_native_function_check     (SwfdecAsContext *cx,
                                                             SwfdecAsObject *object,
                                                             GType type,
                                                             gpointer *result,
                                                             guint argc,
                                                             SwfdecAsValue *argv,
                                                             const char *args,
                                                             ...);
    gboolean            swfdec_as_native_function_checkv    (SwfdecAsContext *cx,
                                                             SwfdecAsObject *object,
                                                             GType type,
                                                             gpointer *result,
                                                             guint argc,
                                                             SwfdecAsValue *argv,
                                                             const char *args,
                                                             va_list varargs);
    #define             SWFDEC_AS_CHECK                     (type,result,...)

## Object Hierarchy

      GObject
       +----SwfdecGcObject
             +----SwfdecAsObject
                   +----SwfdecAsFunction
                         +----SwfdecAsNativeFunction

      GObject
       +----SwfdecGcObject
             +----SwfdecAsObject
                   +----SwfdecAsFunction
                         +----SwfdecAsNativeFunction

## Description

Functions is the basic object for executing code in the Swfdec script engine. There is multiple different variants of functions, such as script-created ones and native functions.

If you want to create your own functions, you should create native functions. The easiest way to do this is with `swfdec_as_object_add_function()` or `swfdec_as_native_function_new()`.

In Actionscript, every function can be used as a constructor. If you want to make a native function be used as a constructor for your own SwfdecAsObject subclass, have a look at `swfdec_as_native_function_set_construct_type()`.

## Details

### SwfdecAsFunction

    typedef struct _SwfdecAsFunction SwfdecAsFunction;

This is the base executable object in Swfdec. It is an abstract object. If you want to create functions yourself, use SwfdecAsNativeFunction.

### SwfdecAsNative ()

    void                (*SwfdecAsNative)                   (SwfdecAsContext *context,
                                                             SwfdecAsObject *thisp,
                                                             guint argc,
                                                             SwfdecAsValue *argv,
                                                             SwfdecAsValue *retval);

This is the prototype for all native functions.

`context` : | SwfdecAsContext
`thisp` : | the this object. ### Warning Can be `NULL`.
`argc` : | number of arguments passed to this function
`argv` : | the `argc` arguments passed to this function
`retval` : | set to the return value. Initialized to undefined by default

### SwfdecAsNativeFunction

    typedef struct _SwfdecAsNativeFunction SwfdecAsNativeFunction;

This is the object type for native functions.

### swfdec_as_function_call()

    #define             swfdec_as_function_call(function, thisp, n_args, args, return_value)

Calls the given function. This is a macro that resolves to `swfdec_as_function_call_full()`.

`function` : | the SwfdecAsFunction to call
`thisp` : | this argument to use for the call or `NULL` for none
`n_args` : | number of arguments to pass to the function
`args` : | the arguments to pass or `NULL` to read the last `n_args` stack elements.
`return_value` : | pointer for return value or `NULL` to push the return value to the stack

### swfdec_as_function_call_full ()

    void                swfdec_as_function_call_full        (SwfdecAsFunction *function,
                                                             SwfdecAsObject *thisp,
                                                             gboolean construct,
                                                             SwfdecAsObject *super_reference,
                                                             guint n_args,
                                                             const SwfdecAsValue *args,
                                                             SwfdecAsValue *return_value);

Calls the given function.

`function` : | the SwfdecAsFunction to call
`thisp` : | this argument to use for the call or `NULL` for none
`construct` : | call this function as a constructor. This is only relevant for native functions.
`super_reference` : | The object to be referenced by the super object in this function call or `NULL` to use the default.
`n_args` : | number of arguments to pass to the function
`args` : | the arguments to pass or `NULL` to read the last `n_args` stack elements.
`return_value` : | pointer for return value or `NULL` to push the return value to the stack

### swfdec_as_native_function_new ()

    SwfdecAsFunction*   swfdec_as_native_function_new       (SwfdecAsContext *context,
                                                             const char *name,
                                                             SwfdecAsNative native,
                                                             SwfdecAsObject *prototype);

Creates a new native function, that will execute `native` when called. You might want to use `swfdec_as_object_add_function()` instead of this function.

`context` : | a SwfdecAsContext
`name` : | name of the function
`native` : | function to call when executed
`prototype` : | The object to be used as "prototype" property for the created function or `NULL` for none.
Returns : | a new SwfdecAsFunction

### swfdec_as_native_function_set_construct_type ()

    void                swfdec_as_native_function_set_construct_type
                                                            (SwfdecAsNativeFunction *function,
                                                             GType type);

Sets the `type` to be used when using `function` as a constructor. If this is not set, using `function` as a constructor will create a SwfdecAsObject.

`function` : | a SwfdecAsNativeFunction
`type` : | GType used when constructing an object with `function`

### swfdec_as_native_function_check ()

    gboolean            swfdec_as_native_function_check     (SwfdecAsContext *cx,
                                                             SwfdecAsObject *object,
                                                             GType type,
                                                             gpointer *result,
                                                             guint argc,
                                                             SwfdecAsValue *argv,
                                                             const char *args,
                                                             ...);

This function is a convenience function to validate and convert arguments to a native function while avoiding common pitfalls. You typically want to call it at the beginning of every native function you write. Or you can use the `SWFDEC_AS_CHECK()` macro instead which calls this function. The `cx`, `object`, `argc` and `argv` paramters should be passed verbatim from the function call to your native function. If `type` is not 0, `object` is then checked to be of that type and cast to `result`. After that the `args` string is used to convert the arguments. Every character in `args` describes the conversion of one argument. For that argument, you have to pass a pointer that takes the value. For the conversion, the default conversion functions like `swfdec_as_value_to_string()` are used. If not enough arguments are available, the function stops converting and returns `NULL`. The following conversion characters are allowed:

- "b": convert to boolean. Requires a `gboolean` pointer

- "i": convert to integer. Requires an `integer` pointer

- "n": convert to number. Requires a `double` pointer

- "o": convert to object. Requires a SwfdecAsObject pointer. If the conversion fails, this function immediately returns `FALSE`.

- "O": convert to object or `NULL`. Requires a SwfdecAsObject pointer.

- "s": convert to garbage-collected string. Requires a const `char` pointer

- "v": copy the value. The given argument must be a pointer to a SwfdecAsValue

- "|": optional arguments follow. Optional arguments will be initialized to the empty value for their type. This conversion character is only allowed once in the conversion string.

`cx` : | a SwfdecAsContext
`object` : | this object passed to the native function
`type` : | expected type of `object` or 0 for any
`result` : | pointer to variable taking cast result of `object`
`argc` : | count of arguments passed to the function
`argv` : | arguments passed to the function
`args` : | argument conversion string
`...` : | pointers to variables taking converted arguments
Returns : | `TRUE` if the conversion succeeded, `FALSE` otherwise

### swfdec_as_native_function_checkv ()

    gboolean            swfdec_as_native_function_checkv    (SwfdecAsContext *cx,
                                                             SwfdecAsObject *object,
                                                             GType type,
                                                             gpointer *result,
                                                             guint argc,
                                                             SwfdecAsValue *argv,
                                                             const char *args,
                                                             va_list varargs);

This is the valist version of `swfdec_as_native_function_check()`. See that function for details.

`cx` : | a SwfdecAsContext
`object` : | this object passed to the native function
`type` : | expected type of `object`
`result` : | pointer to variable taking cast result of `object`
`argc` : | count of arguments passed to the function
`argv` : | arguments passed to the function
`args` : | argument conversion string
`varargs` : | pointers to variables taking converted arguments
Returns : | `TRUE` if the conversion succeeded, `FALSE` otherwise

### SWFDEC_AS_CHECK()

    #define             SWFDEC_AS_CHECK(type,result,...)

This is a shortcut macro for calling `swfdec_as_native_function_check()` at the beginning of a native function. See that function for details. It requires the native function parameters to have the default name. So your function must be declared like this:

    static void
    my_function (SwfdecAsContext *cx, SwfdecAsObject *object,
        guint argc, SwfdecAsValue *argv, SwfdecAsValue *rval);

`type` : | required type of this object or 0 for ignoring
`result` : | converted this object
`...` : | conversion string and pointers taking converted values