Navigation:  Programming Cookbook > External Interfacing >

External Libraries

Previous pageReturn to chapter overviewNext page

In Smalltalk everything is (or should be) an object, and methods should be invoked by sending messages to objects. Consequently we represent external libraries with classes in Dolphin, and wrap each function we wish to call in a particular library in a method (an ExternalMethod) that describes the types of the parameters the external function call is expecting. So each separate external library has a class (a subclass of ExternalLibrary) whose methods represent the external functions. The External Library pattern details the steps necessary to create one of these beasties.

The concept of "types" in Smalltalk is controversially somewhat different than that of Java, C/C++, and many other languages. Smalltalk objects carry their type along with them, and respond to messages in an appropriate manner. This is known as dynamic typing. We typically group a set of messages (and the behaviour expected when those messages are acted upon) into a "protocol". Protocols are independent of any particular class. Protocols are arguably the nearest thing to types in Smalltalk, not classes. Furthermore, Smalltalk variables (including parameters) are typeless: When the only thing one can do to an object is to send it messages, one doesn't care about its internal representation, or its class, only whether it correctly responds to a given protocol. When calling external functions, however, we must map Smalltalk objects to a notion of types that does include representation, because, in the external world,"type" generally specifies representation. Dolphin achieves this mapping by including type information in a special form of primitive method format, and by performing appropriate type conversions.

The external call interface primitives provide automatic conversion of objects for parameters and return values of the following types:

Signed (two's complement) and unsigned integers of 8, 16, 32, and 64 bits
Single (32-bit) and double (64-bit) precision floating point numbers
Characters
Strings
Booleans
Handles
Pointers
Structures (pass and return by value, or by reference)
GUIDs
Active-X Automation types (BSTR, VARIANT, VARIANT_BOOL)

The precise set of parameter types, and the automatic conversion and validation applied are documented in Parameter Types, Validation and Conversion (though it is recommended ExternalDescriptor's class comment be perused to check the latest set and their corresponding validation rules). For example, Dolphin Strings are null-terminated, so they can be safely passed to C/C++ functions as C strings (the null-terminator is not included in the size a String answers when one sends it the #size message) using the lpstr or lpvoid types.