previous
index
next

Dyncallback C library API

This library extends dyncall with function callback support, allowing the user to dynamically create a callback object that can be called directly, or passed to functions expecting a function-pointer as argument.

Invoking a dyncallback calls into a user-defined unified handler that permits iteration and thus dynamic handling over the called-back-function’s parameters.

The flexibility is constrained by the set of supported types, though.

For style conventions and supported types, see dyncall API section. In order to use dyncallback, include "dyncall_callback.h".

Callback Object

The Callback Object is the core component to this library. Types

typedef struct DCCallback DCCallback;
Details

The Callback Object is an object that mimics a fully typed function call to another function (a generic callback handler, in this case).

This means, a pointer to this object is passed to a function accepting a pointer to a callback function as the very callback function pointer itself . Or, if called directly, cast a pointer to this object to a function pointer and issue a call.

Allocation

Functions
DCCallback* dcbNewCallback(const char*        signature, 
                           DCCallbackHandler* funcptr, 
                           void*              userdata); 
void dcbFreeCallback(DCCallback* pcb);

dcbNewCallback creates and initializes a new Callback object, where signature is the needed function signature (format is the one outlined in the language bindings-section of this manual, see Table 2) of the function to mimic, funcptr is a pointer to a callback handler, and userdata a pointer to custom data that might be useful in the handler. Use dcbFreeCallback to destroy the Callback object.

As with dcNewCallVM/dcFree, this will allocate memory using the system allocators or custom overrides.

Callback handler

The unified callback handler’s declaration used when creating a DCCallback is:

char cbHandler(DCCallback* cb, 
               DCArgs*     args, 
               DCValue*    result, 
               void*       userdata);

cb is a pointer to the DCCallback object in use, args allows for dynamic iteration over the called-back-function’s arguments (input) and result is a pointer to a DCValue object in order to store the callback’s return value (output, to be set by handler).
Finally, userdata is a pointer to some user defined data that can be set when creating the callback object. The handler itself returns a signature character (see Table 2) specifying the data type used for result.


previous
index
next