User Manual Index

General Information

  • Overview
  • Technical Support and Upgrades
  • Purchase and Licensing options
  • What's new in this version?
  • Frequently Asked Questions
  • Installation tips
  • About Sample Application
Using Virtual Serial Port
  • Virtual Serial Port Methods Overview
  • Virtual Serial Port Events Overview
  • Virtual Serial Port Properties Overview
  • Redistribution
Eltima Software GmbH
Lyoner Strasse 26
60528 Frankfurt, Germany 		Support Line:
Tel: +49 69 677 33 496 [CET]
Fax: +49 69 677 33 200 		Customer Care Center:
www.eltima.com/ccc


Overview

Virtual Serial Port is a powerful advanced ActiveX Control that allows your application to create custom additional virtual serial ports in system and fully control them. Created virtual serial ports look absolutely like real serial ports for other Windows applications. From your application you can control data sent to virtual serial port by other applications and respond to them by sending your own data to virtual serial port, which will be received by other Windows applications as if it was sent from a real serial port.

Advanced VSP ActiveX Control events detecting engine notifies you about various events occurring in system while other applications are working with virtual serial port.

Main Features:

  • Set custom signal lines wiring (DTS, RXT, DSR, CTS, DCD, RING) (for Windows NT4/2000/XP/2003)
    • NEW!
  • Emulate connection line break (for Windows NT4/2000/XP/2003)
    • NEW!
  • Enumerate Virtual Serial Ports (for Windows NT4/2000/XP/2003)
    • NEW!
  • Flexible set of control functions
  • Wide selection of supported events
  • Virtual serial port can have any name
  • Full software emulation of real serial port
  • Full baud rate emulation (for Windows NT4/2000/XP/2003)
    • NEW!
  • Virtual serial port could be created and deleted dynamically during runtime
  • High speed data exchange from/to virtual serial port
  • Examples for Borland/Inprise Delphi, C++ Builder 6.0, Microsoft VC++ 6.0, Microsoft Visual Basic 6.0, Visual Basic.Net, Visual Studio C# and Visual C.Net included
  • No reboot required during installation

The Virtual Serial Port component is compatible with:

  • Microsoft Windows 98 SE, ME, NT4, 2000, XP, 2003
  • Microsoft Visual Basic 5-7
  • Microsoft Visual C++ 5-7
  • Inprise/Borland Delphi 3-8
  • Inprise/Borland C++ Builder 3-6
  • .NET technology support

Eltima Software GmbH


Technical Support

You can easily request support via any of the following methods:

Customer Care Center

Visit our Customer Care Center (CCC) to get qualified technician at your hand, track your inquires and search our growing Q&A database to find out if other user have encountered similar problems.

Support via e-mail:

You can always reach our Support Team via the following e-mail:
support@eltima.com

Support via instant messengers:

ICQ #: 241962083
MSN Messenger ID: jannachelsy@hotmail.com
AOL Messenger ID: jannachelsy
Yahoo! Messenger ID:jannachelsy

Support via phone:

Toll-free support line #: +49 69 677 33 496 [CET]

To get more information about this product and many more other products please visit our site at www.eltima.com


Purchase and Licensing options

VSP AX box

Virtual Serial Port ActiveX Control 4.0

Single developer license [?]
Order via ShareIt!
€ 149.95
$ 179.95

OEM license [?]
Order via ShareIt!
€ 949.95
$ 1149.95

Source code license [?]
Order via ShareIt!
€ 2449.95
$ 2949.95

Single User License [?]
Order via ShareIt!
€ 49.95
$ 59.95

[Single Developer License]

Single Developer License provides commercial rights for redistribution of Eltima Virtual Serial Port ActiveX Control incorporated into your software and entitles you to a single copy of the Software for development purposes. However, unlike OEM License every customer who is going to use your product must purchase additional Single User License to be able to register VSP AX Control in user mode. Developer’s obligation is to notify the end-users about the necessity of purchasing Single User License.

The license is granted per ONE PC / ONE USER only, which means that it is not permissible for the same developer to install more than one copy of the Software. There are no limitations on the purpose and usage conditions of the user's software, which is developed with the legally obtained royalty-free Software license.

Note: if you want to test your software with incorporated Eltima Virtual Serial Port ActiveX Control on a test computer, you must purchase Single User License as well.

UNDER NO CIRCUMSTANCES IT IS PERMISSIBLE TO DISTRIBUTE THE UNLOCKED FILE OF THIS SOFTWARE TO END USERS.

[Single User License]

To use any third-party software that has Eltima Virtual Serial Port ActiveX Control built-in, user must purchase Single User License.

Upon incorporating a single-developer licensed control into your software, every your customer should purchase Single User License to obtain registration info to utilize Eltima Virtual Serial Port ActiveX Control in user mode.

This license is granted per ONE PC / ONE USER only, which means that if you are going to install third-party software with incorporated VSP AX Control at several PCs, you must purchase as many Single User Licenses as many computers you want install it to.

Note: User must purchase this license if he/she is using third-party software that was developed under Single Developer License only.

[OEM License]

The software products purchased through an OEM License may be incorporated into software and hardware sold by you or your company, or may be provided as components of Eltima Software products to accompany software and hardware sold by your side.

You may reproduce and distribute VSP ActiveX as an integral part of or incorporated in your software or hardware product or as a standalone Software maintenance update for existing end-users of your products, excluding any other standalone products.

According to OEM license by Eltima you do not need to pay a fee per every order of your product you incorporate our Control into. The OEM License entitles you to unlimited redistribution of our software as a part of yours (commercial software included). This license lets you use the Control by an unlimited number of developers, on multiple computers. Software with incorporated OEM version of VSP AX Control does not require registration in user mode, ensuring that your customers do not have to pay any additional fees upon purchasing or obtaining your products in other ways.

[Source Code License]

Ordering Source Code license on VSP ActiveX Control you receive all source codes of the Control, extensively commented, including all needed instructions and manuals. In addition we provide full FREE technical and information lifetime 24/7 support, and professional consulting services absolutely for FREE. Our leading developers will help you implement Source codes and understand the advanced part of the product.

We accept Mastercard/Eurocard, Visa, American Express, and Diner's Club online. Alternatively, we support bank transfer/wire transfer, we accept Checks and Money Orders through postal mail.

For orders processing we are using ShareIt! and RegNow companies services - world's leading e-commerce providers for software and shareware sales via the Internet.

share*it!
USA

ShareIt! Inc.
9625 West 76th Street, Suite 150
Eden Prairie, MN 55344, USA

Phone: +1 (952) 646-5747
Fax: +1 (952) 646-4552
E-mail: info@shareit.com
 Germany

Share-it!
Vogelsanger Str. 78
50823 Cologne, Germany

Phone: +49 (0)221 31088-20
Fax: +49 (0)221 31088-29
E-mail: info@shareit.de

regnow
USA

RegNow/Digital River

9625 West 76th Street
Eden Prairie, MN 55344
 Phone (US only): +1 (877) 353 7297
