Creating native functions

## Creating native functions Creating native functions — C functions as first-class JavaScript objects |

## Synopsis

    #include <seed/seed.h>

    SeedValue           (*SeedFunctionCallback)             (SeedContext ctx,
                                                             SeedObject function,
                                                             SeedObject this_object,
                                                             gsize argument_count,
                                                             const SeedValue arguments[],
                                                             SeedException *exception);
    SeedObject          seed_make_function                  (SeedContext ctx,
                                                             SeedFunctionCallback func,
                                                             const gchar *name);
    void                seed_create_function                (SeedContext ctx,
                                                             gchar *name,
                                                             SeedFunctionCallback func,
                                                             SeedObject obj);

## Description

Exposing native C functions to JavaScript is one of the fundamental use cases for libseed when used in an embedding environment; if your application cannot be introspected, or you only have a small number of functions to expose, this is the simplest way to do that.

All native C callbacks should have the prototype of `SeedFunctionCallback()`.

Example 10. Simple C program which embeds Seed with one exposed function

    #include <glib.h>
    #include <seed.h>

    /* Our function, with the signature of SeedFunctionCallback(); say hello! */
    SeedValue hello_world(SeedContext ctx,
                          SeedObject function,
                          SeedObject this_object,
                          gsize argument_count,
                          const SeedValue arguments[],
                          SeedException *exception)
    {
        g_print("Hello, World!\n");
        return seed_make_null(ctx);
    }

    int main(gint argc, gchar ** argv)
    {
        SeedEngine * eng;

        /* Initialize the Seed engine */
        eng = seed_init(&argc, &argv);

        /* Expose a C function to JavaScript */
        seed_create_function(eng->context, "hello_world",
                             (SeedFunctionCallback)hello_world,
                             eng->global);

        /* Call the newly created JavaScript function */
        seed_simple_evaluate(eng->context, "hello_world()", NULL);

        return 0;
    }

## Details

### SeedFunctionCallback ()

    SeedValue           (*SeedFunctionCallback)             (SeedContext ctx,
                                                             SeedObject function,
                                                             SeedObject this_object,
                                                             gsize argument_count,
                                                             const SeedValue arguments[],
                                                             SeedException *exception);

All native C function callbacks should use the prototype of SeedFunctionCallback.

`ctx` : | A SeedContext
`function` : | The SeedObject representing the function
`this_object` : | The SeedObject representing the "this" object in the caller
`argument_count` : | The number of arguments passed into the callback
`arguments` : | An array of SeedValues; the value of the arguments passed in
`exception` : | A reference to a SeedException; use `seed_make_exception()` in order to throw a JavaScript exception from the callback.
Returns : | The SeedValue to return to the caller

### seed_make_function ()

    SeedObject          seed_make_function                  (SeedContext ctx,
                                                             SeedFunctionCallback func,
                                                             const gchar *name);

Creates a JavaScript object representing a first-class function; when the function is called from JavaScript, `func` will be called.

`ctx` : | A valid SeedContext
`func` : | A SeedFunctionCallback to implement the function.
`name` : | The name of the function (used in exceptions).
Returns : | A SeedObject representing the function

### seed_create_function ()

    void                seed_create_function                (SeedContext ctx,
                                                             gchar *name,
                                                             SeedFunctionCallback func,
                                                             SeedObject obj);

Creates a JavaScript object representing a first-class function; when the function is called from JavaScript, `func` will be called. Places the created function as the property `name` on `obj`.

`ctx` : | A valid SeedContext
`name` : | The name of the function (used in exceptions).
`func` : | A SeedFunctionCallback to implement the function.
`obj` : | The SeedObject on which to put the function.