PrinterSDK 使用说明书（Windows / C++ 版）

本说明书对应 HS-POS PrinterSDK Windows / C++ 版，与 Android 1.6.3 API 对齐。

版本：1.6.3-windows-cpp
适用平台：Windows 10 / 11，C++17（CMake / MSVC 或 MinGW）
命名空间：hspos
最后更新：2026-07-18
对应 Android 版本：com.hspos.printerSDK 1.6.3（PrinterSDK_使用说明书.pdf）
配套文档：PrinterSDK_API_说明文档.md、PrinterSDK_Windows_CPP_API对照表.md

重要（C++）：FeedPaper(connection, n) 的 n 为 点（ESC J）；走纸 行 请使用 PrintAndFeedLines。票据收尾推荐 FeedAndCutPaper。

目录

1. 产品简介
2. 系统要求与集成方式
3. SDK 架构说明
4. 快速开始
5. Windows 运行环境与权限说明
6. 打印机连接
7. 标准 POS 打印
8. 页模式打印
9. 标签模式打印
10. 状态查询与设备控制
11. 常量参考
12. 完整示例
13. 常见问题与排查
14. API 速查表
15. 与 Android / C# 版的平台差异说明

1. 产品简介

PrinterSDK（Windows 版） 是 HS-POS PrinterSDK 在 Windows / 原生 C++ 平台上的实现，与 Android 版 com.hspos.printerSDK 1.6.3 API 对齐，支持 ESC/POS 标准小票打印和 JPL 标签打印。通过统一的 PrinterSdk 入口类，开发者可以用同一套 API 完成设备发现、连接、打印与状态查询。

主要特性

对外核心类型

集成后，业务代码通常只需关注以下类型：

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

• PrinterSdk：统一入口类（单例，PrinterSdk::GetInstance()）
• PrinterConstants：常量定义（对齐 Android PrinterConstants，命名为 PascalCase（与 C# 一致））
• IPrinterConnection：打印机连接句柄接口（对齐 Android PrinterConnection）

与 Android 的命名对照：PrinterSDK → PrinterSdk；PrinterConnection → IPrinterConnection；com.hspos.printerSDK → hspos；camelCase 方法 → PascalCase 方法（如 printText → PrintText）。完整对照见 PrinterSDK_Windows_CPP_API对照表.md。

2. 系统要求与集成方式

2.1 环境要求

2.2 集成方式一：CMake 链接静态库

add_subdirectory(path/to/PrinterAPI_CPP)  # 或 find_package 后
target_link_libraries(your_app PRIVATE hspos_printer_sdk)
target_include_directories(your_app PRIVATE path/to/PrinterAPI_CPP/include)

MinGW 本地构建示例：

$env:PATH = "C:\msys64\ucrt64\bin;" + $env:PATH
cd "C:\Windows Project\PrinterAPI_CPP"
cmake -B build -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release -DHSPOS_BUILD_SHARED=OFF
cmake --build build -j

产物：build\libHspos.PrinterSdk.a（或 SHARED 时的 .dll / .lib）、win_demo.exe、console_demo.exe。

2.3 集成方式二：源码一起编译

