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.

3.3.1. Printing flow

Using the SMPort class, print per the following procedure.

../_images/port_flow.png
  • 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 Printing 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.

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, 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.