PosPrinter Class

2/27/2008

Defines the programmatic interface for a UPOS Printer device.

Namespace: Microsoft.PointOfService
Assembly: Microsoft.PointOfService (in microsoft.pointofservice.dll)

Syntax

'Declaration
Public MustInherit Class PosPrinter
    Inherits PosCommon

public abstract class PosPrinter : PosCommon

public ref class PosPrinter abstract : public PosCommon

public abstract class PosPrinter extends PosCommon

public abstract class PosPrinter extends PosCommon

Remarks

PosPrinter class defines three printer "stations," as follows:

• Journal. Used for simple text messages that log transaction and activity information kept by the store for audit and other purposes.

• Receipt. Used to print transaction information (typically given to the customer), or for store reports. Receipt contains either a knife to automatically cut the paper between transactions, or a tear bar to manually cut the paper.

• Slip. Used to print information on a form (typically given to the customer), or to print "validation" information on a form. The form type is usually a check or credit card slip.

  Sometimes, limited forms-handling capability is integrated with the receipt or journal station to allow validation printing. Frequently this limits the number of print lines, because of the station’s forms-handling throat depth. The service object nevertheless addresses this printer functionality as a slip station.

The default character set of POS printers can print ASCII characters 0x20 through 0x7F. This include space, digits, uppercase, lowercase, and some special characters. (If the Printer device does not support all these. Then it should translate them to close approximations, for example, lowercase to uppercase.)

POS Printer devices may have several additional capabilities. See the capabilities properties for specific information.

POS Printer devices use the general output programming model, with some improvements:

• The following methods are always performed synchronously: BeginInsertion, EndInsertion, BeginRemoval, EndRemoval, ChangePrintSide, and CheckHealth. These methods will fail if asynchronous output is outstanding.

• The PrintImmediate method is also always performed synchronously. PrintImmediate tries to print its data immediately (that is, as the very next printer operation). It can be called when asynchronous output is outstanding. PrintImmediate is primarily intended for use in exception conditions when asynchronous output is outstanding.

• The following methods are performed either synchronously or asynchronously, depending on the value of the AsyncMode property: PrintNormal, PrintTwoNormal, CutPaper, RotatePrint, PrintBarCode, PrintBitmap, TransactionPrint, and MarkFeed. When the AsyncMode property is set to false, these methods print synchronously and return their completion status to the application.

• When AsyncMode is set to true, these methods operate as follows:

  • The service object buffers the request, sets the OutputID property to an identifier for this request, and returns as soon as possible. When the device successfully completes the request, the service object raises an OutputCompleteEvent event. A parameter of this event contains the Output ID of the completed request.

    Asynchronous printer methods will not return an error status because of a printing problem, such as out of paper or printer fault. These errors will be reported only by an ErrorEvent event. An error status is returned only if the printer is not claimed and enabled, a parameter is invalid, or the request cannot be queued. The first two error cases are because of an application error. The last is a serious system resource exception.

  • If an error occurs when it performs an asynchronous request, the service object queues an ErrorEvent event and delivers it. The ErrorStation property is set to the station or stations that were printing when the error occurred. The ErrorLevel and ErrorString properties are also set.

    The event handler can call synchronous print methods (but not asynchronous methods), can then either retry the outstanding output or clear it.

  • The service object guarantees that asynchronous output is performed on a first-in first-out basis.

  • All output buffered by the application can be deleted by calling the ClearOutput method. OutputCompleteEvent events will not be raised for cleared output. This method also stops any output that may be in progress (when it is possible).

  • The property FlagWhenIdle can be set to cause the service object to raise a StatusUpdateEvent event when all outstanding outputs have finished, whether successfully or because they were cleared.

Transaction Mode

The transaction mode model is as follows:

• A transaction is a sequence of print operations that is printed to a station as a unit. Print operations that can be included in a transaction are PrintNormal, CutPaper, RotatePrint, PrintBarCode, PrintBitmap, and MarkFeed. During a transaction, the print operations are first validated. If valid, they are added to the transaction but not yet printed. After the application has added as many operations as required, it calls the TransactionPrint method.

• If the transaction is printed synchronously, the returned status indicates either that the transaction printed successfully or that an error occurred during the print. If the transaction is printed asynchronously, the asynchronous print rules listed here are followed. If an error occurs and the ErrorEvent handler causes a retry, the transaction is retried.

Page Mode

