Windows Standard
Serial Communications
for eVC
Programmer's Manual
(WSC_4eVC)
Version 3.4
May 8, 2005
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2005
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 1-256-881-4630
FAX : 1-256-880-0925
email : info@marshallsoft.com
web : www.marshallsoft.com
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1 Introduction
1.1 Features2 Library Overview
1.2 Example Code Segment
1.3 Documentation Set
1.4 Installation
1.5 Uninstalling
1.6 Ordering
1.7 Updates
2.1 Dynamic Link Libraries3 Example Programs
2.2 Static Linking
2.3 Compiling Programs
2.4 Emulation
3.1 WSCVER (WSC Version)4 Revision History
3.2 SIMPLE
3.3 MESSAGE
3.4 DEVICE
3.5 MODEM
3.6 XMS and XMR
3.7 YMS and YMR
The Windows/CE Standard Serial Communications Library for eVC (WSC4eVC) is a powerful toolkit that allows software developers to quickly develop serial port communications applications for Windows CE and the Mobile-based Pocket PC using the eMbedded Visual C++ development system. The Windows/CE Standard Serial Communications Library (WSC/CE) SDK is a dynamic link library (DLL) that uses the standard Windows API (Application Programmer's Interface).
The WSC/CE component library uses a simple interface to communicate with any device connected to a serial port. WSC4eVC includes several eMbedded Visual C++ (eVC) example programs demonstrating serial communication functions.
The Windows/CE Standard Serial Communications Library (WSC/CE) includes 33 functions, modem control , and XMODEM and YMODEM protocols. WSC4eVC will work with all Pocket PC (PPC) platforms supported by Microsoft eMbedded Visual C++ v3.0 (eVC3) and eMbedded Visual C++ v4.0 (eV4). The eVC comm library can also be used with Bluetooth serial. The library can also be used with the Pocket PC emulator that is provided with Microsoft Embedded Tools. This will allow a programmer to develop serial communication applications without having the physical Windows/CE device.
The WSC/CE DLL (WSC32.DLL) can be used from any language capable of calling the Windows/CE API. MarshallSoft provides separate products for Windows 95/98/ME and NT/2000/XP. Evaluation versions for these may be downloaded from our web site at
http://www.marshallsoft.com/serial-communication-library.htm
When comparing the Windows/CE Standard Serial Communications Library component library against our competition, note that:
Our goal is to provide a robust serial communication component library that you and your customers can depend upon. A fully functional evaluation version is available. Contact us if you have any questions.
Some of the many features of the Windows/CE Standard Serial Communications Library for eVC component library are as follows:
A good selection of eVC++ example programs with full source code are included. Refer to Section 6 for more details on each of the example programs.
[PROGRAM] [DESCRIPTION]
WSCVER : Program that displays the WSC version number and build.
SIMPLE : A simple terminal program (uses timer).
MESSAGE : A simple terminal program (uses Windows message loop).
DEVICE : Sends a user command to a serial device.
MODEM : Same as SIMPLE but controls flow control, modem lines, etc.
XMS , XMR : XMODEM send/receive programs.
YMS , YMR : YMODEM send/receive programs.
// pass keycode (0 for evaluation version) to WSC
SioKeyCode(0);
// open the port
Code = SioReset(Port, 1024, 1024);
if(Code<0)
{// SioReset fails
wsprintf((LPWSTR)Temp,L"Cannot open COM%1d: Error %d",1+Port,Code);
MsgBox((LPWSTR)&Temp);
}
else
{// open opened successfully
wsprintf((LPWSTR)Temp,(LPWSTR)L"COM%1d opened @ %d",1+Port,BaudRate);
MsgBox((LPWSTR)&Temp);
// set baud rate (default is 19200)
SioBaud(Port,BaudRate);
// set DTR & RTS
SioDTR(Port,'S');
SioRTS(Port,'S');
// set hardware (RTC/CTS) flow control
Code = SioFlow(Port, 'H');
// set parity, stop bits & data bits (default is 8N1)
SioParms(Port, WSC_NoParity, WSC_OneStopBit, WSC_WordLength8);
// transmit "AT" followed by a carriage return
Code = SioPuts(Port, "AT\r", 3);
// close port
SioDone(Port);
}
Documentation is located in the /APPS subdirectory where WSC4EVC is installed and also can be accessed online from the Windows/CE Standard Serial Communications Library for eVC product page at:
http://www.marshallsoft.com/evc-serial-comm-pocketpc.htm
Documentation consists of four manuals. This is the first manual (WSC_4eVC) in the set.
Each manual comes in three formats:
The WSC_4eVC Programmer's Manual is the language specific eMbedded Visual C++ manual and provides information needed to compile your programs in an eVC++ environment.
The WSC/CE User's Manual (WSC_eUSR) discusses language independent serial communications programming issues such as XMODEM/YMODEM modem control, Bluetooth serial, USB, threads, flow control, etc . Ordering information is also provided in the manual.
The WSC/CE Reference Manual (WSC_eREF) contains details on each individual WSC/CE function.
The Serial Communications Manual (SERIAL) contains background information on serial port hardware.
Use Microsoft Word or Microsoft WordPad to print the document files.
The SETUP program creates a directory (default WSC4eVC) on the desktop machine with the following sub-directories (folders).
DOCS : All documentation.
APPS : All example code.
COPY : DLL's to be copied to the PPC WINDOWS directory.
PPC_2002_ARM : ARM/PPC version of WSC32.DLL and XYM32.DLL
ARM/PPC version of WSC32.LIB and XYM32.LIB
PPC_2002_X86 : X86/PPC emulator version of WSC32.DLL and XYM32.DLL
X86/PPC emulator version of WSC32.LIB and XYM32.LIB
PPC_2003_ARMV4 : ARMV4/PPC version of WSC32.DLL and XYM32.DLL
ARMV4/PPC version of WSC32.LIB and XYM32.LIB
PPC_2003_EMU : PPC emulator version of WSC32.DLL and XYM32.DLL
PPC emulator version of WSC32.LIB and XYM32.LIB
NOTE: The COPY directory contains the version of WSC32.DLL and XYM32.DLL chosen when SETUP is run.
After SETUP completes, the DLL's in the COPY directory (folder) must be copied to your Win/CE machine's \WINDOWS directory (folder) using ActiveSync. ActiveSync can be downloaded from Microsoft at
http://www.microsoft.com/windowsmobile/downloads/default.mspx
Microsoft Embedded Tools v3 or v4 must be installed on your desktop in order to compile the example programs. Download from Microsoft at:
http://www.microsoft.com/downloads/search.aspx?displaylang=en&categoryid=8
Uninstalling WSC4eVC is very easy. WSC4eVC does not modify the registry. First, delete the WSC4eVC project directory created when installing WSC4eVC. Second, delete WSC32.DLL and XYM32.DLL your Win/CE machine's \WINDOWS directory (folder) using ActiveSync.
WSC4eVC can be registered for $115 (or $195 with source code). Refer to Section 1.6, "Ordering" in the WSC/CE User's Manual (WSC_eUSR) for details on ordering or purchase a developer license online at
http://www.marshallsoft.com/order.htm
An update for WSC4eVC may be purchased for $30 (for email delivery) if ordered within one year of the original purchase (or previous update). After one year, WSC4eVC can be updated for $55. See Section 1.6, "Ordering" in the WSC/CE User's Manual (WSC_eUSR) for details.
Note that the registered DLL's do not expire.
WSC4eVC is implemented as a Win/CE dynamic link library (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to the traditional static library which is bound to each and every application that uses it at link time.
Registered users (who have ordered WSC4eVC with source code) can easily compile WSC32.CPP into their application, so that the WSC32.DLL is not needed.
In the WSC/CE prototype file wsc.h, change
#ifdef WSC_IMPLEMENTATION
#define WSCDLLEXPORT _declspec(dllexport)
#else
#define WSCDLLEXPORT _declspec(dllimport)
#endif
to
#define WSCDLLEXPORT
Microsoft Embedded Tools v3 or V4 must be installed on your desktop computer in order to compile the example programs.
Example programs can also be compiled with the Pocket PC emulator that is provided with Microsoft Embedded Tools. This will allow a programmer to develop serial communication applications without having the physical Windows/CE device.
The following information describes how to run the SimpleV4 example program on the PPC 2003 emulator, and assumes that you have installed WSC4eVC into the default directory C:\WSC4eVC
COPY C:\WSC4eVC\COPY\wsc32.dll APPS\emulatorRel
C:\WSC4eVC\APPS\emulatorRel
For more information on using the emulator, search for "Moving Files to and from the Emulator" at
http://msdn.microsoft.com
All example program compile using Microsoft's Embedded Tools v3 (eVC3) or Embedded Tools v4 (eVC4). eVC3 project files end with "V3.vcp" while eVC4 project files end with "V4.vcp".
The first example program is the WSCVER ("WSC Version") program which displays the WSC library version number. Its purpose is display the WSC/CE version, build, and registration string as well as to verify that WSC32.DLL is being found and loaded by Windows/CE.
SIMPLE is a very simple communications program using WSC4eVC. Everything typed on the keyboard is sent to the serial port, and everything incoming from the serial port is displayed on the screen.
Test SIMPLE by connecting the PPC to a RS232 serial device or another computer using the serial port or Bluetooth (virtual) serial port.
MESSAGE is a very simple communications program using WSC4eVC. Everything typed on the keyboard is sent to the serial port, and everything incoming from the serial port is displayed on the screen.
MESSAGE is the same program as SIMPLE except that it uses Windows messages in the Windows message loop rather than a timer to check for incoming serial data.
The DEVICE program is designed for talking to an arbitrary serial device. Use this program as a guide when communicating with serial devices other than modems and other computers.
The MODEM program uses WSC/CE functions to set flow control (hardware, software, or none), DTR line (set or clear), RTS line (set or clear), display the transmit & receive queue sizes, detect a break signal, and detect changes in DSR and CTS. Various line errors can be checked such as parity error, framing error, data overrun, receive queue overflow, and transmit buffer full.
XMS (XMODEM Send) and XMR (XMODEM Receive) are programs that send and receive files using the XMODEM protocol. The default for the local directory is \My Documents.
YMS (YMODEM Send) and YMR (YMODEM Receive) are programs that send and receive files using the YMODEM protocol. The default for the local directory is \My Documents.
Version 3.3: July 21, 2003
Version 3.4: May 8, 2005