将 include/hspos 加入头文件搜索路径，并把 src/*.cpp 与 src/communication/*.cpp 编入工程，链接 windowscodecs、ole32、ws2_32、setupapi、bthprops 等 Windows 库（以 CMakeLists.txt 为准）。

2.4 源码模块结构

PrinterAPI_CPP/
├── CMakeLists.txt
├── include/hspos/                 ← 对外头文件
│   ├── HsposPrinterSdk.hpp        ← 一键包含入口
│   ├── PrinterSdk.hpp             ← 统一门面
│   ├── PrinterConstants.hpp
│   ├── PrinterCommands.hpp
│   ├── JplCommands.hpp
│   ├── ImageUtils.hpp
│   └── communication/             ← 连接抽象与实现
├── src/                           ← 实现
├── samples/
│   ├── console_demo/              ← 控制台样例
│   └── win_demo/                  ← 窗体测试工具
└── docs/                          ← 本说明书与 API 文档

建议： 业务层统一调用 PrinterSdk，不要直接拼装底层指令类，以便升级兼容。

3. SDK 架构说明

┌─────────────────────────────────────────────┐
│              您的 Windows / C++ 应用          │
└────────────────────┬────────────────────────┘
                      │ PrinterSdk::GetInstance()
                      ▼
┌─────────────────────────────────────────────┐
│                  PrinterSdk                  │
│  连接 │ 标准打印 │ 页模式 │ 标签模式 │ 状态   │
└──────┬──────────────────────────────────────┘
       │
       ▼
std::shared_ptr<IPrinterConnection>
（USB / 蓝牙 / 网络 / 串口 / 并口）
       │
       ▼
      物理打印机

连接对象使用 std::shared_ptr<IPrinterConnection>。打印前请确保 connection && connection->IsConnected()。

4. 快速开始

4.1 初始化

Windows C++ 版无需 Android Context，也无需权限回调转发：

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

int main() {
    auto& sdk = PrinterSdk::GetInstance();
    // ... 连接与打印 ...
    sdk.Release();
    return 0;
}

4.2 最小打印流程

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

auto& sdk = PrinterSdk::GetInstance();
auto conn = sdk.ConnectNetworkPrinter("192.168.1.100", 9100);
if (!conn || !conn->IsConnected()) {
    // 连接失败
    return;
}

sdk.InitPrinter(conn);
sdk.SetAlignment(conn, PrinterConstants::AlignmentCenter);
sdk.PrintText(conn, "Hello PrinterSdk\n");
sdk.FeedAndCutPaper(conn);
sdk.DisconnectPrinter(conn);

中文小票推荐：

sdk.InitPrinter(conn);
sdk.SetChineseMode(conn);
sdk.SetDoubleByteEncoding(conn, PrinterConstants::DoubleByteEncodingGbk);
sdk.PrintTextInGbk(conn, "你好，打印机");
sdk.FeedAndCutPaper(conn);

5. Windows 运行环境与权限说明

Windows 版没有 Android 风格的运行时权限（Runtime Permission）模型，因此不需要：

• 在应用清单中声明 BLUETOOTH / USB_PERMISSION / ACCESS_FINE_LOCATION 等权限；
• 在窗体/Activity 中转发 onRequestPermissionsResult；
• 处理 USB / 蓝牙权限弹窗回调。

取而代之，Windows 上的设备访问权限由操作系统驱动与设备管理器管理。以下是各连接方式在 Windows 上的运行环境要求：

5.1 串口（Serial / COM）

5.2 并口（Parallel / LPT，Windows 额外能力）

Android 平台不支持并口；Windows 版新增了对传统并口打印机/工控设备的支持：

5.3 USB

5.4 蓝牙

5.5 网络（TCP/IP）

5.6 与 Android 权限模型对照小结

6. 打印机连接

所有连接方法返回 std::shared_ptr<IPrinterConnection> 对象。连接失败时返回 nullptr。

6.1 USB 连接

auto devices = sdk.GetUsbDevices();
if (devices.size() > 0)
{
    auto conn = sdk.ConnectUsbPrinter(devices[0]);
}

// 也可按端口名/设备路径直连
shared_ptr<IPrinterConnection> conn2 = sdk.ConnectUsbPrinter("USB001");

• GetUsbDevices() 返回 UsbPrinterInfo 列表，包含 PortName、DevicePath、VendorId、ProductId、VidPidText（形如 VID:0x0FE6,PID:0x811E）等信息，便于按厂商设备过滤。
• Windows 无需申请 USB 权限，不存在 HasUsbPermission / RequestUsbPermission（详见 第 15 节）。

6.2 蓝牙连接

// 获取已配对设备
auto paired = sdk.GetBluetoothPairedDevices();

// 获取蓝牙设备（已配对 + 已扫描缓存）
auto devices = sdk.GetBluetoothDevices();

// 获取蓝牙打印机列表（内部别名，等价于 GetBluetoothDevices）
var printers = sdk.GetBluetoothPrinters();

// 方式一：注册监听器 + 后台扫描（贴近 Android 用法）
sdk.AddBluetoothListener(new MyBluetoothListener());
sdk.StartBluetoothDiscovery();
// ... 等待若干秒后
auto all = sdk.GetBluetoothPairedDevices(); // 或 DiscoverBluetoothDevices
sdk.StopBluetoothDiscovery();

// 方式二：Windows 额外提供的同步扫描（简单场景更方便，注意耗时，建议放在后台线程）
auto discovered = sdk.DiscoverBluetoothDevices(true);

// 连接（未配对设备可让 SDK 自动触发系统配对）
auto conn = sdk.ConnectBluetoothPrinter(paired[0]);

C++ 版当前不提供 Android 风格的蓝牙监听器回调；请使用 DiscoverBluetoothDevices / GetBluetoothPairedDevices 主动获取列表。
蓝牙设备需先在系统设置中配对，或通过 PairBluetoothDevice(address, pin) / ConnectBluetoothPrinter(device, true) 触发系统配对流程。

6.3 网络连接

当前提供同步连接。UI 场景请放到工作线程调用。

auto conn = sdk.ConnectNetworkPrinter("192.168.1.100", 9100);
if (!conn || !conn->IsConnected()) {
    // 连接失败
    return;
}
// 在工作线程中执行打印，避免阻塞 UI

6.4 串口连接

auto ports = PrinterSdk::ListSerialPorts();
// 常见端口：COM1、COM3、COM5（以设备管理器实际显示为准）

// 简化方式：端口名 + 波特率
auto conn = sdk.ConnectSerialPrinter("COM3", 9600);

// 完整方式：自定义校验位 / 流控
SerialPortSettings settings;
settings.portName = "COM3";
// ...
auto conn2 = sdk.ConnectSerialPrinter(settings);
/* 原 C# 对象初始化等价字段：
    PortName = "COM3",
    BaudRate = 9600,
    Parity = System.IO.Ports.Parity.None,
    DataBits = 8,
    StopBits = System.IO.Ports.StopBits.One,
    Handshake = System.IO.Ports.Handshake.None
});

常见波特率：9600、19200、38400、57600、115200。

6.5 并口连接（Windows 额外能力）

Android 平台不支持并口；如果客户设备为传统工控一体机、老式针式/热敏打印机，Windows 版提供并口支持：

var lptPorts = sdk.GetParallelDevices();
// 常见端口：LPT1、LPT2、LPT3

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

并口通常只支持写出，多数机型不支持状态回读，QueryRtStatus / GetPrinterStatus 在并口连接下可能返回 nullptr / StatusOffline，属预期行为。

6.6 断开连接与通信辅助

// 断开连接
sdk.DisconnectPrinter(connection);

// 释放 SDK 资源
sdk.Release();

Windows 版不提供 GetCommunicationManager()。
ClearBuffer / CancelPrint 当前 C++ 版暂未封装，可用 SendCommand 发送 CAN（0x18）等指令。

7. 标准 POS 打印

以下所有方法第一个参数均为 auto connection，返回 bool 表示指令是否成功写入端口（不代表打印机机械动作已完成）。

7.1 初始化与重置

7.2 文本打印

sdk.InitPrinter(connection);
sdk.SetAlignment(connection, PrinterConstants::AlignmentCenter);
sdk.SetChineseDoubleSize(connection, true);  // 汉字倍宽倍高 FS W
sdk.SetBold(connection, true);
sdk.PrintTextInGbk(connection, "欢迎光临\n");
sdk.SetBold(connection, false);
sdk.SetChineseDoubleSize(connection, false);  // 恢复汉字正常尺寸

左右分列一行（80mm 小票常用）

纸宽常量（PrinterConstants）：

// 80mm 商业小票：左商品名、右价格
sdk.InitPrinter(connection);
sdk.SetPrintAreaWidth(connection, PrinterConstants::PaperWidth80Mm);
sdk.SetPrintAreaLeftMargin(connection, 0);
sdk.SetAlignment(connection, PrinterConstants::AlignmentLeft);

sdk.PrintTextLineLeftRight(connection, "Lorem ipsum", "$1.25");
sdk.PrintTextLineLeftRight(connection, "Sub Total", "$150.70");

// 合计行放大时，字符宽改为 24（GS ! 倍宽倍高后）
sdk.SetBold(connection, true);
sdk.SetTextScale(connection, 1, 1);
sdk.PrintTextLineLeftRight(connection, "TOTAL", "$155.99",
    PrinterConstants::PaperWidth80Mm, 24);
sdk.SetTextScale(connection, 0, 0);
sdk.SetBold(connection, false);

实现原理：ESC $ 定位到行首打印左列，再 ESC $ 定位到右侧打印右列并换行。倍宽倍高后请同步增大 charWidthDots（通常 12→24）。

7.2.1 字体倍宽倍高（三种指令，勿混淆）

打印机有 三套不同的倍宽倍高指令，适用场景不同：

打印机会按 最后收到的指令 生效；混用时请注意顺序。

① 汉字倍宽倍高 — SetChineseDoubleSize()（推荐打中文）

// 开启汉字倍宽倍高 → 1C 57 01
sdk.SetChineseDoubleSize(connection, true);
// 或
sdk.SetChineseDoubleSize(connection, PrinterConstants::ChineseDoubleSizeOn);

sdk.PrintTextInGbk(connection, "爱尚自身\n");

// 取消，恢复汉字正常尺寸 → 1C 57 00
sdk.SetChineseDoubleSize(connection, false);
// 或传入 int（仅最低位有效：0/1）
sdk.SetChineseDoubleSize(connection, PrinterConstants::ChineseDoubleSizeNormal);

参数 n 仅 最低位 有效：0=取消，1=汉字倍宽倍高同时开启。

② 字符尺寸 — SetTextScale()（GS ! n）

sdk.SetTextScale(connection, 0, 0);  // 正常
sdk.SetTextScale(connection, 1, 1);  // 2倍宽 + 2倍高
sdk.SetTextScale(connection, 1, 0);  // 仅2倍宽
sdk.SetTextScale(connection, 0, 1);  // 仅2倍高

③ 打印模式 — SetPrintMode()（ESC ! n）

sdk.SetPrintMode(connection, PrinterConstants::PrintModeDoubleWidth);
sdk.SetPrintMode(connection, PrinterConstants::PrintModeDoubleHeight);
sdk.SetPrintMode(connection, PrinterConstants::PrintModeDouble);
sdk.SetPrintMode(connection, PrinterConstants::PrintModeNormal);

7.3 格式设置

7.4 条码与二维码

如何选择条码 TYPE（重要）

PrintBarcode() 的第二个参数 type 必须传入 PrinterConstants::BarcodeType* 常量，不要手写 0、1、2 等数字，也不要与标签模式的条码类型编号（0–29）混用。

测试时不知道选哪个？ 优先使用 Code 128——兼容性最好，支持字母和数字，适合订单号、物流单号等大多数场景：

// 推荐：首次测试条码功能时使用此组合
sdk.PrintBarcode(connection,
    PrinterConstants::BarcodeTypeCode128,  // ← TYPE 选这个
    "1234567890",                          // 任意字母数字均可
    PrinterConstants::BarcodeHriBelow,
    80, 2);

按业务场景选择：

注意： 标准小票（ESC/POS）与标签模式（JPL）的条码 type 不是同一套编号。标准打印用 BarcodeType*（值为 0x41–0x49）；标签打印用 LabelBarcodeType*（值为 0–29），详见 第 9 节。

// 一维条码
sdk.PrintBarcode(connection,
    PrinterConstants::BarcodeTypeCode128,  // 条码类型
    "1234567890",                          // 数据
    PrinterConstants::BarcodeHriBelow,      // 文字位置
    80,                                    // 高度（点）
    2);                                    // 宽度

// 二维码（简易）
sdk.PrintQrCode(connection, "https://example.com", 3);

// 二维码（标准，可指定对齐和纠错级别）
sdk.PrintQrCodeStandard(connection,
    "https://example.com", 3,
    PrinterConstants::AlignmentCenter,
    PrinterConstants::QrEccLevelM);

// 双二维码
sdk.PrintDoubleQrCode(connection, n, qr1Pos, qr1Data, qr1Ecc, qr1Ver,
    qr2Pos, qr2Data, qr2Ecc, qr2Ver);

// PDF417
sdk.PrintPdf417(connection, columns, rows, moduleWidth, rowHeight,
    errorCorrectionLevel, option, data);

条码格式预设置（可选，在 PrintBarcode 之前调用）：

sdk.SetBarcodeHriPosition(connection, PrinterConstants::BarcodeHriBelow);
sdk.SetBarcodeHeight(connection, 80);
sdk.SetBarcodeWidth(connection, 2);
sdk.PrintBarcode(connection, PrinterConstants::BarcodeTypeCode128, "1234567890",
    PrinterConstants::BarcodeHriBelow, 80, 2);

条码类型常量：

HRI 文字位置：

7.5 图片打印

PrintRasterImageFrom* 会将图片转为黑白点阵后下发。默认使用 AUTO 压缩（在 GS v 0 与 JBIG 间自动择优，传输更少、打印更快）。

与 Android 的差异：Android 版 printRasterImageFromFile/FromData/FromPixels 各提供 3 个重载（无尺寸、指定尺寸、指定尺寸+压缩模式）。Windows 版目前各提供 2 个重载：无尺寸（内部使用 58mm 纸宽 + AUTO 压缩的默认值）与「指定尺寸 + 压缩模式」（mode 为必填参数，非可选重载）。业务层如只需默认压缩，直接传 PrinterConstants::RasterCompressionAuto 即可，效果与 Android 一致。

// 从文件（默认参数：58mm 纸宽、AUTO 压缩）
sdk.PrintRasterImageFromFile(connection, @"C:\images\logo.png");

// 从文件（自定义尺寸 + 压缩模式，推荐显式传入）
sdk.PrintRasterImageFromFile(connection, @"C:\images\logo.png", 384, 200,
    PrinterConstants::RasterCompressionAuto);

// 从字节数组
sdk.PrintRasterImageFromData(connection, imageBytes);
sdk.PrintRasterImageFromData(connection, imageBytes, 384, 200,
    PrinterConstants::RasterCompressionJbig);   // 强制 JBIG

// 从像素数组（ARGB int[]）
int[] pixels = /* ... */;
sdk.PrintRasterImageFromPixels(connection, pixels, width, height);
sdk.PrintRasterImageFromPixels(connection, pixels, width, height, 384, 200,
    PrinterConstants::RasterCompressionGsV0);  // 强制标准 GS v 0

压缩模式常量（PrinterConstants::RasterCompression*）：

• 图片会自动转为黑白点阵。宽度建议不超过打印机有效打印宽度（58mm 纸约 384 点，80mm 纸约 576 点）。
• targetHeight 传 0 表示按宽度等比缩放。
• 日常业务使用默认 AUTO 即可；若 JBIG 打印异常，可改为 RasterCompressionGsV0。

7.6 走纸与切纸

切刀通常在打印头上方约 10–20mm。内容打完后请用 FeedAndCutPaper。
制表 / 反向走纸 / 水平线等 API 当前 C++ 版尚未提供，可用 SendCommand 扩展。

sdk.PrintAndFeedLines(connection, 4);                   // 走纸 4 行
sdk.FeedPaper(connection, 100);                         // 再走纸 100 点
sdk.CutPaper(connection, PrinterConstants::CutPartial); // 半切
// 或一步完成：
sdk.FeedAndCutPaper(connection);

7.7 外设控制

// 打开钱箱
sdk.OpenCashDrawer(connection, PrinterConstants::CashDrawerPin2);
sdk.OpenCashDrawer(connection, PrinterConstants::CashDrawerPin5);

// 蜂鸣
sdk.Beep(connection);                 // 默认 1 次
sdk.Beep(connection, 3, 2);           // 3 次，每次约 100ms

7.8 缓冲区控制

当前 C++ 版暂未提供 ClearBuffer / CancelPrint 封装；如需可使用 SendCommand 发送 CAN（0x18）等指令。

8. 页模式打印

页模式（Page Mode）允许在指定区域内按坐标绘制内容，适合制作复杂票据版式。

8.1 基本流程

sdk.InitPrinter(connection);

// 1. 进入页模式（自动完成 GS P + ESC W + ESC T 初始化）
sdk.SelectPageMode(connection);
// 或自定义打印区域（80mm 纸宽约 576 点）
sdk.SelectPageModeEx(connection, 0, 0, 576, 800);

// 2. 可选：调整区域或方向
sdk.SetPrintAreaInPageMode(connection, 0, 0, 576, 800);
sdk.SetPrintAreaDirection(connection, PrinterConstants::PageDirectionLeftToRight);

// 3. 绘制内容（坐标单位为点，原点在打印区域左上角）
sdk.DrawTextGbkInPageMode(connection, 100, 100, "商品名称");
sdk.DrawBarcodeInPageMode(connection, 100, 200, PrinterConstants::BarcodeTypeCode128, "123456");
sdk.DrawQrCodeInPageMode(connection, 100, 300, 3, PrinterConstants::QrEccLevelM, "https://example.com");
sdk.DrawImageFromFileInPageMode(connection, 100, 400, @"C:\images\logo.png", 100, 50);
sdk.DrawRectangleBorderInPageMode(connection, 50, 50, 500, 100);   // 边框
sdk.DrawFilledRectangleInPageMode(connection, 60, 60, 200, 80);     // 实心

// 4. 打印并退出
sdk.PagePrintPage(connection);   // ESC FF，将页缓冲内容打印出来
sdk.ExitPageMode(connection);    // ESC S，返回标准模式

页模式排版辅助（80mm 小票常用）

int w = PrinterConstants::PaperWidth80Mm;  // 576
int y = 40;
sdk.DrawTextCenteredInPageMode(connection, w, y, "2847 Madison Avenue");
y += 36;
sdk.DrawTextLineLeftRightInPageMode(connection, w, y, "Bank Card", "**** **** **** 1234");

NV 位图 / Logo（打印机内存，FS p）

打印机出厂或工具预存的 Logo 保存在 NV 存储器中，无需传图即可打印：

mode 使用 PrinterConstants::NvBitmapMode*（0 正常 / 1 倍宽 / 2 倍高 / 3 倍宽倍高）。

// 页模式顶部居中 Logo（nvNumber、imageWidthDots 按打印机手册调整）
sdk.DrawNvBitmapCenteredInPageMode(connection, 576, 40, 1,
    PrinterConstants::NvBitmapModeNormal, 256);
y += 100;  // 预留 Logo 高度

注意： 页模式与标签模式（JPL）是不同指令体系，请勿混用。SelectPageMode() / SelectPageModeEx() 会自动设置移动单位、打印区域和默认方向；若只调用 SelectPageMode() 而不设置区域，打印机无法正确定位内容。

8.2 页模式 API 列表

9. 标签模式打印

标签模式适用于标签纸打印机，使用 JPL 指令集进行精确布局。

9.1 基本流程

// 1. 启用标签模式
sdk.EnableLabelMode(connection);

// 2. 开始标签页（x, y, width, height, rotation）
sdk.LabelPageBegin(connection, 0, 0, 576, 400, 0);

// 3. 绘制内容
sdk.PrintLabelTextGbk(connection, "商品标签", 50, 50, 24, 0);
sdk.PrintLabelBarcode(connection,
    PrinterConstants::LabelBarcodeTypeCode128, "1234567890", 50, 100, 80, 2);
sdk.PrintLabelQrCode(connection, "https://example.com", 50, 200, 3);
sdk.DrawLabelImageFromFile(connection, 300, 50, @"C:\images\logo.png");
sdk.DrawLabelLine(connection, 50, 300, 500, 300);
sdk.DrawLabelRect(connection, 50, 320, 500, 380);

