Mercurial > pub > dyncall > dyncall
annotate dyncallback/dyncallback.3 @ 357:d982a00c2177
- PPC64 asm syntax fix, specifying explicitly comparison mode for cmpi (newer toolchains complain, older ones took optional field of instruction which happened to be same value)
| author | Tassilo Philipp |
|---|---|
| date | Tue, 25 Feb 2020 18:16:13 +0100 |
| parents | 7cb8a0aaf638 |
| children | e2899b4ff713 |
| rev | line source |
|---|---|
| 0 | 1 .\" Copyright (c) 2007-2014 Daniel Adler <dadler AT uni-goettingen DOT de>, |
| 2 .\" Tassilo Philipp <tphilipp AT potion-studios DOT com> | |
| 3 .\" | |
| 4 .\" Permission to use, copy, modify, and distribute this software for any | |
| 5 .\" purpose with or without fee is hereby granted, provided that the above | |
| 6 .\" copyright notice and this permission notice appear in all copies. | |
| 7 .\" | |
| 8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
| 9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
| 10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
| 11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
| 12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
| 13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
| 14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
| 15 .\" | |
| 16 .Dd $Mdocdate$ | |
| 17 .Dt dyncallback 3 | |
| 18 .Sh NAME | |
| 19 .Nm dyncallback | |
| 20 .Nd callback interface of dyncall | |
| 21 .Sh SYNOPSIS | |
| 22 .In dyncall_callback.h | |
| 23 .Ft DCCallback * | |
| 24 .Fn dcbNewCallback "const char * signature" "DCCallbackHandler * funcptr" "void * userdata" | |
| 25 .Ft void | |
| 26 .Fn dcbInitCallback "DCCallback * pcb" "const char * signature" "DCCallbackHandler * funcptr" "void * userdata" | |
| 27 .Ft void | |
| 28 .Fn dcbFreeCallback "DCCallback * pcb" | |
| 29 .Ft void | |
| 30 .Fn dcbGetUserData "DCCallback * pcb" | |
| 31 .Sh DESCRIPTION | |
| 32 The | |
| 33 .Nm | |
| 34 dyncall library has an interface to create callback objects, that can be passed | |
| 35 to functions as callback arguments. In other words, a pointer to the callback | |
| 36 object can be "called", directly. The callback handler then allows iterating | |
| 37 dynamically over the arguments once called back. | |
| 38 .Pp | |
| 39 .Fn dcbNewCallback | |
| 40 creates a new callback object, where | |
| 41 .Ar signature | |
|
96
95f67e67feb0
- updated dyncallback.3, blurb about handler's retval signature character was outdated
cslag
parents:
93
diff
changeset
|
42 is a signature string describing the function to be called back (see manual or |
|
95f67e67feb0
- updated dyncallback.3, blurb about handler's retval signature character was outdated
cslag
parents:
93
diff
changeset
|
43 dyncall_signature.h for format). This is needed for |
| 0 | 44 .Nm |
| 45 dyncallback to correctly prepare the arguments passed in by the function that | |
| 46 calls the callback handler. Note that the handler doesn't return the value | |
|
96
95f67e67feb0
- updated dyncallback.3, blurb about handler's retval signature character was outdated
cslag
parents:
93
diff
changeset
|
47 specified in the signature, directly, but a signature character, specifying the |
|
95f67e67feb0
- updated dyncallback.3, blurb about handler's retval signature character was outdated
cslag
parents:
93
diff
changeset
|
48 return value's type. |
|
95f67e67feb0
- updated dyncallback.3, blurb about handler's retval signature character was outdated
cslag
parents:
93
diff
changeset
|
49 The return value itself is stored where the handler's |
|
95f67e67feb0
- updated dyncallback.3, blurb about handler's retval signature character was outdated
cslag
parents:
93
diff
changeset
|
50 3rd parameter points to (see below). |
| 0 | 51 .Ar funcptr |
| 52 is a pointer to the | |
| 53 .Nm | |
| 54 dyncallback callback handler (see below), and | |
| 55 .Ar userdata | |
| 56 a pointer to arbitrary user data you want to use in the callback handler. | |
| 57 Use the returned pointer as callback argument in functions requiring a callback | |
| 58 function pointer. | |
| 59 .Pp | |
| 60 .Fn dcbInitCallback | |
| 61 (re)initialize the callback object. | |
| 62 .Pp | |
| 63 .Fn dcbFreeCallback | |
| 64 destroys and frees the callback handler. | |
| 65 .Pp | |
| 66 .Fn dcbGetUserData | |
| 67 returns a pointer to the userdata passed to the callback object on creation or | |
| 68 initialization. | |
| 69 .Pp | |
| 70 Declaration of a dyncallback handler (following function pointer definition in | |
| 71 dyncallback/dyncall_callback.h): | |
| 72 .Bd -literal -offset indent | |
| 73 char cbHandler(DCCallback* cb, | |
| 74 DCArgs* args, | |
| 75 DCValue* result, | |
| 76 void* userdata); | |
| 77 .Ed | |
| 78 .Pp | |
| 79 .Ar cb is a pointer to the DCCallback object in use | |
| 80 .Nm | |
| 81 result is a pointer to a DCValue object in order to store the callback's | |
| 82 return value (output, to be set by handler). Finally, | |
| 83 .Ar userdata is a pointer to some user defined data that can be | |
| 84 set when creating the callback object. | |
| 85 The handler itself returns a signature character (see manual for format) | |
| 86 specifying the data type used for | |
| 87 .Ar result . | |
| 88 .Sh EXAMPLE | |
| 89 Let's say, we want to create a callback object and call it. For simplicity, this | |
| 90 example will omit passing it as a function pointer to a function (e.g. compar | |
| 91 in qsort(), etc.) and demonstrate calling it, directly. First, we need to define | |
| 92 our callback handler - the following handler illustrates how to access the passed- | |
| 93 in arguments: | |
| 94 .Bd -literal -offset indent | |
| 95 char cbHandler(DCCallback* cb, | |
| 96 DCArgs* args, | |
| 97 DCValue* result, | |
| 98 void* userdata) | |
| 99 { | |
| 100 int* ud = (int*)userdata; | |
| 101 int arg1 = dcbArgInt (args); | |
| 102 float arg2 = dcbArgFloat (args); | |
| 103 short arg3 = dcbArgShort (args); | |
| 104 double arg4 = dcbArgDouble (args); | |
| 105 long long arg5 = dcbArgLongLong(args); | |
| 106 | |
| 107 // .. do something .. | |
| 108 | |
| 109 result->s = 1244; | |
|
96
95f67e67feb0
- updated dyncallback.3, blurb about handler's retval signature character was outdated
cslag
parents:
93
diff
changeset
|
110 return 's'; |
| 0 | 111 } |
| 112 .Ed | |
| 113 .Pp | |
| 114 Note that the return value of the handler is a signature character, not the | |
|
96
95f67e67feb0
- updated dyncallback.3, blurb about handler's retval signature character was outdated
cslag
parents:
93
diff
changeset
|
115 actual return value, itself. |
| 0 | 116 Now, let's call it through a DCCallback object: |
| 117 .Bd -literal -offset indent | |
| 118 DCCallback* cb; | |
| 119 short result = 0; | |
| 120 int userdata = 1337; | |
| 121 cb = dcbNewCallback("ifsdl)s", &cbHandler, &userdata); | |
| 122 result = ((short(*)(int, float, short, double, long long))cb) | |
| 123 (123, 23.f, 3, 1.82, 9909ll); | |
| 124 dcbFreeCallback(cb); | |
| 125 .Ed | |
|
250
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
96
diff
changeset
|
126 .Sh CONFORMING TO |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
96
diff
changeset
|
127 The dyncallback library needs at least a c99 compiler with additional support |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
96
diff
changeset
|
128 for anonymous structs/unions (which were introduced officially in c11). Given |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
96
diff
changeset
|
129 that those are generally supported by pretty much all major c99 conforming |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
96
diff
changeset
|
130 compilers (as default extension), it should build fine with a c99 toolchain. |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
96
diff
changeset
|
131 Strictly speaking, dyncall conforms to c11, though. |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
96
diff
changeset
|
132 .Ed |
| 0 | 133 .Sh SEE ALSO |
| 134 .Xr dyncall 3 , | |
| 135 .Xr dynload 3 | |
| 93 | 136 and the dyncall manual (available in HTML and PDF format) for more information. |
| 0 | 137 .Sh AUTHORS |
| 138 .An "Daniel Adler" Aq dadler@uni-goettingen.de | |
| 139 .An "Tassilo Philipp" Aq tphilipp@potion-studios.com |