Introduction

One feature that puts the “Open” in OpenInsight is the ability to use functions that are stored within DLL files. Quite often these are Windows API functions but they can also be third-party utilities. The OpenInsight 7.0 Programmers Reference Manual has a lot of information on how to make this work (see Chapter 7: Calling DLL Functions from Basic+). However, the list of parameter types has not been updated with those that were introduced in OpenInsight 7.0. Here is a complete list:

Data Types

VOIDvoid, only valid as a return type
CHARansi or utf8 character value
ACHARansi character value
UCHARutf8 character value
WCHARunicode character value
BYTE1 byte signed integer
UBYTE1 byte unsigned integer
SHORT2 byte signed integer
USHORT2 byte unsigned integer
LONG4 byte signed integer
ULONG4 byte unsigned integer
INTplatform signed integer
UINTplatform unsigned integer
FLOAT4 byte floating point number
DOUBLE8 byte floating point number
HANDLEgeneric windows handle value
LPVOIDgeneric pointer value
LPCHARpointer to ansi or utf8 characters
LPACHARpointer to ansi characters
LPUCHARpointer to utf8 characters
LPWCHARpointer to unicode characters
LPBYTEpointer to 1 byte signed integer
LPUBYTEpointer to 1 byte unsigned integer
LPSHORTpointer to 2 byte signed integer
LPUSHORTpointer to 2 byte unsigned integer
LPLONGpointer to 4 byte signed integer
LPULONGpointer to 4 byte unsigned integer
LPINTpointer to platform signed integer
LPUINTpointer to platform unsigned integer
LPFLOATpointer to 4 byte floating point number
LPDOUBLEpointer to 8 byte floating point number
LPHANDLEpointer to generic windows handle value
LPSTRpointer to null terminated ansi or utf8 string
LPASTRpointer to null terminated ansi string
LPUSTRpointer to null terminated utf8 string
LPWSTRpointer to null terminated unicode string
LPBINARYpointer to binary data

Notes

  1. New Data Types are indicated in BLUE.
  2. The new Data Types distinguish between Ansi, Unicode, and UTF8 to allow for more accurate transfer of data.
  3. LPCHAR used to be the only means for specifying strings. In reality, LPCHAR means “Pointer to an array of characters.” However, most DLL parameters want a null terminated string of characters, which cannot be guaranteed by LPCHAR. We recommend using LPCHAR, LPACHAR, LPUCHAR, and LPWCHAR only for passing pointers to single characters or for backward compatibility.
  4. LPSTR, LPASTR, LPUSTR, and LPWSTR should now be used when passing strings. These types append a null character when passing BASIC+ strings to the DLL. When used as return values, the LPSTR types truncate returned strings at the first null character.
  5. Always use the specific pointer type rather than the generic. LPCHAR and LPSTR are generic because they do not specify Ansi, Unicode or UTF8 translation. Using these types will cause strings to be passed “as is” without proper conversion. Use the Ansi, Unicode, and UTF8 counterparts to these types to ensure proper encoding of data.
  6. LPBINARY is meant for passing an array of bytes. Use this when passing Structs to and from a DLL function.
  7. As before, to specify the passing of an explicit pointer, declare the parameter as LPVOID rather than LPx. Otherwise, the LPx types will pass the pointer to the pointer.
  • No labels