Class: ExternalLibraryFunction

• Inheritance
• Description
• Class protocol
  • class initialization
  • constants
  • instance creation
• Instance protocol
  • accessing
  • invoking
  • printing
  • private
  • private-accessing
  • private-invoking
  • testing

Inheritance:

   Object
   |
   +--ExecutableFunction
      |
      +--ExternalFunction
         |
         +--ExternalLibraryFunction

Package:

stx:libbasic

Category:

System-Support

Version:

rev: 1.78 date: 2010/02/02 15:44:48

user: cg

file: ExternalLibraryFunction.st directory: libbasic

module: stx stc-classLibrary: libbasic

Description:

instances of me are used to interface to external library functions (as found in a dll/shared object).

Inside a method, when a special external-call pragma such as:
    <api: bool MessageBeep(uint)>

is encountered by the parser, the compiler generates a call via
    <correspondingExternalLibraryFunctionObject> invokeWithArguments: argumentArray.

In the invoke method, the library is checked to be loaded (and loaded if not already),
the arguments are converted to C and pushed onto the C-stack, the function is called,
and finally, the return value is converted back from C to a smalltalk object.

The parser supports the call-syntax of various other smalltalk dialects:
    Squeak / ST-X:
        <cdecl:   [async] [virtual|nonVirtual][const] returnType functionNameStringOrIndex ( argType1..argTypeN ) module: moduleName > 
        <apicall: [async] [virtual|nonVirtual][const] returnType functionNameStringOrIndex ( argType1..argTypeN ) module: moduleName >

    Dolphin:
        <stdcall: [virtual|nonVirtual][const] returnType functionNameStringOrIndex argType1..argTypeN>
        <cdecl:   [virtual|nonVirtual][const] returnType functionNameStringOrIndex argType1..argTypeN> 

    ST/V:
        <api: functionName argType1 .. argTypeN returnType> 
        <ccall: functionName argType1 .. argTypeN returnType> 
        <ole: vFunctionIndex argType1 .. argTypeN returnType>

    VisualWorks:
        <c: ...>
        <c: #define NAME value>

Class protocol:

 addToDllPath: aDirectoryPathName

can be used during initialization, to add more places for dll-loading

 dllPath

 dllPath: aCollectionOfDirectoryPathNames

 initialize

using inline access to corresponding c--defines to avoid duplicate places of knowledge

 removeFromDllPath: aDirectoryPathName

remove added places from dll-loading

 callTypeAPI

 callTypeC

 callTypeCDecl

 callTypeMASK

 callTypeOLE

 name: functionName module: moduleName returnType: returnType argumentTypes: argTypes

Instance protocol:

 argumentTypes

 argumentTypesString

 beAsync

let this execute in a separate thread, in par with the other execution thread(s).
Ignored under unix/linux (until those support multiple threads too).

 beCallTypeAPI

 beCallTypeC

 beCallTypeOLE

 beCallTypeUNIX64

 beCallTypeV8

 beCallTypeV9

 beCallTypeWINAPI

 beConstReturnValue

specify that a pointer return value is not to be finalized
(i.e. points to static data or data which is freed by c)

 beNonVirtualCPP

specify this as a non-virtual c++-function

 beUnlimitedStack

let this execute on the c-stack (as opposed to the thread-stack)
for unlimited auto-sized-stack under unix/linux.
Ignored under windows.

 beVirtualCPP

specify this as a virtual c++-function

 callTypeNumber

 isAsync

is this executed in a separate thread, in par with the other execution thread(s) ?

 isCPPFunction

is this a virtual or non-virtual c++-function ?

 isCallTypeAPI

 isCallTypeC

 isCallTypeOLE

 isConstReturnValue

is the pointer return value not to be finalized
(i.e. points to static data or data which is freed by c)

 isNonVirtualCPP

is this a non-virtual c++-function ?

 isUnlimitedStack

will this execute on the c-stack (as opposed to the thread-stack)
for unlimited auto-sized-stack under unix/linux.
Ignored under windows.

 isVirtualCPP

is this a virtual c++-function ?

 moduleName

 returnType

 vtableIndex

 invoke

 invokeCPPVirtualOn: anInstance

 invokeCPPVirtualOn: instance with: arg

 invokeCPPVirtualOn: instance with: arg1 with: arg2

 invokeCPPVirtualOn: instance with: arg1 with: arg2 with: arg3

 invokeCPPVirtualOn: instance with: arg1 with: arg2 with: arg3 with: arg4

 invokeCPPVirtualOn: instance withArguments: args

 invokeWith: arg

 invokeWith: arg1 with: arg2

 invokeWith: arg1 with: arg2 with: arg3

 invokeWith: arg1 with: arg2 with: arg3 with: arg4

 invokeWithArguments: argArray

 printOn: aStream

 adjustTypes

 linkToModule

link this function to the external module.
I.e. retrieve the module handle and the code pointer.

 loadLibrary: dllName

 prepareInvoke

 ffiTypeSymbolForType: aType

map type to one of the ffi-supported ones:
sint8, sint16, sint32, sint64
uint8, uint16, uint32, uint64
bool void pointer handle

 name: functionNameOrVirtualIndex module: aModuleName returnType: aReturnType argumentTypes: argTypes

 owningClass

 owningClass: aClass

 setModuleName: aModuleName

 invokeCPPVirtualFFIOn: instance withArguments: arguments

 invokeFFIWithArguments: arguments

 invokeFFIwithArguments: argumentsOrNil forCPPInstance: aCPlusPlusObjectOrNil

 isExternalLibraryFunction

return true, if the receiver is some kind of externalLibrary function;
true is returned here