cinvoke.h File Reference

Main C/Invoke Header. More...

Go to the source code of this file.

Data Structures
struct	_CInvLibrary
struct	_CInvFunction
struct	_CInvStructMember
struct	_CInvStructure
struct	_CInvCallback
Typedefs
typedef _CInvLibrary	CInvLibrary
typedef _CInvFunction	CInvFunction
typedef void(*)	cinv_cbfunc_t (CInvFunction *f, void *parameters[], void *returnout, void *userdata)
	Function type which must be implemented when invoking interfaces which use callbacks.
typedef _CInvStructMember	CInvStructMember
typedef _CInvStructure	CInvStructure
typedef _CInvCallback	CInvCallback
Functions
CInvContext *	cinv_context_create ()
	Creates a new C/Invoke context.
const char *	cinv_context_geterrormsg (CInvContext *context)
	Gets the error message corresponding to the error which occurred when a C/Invoke function fails.
cinv_int32_t	cinv_context_geterrorcode (CInvContext *context)
	Gets the error code corresponding to the error which occurred when a C/Invoke function fails, or 0 if the last call succeeded.
cinv_status_t	cinv_context_delete (CInvContext *context)
	Deletes a C/Invoke context.
CInvLibrary *	cinv_library_create (CInvContext *context, const char *path)
	Loads a shared library and creates a library object.
void *	cinv_library_load_entrypoint (CInvContext *context, CInvLibrary *library, const char *name)
	Loads an entrypoint (function pointer) from a shared library.
cinv_status_t	cinv_library_delete (CInvContext *context, CInvLibrary *library)
	Deletes a library object.
CInvFunction *	cinv_function_create (CInvContext *context, cinv_callconv_t callingconvention, const char *returnformat, const char *parameterformat)
	Creates a function object, which descibes the prototype of a function which can be invoked.
cinv_status_t	cinv_function_invoke (CInvContext *context, CInvFunction *function, void *entrypoint, void *returnvalout, void *parameters[])
	Calls the entrypoint given using the prototype specified.
cinv_status_t	cinv_function_delete (CInvContext *context, CInvFunction *function)
	Deletes a function object.
CInvStructure *	cinv_structure_create (CInvContext *context)
	Creates a new structure description.
cinv_status_t	cinv_structure_addmember_value (CInvContext *context, CInvStructure *structure, const char *name, cinv_type_t type)
	Adds a simple type member to a structure description.
cinv_status_t	cinv_structure_addmember_struct (CInvContext *context, CInvStructure *structure, const char *name, CInvStructure *type)
	Adds a structure type member to a structure description.
cinv_status_t	cinv_structure_finish (CInvContext *context, CInvStructure *structure)
	Finishes a structure, completing its description.
cinv_status_t	cinv_structure_getsize (CInvContext *context, CInvStructure *structure, int *size_out)
	Returns the size, in bytes, of a structure.
void *	cinv_structure_create_instance (CInvContext *context, CInvStructure *structure)
	Allocates memory for a structure instance.
cinv_status_t	cinv_structure_instance_setvalue (CInvContext *context, CInvStructure *structure, void *instance, const char *name, void *value_ptr)
	Sets the value of a member inside of a structure.
void *	cinv_structure_instance_getvalue (CInvContext *context, CInvStructure *structure, void *instance, const char *name)
	Gets a pointer to the value of a member inside of a structure.
cinv_status_t	cinv_structure_delete_instance (CInvContext *context, void *instance)
	Frees the memory associated with a structure instance.
cinv_status_t	cinv_structure_delete (CInvContext *context, CInvStructure *structure)
	Deletes a structure description.
CInvCallback *	cinv_callback_create (CInvContext *context, CInvFunction *prototype, void *userdata, cinv_cbfunc_t cbfunc)
	Creates a callback object.
void *	cinv_callback_getentrypoint (CInvContext *context, CInvCallback *callback)
	Returns a function pointer which can be passed as a callback to a function being invoked.
cinv_status_t	cinv_callback_delete (CInvContext *context, CInvCallback *callback)
	Deletes a callback object.

---

Detailed Description

Main C/Invoke Header.

---

Typedef Documentation

typedef void(*) cinv_cbfunc_t(CInvFunction *f, void *parameters[], void *returnout, void *userdata)

Function type which must be implemented when invoking interfaces which use callbacks.

Parameters:

[in]	f	The function object which describes the prototype of the callback.
[in]	parameters	An array of pointers to the callback arguments.
[out]	returnout	A pointer to a value which should be set to the return value. Should be ignored if there is no return value.
[in]	userdata	A user-defined pointer to arbitrary data.

---

Function Documentation

CInvContext* cinv_context_create

(

)

Creates a new C/Invoke context.

Returns:

A new C/Invoke context object, or NULL if an error occurs.

