Export (0) Print
Expand All

PosPrinter Class (POS for .NET v1.12 SDK Documentation)

2/27/2008

Defines the programmatic interface for a UPOS Printer device.

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

public abstract class PosPrinter : PosCommon
public abstract class PosPrinter extends PosCommon
public abstract class PosPrinter extends PosCommon

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.

Name

Data

Remarks

Paper cut

ESC|#P

Cuts receipt paper. The character ‘#’ is replaced by an ASCII decimal string telling the percentage cut desired. If ‘#’ is omitted, a full cut is performed. For example, the C string "\x1B|75P" requests a 75% partial cut.

Feed and Paper cut

ESC|#fP

Cuts receipt paper, after feeding the paper the number of lines specified by the RecLinesToPaperCut property. The character ‘#’ is defined by the "Paper cut" escape sequence.

Feed, Paper cut, and Stamp

ESC|#sP

Cuts and stamps receipt paper, after feeding the paper by the number of lines specified by the RecLinesToPaperCut property. The character ‘#’ is defined by the "Paper cut" escape sequence.

Fire stamp

ESC|sL

Raises the stamp solenoid that usually contains a graphical store emblem.

Print bitmap

ESC|#B

Prints the pre-stored bitmap. The character ‘#’ is replaced by the bitmap number.

Print top logo

ESC|tL

Prints the pre-stored top logo.

Print bottom logo

ESC|bL

Prints the pre-stored bottom logo.

Feed lines

ESC|#lF

Feed the paper forward by the specified lines. The character ‘#’ is replaced by an ASCII decimal string telling the number of lines to be fed. If ‘#’ is omitted, then one line is fed.

Feed units

ESC|#uF

Feed the paper forward by mapping mode units. The character ‘#’ is replaced by an ASCII decimal string telling the number of units to be fed. If ‘#’ is omitted, then one unit is fed.

Feed reverse

ESC|#rF

Feed the paper backward by the specified lines. The character ‘#’ is replaced by an ASCII decimal string telling the number of lines to be fed. If ‘#’ is omitted, then one line is fed.

Print Mode - Characteristics that are remembered until explicitly changed.

Name

Data

Remarks

Font font selection

ESC|#fT

Selects a new font for the following data. Values for the character ‘#’ are as follows:

0 = Default font.1 = Select first font from the FontTypefaceList property.2 = Select second font from the FontTypefaceList property.And so on.

Print Line - 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 thickness is used.

Italic

ESC|iC

Prints in italic.

Alternate color (Custom)

ESC|#rC

Prints by using an alternate custom color. The character ‘#’ is replaced by an ASCII decimal string that indicates the desired color. The value of the decimal string is equal to the value of the cartridge constant used in the Printer device properties. If ‘#’ is omitted, the secondary color (Custom Color 1) is selected. Custom Color 1 is usually red.

Reverse video

ESC|rvC

Prints in a reverse video format.

Shading

ESC|#sC

Prints in a shaded manner. The character ‘#’ is replaced by an ASCII decimal string telling the percentage shading desired. If ‘#’ is omitted, then a printer-specific default level of shading is used.

Single high & wide

ESC|1C

Prints normal size.

Double-wide

ESC|2C

Prints double-wide characters.

Double-high

ESC|3C

Prints double-high characters.

Double-high & wide

ESC|4C

Prints double-high and 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.

RGB color

ESC|#fC

Prints in # color. The character ‘#’ is replaced by an ASCII decimal string that indicates the additive amount of RGB to produce the desired color. There are 3 digits each of Red, Green, and Blue elements. Valid values range from "000" to "255". (For example, "255255000" represents yellow.) Color matching to the subtractive percentage of CMY (Cyan, Magenta, and Yellow components) to produce the desired color specified by the RGB is up to the service object. If ‘#’ is omitted, the primary color is used. Bitmap printing is not affected.

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.

SubScript

ESC|tbC

Prints subscript characters.

SuperScript

ESC|tpC

Prints superscript characters.


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

Any public static (Shared in Visual Basic) members of this type are thread-safe. Any instance members are not guaranteed to be thread-safe.
Show:
© 2014 Microsoft