for Windows / CE
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 USA
Voice : 1-256-881-4630
FAX : 1-256-880-0925
email : firstname.lastname@example.org
web : www.marshallsoft.com
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1.1 Using Both WSC4eVC and WSC4eVB2 Applications Notes
1.2 Versions of Win/CE supported
1.2.1 Pocket PC (PPC)1.3 Documentation Set
1.2.2 Handheld PC (HPC)
1.4 User Support
1.5.1 Source Code1.6 Updates
1.5.2 WSC/CE and WSC Discount
1.5.3 Academic Discount
1.5.4 Disk Only
1.5.5 Disk and Printed Manuals
1.7 Customer ID
1.8 License File
2.1 Keycode (License Key)3 XMODEM and YMODEM (XYM)
2.2 USB Ports
2.4 SioPuts Notes
2.5 Hardware Flow Control & Blocking
2.6 Bluetooth Serial
3.1 XYM Introduction4 Problems
3.2 XYM Example Programs
3.3 XYM Function Summary
5 Legal Issues
5.1 Registration6 Summary
6.1 WSC/CE Function Summary
The Windows/CE Standard Serial Communications Library (WSC/CE) is a powerful toolkit that allows software developers to quickly develop serial port communications applications for Windows CE and the Mobile-based Pocket PC. The Windows/CE Standard Serial Communications Library (WSC/CE) SDK is a dynamic link library (DLL) that uses the standard Windows/CE API (Application Programmer's Interface).
There are two versions of WSC/CE: the Windows Standard Serial Communications Library for eVC (WSC4eVC) and the Windows Standard Serial Communications Library for eVB (WSC4eVB). Both use the same Windows/CE DLL (WSC32.DLL).
WSC4eVC requires Microsoft Embedded Tools 3 (eVC3) or Microsoft Embedded Tools 4 (eVC4). WSC4eVB requires eMbedded Visual Basic v3.0 (eVB3) since VB is not supported in Embedded Tools 4. Note that eVC3/eVB3 supports Pocket PC 2002 while eVC4 supports Pocket PC 2003.
Both versions of Embedded Tools can be downloaded from the Microsoft Web site at:
The WSC/CE Serial Comm library can also be used with Bluetooth serial as well as 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 latest versions of our serial communications software can be found at:
Programs written in both eVC (eMbedded Visual C++) and eVB (eMbedded Visual Basic) use the same WSC/CE DLL (WSC32.DLL). Therefore, it is necessary to purchase only one of the libraries in order to receive the registered DLL for use by both WSC4eVC and WSC4eVB.
The only differences between WSC4eVC and WSC4eVB are the Programmer's Manual and the example programs.
WSC/CE supports Pocket PC 2002 and Pocket PC 2003 versions of Windows/CE.
Both WSC4eVC and WSC4eVB run on Pocket PC (PPC) computers (PPC 2002 and PPC 2003), and use the same Win/CE Pocket PC DLL (WSC32.DLL).
WSC4eVC will work with all Pocket PC platforms supported by Microsoft Embedded Visual C++ v3 (eVC3) and Embedded Visual C++ v4 (eVC4).
WSC4eVB will work with all Pocket PC platforms supported by Microsoft Embedded Visual Basic 3 (eVB3).
Embedded Visual Basic Runtime for Pocket PC 2003 is available from Microsoft to allow VB3 programs to run on Pocket PC 2003 platforms. Search
http://msdn.microsoft.com/mobility for "eMbedded Visual Basic Runtime for Windows Mobile-based Pocket PC 2003", or see http://msdn.microsoft.com/mobility/windowsmobile/downloads/evb.aspx For the latest version of our serial communications software, see http://www.marshallsoft.com/serial-communication-library.htm
Handheld PC (HPC) versions of the library LIB and DLL files (WSC32.LIB and WSC32.DLL) are available on request at, although we do not have any HPC example programs.
The complete set of documentation consists of four manuals in three formats (MS WORD, ASCII text, and HTML). This is the second manual (WSC_eUSR) in the set.
Each manual comes in three formats:
The WSC_4eVC and the WSC_4eVB Programmer's Manuals are the language specific eMbedded Visual C++ and eMbedded Visual Basic manuals that provide information needed to compile mobile based application programs in an embedded environment
[NAME] [DESCRIPTION] WSC_4eVC : WSC/CE Programmer's Manual for eMbedded Visual C++ WSC_4eVB : WSC/CE Programmer's Manual for eMbedded Visual Basic
The WSC/CE User's Manual (WSC_eUSR) discusses language independent serial communications programming issues such as modem control, Bluetooth, USB, threads, flow control, emulation, etc . Ordering information is also provided in the manual.
The WSC 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. Documentation can be accessed online at:
We want you to be successful in developing your applications using WSC/CE! We are committed to providing the best library that we can. If you have any suggestions or comments, please let us know.
If you are having a problem using WSC/CE, refer to Section 4.0 "Problems". If you still cannot resolve your problem, email us at
To avoid having your email deleted by our spam scanners, begin the SUBJECT of your email with "WSC4eVC" or "WSC4eEVB". Zip up any attachments and send plain ASCII text email only.
You can also reach us at +1-256-881-4630 between 7:00 AM and 7:00 PM CST Monday through Friday. You can also often reach us on Saturday.
The latest versions of our products are available on our web site at
http://www.marshallsoft.com and on our anonymous FTP sites at ftp://ftp.marshallsoft.com/pub ftp://ftp.marshallsoft.net/pub Registered users can update to the latest DLL's at http://www.marshallsoft.com/oem.htm
A developer license for WSC/CE (WSC4eVC or WSC4eVB) may be purchased for $115 (USD) for email delivery, or $195 (USD) with source code for the DLL.
It is necessary to only register only one of the libraries in order to receive the registered DLL for use by both WSC4eVC and WSC4eVB. See Section 1.1 above.
The fastest and easiest way to order is on our web site at
You can also order by completing INVOICE.TXT (contained within the WSC/CE zip file) and emailing (email@example.com), mailing (see our address at top), or faxing (+1.256.880.0925) it to us.
Multiple copy discounts (3 or more) and site licenses are available. Please call for details.
We accept American Express, VISA, MasterCard, Discover, checks in US dollars drawn on a US bank, International Postal Money Orders, and purchase orders (POs) within the USA from recognized US schools and companies listed in Dun & Bradstreet.
For credit card orders, be sure to include the account number, the expiration date, the exact name on the credit card, and the complete card billing address (the address to which the credit card bill is mailed - not the bank's address). Please include the Card Verification Code (last 3 numbers printed on the back of Visa, MasterCard and Discover cards, or the 4 numbers of the front of American Express cards.) The cardholder's signature is required on faxed orders.
Print the file INVOICE.TXT if a "Pro Forma" invoice is needed. The registered package includes:
There are two ways to order Source Code for WSC/CE.
Purchase both the Windows/CE embedded and Windows desktop (Windows 95/93/ME/XP/NT/2000) versions of the MarshallSoft Serial Communication Libraries at the same time for $189 (with source $279). Discount will be provided in the order confirmation sent to the customer. This offer is not retroactive.
We offer an "academic price" of 30% off the normal price for prepaid email orders to faculty and full time students currently enrolled in any accredited high school, college, or university. To qualify for the discount, your school must have a web site and you must have an email address at your school.
When ordering, ask for the "academic discount", or enter "student at" (or "faculty at") and your schools web site address (URL) in the comments field of the order form on our web site order page. Your order will be sent to your email address at your school.
This offer is not retroactive and cannot be used with any other discount. Products bought with academic pricing are for educational purposes only.
The academic discount does not apply to source code.
When ordering WSC/CE, a 3.5" HD disk can be purchased for $5 for delivery to the, US, Canada, and Mexico. For all other destinations, the cost is $8. A CD can be purchased instead for an additional $3.
Printed manuals (see Section 1.1 "Documentation Set") are the same as in the WSC/CE evaluation distribution. Printed manuals can be purchased for $20 for delivery to the US, Canada, and Mexico. For all other destinations, printed manuals are $25. Printed manuals also come with a 3.5" HD disk.
See INVOICE.TXT or http://www.marshallsoft.com/order.htm
When you register the WSC/CE Serial Communication SDK you will receive a set of registered DLLs plus a license file (WSCxxxx.LIC) that can be used to update the registered DLL's for a period of one year from purchase. Updates can be downloaded from
After one year, the developer license must be updated to be able to download updates. The developer license can be updated for $30 if ordered within one year from the original purchase (or previous update). After one year, licenses can be updated for $55. Source code can be updated for $25 in addition to the license update.
Note that the registered DLL's do not expire.
The Customer ID is the 4 or 5 digits following the product name (WSC) in the license file. For example, customer 1234 will receive license file WSC1234.LIC. Provide the Customer ID in the email Subject when contacting us for technical support (WSC4C 1234).
When a developer license is purchased, the developer will receive a license file named WSCxxxx.LIC, where "xxxx" is the 4 or 5 digit customer ID. The license file is an encrypted binary file used for updating WSC as explained in section 1.6 "Updates". The license file is required in order to create (or update) the registered DLL's.
When you register WSC/CE, you will receive a new set of DLL's and a key code for your DLL's. Pass this keycode as the second argument to SioKeyCode. The keycode will be found in the file named "KEYCODE". The registered keycode is a 9 or 10 digit number. It is not your Customer ID. The keycode for the evaluation (shareware) version is 0.
WSC/CE will work with USB ports which have a "USB / Serial Port" converter installed.
The Win/CE driver that comes with the "USB / Serial Port" converter will create a virtual RS232 serial port, and handle the conversion between RS232 serial data and USB data.
The Windows/CE Serial Communications Library (WSC/CE) is thread safe. Note that calling
SioEvent(Port, EV_RXCHAR) will block the thread in which SioEvent is called. The blocking can be stopped by calling (from another thread) SioSetInteger(Port, 'S', 1) [eVC] SioSetInteger(Port, ASC("S"), 1) [eVB]
The SioPuts function can operate in two ways: (1) "wait for completion" and (2) "immediate return".
In the first (default) way ("wait for completion"), SioPuts will not return to the caller until the entire contents of the buffer (passed to SioPuts) has been accepted by the UART
In the second way ("immediate return"), the contents of the buffer (passed to SioPuts) is queued in the transmit (TX) buffer within Windows, after which SioPuts returns. This means that SioPuts will return immediately, before any data is passed to the UART for transmission. This allows the calling program code to continue processing at the same time that the serial data is being transmitted.
In all cases, the value returned by SioPuts must be checked by the caller to determine the number of bytes actually accepted.
To enable the second method of operation (immediate return) for SioPuts , call SioInteger as follows before calling SioPuts.
SioSetInteger(Port, WSC_WAIT_ON_PUTS, 1)
If hardware flow control is set, and CTS is 0, your application will block until CTS is raised by the serial device (modem, etc.). To prevent blocking because there is no modem connected, do this:
Another way to avoid blocking is to put the serial code in a Win32 thread. The thread may block but your invoking code will not.
Bluetooth is a short range radio that can be used to connect two Bluetooth enabled devices. Both Windows Standard Serial Communications Library for eVC (WSC4eVC) and the Windows Standard Serial Communications Library for eVB (WSC4eVB) SDK can be used with Bluetooth serial ports.
A PPC (Pocket PC) program using WSC/CE can communicate with any other Bluetooth enabled device such as PPC's, HPC's, desktop / laptop PC's, GPS receivers, Smartphone, etc.
Bluetooth makes use of two virtual serial ports: one named "inbound" and the other named "outbound". For example, iPAQ 3970 uses COM7 for inbound and COM8 for outbound, while the iPAQ 4355 uses COM8 for inbound and COM6 for outbound.
To discover which ports your machine is using, select the Bluetooth Manager, turn the Bluetooth radio on, and then choose the "Serial Port" entry. The Bluetooth port assignments cannot be changed.
The inbound port is for accepting "inbound" serial connections, and the outbound port is for initiating "outbound" serial connections. The only difference between inbound and outbound is which device initiates the serial connection over Bluetooth. Use the outbound port to initiate the connection and the inbound port to accept the connection from some other device. Once the Bluetooth connection is established, the one port is used for normal serial communications in both directions.
Some Bluetooth devices require that they be configured as "paired devices". For these devices, follow the directions for the particular device.
For more information on Bluetooth, see http://www.bluetooth.com
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, which is the same that is provided in the WSC/CE Programmer's Manual, 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
For more information on using the emulator, search for "Moving Files to and from the Emulator" at
The XMODEM and YMODEM functions are implemented as DLL's (Dynamic Link Libraries), in XYM32.DLL, and are state driven like the Modem I/O functions described in the previous section.
Files can be sent and received using XMODEM, XMODEM/CRC, XMODEM/1K, and YMODEM. The basic procedure used to run XMODEM and YMODEM is as follows:
Refer to XMODEM.TXT for more information on the internal operation of the XMODEM protocol, and to YMODEM.TXT for more information on the internal operation of the YMODEM protocol.
There are four XMODEM and YMODEM example programs. Example programs are found in the APPS directory, which is created when running SETUP.
Refer to the WSC/CE Reference Manual (WSC_eREF) for more information on individual XY Modem functions (XYM32.DLL).
We recommend the following steps if you believe that you have discovered a bug in the library:
If the problem is an error in the library and can be solved with an easy work-around, we will publish the work-around. If the problem requires a modification to the library, we will make the change and make the modified library available to our customers without charge.
See Section 1.5 "Ordering" for information on ordering.
MarshallSoft Computing, Inc. grants the registered user of WSC the right to use one copy of the WSC DLL's on a single computer in the development of any software product. The user may not use the library on more than one computer at the same time.
The "student" registered DLL's may not be distributed under any circumstances, nor may they be used for any commercial purpose.
The "professional" registered DLL's may be distributed (without royalty) in object form only, as part of the user's compiled application. The registered DLL's may NOT be distributed as part of any software development system (compiler or interpreter) without our express written permission. The source code for the library (WSC32.CPP and XYM32.CPP) is copyrighted by MarshallSoft Computing and may not be released in whole or in part.
MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE.
Some states do not allow the exclusion of the limit of liability for consequential or incidental damages, so the above limitation may not apply to you.
This agreement shall be governed by the laws of the State of Alabama and shall inure to the benefit of MarshallSoft Computing, Inc. and any successors, administrators, heirs and assigns. Any action or proceeding brought by either party against the other arising out of or related to this agreement shall be brought only in a STATE or FEDERAL COURT of competent jurisdiction located in Madison County, Alabama. The parties hereby consent to in personam jurisdiction of said courts.
Refer to the WSC/CE Reference Manual (WSC_eREF) for detailed information on the WSC/CE functions. A one line summary of each function follows.
There are 33 functions in the WSC/CE library.