const char* cinv_context_geterrormsg

(

CInvContext *

context

)

Gets the error message corresponding to the error which occurred when a C/Invoke function fails.

Parameters:

[in]

context

A C/Invoke context.

Returns:

An error message.

cinv_int32_t cinv_context_geterrorcode

(

CInvContext *

context

)

Gets the error code corresponding to the error which occurred when a C/Invoke function fails, or 0 if the last call succeeded.

The code returned will be platform-specific.

Parameters:

[in]

context

A C/Invoke context.

Returns:

An error code, or 0 if no error occurred.

cinv_status_t cinv_context_delete

(

CInvContext *

context

)

Deletes a C/Invoke context.

Parameters:

[in]

context

A C/Invoke context.

Returns:

A standard C/Invoke status code.

CInvLibrary* cinv_library_create	(	CInvContext *	context,
		const char *	path
	)

Loads a shared library and creates a library object.

Parameters:

[in]	context	A C/Invoke context.
[in]	path	A filesystem path to load. The semantics of how libraries are searched for are system-specific. For maximum portability, always specify a fully-qualified path.

Returns:

A new library object, or NULL if an error occurred.

void* cinv_library_load_entrypoint	(	CInvContext *	context,
		CInvLibrary *	library,
		const char *	name
	)

Loads an entrypoint (function pointer) from a shared library.

Parameters:

[in]	context	A C/Invoke context.
[in]	library	The library to load from.
[in]	name	The name of the symbol (function) to load.

Returns:

A pointer to the entrypoint, or NULL if an error occurred.

cinv_status_t cinv_library_delete	(	CInvContext *	context,
		CInvLibrary *	library
	)

Deletes a library object.

Parameters:

[in]	context	A C/Invoke context.
[in]	library	The library to delete.

Returns:

A standard C/Invoke status code.

CInvFunction* cinv_function_create	(	CInvContext *	context,
		cinv_callconv_t	callingconvention,
		const char *	returnformat,
		const char *	parameterformat
	)

Creates a function object, which descibes the prototype of a function which can be invoked.

Parameters:

[in]	context	A C/Invoke context.
[in]	callingconvention	A calling convention to use. The value CINV_CC_DEFAULT is aliased to the default calling convention for the current platform.
[in]	returnformat	A string containing a character type code, or an empty string for functions returning 'void'. See the parameterformat documentation below for a list of type codes.
[in]	parameterformat	A string containing zero or more characters, each character representing the type of a parameter to the function. The available type codes are: c - char type. s - short type. i - int type. l - long type. e - long long type. f - float type. d - double type. p - any pointer type. 2 - the integer type which uses 2 bytes on the current platform. 4 - the integer type which uses 4 bytes on the current platform. 8 - the integer type which uses 8 bytes on the current platform. Note that functions accepting or returning structures are not supported, only pointers to structures.

Example

A function with the following prototype:

 int myfunction(char *ptr, float f);

Could be captured using the following call:

 cinv_function_create(ctx, CINV_CC_DEFAULT, "i", "pf");

Returns:

A new function object, or NULL if an error occurred.

cinv_status_t cinv_function_invoke	(	CInvContext *	context,
		CInvFunction *	function,
		void *	entrypoint,
		void *	returnvalout,
		void *	parameters[]
	)

Calls the entrypoint given using the prototype specified.

Parameters:

[in]	context	A C/Invoke context.
[in]	function	The prototype of the function being called.
[in]	entrypoint	The function pointer to call through.
[out]	returnvalout	A pointer to the return value which will be set when the function is called. Can be NULL if the called function returns 'void'. The type of the pointer must match the return type and the memory must be allocated by the caller.
[in]	parameters	An array of pointers to the parameters of the function. Can be NULL if the function takes no parameters. Note that each parameter is passed via a pointer, so if the value being passed is for a pointer, place a pointer to the pointer in the array. The caller is responsible for allocating and de-allocating the memory for the parameters.

Returns:

A standard C/Invoke status code.

cinv_status_t cinv_function_delete	(	CInvContext *	context,
		CInvFunction *	function
	)

Deletes a function object.

Parameters:

[in]	context	A C/Invoke context.
[in]	function	The function to delete.

Returns:

A standard C/Invoke status code.

CInvStructure* cinv_structure_create

(

CInvContext *

context

)

Creates a new structure description.

Parameters:

[in]

context

A C/Invoke context.

Returns:

A new structure description object, or NULL if an error occurred.

cinv_status_t cinv_structure_addmember_value	(	CInvContext *	context,
		CInvStructure *	structure,
		const char *	name,
		cinv_type_t	type
	)

Adds a simple type member to a structure description.

Parameters:

[in]	context	A C/Invoke context.
[in]	structure	The structure description to add to.
[in]	name	The name of the member to add.
[in]	type	The type of the member to add.

