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-External Memory

Version:

rev: 1.44 date: 2021/05/26 07:51:04

user: cg

file: ExternalFunctionCallback.st directory: libbasic

module: stx stc-classLibrary: libbasic

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>

copyright
COPYRIGHT (c) 2007 by eXept Software AG
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

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: returnTypeIn argumentTypes: argumentTypesIn

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.

Usage example(s):

|cb| cb := self errorCallbackProcFor:[:a1 :a2 :a3 | Transcript showCR:('%1 %2 %3' bindWith:a1 with:a2 with:a3)]. ExternalFunctionCallback testCall:cb withArguments:#(#[1 2 3] 456 'hello'). cb release

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

(comment from inherited method)
remove all references to objects that may refer to self.
Subclasses may redefine this method but should do a 'super 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