// 4. 打印
sdk.BackPaperToPrintPosition(connection);
sdk.LabelPagePrint(connection);       // 打印 1 份
sdk.LabelPagePrint(connection, 3);    // 打印 3 份

// 5. 退出标签模式
sdk.DisableLabelMode(connection);

说明： PrintLabelQrCode 简易重载的实际签名为 PrintLabelQrCode(connection, string data, int x, int y)（无 size 参数，模块大小由内部默认值决定）；如需指定版本、纠错等级、模块宽度，请使用完整参数重载 PrintLabelQrCode(connection, x, y, version, eccLevel, unitWidth, rotate, data)。

9.2 标签模式 API 列表

10. 状态查询与设备控制

SDK 提供 两种 状态获取方式，适用场景不同：

说明： 除「便捷判断」外，SDK 不对状态字节做业务解析，位含义请按下文对照表在业务层自行判断。不同机型可能有差异，以实机为准。网口、串口连接下状态查询更可靠；并口通常不支持状态回读。

10.1 SDK 便捷状态 API

int status    = sdk.GetPrinterStatus(connection);
bool online    = sdk.IsPrinterOnline(connection);
bool hasPaper  = sdk.HasPaper(connection);
bool coverOpen = sdk.IsCoverOpen(connection);

GetPrinterStatus 内部依次查询 StatusTypePrinter（打印机状态）、StatusTypeOffline（脱机状态）、StatusTypePaperSensor（纸传感器状态），合成为下列简化常量的按位组合：

上述常量为 SDK 封装用简化值，与 ESC/POS 标准状态字节的位定义不完全相同。精确判断请用 10.2 的原始字节按位解析。

10.2 主动查询（DLE EOT / GS r）

API

// DLE EOT：10 04 n
byte[]? rt = sdk.QueryRtStatus(connection, type, timeoutMs);

// GS r：1D 72 n（部分机型更兼容，返回格式与 DLE EOT 同类）
byte[]? tx = sdk.QueryTransmitStatus(connection, type, timeoutMs);

查询类型 type（PrinterConstants::StatusType*）

timeoutMs 为等待响应毫秒数；无响应返回 nullptr。

n=1 打印机状态字节（DLE EOT 1 / GS r 1）

n=2 脱机状态字节

n=3 错误状态字节

n=4 纸传感器状态字节

10.3 状态相关 API 汇总

11. 常量参考

说明： PrinterConstants 中的 int/byte[] 常量供集成方在业务代码中使用（如 PrinterConstants::AlignmentCenter）。命名规则为 C# PascalCase；括号内注明对应的 Android 常量名，便于迁移比对。

11.1 对齐与切纸

PrinterConstants::AlignmentLeft      // 0 - 左对齐 (Android: ALIGNMENT_LEFT)
PrinterConstants::AlignmentCenter    // 1 - 居中   (Android: ALIGNMENT_CENTER)
PrinterConstants::AlignmentRight     // 2 - 右对齐 (Android: ALIGNMENT_RIGHT)

PrinterConstants::CutFull            // 0 - 全切 (Android: CUT_FULL)
PrinterConstants::CutPartial         // 1 - 半切 (Android: CUT_PARTIAL)

11.2 二维码

PrinterConstants::QrcodeSizeSmall    // 1
PrinterConstants::QrcodeSizeNormal   // 2
PrinterConstants::QrcodeSizeLarge    // 3

PrinterConstants::QrEccLevelL        // 1 — 约 7% 纠错
PrinterConstants::QrEccLevelM        // 2 — 约 15% 纠错
PrinterConstants::QrEccLevelQ        // 3 — 优化纠错
PrinterConstants::QrEccLevelH        // 4 — 约 30% 纠错

11.3 页模式方向

PrinterConstants::PageDirectionLeftToRight   // 0
PrinterConstants::PageDirectionBottomToTop   // 1
PrinterConstants::PageDirectionRightToLeft   // 2
PrinterConstants::PageDirectionTopToBottom   // 3

11.4 打印模式组合

PrinterConstants::PrintModeNormal          // 0 — 正常
PrinterConstants::PrintModeDoubleWidth     // 1 — 倍宽
PrinterConstants::PrintModeDoubleHeight    // 2 — 倍高
PrinterConstants::PrintModeDouble          // 3 — 倍宽+倍高
PrinterConstants::PrintModeBold            // 8 — 加粗
PrinterConstants::PrintModeReverse         // 16 — 反白
PrinterConstants::PrintModeUnderline       // 128 — 下划线

11.4.1 光栅图压缩模式

用于 PrintRasterImageFrom* 的 compressionMode 参数：