Phone: +1 (952) 646 5331

Fax: +1 (800) 442 3172

Security Guarantee. Online order placement page has been secured with a digital certificate by VeriSign, Inc. This is shown via the "site certificate" that sits on all secure pages. To view this certificate, click on the VeriSign logo at the bottom of the page or the solid key on the status bar of your browser window. A small frame displaying site security information will appear.

VeriSign, Inc.

Lifetime technical support is available 24 hours a day, 7 days a week, 365 days a year via email, phone or fax. If you have any problems using our products, please send us your detailed comments, suggestions, questions. We value every customer and will reply to you as soon as possible. If you are a registered user, you can use the technical support via email or fax. Our registered users can also submit support requests by e-mail for priority support customers.

Money back guarantee. To insure that you are receiving quality service and ordered products work as they were announced to, Eltima offers an honor-based 14 days money-back-guarantee when you purchase any of our products. Honor-based means we will be glad to return your investment when we are sure the product is malfunctioning on client's PC and we receive assistance in finding out the reason on the side of our customers.


What's new in this version?

Changes in version 4.5
Build 4.5.3.73 [Released: February 20, 2006]

  • Added: New input/output methods: ReadArray and WriteArray
  • Added: Parity, Stopbits, Databits, Baudrate, ControlHandShake and FlowReplace properties to check serial port configuration settings
  • Added: OnBreak event
  • Improved: VB6, VB.Net and C# samples
  • Fixed: SetTimeouts method

Changes in version 4.2
Build 4.2.2.54 [Released: January 10, 2006]

  • Fixed: Serial port driver for Windows NT4

Changes in version 4.2
Build 4.2.2.52 [Released: November 25, 2005]

  • Fixed: Problems with removing serial ports

Changes in version 4.2
Build 4.2.2.49 [Released: November 21, 2005]

  • Added: New methods ReadStr and WriteStr

Changes in version 4.1
Build 4.1.2.41 [Released: October 24, 2005]

  • The pool of threads that are waiting for events is decreased. This allows you to create more virtual serial ports in the system

Changes in version 4.1
Build 4.1.2.40 [Released: October 4, 2005]

  • EV_ERR and EV_BREAK signals are added to OnEvent

Changes in version 4.1
Build 4.1.2.39 [Released: September 19, 2005]

  • Problem with OnRxChar event when there is nothing to read from remote port us fixed
  • Microsoft Visual C 6.0/7.0 projects by default will not stop in debug mode

Changes in version 4.1
Build 4.1.2.37 [Released: September 8, 2005]

  • All 64-bit Windows OS versions are supported now

Changes in version 4.0
Build 4.0.0.13 [Released: July 5, 2005]

  • A bug in security module is fixed
  • Handle property is known as HandleControl

Changes in version 4.0
Build 4.0.0.6 [Released: April 28, 2005]

  • Open method is now known as Attach
  • isCreated property is introduced
  • CountVirtualPort property is introduced
  • SetBreak method is introduced
  • SetWiring method is introduced
  • EnumVirtualPort method is introduced

Changes in version 3.8
Build 3.8.5.31 [Released: April 6, 2005]

  • ActiveX Control has been renamed from VSPort.ocx into VSPort.dll
  • Open method is now known as Attach
  • GetIsOpened method is now known as IsOpened
  • GetInCount method is now known as InCount
  • GetHandle method is now known as Handle
  • ActiveX Control rewritten using ATL technology
  • VB.Net and C# can now read/write the whole array of data
  • New samples of using VSP ActiveX Control in console applications added for VC6 and VC.Net

Changes in version 3.6
Build 3.6.5.10 [Released: February 17, 2005]

  • Reworked events management scheme
  • New threads pool added to work with events to speed it up

Changes in version 3.5
Build 3.5.0.21 [Released: December 01, 2004]

  • Full baud rate emulation implemented (for Windows 2000/XP)
  • Multiple core enhancements
  • Examples refreshed

Changes in version 3.0
Build 3.0.3.65 [Released: October 17, 2004]

  • Operating systems support expanded
  • Open method improved
  • New examples

Changes in version 2.52
Build 2.52.0.99 [Released: June 12, 2004]

  • Create method changed to CreatePort for better compatibility with Delphi
  • SetTimeouts method added

Changes in version 2.51
Build 2.51.8.4 [Released: May 30, 2004]

  • Added support of Microsoft Windows NT4

Changes in version 2.5

  • New method Open
  • Virtual Serial Ports now are not always deleted when your application exits. You can control this by setting DeleteOnExit property
  • Improved support of Visual Basic 6 (thread unsafe environmend issues)
  • Fixed bug not allowing you to call Read method from OnRxChar event handler in Visual Basic 6

Changes in version 2.0

  • Fully new architecture (supporting WDM, PnP, PowerManagement). Full integration in Windows XP
  • Virtual Serial Bus driver added - full PnP support
  • Simplified and improved programming interface


Frequently Asked Questions

  1. Q. My problem is following: I'm sending 10000 bytes down the line and remote port receives just 8000.

    2. A. You must enable "Hardware Flow Control" option for both ports. To get more information about this problem please reffer to MSDN page (pay attention to "p" parameter).

  2. Q. I have registration key and OEM version of Virtual Serial Port ActiveX, what should I do next?

    • if you are using VC6, VC7, VB6, VB7 or C# then do the following:
      • Remove Virtual Serial Port ActiveX Demo
      • Install Virtual Serial Port ActiveX OEM version
      • Place ActiveX Control on the form or start the project that has Virtual Serial Port ActiveX Control already
      • In case you already had Virtual Serial Port ActiveX on your form remove it first and place it again
      • You will be prompted to enter name and registration key
      • Restart Integrated Development Environment (close and reopen your development environment)
    • Borland Delphi/Builder
      • Select "Components\Import ActiveX Control..." and select Virtual Serial Port ActiveX"
      • In "Class names" field change default name to something else, for instance TVirtualSerialPortAx_1_0 and press "Install" button
      • In registration dialog enter name and registration key
      • Restart Integrated Development Environment (close and reopen your development environment)
      • Carry on installation process as it was described at Installation Tip page

  3. Q. I have being using a demo version for awhile and haven't had any problems. Then I have bought OEM/Single-Developer license and got "Wrong license" error. What did I do wrong?
    • For Delphi project:

      • open the package Virtual Serial Port ActiveX Control was installed in, remove VSPortLib_TLB.dcr and VSPortLib.pas files and rebuild the project. After that reinstall Virtual Serial Port ActiveX into this project again.

    • For C Builder project:

      • open the package Virtual Serial Port ActiveX Control was installed in and reinstall it again into this package but name it differently, for instance TVSPortAx_4_1.

    • For VC6/VC7 project:

      • remove ActiveX Control and place it again on the form.

  4. Q. I have created COM10, however I cannot open it using my own application. What do I do wrong?

    5. A. In order to open port COM10 and above, you must use the full system path to it, i.e. \\.\COM10 and so on.

  5. Q. I have found a bug in your component/program, how may I report about it?

    6. A. You may report it by sending email to support@eltima.com