Returns:

A standard C/Invoke status code.

cinv_status_t cinv_structure_addmember_struct	(	CInvContext *	context,
		CInvStructure *	structure,
		const char *	name,
		CInvStructure *	type
	)

Adds a structure type member to a structure description.

Note that this is distinct from adding a pointer to a structure, to do that one would call cinv_structure_addmember_value with a CINV_T_PTR argument.

Parameters:

[in]	context	A C/Invoke context.
[in]	structure	The structure description to add to.
[in]	name	The name of the member to add.
[in]	type	A structure description describing the type of the member to add. This description must be finished.

Returns:

A standard C/Invoke status code.

cinv_status_t cinv_structure_finish	(	CInvContext *	context,
		CInvStructure *	structure
	)

Finishes a structure, completing its description.

This function must be called before using the structure description object.

Parameters:

[in]	context	A C/Invoke context.
[in]	structure	The structure description to finish.

Returns:

A standard C/Invoke status code.

cinv_status_t cinv_structure_getsize	(	CInvContext *	context,
		CInvStructure *	structure,
		int *	size_out
	)

Returns the size, in bytes, of a structure.

Parameters:

[in]	context	A C/Invoke context.
[in]	structure	The structure description.
[out]	size_out	The number of bytes required to hold the structure in memory.

Returns:

A standard C/Invoke status code.

void* cinv_structure_create_instance	(	CInvContext *	context,
		CInvStructure *	structure
	)

Allocates memory for a structure instance.

Parameters:

[in]	context	A C/Invoke context.
[in]	structure	The structure description to allocate memory for.

Returns:

A pointer to memory which can hold the given structure.

cinv_status_t cinv_structure_instance_setvalue	(	CInvContext *	context,
		CInvStructure *	structure,
		void *	instance,
		const char *	name,
		void *	value_ptr
	)

Sets the value of a member inside of a structure.

Parameters:

[in]	context	A C/Invoke context.
[in]	structure	The structure description corresponding to the given instance.
[in]	instance	The structure instance to set the member value of.
[in]	name	The name of the member to set.
[in]	value_ptr	A pointer to the value to set. If the value being set is a pointer, you should pass a pointer to a pointer. If the value being set is an embedded structure, create a structure instance with cinv_structure_create_instance and pass the instance pointer.

Returns:

A standard C/Invoke status code.

void* cinv_structure_instance_getvalue	(	CInvContext *	context,
		CInvStructure *	structure,
		void *	instance,
		const char *	name
	)

Gets a pointer to the value of a member inside of a structure.

Parameters:

[in]	context	A C/Invoke context.
[in]	structure	The structure description corresponding to the given instance.
[in]	instance	The structure instance to get the member value from.
[in]	name	The name of the member to get.

Returns:

A pointer to the value, or NULL if an error occurred. If the value being returned is a pointer type, this will be a pointer to that pointer. If the value being returned is an embedded structure, this will be an instance pointer. In all cases, the pointer being returned is internal to the structure instance and does not need to be deallocated separately.

cinv_status_t cinv_structure_delete_instance	(	CInvContext *	context,
		void *	instance
	)

Frees the memory associated with a structure instance.

Parameters:

[in]	context	A C/Invoke context.
[in]	instance	The structure instance to delete.

Returns:

A standard C/Invoke status code.

cinv_status_t cinv_structure_delete	(	CInvContext *	context,
		CInvStructure *	structure
	)

Deletes a structure description.

Note that the descriptions of any embedded structure members are not deleted.

Parameters:

[in]	context	A C/Invoke context.
[in]	structure	The structure description to delete.

Returns:

A standard C/Invoke status code.

CInvCallback* cinv_callback_create	(	CInvContext *	context,
		CInvFunction *	prototype,
		void *	userdata,
		cinv_cbfunc_t	cbfunc
	)

Creates a callback object.

Parameters:

[in]	context	A C/Invoke context.
[in]	prototype	A function object which specifies the prototype of the callback.
[in]	userdata	A pointer which can be used to store user-defined data to be passed to the callback.
[in]	cbfunc	The function to forward calls to.

Returns:

A new callback object, or NULL if an error occurred.

void* cinv_callback_getentrypoint	(	CInvContext *	context,
		CInvCallback *	callback
	)

Returns a function pointer which can be passed as a callback to a function being invoked.

Parameters:

[in]	context	A C/Invoke context.
[in]	callback	A callback object.

Returns:

A function pointer.

cinv_status_t cinv_callback_delete	(	CInvContext *	context,
		CInvCallback *	callback
	)

Deletes a callback object.

Parameters:

[in]	context	A C/Invoke context.
[in]	callback	A callback object.

Returns:

A standard C/Invoke status code.

---