PrinterConstants::RasterCompressionGsV0     // 0 — GS v 0 标准光栅
PrinterConstants::RasterCompressionLineRle  // 1 — US ( P 逐行 RLE（需固件支持）
PrinterConstants::RasterCompressionJbig     // 2 — US ( J JBIG 压缩
PrinterConstants::RasterCompressionAuto     // 3 — 自动（默认，GS v 0 ↔ JBIG）

11.5 钱箱与行间距

PrinterConstants::CashDrawerPin2       // 0 — 钱箱引脚 2
PrinterConstants::CashDrawerPin5       // 1 — 钱箱引脚 5

PrinterConstants::LineSpacingDefault   // 0 — 默认行间距
PrinterConstants::LineSpacing18        // 1 — 1/8 英寸
PrinterConstants::LineSpacing16        // 2 — 1/6 英寸

11.6 状态相关常量

完整位定义见 第 10 节。

// SDK 便捷判断（简化值，非 ESC/POS 原位）
PrinterConstants::StatusOffline             // 0x00
PrinterConstants::StatusOnline              // 0x01
PrinterConstants::StatusPaperOut            // 0x02
PrinterConstants::StatusCoverOpen           // 0x04

// 主动查询 type（DLE EOT / GS r）
PrinterConstants::StatusTypePrinter         // 1
PrinterConstants::StatusTypeOffline         // 2
PrinterConstants::StatusTypeError           // 3
PrinterConstants::StatusTypePaperSensor     // 4

11.7 条码类型（标准小票 ESC/POS）

测试条码功能时，不确定选哪个 TYPE 请直接用 BarcodeTypeCode128。完整选型说明见 7.4 节。

// 通用首选（测试推荐）
PrinterConstants::BarcodeTypeCode128   // 0x49 — 字母数字均可

// 商品零售
PrinterConstants::BarcodeTypeEan13     // 0x43 — 12~13 位数字
PrinterConstants::BarcodeTypeEan8      // 0x44 — 7~8 位数字
PrinterConstants::BarcodeTypeUpcA      // 0x41 — 11~12 位数字
PrinterConstants::BarcodeTypeUpcE      // 0x42 — UPC-E 压缩码

// 其他
PrinterConstants::BarcodeTypeCode39    // 0x45 — 工业标识
PrinterConstants::BarcodeTypeItf       // 0x46 — 偶数位数字
PrinterConstants::BarcodeTypeCodabar   // 0x47 — 以 A~D 起止
PrinterConstants::BarcodeTypeCode93    // 0x48 — 高密度

// HRI 可读文字位置
PrinterConstants::BarcodeHriNone       // 0 — 不显示
PrinterConstants::BarcodeHriBelow      // 2 — 条码下方（常用）

// 旧版别名（等价于 BarcodeType*）
PrinterConstants::BarcodeCode128       // = BarcodeTypeCode128
PrinterConstants::BarcodeCode39        // = BarcodeTypeCode39
PrinterConstants::BarcodeEan13         // = BarcodeTypeEan13

11.8 标签模式条码类型（JPL，与 ESC/POS 不同）

标签模式 PrintLabelBarcode() 的 type 使用 0–29 编号，与上方 BarcodeType* 无关：

PrinterConstants::LabelBarcodeTypeCode128   // 8 — 标签模式 Code 128（常用）
PrinterConstants::LabelBarcodeHeightDefault // 80 — 标签条码默认高度
PrinterConstants::LabelBarcodeUnitWidth2    // 2 — 标签条码默认模块宽度
PrinterConstants::LabelFontHeight24         // 24 — 标签常用字号

12. 完整示例

12.1 小票打印（蓝牙）

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

public void PrintReceipt()
{
    auto& sdk = PrinterSdk::GetInstance();
    auto devices = sdk.GetBluetoothPairedDevices();
    if (devices.size() == 0)
    {
        std::cerr <<("未找到已配对打印机");
        return;
    }

    auto conn = sdk.ConnectBluetoothPrinter(devices[0]);
    if (conn == nullptr || !conn.IsConnected())
    {
        std::cerr <<("连接失败");
        return;
    }

    try
    {
        sdk.InitPrinter(conn);

        // 标题
        sdk.SetAlignment(conn, PrinterConstants::AlignmentCenter);
        sdk.SetChineseDoubleSize(conn, true);
        sdk.SetBold(conn, true);
        sdk.PrintTextInGbk(conn, "=== 收银小票 ===\n\n");

        // 正文
        sdk.SetBold(conn, false);
        sdk.SetChineseDoubleSize(conn, false);
        sdk.SetAlignment(conn, PrinterConstants::AlignmentLeft);
        sdk.PrintTextInGbk(conn, "商品：苹果 x2\n");
        sdk.PrintTextInGbk(conn, "单价：5.00 元\n");
        sdk.PrintTextInGbk(conn, "合计：10.00 元\n\n");

        // 分隔线
        sdk.FixedHorizontalLine(conn);

        // 条码
        sdk.PrintBarcode(conn,
            PrinterConstants::BarcodeTypeCode128, "20260707001",
            PrinterConstants::BarcodeHriBelow, 80, 2);

        // 二维码
        sdk.PrintQrCode(conn, "https://example.com/order/001", 3);

        // 切纸
        sdk.FeedLine(conn);
        sdk.CutPaper(conn, PrinterConstants::CutPartial);

        std::cerr <<("打印完成");
    }
    catch (Exception ex)
    {
        std::cerr <<($"打印失败: {ex.Message}");
    }
    finally
    {
        sdk.DisconnectPrinter(conn);
    }
}

12.2 标签打印（网络）

public void PrintLabel()
{
    auto& sdk = PrinterSdk::GetInstance();
    auto conn = sdk.ConnectNetworkPrinter("192.168.1.100", 9100);
if (!conn || !conn->IsConnected()) {
    // 连接失败
    return;
}
// 在工作线程中执行打印，避免阻塞 UI
            sdk.LabelPageBegin(conn, 0, 0, 576, 400, 0);

            sdk.PrintLabelTextGbk(conn, "产品名称", 30, 30, 24, 0);
            sdk.PrintLabelBarcode(conn,
                PrinterConstants::LabelBarcodeTypeCode128,
                "6901234567890", 30, 80, 80, 2);
            sdk.PrintLabelQrCode(conn, "https://example.com/p/001", 30, 200, 3);
            sdk.DrawLabelRect(conn, 10, 10, 566, 390);

            sdk.LabelPagePrint(conn);
            sdk.DisableLabelMode(conn);
            sdk.DisconnectPrinter(conn);
        },
        onFailed: errorMessage =>
        {
            std::cerr <<(errorMessage);
        });
}

12.3 并口打印（Windows 独有，工控设备常用）

public void PrintOverParallelPort()
{
    auto& sdk = PrinterSdk::GetInstance();
    var ports = sdk.GetParallelDevices();
    if (ports.Count == 0)
    {
        std::cerr <<("未检测到并口设备");
        return;
    }

    auto conn = sdk.ConnectParallelPrinter(ports[0]);
    if (conn == nullptr)
    {
        std::cerr <<("并口连接失败");
        return;
    }

    sdk.InitPrinter(conn);
    sdk.PrintText(conn, "并口打印测试\n");
    sdk.FeedAndCutPaper(conn);
    sdk.DisconnectPrinter(conn);
}

13. 常见问题与排查

13.1 连接问题

13.2 打印问题

13.3 开发建议

1. 网络连接：当前为同步 ConnectNetworkPrinter；在 UI 程序中请放到工作线程调用。
2. 检查返回值：所有打印方法返回 bool，失败时应记录日志。
3. 及时释放资源：应用退出前调用 sdk.Release()，并对每个连接调用 DisconnectPrinter。
4. 使用常量：不要硬编码对齐、条码类型等数值。
5. 连接后先 init：打印前调用 InitPrinter(connection) 确保打印机就绪。
6. 一次连接多次打印：同一 IPrinterConnection 可复用，无需每次重连。

13.4 日志与调试

• 可在应用中使用 Microsoft.Extensions.Logging 或 Console 输出记录关键调用与异常，SDK 内部对多数底层异常做了吞掉处理（返回 false/nullptr），排查连接问题建议先用 第 10 节 的状态查询 API 或抓包确认底层通信是否成功。
• 建议先用官方 窗体测试工具 win_demo（samples\win_demo）验证目标打印机连接与出纸正常，再接入业务工程。

14. API 完整速查表

以下列出 PrinterSdk.cs 中全部 公开方法（含重载）。

14.1 单例与生命周期

14.2 连接与通信

14.3 标准打印 — 初始化与文本

14.4 标准打印 — 格式设置

14.5 标准打印 — 条码 / 二维码 / 图片

14.6 标准打印 — 走纸 / 切纸 / 外设 / 缓冲

14.7 页模式

14.8 标签模式

14.9 状态查询

14.10 接口 / 类型

方法签名与参数详见 PrinterSdk.hpp 或 IDE 自动补全，也可参阅 PrinterSDK_API_说明文档.md。

15. 与 Android / C# 版的平台差异说明

API 完备性： 已实现方法见 PrinterSDK_API_说明文档.md 正文；Android 有而 C++ 暂未实现 / 不移植的方法，已在同一文档增加 「暂未实现 API」 与 「Android 平台专属 API」 占位章节（含规划签名与临时替代说明）。对照表见 Android_API覆盖对照.md。

附录：版本更新记录

技术支持： 如有问题，请参考本文 第 13 节，或使用 samples\win_demo 窗体测试工具 win_demo进行连接与打印诊断。方法级详细说明见 PrinterSDK_API_说明文档.md。