Installation tips

Installation into Microsoft Visual C#.Net/ Microsoft Visual VB.Net

To install Virtual Serial Port ActiveX Control into Visual Studio, click "Tools->Add/remove Toolbox Items..." menu item, select "COM Components" tab in "Customize Toolbox" window, click and choose "Virtual Serial Port ActiveX Control" and press "OK" button.

Now you can drag and drop control to the form and use all methods and events provided by Virtual Serial Port ActiveX Control.

For more information see the example source code for MS Visual C++.Net and MS Visual C++.

Installation into Microsoft Visual C++.Net/ Visual C++ 6.0

To install Virtual Serial Port ActiveX Control into Visual Studio, right-click the form and select "Insert ActiveX Control" menu item, select "COM Components" tab in "Customize Toolbox" window, click and choose "Virtual Serial Port ActiveX Control" and press "OK" button.

Now you can drag and drop control to the form and use all methods and events provided by Virtual Serial Port ActiveX Control.

Installation into Microsoft Visual Basic 5-6

To install Virtual Serial Port ActiveX Control into Visual Basic, click Project->Components menu item and choose "Virtual Serial Port ActiveX Control".

Now you can drag and drop control to the form and use all methods and events provided by Virtual Serial Port ActiveX Control.

For more information see the example source code for MS Visual Basic 6.

Installation into Borland C++ Builder and Delphi

To install Virtual Serial Port ActiveX Control into Delphi or C++ Builder, click Component->Import ActiveX Control menu item, choose "Virtual Serial Port ActiveX Control" and press "Install..." key.

You will get the confirmation message when the package is recompiled, and TVirtualSerialPortAx control will appear in the components palette.

For more information see the example source code for Delphi and C++ Builder.


About sample application

In the samples directory of the VSP ActiveX Control you can find "Virtual Serial Port Control Center" demo application, which purpose is to show functionality of the software. It allows to create ports, pairs, reset Virtual Serial Bus, check versatile information about Virtual Serial Ports, emulate full baudrate and connection line break.

Note, that Virtual Serial Port Control Center may slightly differ in different programming language version.

In "Port1" textbox you can type the name of the Virtual Serial Port, which will be created when you press "Create port" button. Note, that in a case of successful port creation, "Create port" button will change its name to "Delete port". When you press "Delete port" button, an attempt to delete virtual serial port will be performed.

"Create pair" button creates Virtual Serial Pair with the names you have typed in Port1 and Port2 textboxes.

"Reset Bus" button removes all Virtual Serial Pairs, currently exist in the system.

"Send file" button allows selecting file to be sent through Virtual Serial Pair. You may send it in chunks of bytes which amounts could be set in corresponding textbox.

"Port 1 detail and timeouts" provides with extensive information about first Virtual Serial Port. You may check the state of Virtual Serial Port, baudrate information, data bits, stop bits, parity and check timeout values (ReadIntervalTimeout, ReadTotalTimeoutMultiplier, ReadTotalTimeoutConstant, WriteTotalTimeoutMultiplier and WriteTotalTimeoutConstant).

"Port 1 control line states" provides with information about different control lines such as CTS, DSR, DCD, RING. Beside status information, you may turn on/off those signal lines, thus getting different wiring connection.

"Port activity" textfield provides detailed log of detected events.

"Virtual Serial Port Terminal" becomes active only when other application opens virtual serial port. Now, if other application sends something to virtual serial port, you will see it in terminal window. If you type anything in this window, other application will receive it. Note, that virtual serial port terminal is very simple, and supports sending data only when you type it. So, when you cut and paste something to it, the data will not be sent.

"Emulate baudrate" and "Emulate line break" checkboxes emulate full baudrate control and break connection line correspondingly. Mentioned options are available under Windows NT4/2000/XP/2003.

Remark: In case you are using C Builder or Borland Delphi then prior to compiling the sample application you have to import ActiveX into your development environment. For more details, please, check Install Tips.


Methods Overview

Virtual Serial Ports ActiveX Control provides the following methods to control virtual serial port:

Method | Brief Description
CreatePort | Creates virtual serial port
Delete | Deletes virtual serial port

Send/Receive operations

Method | Brief Description
Write | Send data to port so other application which is listening to virtual serial port will receive it
WriteStr | Send string to serial port
WriteArray | Send communication data to serial port as Byte array of VARIANT type
Read | Receive data other application has sent to virtual serial port
ReadStr | Receive string from port
ReadArray | Receive data from port as Byte array of VARIANT type

Other operations

Method | Brief Description
SetCTS | Change the state of CTS signal line for virtual serial port
SetDSR | Change the state of DSR signal line for virtual serial port
SetDCD | Change the state of DCD signal line for virtual serial port
SetRING | Change the state of RING signal line for virtual serial port
SetStrictBaudrate | Change the state of strict baudrate for virtual serial port
PurgeQueue | Discards all characters from the input buffer
ResetBus | Delete all virtual serial ports from the system
Attach | Attach existing virtual serial port
SetTimeouts | Set timeouts for virtual serial port
EnumVirtualPort | Returns a name of virtual serial port specified by parameter NumberPort
SetBreak | Break virtual serial port
SetWiring | Sets connection type depending on parameters

See also:

Virtual Serial Port Events Overview, Virtual Serial Port Properties Overview


Events Overview

Virtual Serial Ports ActiveX Control provides a set of events to control virtual serial port state changes:

Event | Brief Description
OnBaudRate | Baud rate change was detected
OnDTR | DTR (data-terminal-ready) signal state changed
OnHandFlow | Flow control change detected
OnLineControl | Line control change detected
OnOpenClose | Port Open or Close operation detected
OnRxChar | A character was received and placed in the input buffer
OnRTS | RTS (ready-to-send) signal state changed
OnSpecialChars | Change of event (special) characters was detected
OnTimeouts | Timeouts change was detected
OnEvent | Triggered every time a communication event occurs
OnBreak | Break signal state changed

See also:

Virtual Serial Port Methods Overview, Virtual Serial Port Properties Overview


Properties Overview

Virtual Serial Ports ActiveX Control provides the following properties:

Property | Brief Description
DeleteOnExit | Controls behavior of virtual serial port when your application exits.
IsOpened | Checks the state of virtual serial port
InCount | Returns the amount of bytes currently stored in input buffer
IsCreated | Returns information about current virtual serial port state
CountVirtualPort | Returns information about number of virtual serial ports already created
HandleControl | Returns the handle of the controlling port
Parity | Returns Parity value of the controlling port
Stopbits | Returns Stopbits value of the controlling port
Databits | Returns Databits value of the controlling port
Baudrate | Returns Baudrate value of the controlling port
ControlHandShake | Returns ControlHandShake flags of the controlling port
FlowReplace | Returns FlowReplace flags of the controlling port

See also:

Virtual Serial Port Events Overview, Virtual Serial Port Methods Overview


Redistribution

Here is a step-by-step instruction how VSP ActiveX Control should be installed on target machines (you can include this as a part of your software installation). Please, note that you need to own OEM license to be able to redistribute Eltima Virtual Serial Port ActiveX Control without any limitations. Only OEM License grants commercial royalty-free redistribution rights.

Microsoft Windows 2000, XP

The following files should be copied to the target machine's temporary (permanent) installation directory. All these files can be found in the folder where you have VSP ActiveX Control installed. (You can find these files in NT5 directory).

File | Description
Vsb.inf | .INF file is needed for correct installation of virtual serial bus driver
Vsb.sys | Virtual Serial Bus Driver
Vsbsetup.exe | Executable that will silently install virtual serial bus driver
Vserial.inf | .INF file is needed for correct installation of virtual serial port driver
Vserial.sys | Virtual Serial Port driver
VSPort.dll | Virtual Serial Port ActiveX Control

After all these files are copied on target machine, your installation program should execute "vsbsetup.exe" without any parameters. This will register vsb.sys in the system and load it. "VSPort.dll" file should be marked as self-registering activex control or you can manually register it in the system by executing "regsvr32 VSPort.dll".

If you plan to provide end-customer with uninstall option, you should keep "vspsetup.exe" on target system. As soon as uninstallation is needed, you should execute "vspsetup.exe /u". This will safely remove virtual serial bus from target system. No reboot will be required. Also, do not forget to unregister VSPort.dll activex control.

Microsoft Windows XP, 2003 x64

The following files should be copied to the target machine's temporary (permanent) installation directory. All these files can be found in the folder where you have VSP ActiveX Control installed. (You can find these files in NT5x64 directory).

File | Description
Vsb.inf | .INF file is needed for correct installation of virtual serial bus driver
Vsb.sys | Virtual Serial Bus Driver
Vsbsetup.exe | Executable that will silently install virtual serial bus driver
Vserial.inf | .INF file is needed for correct installation of virtual serial port driver
Vserial.sys | Virtual Serial Port driver
VSPort.dll | Virtual Serial Port ActiveX Control

After all these files are copied on target machine, your installation program should execute "vsbsetup.exe" without any parameters. This will register vsb.sys in the system and load it. "VSPort.dll" file should be marked as self-registering activex control or you can manually register it in the system by executing "regsvr32 VSPort.dll".

If you plan to provide end-customer with uninstall option, you should keep "vspsetup.exe" on target system. As soon as uninstallation is needed, you should execute "vspsetup.exe /u". This will safely remove virtual serial bus from target system. No reboot will be required. Also, do not forget to unregister VSPort.dll activex control.

Microsoft Windows NT4

The following files should be copied to the target machine temporary (permanent) installation directory. All these files can be found in the folder where you have VSP ActiveX Control installed. (You can find these files in NT4 directory).

File | Description
Vsprt_nt4.sys | Virtual Serial Port Device Driver for NT4.
vsbsetupnt.exe | Executable that will silently install virtual serial port driver.
VSPort.dll | Virtual Serial Port ActiveX Control

After all these files are copied on target machine, your installation program should execute "vsbsetupnt.exe" without any parameters. This will register vsprt_nt4.sys in the system and load it. "VSPort.dll" file should be marked as a self-registering activex control or you can manually register it in the system by executing "regsvr32 VSPort.dll".

If you plan to provide end-customer with uninstall option, you should keep "vspsetupnt.exe" on target system. As soon as uninstallation is needed, you should execute "vspsetupnt.exe /u". This will safely remove virtual serial bus from target system. No reboot will be required. Also, do not forget to unregister VSPort.dll activex control.

Microsoft Windows 98/Me

The following files should be copied to the target machine temporary (permanent) installation directory. All these files can be found in the folder where you have VSP ActiveX Control installed. (You can find these files in Win9x directory).

File | Description
VSPD.VXD | Virtual Serial Port Device Driver for Windows 98/Me. Should be copied to SYSTEM directory (for example "C:\Windows\System")
VSPort.dll | Virtual Serial Port ActiveX Control

"VSPort.dll" file should be marked as self-registering activex control or you can manually register it in the system by executing "regsvr32 VSPort.dll".

Automatic installation

In case you would like to automate installation process on clients machine independently what version it runs you must copy all drivers in the following subdirectories where you have installed your application:

  • Win9x for Windows 9x versions
  • NT4 for Windows NT4
  • NT5 for Windows 2000, XP and 2003
  • NT5x64 for 64-bit Windows XP/2003 versions

Along mentioned drivers you must copy vspdxp_install.exe file. To start installation process issue vspdxp_install.exe command and in order to uninstall - vspdxp_install.exe/u.


DCB Structure

Attach Method

The Attach method opens existing virtual serial port, previously created by CreatePort method
BOOL Attach(
BSTR PortName // name of the virtual serial port
);

Parameters
PortName
[in] Name of the existing virtual serial port to be opened.

Return Values
If the function succeeds, the return value is TRUE. If the virtual serial port does not exist or no virtual serial bus is present in your system or virtual serial port is already assigned to another instance of VSP AX Control, the return value is FALSE.

Remarks
Use this method when you need to re-establish connection with existing virtual serial port, which was previously created by another instance of the control and connection was lost (your application exited without deleting virtual serial port).

See also

CreatePort method


CreatePort Method

The CreatePort method creates new virtual serial port.
BOOL CreatePort(
BSTR PortName // name of the virtual serial port
);

Parameters
PortName
[in] Name of virtual serial port to be created. Could be any but not longer than 128 characters

Return Values
If the function succeeds, the return value is TRUE. If the port is already created or no virtual serial bus is present in the system or virtual serial port could not be created for any other reason, the return value is FALSE.

Remarks
Use Delete method to delete created virtual serial port. If your program exits without calling Delete method, it will be called automatically in virtual serial port object destructor.

See also

Delete method , Attach method


Delete Method

The Delete method deletes virtual serial port.
BOOL Delete(
void
);

Return Values
If the function succeeds, the return value is TRUE. If the port was not created or it is currently used by other application, the return value is FALSE.

Remarks
Use Delete method to delete created virtual serial port. If your program exits without calling Delete method, it will be called automatically in virtual serial port object destructor.

See also

CreatePort method , DeleteOnExit property , Attach method


PurgeQueue Method

The PurgeQueue method discards all characters from the input buffer of the virtual serial port.
BOOL PurgeQueue(
void
);

Return Values
If the function succeeds, the return value is TRUE. If the port was not created the return value is FALSE.


EnumVirtualPort Method

The NumberPort method returns a name of virtual serial port specified by parameter NumberPort
BSTR EnumVirtualPort(
LONG NumberPort // port number obtained from CountVirtualPort property
);

Parameters
CountVirtualPort
[in] existing virtual serial port number.

Return Values
virtual serial port name such as COM1, COM2 etc.

