Reading and Writing Binary Data

Reading and writing binary data with PortController is generally similar to reading and writing text data. There are, however, some differences to be noted. Here are some things to consider when dealing with binary data.

Visual Basic

Writing binary data in Visual Basic is straightforward. When writing a single byte, simply use the Chr() function to convert your data to a character type before writing it to the serial port:

' Single byte example
Dim tmp As Byte
tmp = 1
myPortController.Write Chr(tmp)

If you want to write an array of bytes to the serial port, use the StrConv function to convert the byte array to Unicode before calling the Write() method:

'Byte array example
Dim tmp(0 To 2) As Byte
tmp(0) = 1
tmp(1) = 0
tmp(2) = 3
myPortController.Write StrConv(tmp, vbUnicode)

Otherwise, reading binary data using the PortController is no different that reading text data. The read binary data is stored in a String just like text data. You may convert this String to a Byte Array or any other appropriate type.

Note: PortController's ReadBinary() and WriteBinary() methods are intended only for use in Visual C++ and offer no advantages over PortController's Read() and Write() methods in Visual Basic.

Visual C++

There is one important thing to remember when dealing with binary data in Visual C++: because binary data may have embedded null bytes it is important to use methods and data types that do not consider a null byte to mark the end of a string. Unfortunately, the PortController wrapper code that Visual Studio generates when PortController is added to the project internally uses a function that is not null-safe. For this reason, we have added the WriteBinary() and ReadBinary() methods for Visual C++ developers to use when reading or writing data that may contain null bytes. These methods look and behave largely like their Read() and Write() cousins, but contain one important difference in their buffer parameter type: instead of passing a BSTR, these methods pass a long value.

This long value is simply a pointer to the buffer that, in the case of WriteBinary() holds the data to be written, or, in the case of ReadBinary(), a pointer to the location where memory is to be allocated and the read data stored.

The following examples demonstrate how to read and write binary data with PortController in Visual C++:

Writing Binary Data

BYTE myBinaryData[3] = {0x01, 0x00, 0x03};
m_myPortController.WriteBinary((long)&myBinaryData, 3, 0); // writes 3 bytes

Reading Binary Data

long numBytesRead;
BYTE *readBytes;
readBytes = (BYTE *)m_myPortController.ReadBinary(10, 0, &numBytesRead);  // reads 10 bytes

Note: It is ok to pass a pointer across the COM boundry with PortController since PortController is run as an in-process COM server. Pointers remain valid because PortController and the client application share the same memory space.

Delphi

Reading and writing binary data with PortController in Delphi is similar to reading and writing text data. In fact, there are no differences between reading binary data with PortController and reading text data with PortController.

Also, only dynamic byte arrays may be directly passed into the Write method. Fixed size arrays must first be converted to dynamic arrays or converted directly to WideString. While Delphi automatically converts AnsiString and String types to WideString, it is necessary to explicitly convert dynamic byte arrays.

When writing a single byte, simply use the Chr() function to convert your data to a character type before writing it to the serial port:

// Single byte example
var tmp: Byte;           // declare variable in the proper place.
tmp := 1;
myPortController.Write(Chr(tmp), 0, 0);

If you wish to write an array of bytes to the serial port, use the AnsiString function before calling the Write() method. Delphi internally converts binary arrays in AnsiString form to type WideString:

// Byte array example
var
  BinArr: array of Byte;                // declare array in the proper place.
SetLength(BinArr, 3);
BinArr[0] := 1;
BinArr[1] := 0;
BinArr[2] := 3;
myPortController.Write(AnsiString(BinArr), 0, 0);

Note: Delphi String type behavior depends on the {$H} compiler option. In the default {$H+} state, the compiler interprets the write string as an AnsiString when it appears without a bracketed number after it. Use the {$H-} directive to turn the write string into ShortString. Beware, however, that a ShortString is able to hold only 255 bytes.