eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ExternalFunctionCallback':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: ExternalFunctionCallback


Inheritance:

   Object
   |
   +--ExecutableFunction
      |
      +--ExternalFunction
         |
         +--ExternalFunctionCallback

Package:
stx:libbasic
Category:
System-Support
Version:
rev: 1.32 date: 2018/02/19 16:29:54
user: cg
file: ExternalFunctionCallback.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


an ExternalFunctionCallback wraps a block into a C-callable function;
i.e. it creates a closure, which as seen from C-code looks like an ordinary
function pointer, but when invoked evaluates a smalltalk block.

A callback is created with:
   cb := ExternalFunctionCallback new.
the arguments (as passed from the C-caller into ST)
and the returnValue (from ST to the C-caller) are specified with:
   cb returnType:#bool argumentTypes:#(uint).
Then, the code is generated with:
   cb generateClosure.

After that, the callBack-functions address can be acquired with:
   cb address.  'can be passed to C'.
and handed out to C. (you can also hand out the callBack directly - as it is a subclass of
ExternalBytes.
The actual action of the callback can be changed (at any time later) with:
    cb action:[:args | Transcript showCR:args. true].

Eventually, the callback MUST be released:
    cb release.

[supported returnTypes:]
    int
    uint
    uint8
    uint16
    uint32
    uint64
    sint
    sint8
    sint16
    sint32
    sint64
    long    system dependent sint32 or sint64
    ulong   system dependent uint32 or uint64

    bool
    float
    double
    void

    pointer, 
    handle, 
    charPointer, 
    bytePointer, 
    floatPointer
    doublePointer
    intPointer
    shortPointer
    wcharPointer

    <name of subclass of ExternalAddress>

[supported argumentTypes:]
    handle
    pointer
    voidPointer

    long, ulong - system dependent

    int, 
    uint8, sint8, uint16, sint16,
    uint32, sint32,
    float, double
    void

    charPointer, floatPointer, doublePointer,

    <name of subclass of ExternalAddress>


Class protocol:

constants
o  callTypeAPI

o  callTypeC

o  callTypeCDecl

o  callTypeMASK

o  callTypeOLE

o  callTypeUNIX64

helpers
o  closureIndexFor: aCallBack

o  testCall: aCallback withArgument: arg
a simple test, if I can be called

o  testCall: aCallback withArguments: args
a simple test, if I can be called

instance creation
o  callbackFor: aBlock returnType: returnType argumentTypes: argumentTypes
generate a callback for the ErrorCallbackProc signature:
ErrorCallbackProc(HWND hWnd, int nErrID, LPTSTR lpErrorText)
which, can be given to an external API call and which invokes the
three arg block when clled.
Do not forget to eventually release the callback to avoid a memory leak.

o  errorCallbackProcFor: aThreeArgBlock
generate a callback for the ErrorCallbackProc signature:
ErrorCallbackProc(HWND hWnd, int nErrID, LPTSTR lpErrorText)
which, can be given to an external API call and which invokes the
three arg block when clled.
Do not forget to eventually release the callback to avoid a memory leak.


Instance protocol:

accessing
o  action: aBlock
set the action-block, to be evaluated when C calls me.
The C-arguments will be passed as arguments to the block.
The value returned by the block will be returned to the C-caller.

o  beCallTypeAPI

o  beCallTypeC

o  beCallTypeOLE

o  beCallTypeUNIX64

o  beCallTypeWINAPI

o  callTypeNumber

o  isCallTypeAPI

o  isCallTypeC

o  isCallTypeOLE

callback
o  callFromCWith: argList
invoked by the C-code, to which we have given out the code-ptr.
Because this is evaluated from C, we probably should not block or abort or do
any other things which confuse C
(its probably a good idea to write something into a queue here)

generation
o  code
(comment from inherited method)
return the code field. This is not an object but the address of the machine instructions.
Therefore an externalAddress representing the code-address is returned

o  getCode
(comment from inherited method)
return the code field. This is not an object but the address of the machine instructions.
Therefore an externalAddress representing the code-address is returned

private-accessing
o  returnType: aReturnType argumentTypes: argTypes
see generateClosure for valid return types

private-generation
o  generateClosure
see failureCode and failureInfo for details

private-releasing
o  release


Examples:


|cb| cb := ExternalFunctionCallback new. cb returnType:#bool argumentTypes:#(uint). cb beCallTypeWINAPI. cb generateClosure. cb action:[:args | Transcript showCR:args. true]. cb code. 'address can be passed to C'. Transcript showCR:cb code. ExternalFunctionCallback testCall:cb withArgument:123. cb action:[:args | Transcript show:'hello '; showCR:args. true]. ExternalFunctionCallback testCall:cb withArgument:123. cb release

ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Sun, 23 Sep 2018 10:27:24 GMT