Page 1
Introduction to calling complex
Windows API functions from eVB
There are
a lot of questions in newsgroups that have a simple eVC
solution, but don't have a straightforward solution in eVB.
For example; How can I enumerate flash cards using eVB?
How can I get a battery status using eVB? How can I get
system information using eVB? The list of similar questions
is never-ending. For eVC it is simple enough to supply the
name of an appropriate API function. This however does not
apply to eMbedded Visual Basic since these API calls target
functions that use structures and pointers and there is
no standard way in eVB to call such functions.
There are a lot of third-party components
that wrap some of unsupported API functions. However,
it is clear that it will be much more convenient to have
a general mechanism that allows calling complex API functions
without individual knowledge about their meaning.
VBPointers library is a free library
for dealing with structures and pointers in eVB.
It is possible to use most API functions that were not available
before. This article contains a library description,
step-by-step instructions of its use and 4 examples
of the calling API functions: enumerating flash cards,
getting system information and retrieving a battery
status.
Library description
For an eVB developer that uses the VBPointers
library a pointer to a structure is just a handle to a memory
block. This handle is created using the VB_AllocPointer
and released via the VB_FreePointer. A memory block handle
is a variable of type Long.
The library contains the set of functions
for setting and getting information from the structures
represented by a memory block handle. The special case is
the string variable. There are several functions for converting
between eVB strings and string pointers used in the Windows
API.
There are 4 types of functions in the
library.
- Pointer allocating (VB_AllocPointer,
VB_AllocStringPointer). These functions allocate a
pointer in a heap and initialize it. For the eVB programmer
the pointer is a handle to a memory block (variable of
type Long). This handle can be used in Windows API functions
and with other functions from the VBPointers library.
- Pointer releasing (VB_Release).
This function is used to release the memory block that has
been allocated by functions from the previous category.
- Position based access to structure
members (VB_GetLongAt, VB_GetWordAt, VB_GetByteAt,
VB_SetLongAt, VB_SetWordAt, VB_SetByteAt). These functions
are used to read/write structure's members.
- Converting a string pointer to eVB
string (VB_CreateString). This function is used
to create an eVB string from a string pointer. For example,
it can be used to retrieve a string from a structure returned
by an API function.
Step-by-step using of the VBPointers
library
The following instructions will help
you to call a Windows API function from eMbedded Visual
Basic.
- Copy the VBPointers.dll to
the \windows directory of your device.
- Include the VBPointers library declaration
into your eVB code. You can find the necessary eVB declarations
in the library package.
- Write a declaration for Windows
API function. Pointers to structures should be replaced
by Long.
- Calculate the size of the structure
in bytes. There is a simple eVC program in the package
that can calculate sizes of structures.
- Pass the calculated size to the
AllocPointer function. It will allocate a memory
block and initialize it with zeros.
- Calculate the offsets of the structure's
members. You can use sample eVC program to calculate offsets.
- Use SetLongAt, SetWordAt, SetByteAt
with calculated offsets to set necessary fields of the
structure. Use AllocStringPointer to set string
(e. g. LPTSTR) members.
- Call the Windows API function. Use
the memory block handle as a pointer to the structure.
- Read the necessary structure's fields
using GetLongAt, GetWordAt, GetByteAt with calculated
offsets. Use CreateString to read string members
(e. g. LPCTSTR).
- Free the memory block using FreePointer.
The simplest way to calculate offsets
and a structure's size is to use the simple eVC program
from the library package. If you don't know how to compile
and run eVC programs you can request the information about
certain structure's parameters from eVC developers. For
example, you can post the request to the DEVBUZZ
eVC forum. In this case the answer will be available
for other eVB developers.
Examples
Enumerating flash cards
Private Sub EnumStorageCards()
Dim FindInfo As Long ' pointer
to WIN32_FIND_DATA structure
Dim FlashCard As Long
Dim FlashCardName As String FindInfo = AllocPointer(560)
' sizeof(WIN32_FIND_DATA) is 560
FlashCard = FindFirstFlashCard(FindInfo)
If FlashCard <> -1 Then Do
' name is stored as part of the structure (offset = 40)
Call CreateString(FindInfo + 40, 200, FlashCardName)
MsgBox "Flash Card Name: " & FlashCardName
Loop While FindNextFlashCard(FlashCard, FindInfo) <> 0
End If
FreePointer (FindInfo)
End Sub
Retrieving
a battery life percent
Private Sub ReportBatteryLifePercent()
Dim PowerStatus As Long
' pointer to SYSTEM_POWER_STATUS_EX structure
Dim LifePercent As Byte PowerStatus = AllocPointer(24)
Call GetSystemPowerStatusEx(PowerStatus, 1)
LifePercent = GetByteAt(PowerStatus, 2)
FreePointer (PowerStatus)
MsgBox "Battery Life Percent: " & LifePercent
End Sub
Retrieving
a processor type
Private Sub ReportProcessorType()
Dim SysInfo As Long
' pointer to SYSTEM_INFO structure
Dim ProcessorType As Long SysInfo = AllocPointer(44)
Call GetSystemInfo(SysInfo)
ProcessorType = GetLongAt(SysInfo, 24)
FreePointer (SysInfo)
MsgBox "Processor Type: " & ProcessorType
End Sub
Using
ShellExecuteEx
Private Sub ExecuteWord()
Dim ExecuteInfo As Long
' pointer to SHELLEXECUTEINFO structure
ExecuteInfo = AllocPointer(60)
Call SetLongAt(ExecuteInfo, 0, 60)
' size of the structure
Call SetLongAt(ExecuteInfo, 16, AllocStringPointer("pword.exe"))
' file name ShellExecuteEx (ExecuteInfo)
FreePointer (ExecuteInfo)
End Sub
Download
Download
the package that contains
- Library binaries for ARM, MIPS,
SH3, x86, x86em processors.
- Documentation.
- Sample eVC program to get sizes
of structures and offsets.
- Sample eVB application.