English site 日本語サイト

3.3. IPort

Class to communicate with a printer.

• Property

  Name	Contents
  PortName	Get the portName when the port is opened.
  PortSettings	Get the portSettings when the port is opened.
  Timeout	Get the timeout when the port is opened.
  HoldPrintTimeout	Set the timeout value for hold print control.

• Method

  Name	Contents
  WritePort	Write data to the printer.
  ReadPort	Read data from the printer.
  GetParsedStatus	Get printer status.
  GetOnlineStatus	Gets printer online status.
  BeginCheckedBlock	Starts to check completion of printing.
  EndCheckedBlock	Terminates to check completion of printing.
  ResetDevice	Reset hardware.
  GetFirmwareInformation	Gets printer model name and firmware version.

3.3.1. Printing flow

Using the SMPort class, print per the following procedure.

• Examples

  byte[] command = new byte[] { 0x41, 0x42, 0x43, 0x44, 0x1B, 0x7A, 0x00, 0x1B, 0x64, 0x02 };
  IPort port = null;
  
  try
  {
  　port = Factory.I.GetPort("BT:COM1", "", 10000);
  
      // Start to check the completion of printing
  　StarPrinterStatus status = port.BeginCheckedBlock();
  
      if (status.Offline)
      {
          // There was an error writing to the port
      }
  
      uint writtenLength = port.WritePort(command, 0, (uint)command.Length);
  
      // Stop to check the completion of printing
  　  status = port.EndCheckedBlock();
  
      if (status.Offline)
      {
          // There was an error writing to the port
      }
  }
  catch (PortException)
  {
      // There was an error writing to the port
  }
  finally
  {
      Factory.I.ReleasePort(port);
  }
  

  Refer to Communication.cs.

3.3.2. PortName

Get the portName specified by GetPort.

• Declaration

  string PortName { get; }
  

3.3.3. PortSettings

Gets the portSettings of the GetPort method.

• Declaration

  string PortSettings { get; }
  

3.3.4. Timeout

Gets the timeoutMillis of the GetPort method.

• Declaration

  uint Timeout { get; }
  

3.3.5. HoldPrintTimeout

added in version 2.7.0

Timeout value for hold print control. [unit: ms]

• Declaration

  int HoldPrintTimeout { get; set; }
  

3.3.6. WritePort

Write data to the printer.

• Declaration

  uint WritePort(byte[] writeBuffer, uint offset, uint size);
  

• Parameter

  Name	Contents	Type
  writeBuffer	Contains the output data in a byte array	byte[]
  offset	Specifies where to begin pulling data from writeBuffer.	uint
  size	Number of bytes to write	uint

• Return value

  Contents	Type
  Written data size	uint

• Exception

  Contents	Type
  when a communication failure occurs	PortException

• Error code

  Value	Contents
  StarResultCode.ErrorFailed	Some kind of error occurred.

Refer to the printing process flow .

3.3.7. ReadPort

Read data from the printer. Please use it only when it is necessary to read Raw byte from the printer.

• Declaration

  uint ReadPort(ref byte[] readBuffer, uint offset, uint size);
  

• Parameter

  Name	Contents	Type
  readBuffer	A Byte Array buffer into which data is read.	byte[]
  offset	specifies where to begin writing data into the readBuffer	uint
  size	Total number of bytes to read	uint

• Return value

  Contents	Type
  The number of bytes that were read This method will succeed even when no all data was read in. Your application should call this function a limited number of times until the expected data has been read in or until an application determined retry threshold has been reached.	uint

• Exception

  Contents	Type
  when a communication failure occurs	PortException

• Error code

  Value	Contents
  StarResultCode.ErrorFailed	Some kind of error occurred.

Important

Restrictions when using a USB connection

If a response of 512 bytes or more is generated from the printer, specify 512 bytes or more for the arguments readBuffer and size.

If you specify less than 512 bytes, you may not be able to read the response.

3.3.8. GetParsedStatus

Get printer status.

• Declaration

  StarPrinterStatus GetParsedStatus();
  

• Parameter

  None

• Return value

  Contents	Type
  Current printer status For the type of status that can be obtained, refer to the StarPrinterStatus structure.	StarPrinterStatus

• Exception

  Contents	Type
  when a communication failure occurs	PortException

• Error code

  Value	Contents
  StarResultCode.ErrorFailed	Some kind of error occurred.

3.3.9. GetOnlineStatus

Gets printer online status.

• Declaration

  bool GetOnlineStatus();
  

• Parameter

  None

• Return value

  Contents	Type
  Online status of the printer true … Online false … Offline	bool

• Exception

  Contents	Type
  when a communication failure occurs	PortException

• Error code

  Value	Contents
  StarResultCode.ErrorFailed	Some kind of error occurred.

3.3.10. BeginCheckedBlock

This method is used in combination with EndCheckedBlock and checks the completion of printing.

To check if the whole data is completely printed, you need to run this method just before sending print data and EndCheckedBlock just after sending print data.

When the control of hold print control is enabled, this method blocks until the paper is removed, and returns control to the application when it is removed. If paper is not removed within the timeout specified by the HoldPrintTimeout, the error is occured.

• Declaration

  StarPrinterStatus BeginCheckedBlock();
  

• Parameter

  None

• Return value

  Contents	Type
  Current printer status For the type of status that can be obtained, refer to the StarPrinterStatus structure.	StarPrinterStatus

• Exception

  Contents	Type
  when a communication failure occurs when the printer is off line	PortException

• Error code

  Value	Contents	Library version
  StarResultCode.ErrorPaperPresent	Paper was not removed within the timeout.	2.7.0+
  StarResultCode.ErrorFailed	Some kind of error occurred.	2.3.0+

• Examples

  Refer to Printing flow about the procedure of the print end monitoring process by BeginCheckedBlock / EndCheckedBlock.

3.3.11. EndCheckedBlock

This method is used together with the BeginCheckedBlock method as a pair.

This method monitors printer status and when the transferred data is printed completely or when the printer status is offline during printing or when occurs the timeout specified by the GetPort , it returns control to the application.

• Declaration

  StarPrinterStatus EndCheckedBlock();
  

• Parameter

  None

• Return value

  Contents	Type
  Current printer status For the type of status that can be obtained, refer to the StarPrinterStatus structure.	StarPrinterStatus

• Exception

  Contents	Type
  when a communication failure occurs No response for the completion of printing from a printer within the timeout	PortException

• Error code

  Value	Contents
  StarResultCode.ErrorFailed	Some kind of error occurred.

• Examples

  Refer to Printing flow about the procedure of the print end monitoring process by BeginCheckedBlock / EndCheckedBlock.

3.3.12. ResetDevice

Reset hardware.

• Syntax

  void ResetDevice();
  

• Parameter

  None

• Return value

  None

• Exception

  Contents	Type
  when a communication failure occurs	PortException

• Error code

  Value	Contents
  StarResultCode.ErrorFailed	Some kind of error occurred.

3.3.13. GetFirmwareInformation

Gets printer model name and firmware version.

• Declaration

  Dictionary<string, string> GetFirmwareInformation();
  

• Parameter

  None

• Return value

  Contents	Type
  The model name and firmware version are returned with Dictionary. When ModelName is set for Key, the model name is acquired from the return value. When FirmwareVersion is set for Key, the firmware version is acquired from the return value.	Dictionary<string, string>

• Exception

  Contents	Type
  when a communication failure occurs	PortException

• Error code

  Value	Contents
  StarResultCode.ErrorFailed	Some kind of error occurred.