PointCardRW Class (POS for .NET v1.12 SDK Documentation)
2/27/2008
Defines the programmatic interface for a UPOS Point Card Reader/Writer device.
Namespace: Microsoft.PointOfService
Assembly: Microsoft.PointOfService (in microsoft.pointofservice.dll)
Syntax
'Declaration
Public MustInherit Class PointCardRW
Inherits PosCommon
public abstract class PointCardRW : PosCommon
public ref class PointCardRW abstract : public PosCommon
public abstract class PointCardRW extends PosCommon
public abstract class PointCardRW extends PosCommon
Remarks
Capabilities
The point card reader/writer has the following capabilities:
Supports reading and writing of the magnetic data of the point card.
Supports reading and writing of data from up to six tracks. The data on the tracks is in a device-specific format. For more information, see the device manual for specific definitions. The data is usually in ASCII format.
Supports point cards with or without a printing area. Actual printing support depends on the capabilities of the device.
Supports both card insertion and ejection.
No special security capabilities, for example, encryption, are supported.
Model
The point card reader/writer reads all the magnetic stripes on a point card. The data length and reading information are put in the property that corresponds to a track.
The point card reader/writer follows the input model of event-driven input during the card insertion process. Also, writing to the printing area and the magnetic stripe follows the output model.
Input Model
An application must call the Open and Claim methods, and then set the DeviceEnabled property to true.
When an application wants a card inserted, it calls the BeginInsertion method, specifying a time-out value.
If a card is not inserted before the time-out period elapses, the point card reader/writer returns an error.
Even if a time-out occurs, the point card reader/writer remains in Insertion mode. If the application still wants a card inserted, it must call the BeginInsertion method again.
To exit insertion mode after a card was inserted or when the application wants to end insertion, the application calls the EndInsertion method.
If there is a point card in the point card reader/writer when the EndInsertion method is called, the point card's data tracks are automatically read and a DataEvent event is queued. When the application sets the DataEventEnabled property to true, the DataEvent event is delivered.
If an error occurs while it reads the point card's data tracks, an ErrorEvent event is queued instead of a DataEvent event. When the application sets the DataEventEnabled property to true, the ErrorEvent event is delivered.
The application can obtain the current number of queued data events by reading the DataCount property.
All queued but undelivered input can be deleted by calling the ClearInput method.
Output Model
To write data to a card, the application calls the PrintWrite method. The ability to write data depends on the capabilities of the device.
The PrintWrite method is always performed asynchronously. All asynchronous output is performed on a first-in, first-out basis.
When the application calls the PrintWrite method, the point card reader/writer assigns a unique identification number for this request. This ID is stored in the OutputId property The point card reader/writer then either queues the request or starts its processing. Either way, the point card reader/writer returns to the application quickly.
When the PrintWrite method is complete, an OutputCompleteEvent event is delivered to the application. The OutputId property associated with the completed request is passed in the OutputCompleteEvent event.
If the PrintWrite method fails during its processing, an ErrorEvent event is delivered to the application. If the application has multiple outstanding output requests, the OutputId property of the request that failed can be determined by watching which requests have successfully completed by monitoring OutputCompleteEvent events. The request that failed is the one that was issued immediately after the last request that successfully completed.
All incomplete output requests can be deleted by calling the ClearOutput method. This method also stops any output that is in progress, if it is possible. No OutputCompleteEvent events are delivered for output requests stopped in this manner.
When done accessing the point card, the application calls the BeginRemoval method, specifying a Timeout value.
If the card is not removed before the time-out period elapses, the point card reader/writer returns an error.
Even if a time-out occurs, the point card reader/writer remains in Removal mode. If the application still wants the card removed, it must call the BeginRemoval method again.
To exit Removal mode, after the card was physically removed or the application wants to end removal, the application calls the EndRemoval method.
Printing Capability
The point card reader/writer supports devices that allow for rewriting the print area of a card.
The point card reader/writer supports printing specified either by dot units or by line units. When the CapPrintMode property is true, the unit type is determined by the value of the MapMode property. When the CapPrintMode property is false, the unit type is defined as lines.
The data to print is passed to the PrintWrite method as the data parameter. Special character modifications, such as double height, depend on the capabilities of the device. The verticalPosition and horizontalPosition parameters indicate the vertical and horizontal start position respectively, expressed in units defined by the MapMode property value.
When using line units, the start position for lines that contains both single and double-high characters is the top of a single-high character for horizontal printing and the bottom of all characters for vertical printing.
Cleaning Capability
The point card reader/writer must be cleaned to prevent errors caused by dirt build-up inside the device.
A special cleaning card is used: either a wet card (such as a card wet with ethanol before use) or a dry card.
To clean, the inserted cleaning card makes several passes over the read heads inside the device.
Some point card reader/writers perform the cleaning operation by use of a switch on the device. Other point card reader/writers perform the cleaning operation completely under control of the application.
Initialization of Magnetic Stripe Data
Some point card reader/writers can initialize the magnetic stripe data to prevent the illegal use of a point card.
Three initialization techniques can be used for point card reader/writers:
Initialize all the data. This includes the start sentinel, end sentinel, and a correct LRC.
Write an application-specific code into the data area by using no sentinels.
Initialize all tracks to empty by writing only start and end sentinels.
Initialization of the magnetic stripe depends on the capability of the device.
Device Sharing
The point card reader/writer is an exclusive-use device, as follows:
The application must claim the device before the application enables it.
The application must claim and enable the device before accessing many point card reader/writer-specific properties.
The application must claim and enable the device before it calls methods that manipulate the device.
Data Characters and Escape Sequences
The default character set of all point card reader/writers is assumed to support at least the ASCII characters 0x20 through 0x7F. This include spaces, digits, uppercase, lowercase, and some special characters. If the point card reader/writer does not support lowercase characters, the service object can translate them to uppercase.
Every escape sequence begins with the escape character ESC, whose value is 27 decimal, followed by a vertical bar (|). This is followed by zero or more digits and lowercase alphabetic characters. The escape sequence is closed by an uppercase alphabetic character. Sequences that do not begin with ESC | are passed through to the point card reader/writer. Also, sequences that begin with ESC | but which are not valid OPOS for .NET escape sequences are passed through to point card reader/writer.
To determine whether escape sequences or data can be performed on point card reader/writer, the application can call the ValidateData method. (For some escape sequences, corresponding capability properties can also be used.)
The following escape sequences are recognized. If an escape sequence specifies an operation that is not supported by the point card reader/writer, then it is ignored.
Print Mode.Characteristics that are remembered until explicitly changed.
Name |
Data |
Remarks |
Font typeface selection |
ESC |#fT |
Selects a new typeface for the following data. Values for the character '#' are as follows: 0 = Default typeface.1 = Select first typeface from the FontTypefaceList property.2 = Select second typeface from the FontTypefaceList property,and so on. |
Print Lin.Characteristics that are reset at the end of each print method or by a “Normal” sequence.
Name |
Data |
Remarks |
Bold |
ESC |bC |
Prints in bold or double-strike. |
Underline |
ESC |#uC |
Prints with underline. The character '#' is replaced by an ASCII decimal string telling the thickness of the underline in printer dot units. If '#' is omitted, then a printer-specific default width is used. |
Italic |
ESC |iC |
Prints in italic. |
Reverse video |
ESC |rvC |
Prints in a reverse-video format. |
Single high and wide |
ESC |1C |
Prints normal size. |
Double wide |
ESC |2C |
Prints double-wide characters. |
Double high |
ESC |3C |
Prints double-high characters. |
Double high and wide |
ESC |4C |
Prints double-high/double-wide characters. |
Scale horizontally |
ESC |#hC |
Prints with the width scaled '#' times the normal size, where '#' is replaced by an ASCII decimal string. |
Scale vertically |
ESC |#vC |
Prints with the height scaled '#' times the normal size, where '#' is replaced by an ASCII decimal string. |
Center |
ESC |cA |
Aligns following text in the center. |
Right justify |
ESC |rA |
Aligns following text at the right side. |
Normal |
ESC |N |
Restores printer characteristics to normal condition. |
Inheritance Hierarchy
System.Object
Microsoft.PointOfService.PosDevice
Microsoft.PointOfService.PosCommon
Microsoft.PointOfService.PointCardRW
Microsoft.PointOfService.BasicServiceObjects.PointCardRWBasic
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread-safe. Any instance members are not guaranteed to be thread-safe.