Remarks

Method available for Windows NT4,2000/XP/2003 only


ResetBus Method

The ResetBus method resets virtual serial bus, deleting all virtual serial ports currently present in system.
BOOL ResetBus(
void
);

Return Values
If the function succeeds, the return value is TRUE. If the port was not created the return value is FALSE.


Read Method

The Read method reads data from virtual serial port input buffer.
LONG Read(
 | BYTE* Buffer , | // data buffer
 | LONG *Count | // number of bytes to read
);

Parameters
Buffer
[out] Pointer to the buffer that receives the data read from the virtual serial port.
Count
[in] Pointer to the number of bytes to be read from the port.

Return Values
The Read function returns the number of bytes received from virtual serial port.

Remarks
If virtual serial port was not created, the return value is 0 (zero).

See also

Write method , WriteStr method , ReadStr method , WriteArray method , ReadArray method,


ReadStr Method

The ReadStr method reads a string from virtual serial port input buffer.
BSTR ReadStr(
void
);

Return Values
The ReadStr function returns the string received from serial port.

Remarks
If virtual serial port was not created, the return value is 0 (zero).

See also

Write method , WriteStr method , Read method , WriteArray method , ReadArray method,


ReadArray Method

The ReadArray method reads data from virtual serial port input buffer and returns as VARIANT type variable of Byte array.
VARIANT ReadArray(
LONG Count // the number of bytes to read
);

Parameters
Count
[in] The number of bytes to be read from the port.

Return Values
The ReadArray read communication data from remote serial port and returns it as variable of VARIANT type of Byte array (VT_ARRAY | VT_UI1).

Remarks
If virtual serial port was not created, the return value is 0 (zero). This method is identical to Read, however is specially created for VB6, C#, VB.Net development environments.

See also

WriteArray method , Write method , WriteStr method , ReadStr method , Read method


SetBreak Method

The SetBreak method opens or close active virtual serial port
BOOL SetBreak(
BOOL bBreak // switch that specifies if port should be opened or closed
);

Parameters
bBreak
If value is set to TRUE then it method close currently active virtual serial port and if value is set to FALSE then method opens it

Return Values
If the function succeeds, the return value is TRUE. If the virtual serial port does not exist or no virtual serial bus is present in your system the return value is FALSE.

Remarks

Method available for Windows NT4,2000/XP/2003 only


SetCTS Method

The SetCTS method sets or clears CTS (clear-to-send) signal.
BOOL SetCTS(
BOOL On // Set or clear CTS signal
);

Parameters
On
[in] Determines setting or clearance CTS signal of a virtual serial port. This parameter can be any of the following values:
Value | Meaning
TRUE | Set the CTS signal
FALSE | Clear the CTS signal

Return Values
If the function succeeds, the return value is TRUE. If the CTS signal was not set/cleared the return value is FALSE.

See also:

SetDSR method , SerDCD method, SetRING method


SetDCD Method

The SetDCD method sets or clears DCD (carrier detect) signal on virtual serial port.
BOOL SetDCD(
BOOL On // Set or clear DCD signal
);

Parameters
On
[in] Determines setting or clearance DCD signal of a virtual serial port. This parameter can be any of the following values:
Value | Meaning
TRUE | Set the DCD signal
FALSE | Clear the DCD signal

Return Values
If the function succeeds, the return value is TRUE. If the DCD signal was not set/cleared the return value is FALSE.

See also:

SetCTS method , SetDSR method, SetRING method


SetDSR Method

The SetDSR method sets or clears DSR (data-set-ready) signal.
BOOL SetDSR(
BOOL On // Set or clear DSR signal
);

Parameters
On
[in] Determines setting or clearance DSR signal of a virtual serial port. This parameter can be any of the following values:
Value | Meaning
TRUE | Set the DSR signal
FALSE | Clear the DSR signal

Return Values
If the function succeeds, the return value is TRUE. If the DSR signal was not set/cleared the return value is FALSE.

See also:

SetCTS method , SetDCD method, SetRING method


SetRING Method

The SetRING method sets or clears RING signal on virtual serial port.
BOOL SetRING(
BOOL On // Set or clear RING signal
);

Parameters
On
[in] Determines setting or clearance RING signal of a virtual serial port. This parameter can be any of the following values:
Value | Meaning
TRUE | Set the RING signal
FALSE | Clear the RING signal

Return Values
If the function succeeds, the return value is TRUE. If the RING signal was not set/cleared the return value is FALSE.

See also:

SetCTS method , SetDCD method, SetDSR method


SetTimeouts Method

SetTimeouts method sets timeouts for virtual serial port. Timeout values set by Application are overridden.
BOOL SetTimeouts(
 | LONG ReadIntervalTimeout,
 | LONG ReadTotalTimeoutMultiplier,
 | LONG ReadTotalTimeoutConstant,
 | LONG WriteTotalTimeoutMultiplier,
 | LONG WriteTotalTimeoutConstant
);

Parameters
ReadIntervalTimeout
[in] Maximum time, in milliseconds, allowed to elapse between the arrival of two characters on the communications line.

ReadTotalTimeoutMultiplier
[in] Multiplier, in milliseconds, used to calculate the total timeout period for read operations. For each read operation, this value is multiplied by the requested number of bytes to be read.

ReadTotalTimeoutConstant
[in] Constant, in milliseconds, used to calculate the total timeout period for read operations. For each read operation, this value is added to the product of the ReadTotalTimeoutMultiplier member and the requested number of bytes.

WriteTotalTimeoutMultiplier
[in] Multiplier, in milliseconds, used to calculate the total timeout period for write operations. For each write operation, this value is multiplied by the number of bytes to be written.

WriteTotalTimeoutConstant
[in] Constant, in milliseconds, used to calculate the total timeout period for write operations. For each write operation, this value is added to the product of the WriteTotalTimeoutMultiplier member and the number of bytes to be written.

Remarks
Timeouts’ values set by the current method will affect the virtual ports that were already created as well as the ones that will be added in future.


SetStrictBaudrate Method

The SetStrictBaudrate method sets or clears strict Baudrate on virtual serial port. (Windows NT4,2000/XP/2003 only)
BOOL SetStrictBaudrate(
BOOL On // Set or clear strict Baudrate
);

Parameters
On
[in] Determines setting or clearance of strict Baudrate for a virtual serial port. This parameter can be any of the following values:
Value | Meaning
TRUE | Set the strict Baudrate
FALSE | Clear the strict Baudrate

Return Values
If the function succeeds, the return value is TRUE. If Baudrate was not set/cleared the return value is FALSE.


SetWiring Method

The SetWiring method sets connection type depending on parameters passed to this method
BOOL SetWiring(
 | LONG Dtr, | // Transmit line signal
 | LONG Rts, | // Receive line signal
 | LONG Out1, | // Output line signal
 | LONG Out2, | // Input line signal
);

Parameters
Dtr, Rst, Out1, Out2

[in] line signals may have following values depending on which port you want connect to:

Value | Meaning | Hex
WIRED_TO_DCD | setting connection to remote DCD line | 0x80
WIRED_TO_RI | setting connection to remote RI line | 0x40
WIRED_TO_DSR | setting connection to remote DSR line | 0x20
WIRED_TO_CTS | setting connection to remote CTS line | 0x10

Return Values
If the function succeeds, the return value is TRUE, alternatively, the return value is FALSE.

Remarks
Method available for Windows NT4,2000/XP/2003 only


Write Method

The Write method writes data to virtual serial port.
LONG Write(
 | BYTE* Buffer, | // data buffer
 | LONG Count | // number of bytes to write
);

Parameters
Buffer
[in] Pointer to the buffer containing the data to be written to the port.
Count
[in] Specifies the number of bytes to write to the port.

Return Values
The Write function returns the number of bytes sent to virtual serial port.

Remarks
If virtual serial port was not created, the return value is 0 (zero).

See also

Read method , ReadStr method , WriteStr method , WriteArray method


WriteStr Method

The WriteStr method writes a string into serial port.
LONG WriteStr(
BSTR Str, // data buffer
);

Parameters
Str
[in] The string that will be written to serial port.

Return Values
The WriteStr function returns the number of bytes written to virtual serial port.

Remarks
If virtual serial port was not created, the return value is 0 (zero).

See also

Read method , ReadStr method , Write method , WriteArray method


WriteArray Method

The WriteArray method writes data to virtual serial port as a BYTE array of VARIANT type.
LONG WriteArray(
VARIANT Buffer, // data buffer
);

Parameters
Buffer
[in] This is variable of VARIANT type that contains an array of Bytes (VT_ARRAY | VT_UI1).

Return Values
The WriteArray function returns the number of bytes written to virtual serial port.

Remarks
If virtual serial port was not created, the return value is 0 (zero). This method is identical to Write, however is specially created for VB6, C#, VB.Net development environments.

See also

Read method, ReadStr method, Write method, WriteStr method


OnBaudRate Event

The OnBaudRate event occurs when other application changes the baud rate for virtual serial port.
OnBaudRate(
LONG BaudRate // baud rate
);

Parameters
BaudRate
[out] Contains new baud rate for virtual serial port.


OnDTR Event

The OnDTR event occurs when other application changes the DTR (data-terminal-ready) signal state.
OnDTR(
BOOL On // DTR signal state
);

Parameters
On
[out] Determines the state of DTR signal. This parameter can be any of the following values:
Value | Meaning
TRUE | DTR signal sent
FALSE | DTR signal cleared

See also

OnRTS event


OnHandFlow Event

OnHandFlow Event

The OnHandFlow event occurs when other application changes flow control parameters for virtual serial port.
OnHandFlow(
 | LONG ControlHandShake, | // Handshake control parameter
 | LONG FlowReplace, | // Flow control parameter
 | LONG XOnLimit, | // Flow control parameter
 | LONG XOffLimit | // Flow control parameter
);

Parameters
ControlHandShake
[out] ControlHandShake is a set of flags that defines the modem lines that are used for flow control. Can be combination of the following flags:
Value | Meaning | Hex
SERIAL_DTR_CONTROL | Enables the DTR line when the device is opened and leaves it on. | 0x01
SERIAL_DTR_HANDSHAKE | Use the modem signal DTR for input flow control. For the real serial port the DTR line is cleared by the controller if the receive buffer reaches the programmed high water mark. See also description of XonLimit and XoffLimit. | 0x02
SERIAL_CTS_HANDSHAKE | Use the modem signal CTS, DCD or DSR respectively for output flow control. For the real serial port if the corresponding modem line(s) found as cleared, the controller will hold data transmission. | 0x08
SERIAL_DCD_HANDSHAKE |  | 0x20
SERIAL_DSR_HANDSHAKE |  | 0x10
SERIAL_DSR_SENSITIVITY | Ignore any character arriving when the DSR line is not set. | 0x40
SERIAL_ERROR_ABORT | If there exists an error condition the driver abort all read and writes to or from this port. | 0x80000000

FlowReplace
[out] FlowReplace is a set of flags defining flow control stuff. Can be combination of the following flags:
Value | Meaning | Hex
SERIAL_AUTO_TRANSMIT | Use the XON/XOFF protocol based flow control for output. | 0x01
SERIAL_AUTO_RECEIVE | Use the XON/XOFF protocol based flow control for input. | 0x02
SERIAL_ERROR_CHAR | If set, the ErrorChar is placed in the stream of received characters on error conditions like buffer overflow, frame errors and so on. | 0x04
SERIAL_NULL_STRIPPING | If set, the reception of a NULL character is ignored. | 0x08
SERIAL_BREAK_CHAR | If set, the BreakChar is placed in the stream of received characters when a break condition was detected. | 0x10
SERIAL_RTS_CONTROL | Enables the RTS line when the device is opened and leaves it on. | 0x40
SERIAL_RTS_HANDSHAKE | Use the modem signal RTS for input flow control. | 0x80

XOnLimit
[out] Minimum number of bytes allowed in the input buffer before flow control is activated to inhibit the sender.

XOffLimit
[out] Maximum number of bytes allowed in the input buffer before flow control is activated to allow transmission by the sender.


OnLineControl Event

The OnLineControl event occurs when other application changes line control parameters for virtual serial port.
OnLineControl(
 | BYTE StopBits, | // Stop Bits
 | BYTE Parity, | // Parity
 | BYTE WordLength | // Data Bits
);

Parameters
StopBits
[out] Number of stop bits to be used. This member can be one of the following values:
Value | Meaning
0 | 1 stop bit
1 | 1.5 stop bits
2 | 2 stop bits

Parity
[out] Parity scheme to be used. This member can be one of the following values:
Value | Meaning
0 | No parity
1 | Odd
2 | Even
3 | Mark
4 | Space

WordLength
[out] Number of bits in the bytes transmitted and received.


OnOpenClose Event

The OnOpenClose event occurs when other application opens or closes virtual serial port.
OnOpenClose(
BOOL Opened // Port state
);

Parameters
Opened
[out] Determines the state change of virtual serial port. This parameter can be any of the following values:
Value | Meaning
TRUE | Port was opened
FALSE | Port was closed


OnRTS Event

The OnRTS event occurs when other application changes the RTS (ready-to-send) signal state.
OnRTS(
BOOL On // RTS signal state
);

Parameters
On
[out] Determines the state of RTS signal. This parameter can be any of the following values:
Value | Meaning
TRUE | RTS signal sent
FALSE | RTS signal cleared

See also

OnDTR event


OnRxChar Event

The OnRxChar event occurs when at least one character was received and placed in the input buffer of the virtual serial port.
OnRxChar(
LONG Count // number of bytes
);

Parameters
Count
[out] Contains the number of the bytes currently available in the input buffer of the virtual serial port.

Remarks
Note, that the Count variable shows not the number of received bytes but the number of bytes currently available for read. This is the same value that could be received via InCount property.


DCB Structure

OnSpecialChars Event

The OnSpecialChars event occurs when other application changes special (event) characters for the virtual serial port.
OnSpecialChars(
 | CHAR EofChar,
 | CHAR ErrorChar,
 | CHAR BreakChar,
 | CHAR EventChar,
 | CHAR XOnChar,
 | CHAR XOffChar
);

Parameters
EofChar
[out] Value of the character used to signal the end of data.

ErrorChar
[out] Value of the character used to replace bytes received with a parity error.

BreakChar
[out] Value of the character used to signal break event.

EventChar
[out] Value of the character used to signal an event.

XOnChar
[out] Value of the XON character for both transmission and reception.

XOffChar
[out] Value of the XOFF character for both transmission and reception.


OnTimeouts Event

The OnTimeouts event occurs when other application changes the timeouts parameters of the virtual serial port. (Only Windows NT/2K/XP)
OnTimeouts(
 | LONG ReadIntervalTimeout,
 | LONG ReadTotalTimeoutMultiplier,
 | LONG ReadTotalTimeoutConstant,
 | LONG WriteTotalTimeoutMultiplier,
 | LONG WriteTotalTimeoutConstant
);

Parameters
ReadIntervalTimeout
[out] Maximum time, in milliseconds, allowed to elapse between the arrival of two characters on the communications line.

ReadTotalTimeoutMultiplier
[out] Multiplier, in milliseconds, used to calculate the total time-out period for read operations. For each read operation, this value is multiplied by the requested number of bytes to be read.

ReadTotalTimeoutConstant
[out] Constant, in milliseconds, used to calculate the total time-out period for read operations. For each read operation, this value is added to the product of the ReadTotalTimeoutMultiplier member and the requested number of bytes.

WriteTotalTimeoutMultiplier
[out] Multiplier, in milliseconds, used to calculate the total time-out period for write operations. For each write operation, this value is multiplied by the number of bytes to be written.

WriteTotalTimeoutConstant
[out] Constant, in milliseconds, used to calculate the total time-out period for write operations. For each write operation, this value is added to the product of the WriteTotalTimeoutMultiplier member and the number of bytes to be written.


OnEvent Event

The OnEvent event is triggered everytime a communication event occurs.
OnEvent(
LONG EvtMask
);

Parameters
EvtMask
[out] The variable that receives a mask indicating the type of event that occurred. Can be one of the following values.
Value | Meaning | Hex
VSERIAL_EV_RXCHAR | A character was received and placed in the input buffer. | 0x00000001
VSERIAL_EV_RTS | The RTS (request-to-send) signal changed state on the remote port. | 0x00000008
VSERIAL_EV_DTR | The DTR (request-to-send) signal changed state on the remote port. | 0x00000010
VSERIAL_EV_RING | A ring indicator was detected. | 0x00000100
VSERIAL_EV_REMOTE_OPENCLOSE | Remote port was opened or closed. | 0x80000000
VSERIAL_EV_REMOTE_LINECONTROL | Line control parameters were changed on the remote port. | 0x40000000
VSERIAL_EV_REMOTE_TIMEOUTS | Timeouts parameters were changed on the remote port. (Only Windows NT/2K/XP) | 0x40000000
VSERIAL_EV_REMOTE_QUEUESIZE | Queue size was changed on the remote port. | 0x20000000
VSERIAL_EV_REMOTE_CHARS | Special (event) characters were changed on the remote port. | 0x10000000
VSERIAL_EV_REMOTE_HANDFLOW | Flow control parameters were changed on the remote port. | 0x08000000
VSERIAL_EV_REMOTE_BAUDRATE | Baud rate was changed on the remote port. | 0x04000000

See also

OnBaudRate , OnDTR , OnHandFlow , OnLineControl , OnOpenClose , OnRxChar , OnRTS , OnSpecialChars , OnTimeouts


OnBreak Event

The OnBreak event occurs when other application changes the Break signal state.
OnBreak(
BOOL On // RTS signal state
);

Parameters
On
[out] Determines the state of Break signal. This parameter can be any of the following values:
Value | Meaning
TRUE | Break signal set
FALSE | Break signal cleared


HandleControl Property

The HandleControl property returns the handle of the controlling port.
LONG HandleControl;


CountVirtualPort Property

The CountVirtualPort property returns information about number of virtual serial ports already created.
LONG CountVirtualPort;

Remarks
If the virtual serial port was not created, the return value is zero. Property available for Windows NT4/2000/XP/2003.


InCount Property

The InCount property returns information about number of bytes received by the virtual serial port but not yet read by a Read operation
LONG InCount;

Remarks
If the virtual serial port was not created, the return value is zero.


DeleteOnExit Property

The DeleteOnExit property specifies whether to delete virtual serial port automatically when your application exits (TRUE) or not (FALSE).
BOOL DeleteOnExit;


IsCreated Property

The IsCreated property returns information about current virtual serial port state. It returns TRUE if virtual port have been already created and FALSE otherwise.
BOOL IsCreated;


IsOpened Property

The IsOpened property returns information about current virtual serial port state.
BOOL IsOpened;


Parity Property

The Parity property returns the current value of Parity control (none, odd, even, mark, or space). If serial port is not recreated, the property will return -1.
LONG Parity;


Stopbits Property

The Stopbits property returns the current value of bits used to indicate end of a byte. Stop bits could be 1, 1.5, or 2. If serial port is not recreated, the property will return -1.
LONG Stopbits;


Databits Property

The Databits property returns the current value of databits (number of data bits to transmit). DataBits to be equal to 5, 6, 7, or 8. If serial port is not recreated, the property will return -1.
LONG Databits;


Baudrate Property

The Baudrate property returns the current baudrate value. If serial port is not recreated, the property will return -1.
LONG Baudrate;


ControlHandShake Property

The ControlHandShake property returns set of flags that defines the modem lines that are used for flow control. For more information about possible values that ControlHandShake may have please check OnHandFlow Event. If serial port is not recreated, the property will return -1.
LONG ControlHandShake;


FlowReplace Property

The FlowReplace property returns a set of flags that define flow control value. For more information about possible values that FlowReplace may have please check OnHandFlow Event. If serial port is not recreated, the property will return -1.
LONG FlowReplace;


DCB Structure

The DCB structure defines the control setting for a serial communications device.

typedef struct _DCB {
  DWORD DCBlength;
  DWORD BaudRate;
  DWORD fBinary: 1;
  DWORD fParity: 1;
  DWORD fOutxCtsFlow:1;
  DWORD fOutxDsrFlow:1;
  DWORD fDtrControl:2;
  DWORD fDsrSensitivity:1;
  DWORD fTXContinueOnXoff:1;
  DWORD fOutX: 1;
  DWORD fInX: 1;
  DWORD fErrorChar: 1;
  DWORD fNull: 1;
  DWORD fRtsControl:2;
  DWORD fAbortOnError:1;
  DWORD fDummy2:17;
  WORD wReserved;
  WORD XonLim;
  WORD XoffLim;
  BYTE ByteSize;
  BYTE Parity;
  BYTE StopBits;
  char XonChar;
  char XoffChar;
  char ErrorChar;
  char EofChar;
  char EvtChar;
  WORD wReserved1;
} DCB;
MEMBERS
DCBlength
Length, in bytes, of the DCB structure.
BaudRate
Baud rate at which the communications device operates. This member can be an actual baud rate value, or one of the following indexes:

