Class: ExternalFunctionCallback

• Inheritance
• Description
• Class protocol
  • constants
  • helpers
  • instance creation
• Instance protocol
  • accessing
  • callback
  • generation
  • private-accessing
  • private-generation
  • private-releasing
• Examples

Inheritance:

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

Package:

stx:libbasic

Category:

System-Support

Version:

rev: 1.40 date: 2019/06/18 14:30:21

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:

 callTypeAPI

 callTypeC

 callTypeCDecl

 callTypeMASK

 callTypeOLE

 callTypeUNIX64

 closureIndexFor: aCallBack

 testCall: aCallback withArgument: arg

a simple test, if I can be called

 testCall: aCallback withArguments: args

a simple test, if I can be called

 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.

 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:

 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.

 beCallTypeAPI

 beCallTypeC

 beCallTypeOLE

 beCallTypeUNIX64

 beCallTypeWINAPI

 callTypeNumber

 isCallTypeAPI

 isCallTypeC

 isCallTypeOLE

 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)

 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

 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

 returnType: aReturnType argumentTypes: argTypes

see generateClosure for valid return types

 generateClosure

see failureCode and failureInfo for details

 release

Examples: