PrinterSDK User Manual (Windows / C++)

This manual documents HS-POS PrinterSDK for Windows / C++, aligned with Android 1.6.3.

Version: 1.6.3-windows-cpp
Platform: Windows 10 / 11, C++17 (CMake / MSVC or MinGW)
Namespace: hspos
Last updated: 2026-07-18
Android counterpart PDFs: PrinterSDK_User_Manual.pdf, PrinterSDK_使用说明书.pdf
Companion docs: PrinterSDK_API_Documentation.md, PrinterSDK_API_说明文档.md, PrinterSDK_Windows_CPP_API对照表.md

Important (C++): FeedPaper(conn, n) feeds dots (ESC J). For lines, use PrintAndFeedLines. Prefer FeedAndCutPaper to finish receipts.

Table of Contents

1. Product Introduction
2. System Requirements and Integration
3. SDK Architecture
4. Quick Start
5. Windows Runtime Environment
6. Printer Connection
7. Standard POS Printing
8. Page Mode Printing
9. Label Mode Printing
10. Status Query and Device Control
11. Constants Reference
12. Complete Examples
13. FAQ and Troubleshooting
14. API Quick Reference
15. Platform Differences vs Android / C#
16. API Reference Links
17. Appendix: Version History

1. Product Introduction

PrinterSDK (Windows C++) is a native C++17 implementation of HS-POS PrinterSDK, aligned with Android package com.hspos.printerSDK 1.6.3 and the Windows C# SDK. It supports ESC/POS receipt printing and JPL label printing through one façade class: PrinterSdk.

Features

Core types

#include "hspos/HsposPrinterSdk.hpp"
using namespace hspos;

auto& sdk = PrinterSdk::GetInstance();

Naming vs Android: PrinterSDK → PrinterSdk; camelCase → PascalCase; PrinterConnection → shared_ptr<IPrinterConnection>.

2. System Requirements and Integration

2.1 Requirements

2.2 Build & link

cd "C:\Windows Project\PrinterAPI_CPP"
cmake -B build -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release -DHSPOS_BUILD_SHARED=OFF
cmake --build build -j

Artifacts: libHspos.PrinterSdk.a (or DLL), win_demo.exe, console_demo.exe.

Also see docs/如何编译.md and docs/如何运行.md.

2.3 Source layout

PrinterAPI_CPP/
├── include/hspos/          # public headers (HsposPrinterSdk.hpp umbrella)
├── src/                    # implementation
├── samples/console_demo/   # CLI demos
├── samples/win_demo/       # GUI test tool
└── docs/                   # this manual + API handbooks

3. SDK Architecture

Your Windows C++ application
        │
        ▼
 PrinterSdk::GetInstance()
   ├── Connection / POS / Page / Label / Status
        │
        ▼
 std::shared_ptr<IPrinterConnection>
   USB / BT / Network / Serial / Parallel
        │
        ▼
   Physical printer

Always verify connection && connection->IsConnected() before printing.

4. Quick Start

#include "hspos/HsposPrinterSdk.hpp"
using namespace hspos;

int main() {
    auto& sdk = PrinterSdk::GetInstance();
    auto conn = sdk.ConnectNetworkPrinter("192.168.1.100", 9100);
    if (!conn || !conn->IsConnected()) return 1;

    sdk.InitPrinter(conn);
    sdk.SetChineseMode(conn);
    sdk.SetDoubleByteEncoding(conn, PrinterConstants::DoubleByteEncodingGbk);
    sdk.SetAlignment(conn, PrinterConstants::AlignmentCenter);
    sdk.PrintTextInGbk(conn, "Hello PrinterSdk\n");
    sdk.FeedAndCutPaper(conn);
    sdk.DisconnectPrinter(conn);
    sdk.Release();
    return 0;
}

5. Windows Runtime Environment

Windows has no Android-style runtime permission model. Device access depends on drivers and Device Manager.

Android-only APIs not present: hasUsbPermission, requestUsbPermission, onRequestPermissionsResult, getCommunicationManager.

6. Printer Connection

Failed connects return an empty shared_ptr.

6.1 USB

auto devices = PrinterSdk::GetUsbDevices();
if (!devices.empty()) auto c = sdk.ConnectUsbPrinter(devices[0]);
auto c2 = sdk.ConnectUsbPrinter("USB001");

6.2 Bluetooth

auto paired = PrinterSdk::GetBluetoothPairedDevices();
auto found = PrinterSdk::DiscoverBluetoothDevices(true); // blocking
if (!paired.empty()) auto c = sdk.ConnectBluetoothPrinter(paired[0]);
PrinterSdk::StopBluetoothDiscovery();

6.3 Network

auto c = sdk.ConnectNetworkPrinter("192.168.1.100", 9100);

Async connect is not implemented yet; call from a worker thread in UI apps.

6.4 Serial

SerialPortSettings s;
s.portName = "COM3";
s.baudRate = 115200;
auto c = sdk.ConnectSerialPrinter(s);
auto ports = PrinterSdk::ListSerialPorts();

6.5 Parallel (Windows extra)

auto c = sdk.ConnectParallelPrinter("LPT1");

6.6 Disconnect

sdk.DisconnectPrinter(c);

7. Standard POS Printing

7.1 Init / reset

InitPrinter / ResetPrinter

7.2 Text

PrintText / PrintTextInUtf8 / PrintTextInGbk / PrintTextLineLeftRight
Magnification: SetTextScale(widthScale, heightScale) (0–7).

7.3 Format

Alignment, bold, underline, reverse, line spacing, Chinese mode / double-byte encoding, print area width/margin.

7.4 Barcodes & QR

PrintBarcode / PrintQrCode / PrintQrCodeStandard / PrintPdf417 / PrintDoubleQrCode

7.5 Raster images

PrintRasterImageFromPixels / FromFile / FromData (GS v 0; WIC for files).
Widths: PaperWidth58Mm (384) / PaperWidth80Mm (576).

7.6 Feed & cut

7.7 Peripherals & raw

OpenCashDrawer / Beep / SelfTest / SendCommand

8. Page Mode Printing

Flow: SelectPageMode / SelectPageModeEx → draw → PagePrintPage → ExitPageMode.

Includes UTF-8/GBK text, centered/right/left-right helpers, barcode (+ centered HRI), QR, line, rectangle, estimators.

9. Label Mode Printing

Flow: EnableLabelMode → LabelPageBegin → draw → LabelPagePrint → DisableLabelMode.

Supports text, barcode, QR, PDF417, images, lines, rectangles, boxes, back-paper.

10. Status Query and Device Control

11. Constants Reference

See PrinterConstants.hpp and the API handbook constants section (alignment, cut, paper widths, barcode/QR, status bits, encodings, page directions, raster modes).

12. Complete Examples

Network receipt

auto& sdk = PrinterSdk::GetInstance();
auto c = sdk.ConnectNetworkPrinter("192.168.1.100", 9100);
sdk.InitPrinter(c);
sdk.SetAlignment(c, PrinterConstants::AlignmentCenter);
sdk.PrintTextInGbk(c, "收银小票\n");
sdk.PrintQrCodeStandard(c, "https://example.com", 6, 1, PrinterConstants::QrEccLevelM);
sdk.FeedAndCutPaper(c);
sdk.DisconnectPrinter(c);

Label

sdk.EnableLabelMode(c);
sdk.LabelPageBegin(c, 0, 0, 400, 300, 0);
sdk.PrintLabelTextGbk(c, "标签", 20, 20);
sdk.PrintLabelQrCode(c, "ABC123", 20, 80);
sdk.LabelPagePrint(c, 1);
sdk.DisableLabelMode(c);

Demos: win_demo.exe, console_demo.exe receipt58 <ip> 9100.

13. FAQ and Troubleshooting

14. API Quick Reference

• English API: PrinterSDK_API_Documentation.md
• Chinese API: PrinterSDK_API_说明文档.md
• Coverage gaps: Android_API覆盖对照.md

15. Platform Differences vs Android / C

API completeness: Implemented methods are in PrinterSDK_API_Documentation.md. Android APIs not yet in C++ (and Android-only APIs) are listed there under Not Yet Implemented / Android-only placeholders with planned signatures and workarounds. See also Android_API覆盖对照.md.

16. API Reference Links

Aligned with Android PDFs under PrintertestAPP\DOC\:

Appendix: Version History