C/Invoke Reference Documentation
To use C/Invoke in an application such as a language interpreter, include <cinvoke.h> in your source code, and link with the cinvoke.[a|lib] static library. No dynamic library is available at this time to avoid potential binary incompatibility issues should the API change in the future.
C/Invoke uses certain conventions throughout its API. All structures in C/Invoke are considered opaque; their members should never be accessed directly. Types are generally allocated on the heap with a *_create function, and each type allocated this way has a corresponding *_delete function. All functions return an error status indicator. This is usually in the form of a cinv_status_t code, which can be either CINV_SUCCESS (1) or CINV_ERROR (0). However, if a function returns a pointer, the function will return a NULL value to indicate errors, in order to avoid redundant parameters.
The C/Invoke API is broken down into several groups: contexts, libraries, functions, structures, and callbacks.
The cinv_context_* functions create, manipulate and destroy CInvContext* objects. A C/Invoke Context is an opaque data structure which is required for all C/Invoke functions to operate. You could consider a call to cinv_context_create as being analagous to initializing the library, except that this function returns a new value each time it is called, allowing the library to be thread-safe.
Contexts can be used to fetch the last error message and code associated with a failed function call.
The cinv_library_* functions provide a cross-platform method of loading shared libraries. A library once loaded can be used to load entrypoints (otherwise known as symbols or function pointers).
In C/Invoke, a Function object represents the information needed to call a C function, similar to a prototype in a header file. Once being created, a function can be passed to cinv_function_invoke, along with an entrypoint and the requisite parameters, to make a call through that entrypoint at runtime.
The cinv_structure_* functions provide a cross-platform interface for manipulating C structure values at runtime. After building a description of the members of a structure, instances of the structure can be allocated and its values set so that it can be passed as a parameter to an invoked function.
Some C library functions take function pointers as arguments, which they then "callback" at a later time. Using the cinv_callback_* functions, an object can be created which can be used to provide a function pointer for this purpose. Creating a callback requires a C/Invoke Function object for a description, as well as a pointer to a generic function which will be called in place of the "fake" callback.
For more detailed information, see the "Files" link above to browse the available functions in the API, or visit http://savannah.nongnu.org/projects/cinvoke for information on joining our mailing list.
Generated on Sun Jul 2 23:50:42 2006 for C/Invoke by
1.4.7