view release on metacpan or  search on metacpan

dyncall/dyncallback/dyncallback.3  view on Meta::CPAN

.Ft DCint
.Fn dcbArgInt "DCArgs * p"
.Ft DClong
.Fn dcbArgLong "DCArgs * p"
.Ft DClonglong
.Fn dcbArgLongLong "DCArgs * p"
.Ft DCuchar
.Fn dcbArgUChar "DCArgs * p"
.Ft DCushort
.Fn dcbArgUShort "DCArgs * p"
.Ft DCuint
.Fn dcbArgUInt "DCArgs * p"
.Ft DCulong
.Fn dcbArgULong "DCArgs * p"
.Ft DCulonglong
.Fn dcbArgULongLong "DCArgs * p"
.Ft DCfloat
.Fn dcbArgFloat "DCArgs * p"
.Ft DCdouble
.Fn dcbArgDouble "DCArgs * p"
.Ft DCpointer
.Fn dcbArgPointer "DCArgs * p"
.Ft DCpointer
.Fn dcbArgAggr "DCArgs * p" "DCpointer target"
.Ft void
.Fn dcbReturnAggr "DCArgs * args" "DCValue * result" "DCpointer ret"
.Sh DESCRIPTION
The
.Nm
dyncall library has an interface to create callback objects, that can be passed
to functions as callback function pointers. In other words, a pointer to the
callback object can be "called", directly. A generic callback handler invoked
by this object then allows iterating dynamically over the arguments once called
back.
.Pp
.Fn dcbNewCallback2
creates a new callback object, where
.Ar signature
is a signature string describing the function to be called back (see manual or
dyncall_signature.h for format), and
.Ar funcptr
is a pointer to a generic callback handler (see below). The signature is needed
in the generic callback handler to correctly retrieve the arguments provided by
the caller of the callback. Note that the generic handler's function
type/declaration is always the same for any callback.
.Ar userdata
is a pointer to arbitrary user data to be available in the generic callback
handler. If the callback expects aggregates (struct, union) to be passed or
returned by value, a pointer to an array of DCaggr* descriptions must be
provided (exactly one per aggregate, in the same order as in the signature) via
the
.Ar aggrs
parameter, otherwise pass NULL. This pointer must point to valid data during
callback.
.Pp
.Fn dcbNewCallback
is the same as
.Fn dcbNewCallback2 ,
with an implicit NULL passed via the
.Ar aggrs
parameter, meaning it can only be used for callbacks that do not use any
aggregate by value.
.Pp
.Em NOTE :
C++ non-trivial aggregates (check with the std::is_trivial type trait) do not
use aggregate descriptions, so the respective pointers in the provided array
must be NULL. See
.Xr dyncall 3
for more information on C++ non-trivial aggregates.
.Pp
Use the pointer returned by
.Fn dcbNewCallback*
as argument in functions requiring a callback function pointer.
.Pp
.Fn dcbInitCallback
and
.Fn dcbInitCallback2
(re)initialize the callback object. For a description of their parameters, see
.Fn dcbNewCallback* .
.Pp
.Fn dcbFreeCallback
destroys and frees the callback handler.
.Pp
.Fn dcbGetUserData
returns a pointer to the userdata passed to the callback object on creation or
(re)initialization.
.Pp
Declaration of a dyncallback handler (following function pointer declaration in
dyncall_callback.h):
.Bd -literal -offset indent
DCsigchar cbHandler(DCCallback* cb,
                    DCArgs*     args,
                    DCValue*    result,
                    void*       userdata);
.Ed
.Pp
.Ar cb
is a pointer to the DCCallback object in use,
.Ar args
is to be used with the
.Fn dcbArg*
functions to iterate over the arguments passed to the callback, and
.Ar result
is a pointer to an object used to store the callback's return value (output, to
be set by the handler). Finally,
.Ar userdata
is the user defined data pointer set when creating or (re)initializing the
callback object.
The handler itself must return a signature character (see manual or
dyncall_signature.h for format) specifying the data type of
.Ar result .
.Pp
Retrieving aggregates by value from the generic handler's
.Ar args
argument can be done via
.Fn dcbArgAggr ,
where
.Ar target
must point to memory large enough for the aggregate to be copied to,
.Em iff
the aggregate is trivial (see below for non-trivial C++ aggregates), in which case