Page Mode printing support is modeled after Transaction Mode printing support.  All activities within Page Mode are handled and recovered as a single entity.  Page Mode support lets the user dynamically compose complex page printouts by using the PrintNormal, PrintBitmap, and PrintBarcode methods and additional Page Mode methods and properties. Composed pages can be printed, saved, and modified multiple times as long as Page Mode is active.

PrintCartridge Mode

The print cartridge model is as follows:

• The application uses the CapJrnCartridgeSensor, CapRecCartridgeSensor, and CapSlpCartridgeSensor properties to determine whether the printer can detect the operating condition of the cartridge.

• Before it determines a cartridge’s operating condition, the application selects a cartridge by using the JrnCurrentCartridge, RecCurrentCartridge, or SlpCurrentCartridge property.

• The condition of the selected cartridge is set up by the service object by using one of the JrnCartridgeState, RecCartridgeState, or SlpCartridgeState properties. The values that these properties are can include order of high priority to low priority as follows: Unknown, Removed, Empty, Cleaning, NearEnd, OK.

• The application uses the CapJrnColor and CapRecColor properties to determine the color capabilities of the station.

• For Mono Color,

  • The CapJrnColor, CapRecColor, and CapSlpColor properties equal Primary.

• For 2 Color,

  • The CapJrnColor, CapRecColor, and CapSlpColor properties are a logical OR combination of Primary and Custom1.

  • Custom1 refers to the secondary color, usually red.

  • Secondary color printing can be done by using the ESC|rC escape sequence.

• For Custom Color,

  • The CapJrnColor, CapRecColor, and CapSlpColor properties are a logical OR combination of Primary and any of the following bit values:Custom1, Custom2, Custom3, Custom4, Custom5, Custom6.

  • Selection of a custom color can be done by using the ESC|#rC escape sequence.

• For Full Color,

  • The CapJrnColor, CapRecColor, and CapSlpColor properties are a logical OR combination of Full and the following values: Cyan, Magenta, Yellow.

  • Full is not used to indicate that a print cartridge is currently installed in the printer. Instead, it is used to indicate that the printer can print in a full color mode.

  • Full color printing is done by using the ESC|#fC command.

• For Full Color with Custom Color(s),

  • CapJrnColor, CapRecColor, and CapSlpColor are a logical OR combination of the settings for custom color values and Full.

The print cartridge state reporting model is as follows:

• The application can set the CartridgeNotify property to enable cartridge state reporting by using StatusUpdateEvent events and the JrnCartridgeState, RecCartridgeState, and SlpCartridgeState properties. CartridgeNotify can be set only before the device is enabled (that is, before the DeviceEnabled property is set to true). This restriction allows for simpler implementation of cartridge status notification without a adverse effects on the application. The application is either prepared to receive notifications or does not want them, and has no need to switch between these cases. The CartridgeNotify property can be set to:

  • Disabled

  • Enabled

The following semantics are added to device enabling (setting the DeviceEnabled property to true) when the CapJrnCartridgeSensor, CapRecCartridgeSensor, and CapSlpCartridgeSensor properties are not 0 and CartridgeNotify is set to Enabled:

• Monitoring the cartridge state begins when the service object detects that the DeviceEnabled property has changed from false to true.

• When the service object detects that DeviceEnabled has been changed from true to false, the state of the cartridge is no longer valid. Therefore, the service object sets JrnCartridgeState, RecCartridgeState, and SlpCartridgeState properties to Unknown.

The POS printer is an exclusive-use device. Therefore:

• The application must claim the device before the application enables it.

• The application must claim and enable the device before accessing many of the printer-specific properties.

• The application must claim and enable the device before the application calls methods that manipulate the device.

The default character set of all POS for .NET printers is assumed to support at least the ASCII characters 20-hex through 7F-hex. This include spaces, digits, uppercase, lowercase, and some special characters. If the printer 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 stopped by an uppercase alphabetic character. Sequences that do not begin with ESC "|" are passed through to the printer. Also, sequences that begin with ESC "|" but are not valid POS for .NET escape sequences are passed through to the printer.

To determine whether escape sequences or data can be performed on a printer station, 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 printer station, it is ignored.

One Shots - Perform indicated action.

Print Mode - Characteristics that are remembered until explicitly changed.

Print Line - Characteristics that are reset at the end of each print method or by a "Normal" sequence.

Inheritance Hierarchy

System.Object
   Microsoft.PointOfService.PosDevice
     Microsoft.PointOfService.PosCommon
      Microsoft.PointOfService.PosPrinter
         Microsoft.PointOfService.BasicServiceObjects.PosPrinterBasic

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.

See Also

Reference

PosPrinter Members
Microsoft.PointOfService Namespace