CBR_110
CBR_19200
CBR_300
CBR_38400
CBR_600
CBR_56000
CBR_1200
CBR_57600
CBR_2400
CBR_115200
CBR_4800
CBR_128000
CBR_9600
CBR_256000
CBR_14400

fBinary
Indicates whether binary mode is enabled. Windows does not support nonbinary mode transfers, so this member must be TRUE.
fParity
Indicates whether parity checking is enabled. If this member is TRUE, parity checking is performed and errors are reported.
fOutxCtsFlow
Indicates whether the CTS (clear-to-send) signal is monitored for output flow control. If this member is TRUE and CTS is turned off, output is suspended until CTS is sent again.
fOutxDsrFlow
Indicates whether the DSR (data-set-ready) signal is monitored for output flow control. If this member is TRUE and DSR is turned off, output is suspended until DSR is sent again.
fDtrControl
DTR (data-terminal-ready) flow control. This member can be one of the following values.

Value | Meaning
DTR_CONTROL_DISABLE | Disables the DTR line when the device is opened and leaves it disabled.
DTR_CONTROL_ENABLE | Enables the DTR line when the device is opened and leaves it on.
DTR_CONTROL_HANDSHAKE | Enables DTR handshaking. function.

fDsrSensitivity
Indicates whether the communications driver is sensitive to the state of the DSR signal. If this member is TRUE, the driver ignores any bytes received, unless the DSR modem input line is high.
fTXContinueOnXoff
Indicates whether transmission stops when the input buffer is full and the driver has transmitted the XoffChar character. If this member is TRUE, transmission continues after the input buffer has come within XoffLim bytes of being full and the driver has transmitted the XoffChar character to stop receiving bytes. If this member is FALSE, transmission does not continue until the input buffer is within XonLim bytes of being empty and the driver has transmitted the XonChar character to resume reception.
fOutX
Indicates whether XON/XOFF flow control is used during transmission. If this member is TRUE, transmission stops when the XoffChar character is received and starts again when the XonChar character is received.
fInX
Indicates whether XON/XOFF flow control is used during reception. If this member is TRUE, the XoffChar character is sent when the input buffer comes within XoffLim bytes of being full, and the XonChar character is sent when the input buffer comes within XonLim bytes of being empty.
fErrorChar
Indicates whether bytes received with parity errors are replaced with the character specified by the ErrorChar member. If this member is TRUE and the fParity member is TRUE, replacement occurs.
fNull
Indicates whether null bytes are discarded. If this member is TRUE, null bytes are discarded when received.
fRtsControl
RTS (request-to-send) flow control. This member can be one of the following values.

Value | Meaning
RTS_CONTROL_DISABLE | Disables the RTS line when the device is opened and leaves it disabled.
RTS_CONTROL_ENABLE | Enables the RTS line when the device is opened and leaves it on.
RTS_CONTROL_HANDSHAKE | Enables RTS handshaking. The driver raises the RTS line when the "type-ahead" (input) buffer is less than one-half full and lowers the RTS line when the buffer is more than three-quarters full. If handshaking is enabled, it is an error for the application to adjust the line by using the EscapeCommFunction function.
RTS_CONTROL_TOGGLE | Windows NT/2000/XP: Specifies that the RTS line will be high if bytes are available for transmission. After all buffered bytes have been sent, the RTS line will be low.

fAbortOnError
Indicates whether read and write operations are terminated if an error occurs. If this member is TRUE, the driver terminates all read and write operations with an error status if an error occurs.
fDummy2
Reserved; do not use.
wReserved
Reserved; must be zero.
XonLim
Minimum number of bytes allowed in the input buffer before flow control is activated to inhibit the sender. Note that the sender may transmit characters after the flow control signal has been activated, so this value should never be zero. This assumes that either XON/XOFF, RTS, or DTR input flow control is specified in fInX, fRtsControl, or fDtrControl.
XoffLim
Maximum number of bytes allowed in the input buffer before flow control is activated to allow transmission by the sender. This assumes that either XON/XOFF, RTS, or DTR input flow control is specified in fInX, fRtsControl, or fDtrControl. The maximum number of bytes allowed is calculated by subtracting this value from the size, in bytes, of the input buffer.
ByteSize
Number of bits in the bytes transmitted and received.
Parity
Parity scheme to be used. This member can be one of the following values.

Value | Meaning
EVENPARITY | Even
MARKPARITY | Mark
NOPARITY | No parity
ODDPARITY | Odd
SPACEPARITY | Space

StopBits
Number of stop bits to be used. This member can be one of the following values.

Value | Meaning
ONESTOPBIT | 1 stop bit
ONE5STOPBITS | 1.5 stop bits
TWOSTOPBITS | 2 stop bits

XonChar
Value of the XON character for both transmission and reception.
XoffChar
Value of the XOFF character for both transmission and reception.
ErrorChar
Value of the character used to replace bytes received with a parity error.
EofChar
Value of the character used to signal the end of data.
EvtChar
Value of the character used to signal an event.
wReserved1
Reserved; do not use.
REMARKS

When a DCB structure is used to configure the 8250, the following restrictions apply to the values specified for the ByteSize and StopBits members:

  • The number of data bits must be 5 to 8 bits.
  • The use of 5 data bits with 2 stop bits is an invalid combination, as is 6, 7, or 8 data bits with 1.5 stop bits.


Handflow to DCB translation

DCB Field | VSP Handflow Flag | VSP Handflow Parameter
fDtrControl | SERIAL_DTR_HANDSHAKE SERIAL_DTR_CONTROL | ControlHandShake
fOutxCtsFlow | SERIAL_CTS_HANDSHAKE | ControlHandShake
fOutxDsrFlow | SERIAL_DSR_HANDSHAKE | ControlHandShake
fDsrSensitivity | SERIAL_DSR_SENSITIVITY | ControlHandShake
fAbortOnError | SERIAL_ERROR_ABORT | ControlHandShake
fOutX | SERIAL_AUTO_TRANSMIT | FlowReplace
fInX | SERIAL_AUTO_RECEIVE | FlowReplace
fErrorChar | SERIAL_ERROR_CHAR | FlowReplace
fNull | SERIAL_NULL_STRIPPING | FlowReplace
fRtsControl | SERIAL_RTS_HANDSHAKE SERIAL_RTS_CONTROL | FlowReplace
XOnLim | - | XOnLimit
XOffLim | - | XOffLimit

See also

Virtual Serial Port Methods Overview