Embedded Visual Basic Windows Ce And Pocket Pc Mobile Applications [Electronic resources] نسخه متنی

UDT API Examples

Now that you have functions to generate binary strings from numbers, you need to look at exactly how to use them.

I said before that both UDTs and Strings are just contiguous, linear memory blocks, so let's look at our initial example UDT, the RECT.

Again a RECT, if written in VB, would look like this:

Public Type RECT
Left As Long
Top As Long
Right As Long
Bottom As Long
End Type

Because eVB doesn't support types, you need to create a binary string that just concatenates the four members in this fashion:

Left & Top & Right & Bottom

Our initial example has the following values:

Left = 100
Top = 50
Right = 1200
Bottom = 175

So you could write code to generate this as a binary string like this:

Dim binaryStringAs String
binaryString= ToBinaryString(100, CE_LONG)
binaryString= binaryString& ToBinaryString (50, CE_LONG)
binaryString= binaryString& ToBinaryString (1200, CE_LONG)
binaryString= binaryString& ToBinaryString (175, CE_LONG)

The last thing you need to know before diving into some examples is that when using a byte string,

you must change the API declaration from what the API viewer gives you. You must declare any UDT parameter as a String instead of the UDT type.

For example, the API viewer defines ClipCursor as

Declare Function ClipCursor Lib "Coredll" Alias "ClipCursor" _
(lpRect As Long) As Long

This is misleading. It looks like the parameter should be a Long, but if you look in the eMbedded Help you see this:

BOOL ClipCursor(CONST RECT *lpRect);

What it's actually looking for is a pointer to a RECT structure or UDT. You need to modify the API declaration to take a String then, so its declaration in the project would be

Declare Function ClipCursor Lib "Coredll"(ByVal lpRect As String) As Long

The rest of the API declarations I give will already be modified to take String parameters, so what you see in the samples will differ from the definitions in the API viewer.

SetLocalTime

Declare Function SetLocalTime Lib "Coredll" (ByVal lpSystemTime As String) _
As Long
Type SYSTEMTIME
Integer wYear;
Integer wMonth;
Integer wDayOfWeek;
Integer wDay;
Integer wHour;
Integer wMinute;
Integer wSecond;
Integer wMilliseconds;
End Type

Surprisingly, eVB doesn't expose any methods that allow you to easily set the device's clock programmatically. There are a few API calls that allow you to set and read the clock in both local time and GMT. Let's look at SetLocalTime.

SetLocalTime takes a single input parameter, a SYSTEMTIME UDT, which you can see defined previously. It's simply 8 Integers, one for each portion of the date. To set the time, you need to create a binary string of desired settings and pass it to this function. To make it both simple and reusable, create a wrapper function called SetDeviceTime (see Listing 9.14) that takes each of the UDT members as parameters, builds the binary string, and makes a call to SetLocalTime.

Listing 9.14 Setting the Device Time Using the SetLocalTime API

Public Function SetDeviceTime(Year As Integer, Month As Integer, _
DayOfWeek As Integer, Day As Integer, _
Hour As Integer, Minute As Integer, _
Second As Integer, Millisecond As Integer) _
As Boolean
Dim binaryString As String
Dim lRet As Long
binaryString = ToBinaryString(Year, CE_INTEGER)
binaryString = binaryString & ToBinaryString(Month, CE_INTEGER)
binaryString = binaryString & ToBinaryString(DayOfWeek, CE_INTEGER)
binaryString = binaryString & ToBinaryString(Day, CE_INTEGER)
binaryString = binaryString & ToBinaryString(Hour, CE_INTEGER)
binaryString = binaryString & ToBinaryString(Minute, CE_INTEGER)
binaryString = binaryString & ToBinaryString(Second, CE_INTEGER)
binaryString = binaryString & ToBinaryString(Millisecond, CE_INTEGER)
lRet = SetLocalTime(binaryString)
' check for success
If lRet = 0 Then
SetDeviceTime = False
Else
SetDeviceTime = True
End If
End Function

To build the binary string, convert each input parameter with ToBinaryString and concatenate them onto the larger string, which you then pass to SetLocalTime.

GetLocalTime

Declare Sub GetLocalTime Lib "Coredll" (ByVal lpSystemTime As String)
Type SYSTEMTIME
Integer wYear;
Integer wMonth;
Integer wDayOfWeek;
Integer wDay;
Integer wHour;
Integer wMinute;
Integer wSecond;
Integer wMilliseconds;
End Type

Retrieving data from a long, concatenated binary string isn't difficult either, provided you know where each data piece starts and how long it is, and if you're writing the code that creates the binary string, you've got that information.

To demonstrate this, write SetDeviceTime's complement, GetDeviceTime (see Listing 9.15). While the inherent Now() function will also provide the current time, the function will provide each piece of the date and time separately, making manipulation easy.

Listing 9.15 Extracting Each Piece of the Current Time into Separate Numeric Variables

Public Function GetDeviceTime(ByRef Year As Integer, _
ByRef Month As Integer, _
ByRef DayOfWeek As Integer, _
ByRef Day As Integer, _
ByRef Hour As Integer, _
ByRef Minute As Integer, _
ByRef Second As Integer, _
ByRef Millisecond As Integer) As Boolean
Dim binaryString As String
Dim lRet As Long
' Allocate space for the variable
binaryString = String(8, Chr(0))
' Call the API
GetLocalTime(binaryString)
' Extract the values from the binary string
' Remember, we must use MidB to extract bytes
Year = FromBinaryString(MidB(binaryString, 1, CE_INTEGER))
Month = FromBinaryString(MidB(binaryString, 3, CE_INTEGER))
DayOfWeek = FromBinaryString(MidB(binaryString, 5, CE_INTEGER))
Day = FromBinaryString(MidB(binaryString, 7, CE_INTEGER))
Hour = FromBinaryString(MidB(binaryString, 9, CE_INTEGER))
Minute = FromBinaryString(MidB(binaryString, 11, CE_INTEGER))
Second = FromBinaryString(MidB(binaryString, 13, CE_INTEGER))
Millisecond = FromBinaryString(MidB(binaryString, 15, CE_INTEGER))
GetDeviceTime = True
End Function

In eVB, VB, or even C for that matter, a function can have only one return value. To return all the members of SYSTEMTIME, you will pass the parameters in ByRef. This allows the called function to modify the variable and when execution returns to the caller, the changes remain.

Because eVB variables are all Variants, they aren't initialized with any size information. To avoid stepping on memory that you haven't yet laid claim to, you must actually allocate space for the UDT data coming back from the API call.

GetLocalTime returns a SYSTEMTIME structure, which is 8 Integers, or 16 bytes long, so the variable binaryString needs to be initialized to 16 bytes. Because Windows CE uses Unicode, each character in a String takes up 2 bytes, so you need 8 characters. You could reasonably set binaryString to any 8 characters8 spaces, ABCDEFGH, a namebut I prefer to set all the bits to zero using the String function. String simply creates a string of a specified lengthin this case, 8using the specified character or charactersin this case, Chr(0), or all bits off. This also ensures that the string is properly terminated by the C language standard.

Next make the API call, which fills the binaryString variable.

Next, extract each member from the binary string. Again, remember that each integer is 2 bytes, so use MidB to extract them, starting at bytes 1 and 2 for the year and finishing at 15 and 16 for the millisecond.

Finally, set the actual return value, which simply indicates we succeeded, and exit the function. Again, because all the parameters were passed in ByRef, the caller will still be able to see the values we set.