Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
dyncallback(3)		 BSD Library Functions Manual		dyncallback(3)

NAME
     dyncallback -- callback interface of dyncall

SYNOPSIS
     #include <dyncall_callback.h>

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

     void
     dcbInitCallback(DCCallback	* pcb, const char * signature,
	 DCCallbackHandler * funcptr, void * userdata);

     void
     dcbFreeCallback(DCCallback	* pcb);

     void
     dcbGetUserData(DCCallback * pcb);

DESCRIPTION
     The dyncallback dyncall library has an interface to create	callback ob-
     jects, that can be	passed to functions as callback	arguments. In other
     words, a pointer to the callback object can be "called", directly.	The
     callback handler then allows iterating dynamically	over the arguments
     once called back.

     dcbNewCallback() creates a	new callback object, where signature is	a sig-
     nature string describing the function to be called	back (see manual for
     format). This is needed for dyncallback dyncallback to correctly prepare
     the arguments passed in by	the function that calls	the callback handler.
     Note that the handler doesn't return the value specified in the signa-
     ture, directly, but simply	'i' or 'f' depending on	whether	it is a	inte-
     gral or floating point type. The return value itself is stored where the
     handler's 3rd parameter points to (see example).  funcptr is a pointer to
     the dyncallback dyncallback callback handler (see below), and userdata a
     pointer to	arbitrary user data you	want to	use in the callback handler.
     Use the returned pointer as callback argument in functions	requiring a
     callback function pointer.

     dcbInitCallback() (re)initialize the callback object.

     dcbFreeCallback() destroys	and frees the callback handler.

     dcbGetUserData() returns a	pointer	to the userdata	passed to the callback
     object on creation	or initialization.

     Declaration of a dyncallback handler (following function pointer defini-
     tion in dyncallback/dyncall_callback.h):

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

     cb	is a pointer to	the DCCallback object in use dyncallback 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 manual for format)
     specifying	the data type used for result.

EXAMPLE
     Let's say,	we want	to create a callback object and	call it. For simplic-
     ity, this example will omit passing it as a function pointer to a func-
     tion (e.g.	compar in qsort(), etc.) and demonstrate calling it, directly.
     First, we need to define our callback handler - the following handler il-
     lustrates how to access the passed- in arguments:

	   char	cbHandler(DCCallback* cb,
			  DCArgs*     args,
			  DCValue*    result,
			  void*	      userdata)
	   {
	     int* ud = (int*)userdata;
	     int       arg1 = dcbArgInt	    (args);
	     float     arg2 = dcbArgFloat   (args);
	     short     arg3 = dcbArgShort   (args);
	     double    arg4 = dcbArgDouble  (args);
	     long long arg5 = dcbArgLongLong(args);

	     //	.. do something	..

	     result->s = 1244;
	     return 'i';
	   }

     Note that the return value	of the handler is a signature character, not
     the actual	return value, itself, and note that the	actual return value is
     of	type short.  Now, let's	call it	through	a DCCallback object:

	     DCCallback* cb;
	     short result = 0;
	     int userdata = 1337;
	     cb	= dcbNewCallback("ifsdl)s", &cbHandler,	&userdata);
	     result = ((short(*)(int, float, short, double, long long))cb)
	       (123, 23.f, 3, 1.82, 9909ll);
	     dcbFreeCallback(cb);

SEE ALSO
     dyncall(3), dynload(3) and	the dyncall manual (available in PDF format)
     for a way more detailed documentation of this library.

AUTHORS
     Daniel Adler <dadler@uni-goettingen.de>
     Tassilo Philipp <tphilipp@potion-studios.com>

BSD				April 10, 2020				   BSD

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dyncallback&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help