# LP_LabelPrinter DLL API Reference

## Data Types

### Handle Types

| Type | Description |
|------|-------------|
| `LP_PRINTER` | Printer object handle |
| `LP_LABEL` | Label object handle (programmatic, includes layout and object list) |
| `LP_LABELDOC` | Label document handle (loaded from LSF file) |

### Structs

```c
typedef struct {
    char printerName[64];  // Printer name
    char portName[32];     // USB port name
    char serialNo[32];     // Mainboard serial number
} LP_USBINFO;
```

### Interface Type Constants

| Constant | Value | Description |
|----------|-------|-------------|
| `LP_DRIVER` | 0 | Windows driver printing |
| `LP_USB` | 1 | USB (driverless) |
| `LP_NET` | 2 | Network printing (port 9100) |
| `LP_RFID_USB` | 4 | RFID USB (driverless) |
| `LP_RFID_NET` | 5 | RFID Network |
| `LP_GBGM_USB` | 6 | GBGM USB |
| `LP_GBGM_NET` | 7 | GBGM Network |
| `LP_GJB_USB` | 8 | GJB USB |
| `LP_GJB_NET` | 9 | GJB Network |

### Object Type Constants

| Constant | Value | Description |
|----------|-------|-------------|
| `LP_OBJ_TEXT` | 0 | Text |
| `LP_OBJ_BARCODE` | 1 | Barcode |
| `LP_OBJ_LINE` | 2 | Line |
| `LP_OBJ_RECT` | 3 | Rectangle |
| `LP_OBJ_IMAGE` | 4 | Image |
| `LP_OBJ_RFID` | 5 | RFID |

### Return Value Convention

| Return Value | Meaning |
|-------------|---------|
| 0 | Success |
| >0 | Success, returns data length (read functions) |
| Negative (-1 etc.) | Failure, call `LpGetLastErrorCode` / `LpGetLastErrorMessage` for details |

---

## 1. Label Layout Management (LP_LABEL)

For scenarios that do not rely on LSF files and create labels purely in code.

### Create & Destroy

| Function | Description |
|----------|-------------|
| `LP_LABEL LpLabel_Create(void)` | Create an empty label object |
| `void LpLabel_Destroy(LP_LABEL label)` | Destroy label and free memory |

### Layout Setters

| Function | Parameters | Description |
|----------|-----------|-------------|
| `LpLabel_SetWidth` | `label, float widthMm` | Label width (mm) |
| `LpLabel_SetHeight` | `label, float heightMm` | Label height (mm) |
| `LpLabel_SetRowGap` | `label, float gapMm` | Row gap (mm) |
| `LpLabel_SetColumnGap` | `label, float gapMm` | Column gap (mm) |
| `LpLabel_SetRowCount` | `label, int count` | Row count |
| `LpLabel_SetColumnCount` | `label, int count` | Column count |
| `LpLabel_SetLeftOffset` | `label, float offsetMm` | Left offset (mm) |
| `LpLabel_SetTopOffset` | `label, float offsetMm` | Top offset (mm) |
| `LpLabel_SetPageLeftEdges` | `label, float edgesMm` | Page left margin (mm) |
| `LpLabel_SetPageRightEdges` | `label, float edgesMm` | Page right margin (mm) |
| `LpLabel_SetStartLocation` | `label, int location` | Start print location |
| `LpLabel_SetLabelOrder` | `label, int order` | Label print order |
| `LpLabel_SetLabelShape` | `label, int shape` | Label shape |

### Layout Getters

| Function | Returns |
|----------|---------|
| `LpLabel_GetWidth` | Label width (mm) |
| `LpLabel_GetHeight` | Label height (mm) |
| `LpLabel_GetRowGap` | Row gap (mm) |
| `LpLabel_GetColumnGap` | Column gap (mm) |
| `LpLabel_GetRowCount` | Row count |
| `LpLabel_GetColumnCount` | Column count |
| `LpLabel_GetLeftOffset` | Left offset (mm) |
| `LpLabel_GetTopOffset` | Top offset (mm) |
| `LpLabel_GetPageLeftEdges` | Page left margin (mm) |
| `LpLabel_GetPageRightEdges` | Page right margin (mm) |
| `LpLabel_GetStartLocation` | Start print location |
| `LpLabel_GetLabelOrder` | Label print order |
| `LpLabel_GetLabelShape` | Label shape |

---

## 2. Label Object Management (LP_LABEL)

### Add Text

```c
int LpLabel_AddText(LP_LABEL label, const char* name,
                     const char* data, float xMm, float yMm,
                     float fontSize, const char* fontName,
                     int textType, float textWidthMm);
```

| Parameter | Description |
|-----------|-------------|
| name | Object name, must start with `text` |
| data | Text content (UTF-8) |
| xMm, yMm | Position (mm) |
| fontSize | Font size (pt) |
| fontName | Font name |
| textType | 0=single line, 1=paragraph |
| textWidthMm | Max paragraph width (mm), pass 0 for single line |
| Returns | Object index (>=0), -1 on failure |

### Add Barcode

```c
int LpLabel_AddBarcode(LP_LABEL label, const char* name,
                        const char* data, float xMm, float yMm,
                        const char* barcodeKind, float scale,
                        float heightMm, int textPosition);
```

| Parameter | Description |
|-----------|-------------|
| name | Object name, must start with `barcode` |
| data | Barcode data |
| xMm, yMm | Position (mm) |
| barcodeKind | Barcode type string (see valid values below) |
| scale | Scale factor |
| heightMm | Barcode height (mm) |
| textPosition | 0=below barcode, 1=above barcode, 2=no text |
| Returns | Object index (>=0), -1 on failure |

**Valid barcode types:** `Code 128 Auto` / `Code 128 A` / `Code 128 B` / `Code 128 C` / `EAN-13` / `EAN-8` / `UPC-A` / `UPC-E` / `UPC 2 Digit Ext.` / `UPC 5 Digit Ext.` / `Code 39` / `Code 39 Extended` / `Code 93` / `ITF-14` / `Interleaved 2 of 5` / `Industrial 2 of 5` / `Standard 2 of 5` / `GS1-128` / `QR Code(2D)` / `PDF 417(2D)` / `Data Matrix(2D)` / `GS1 Data Matrix(2D)` / `GS1 QR Code(2D)` / `GS1 DataBar Expanded Stacked` / `Aztec Code(2D)` / `GridMatrix(2D)` / `Han Xin Code(2D)`

### Add Line

```c
int LpLabel_AddLine(LP_LABEL label, const char* name,
                     float startX, float startY,
                     float endX, float endY, float lineWidth);
```

| Parameter | Description |
|-----------|-------------|
| name | Object name, must start with `line` |
| startX, startY | Start point (mm) |
| endX, endY | End point (mm) |
| lineWidth | Line width (mm) |
| Returns | Object index |

### Add Rectangle

```c
int LpLabel_AddRect(LP_LABEL label, const char* name,
                     float startX, float startY,
                     float endX, float endY, float lineWidth);
```

| Parameter | Description |
|-----------|-------------|
| name | Object name, must start with `rectangle` |
| startX, startY | Top-left corner (mm) |
| endX, endY | Bottom-right corner (mm) |
| lineWidth | Border width (mm) |
| Returns | Object index |

### Add Image

```c
int LpLabel_AddImage(LP_LABEL label, const char* name,
                      float xMm, float yMm, float scale,
                      const char* imageBase64);
```

| Parameter | Description |
|-----------|-------------|
| name | Object name, must start with `image` |
| xMm, yMm | Position (mm) |
| scale | Uniform scale factor |
| imageBase64 | Base64-encoded JPEG/PNG/BMP image data |
| Returns | Object index |

### Add RFID Object

```c
int LpLabel_AddRfid(LP_LABEL label, const char* name,
                     const char* data,
                     int encoderType, int dataType, int dataBlock);
```

| Parameter | Description |
|-----------|-------------|
| name | Object name, must start with `rfid` |
| data | Data to write |
| encoderType | 0=UHF, 1=HF 15693, 2=HF 14443A, 3=HF NFC |
| dataType | 0=text, 1=hex, 2=URL link (NDEF), 3=plain text (NDEF) |
| dataBlock | 0=EPC (UHF), 1=USER (UHF) |
| Returns | Object index |

---

## 3. Object Property Setters (LP_LABEL)

The following functions set additional properties on already-added objects using their index (returned by `LpLabel_Add*`).

### Text Properties

| Function | Parameters | Description |
|----------|-----------|-------------|
| `LpLabel_SetTextAlign` | `label, index, align` | Alignment: 0=left, 1=center, 2=right |
| `LpLabel_SetFontStyle` | `label, index, style` | Font style: 0=normal, 1=bold, 2=italic, 3=bold+italic |

### Barcode Properties

| Function | Parameters | Description |
|----------|-----------|-------------|
| `LpLabel_SetBarcodeText` | `label, index, font, size, offset, align` | Barcode text: font name, size(pt), gap(mm), alignment (0=left,1=right,2=center,3=justify) |

### Line/Rectangle Properties

| Function | Parameters | Description |
|----------|-----------|-------------|
| `LpLabel_SetLineDash` | `label, index, dashStyle` | Dash style: 0=solid, 1=dash, 2=dash-dot, 3=dash-dot-dot, 4=dot |
| `LpLabel_SetRectShape` | `label, index, rectClass` | Shape: 0=normal rect, 1=rounded rect, 2=ellipse, 3=triangle |
| `LpLabel_SetRectRadius` | `label, index, radius` | Corner radius (mm) |
| `LpLabel_SetRectFill` | `label, index, fill` | Fill: 0=no fill, 1=filled |

### Image Properties

| Function | Parameters | Description |
|----------|-----------|-------------|
| `LpLabel_SetImageScale` | `label, index, hScale, vScale` | Horizontal/vertical independent scale |

### RFID Properties

| Function | Parameters | Description |
|----------|-----------|-------------|
| `LpLabel_SetRfidHf` | `label, index, startBlock, modulePower` | HF parameters: start block address, module power (0=12db,1=24db,2=36db,3=48db) |

---

## 4. Programmatic Label Rendering & Printing (LP_LABEL)

| Function | Parameters | Description |
|----------|-----------|-------------|
| `LpLabel_Render` | `label, printer, pageIndex, &pixels, &w, &h, &stride` | Render to 32-bit BGRX pixels, caller must `LpFree` the buffer |
| `LpLabel_SavePreview` | `label, printer, filePath` | Render and save as 32-bit BMP, returns 0 on success |
| `LpLabel_Print` | `label, printer` | Print directly (includes RFID writing), returns 0 on success |
| `LpLabel_PrintBlankPage` | `label, printer, printErrorFlag` | Print blank page, flag=1 adds error mark "XXXXXXXX" |

---

## 5. Printer Management

### Create & Connect

| Function | Description |
|----------|-------------|
| `LP_PRINTER LpPrinter_Create(void)` | Create a printer object |
| `void LpPrinter_Destroy(LP_PRINTER)` | Destroy printer object |
| `int LpPrinter_Connect(LP_PRINTER)` | Connect to printer, returns 0 on success |
| `void LpPrinter_Disconnect(LP_PRINTER)` | Disconnect from printer |

### Parameter Setters

| Function | Parameters | Description |
|----------|-----------|-------------|
| `LpPrinter_SetInterface` | `printer, interfaceType` | Set interface type |
| `LpPrinter_SetUsbSerial` | `printer, serialNo` | Set USB serial number (for multi-printer selection) |
| `LpPrinter_SetNetAddress` | `printer, ip` | Set network printer IP (port fixed at 9100) |
| `LpPrinter_SetName` | `printer, name` | Set driver printer name |
| `LpPrinter_SetDpi` | `printer, dpi` | Set print resolution, default 203 |
| `LpPrinter_SetSpeed` | `printer, speed` | Set print speed (inch/sec), default 4 |
| `LpPrinter_SetDarkness` | `printer, darkness` | Set print darkness 0~20, default 10 |
| `LpPrinter_SetPageDirection` | `printer, dir` | Set paper feed direction |

### Status & Enumeration

| Function | Description |
|----------|-------------|
| `int LpPrinter_EnumUsb(infos, maxCount)` | Enumerate USB printers, returns count |
| `int LpPrinter_GetStatusCode(printer)` | Query status code, 0=ready |
| `int LpPrinter_GetStatusInfo(code, buf, size)` | Convert status code to text description |

---

## 6. Label Document Operations (LP_LABELDOC)

For scenarios using LSF label files.

### Load & Destroy

| Function | Description |
|----------|-------------|
| `LP_LABELDOC LpLabelDoc_Load(path)` | Load from LSF file, returns NULL on failure |
| `LP_LABELDOC LpLabelDoc_LoadFromMemory(data, len)` | Load LSF data from memory |
| `void LpLabelDoc_Destroy(doc)` | Destroy document and free memory |
| `const char* LpLabelDoc_GetLastError()` | Get the last load error message |

### Printer Parameter Getters

| Function | Returns |
|----------|---------|
| `LpLabelDoc_GetPrinterDpi` | Printer DPI stored in LSF |
| `LpLabelDoc_GetPrinterSpeed` | Print speed stored in LSF |
| `LpLabelDoc_GetPrinterDarkness` | Print darkness stored in LSF |
| `LpLabelDoc_GetPrinterPageDirection` | Paper direction stored in LSF |
| `LpLabelDoc_GetPrinterHaveGap` | Whether label has gap (1=yes, 0=no) |
| `LpLabelDoc_AdjustDpiScale` | Manually adjust barcode/image DPI scale |

### Print Parameter Setters

| Function | Description |
|----------|-------------|
| `LpLabelDoc_SetPrintCount(printCount)` | Number of prints |
| `LpLabelDoc_SetCopyCount(copyCount)` | Number of copies per print |
| `LpLabelDoc_SetReverse(reverse)` | Mirror flip (0=normal, 1=mirrored) |

### Object Query

| Function | Description |
|----------|-------------|
| `LpLabelDoc_GetObjectCount(doc)` | Get object count |
| `LpLabelDoc_GetObjectType(doc, index)` | Get object type (LP_OBJ_*) |
| `LpObject_GetName(doc, index, buf, size)` | Get object name |
| `LpObject_GetX(doc, index)` / `LpObject_GetY(doc, index)` | Get object position (mm) |
| `LpObject_GetData(doc, index, buf, size)` | Get object data |
| `LpObject_GetCodeData(doc, index, buf, size)` | Get barcode encoded data |
| `LpObject_GetBarcodeKind(doc, index, buf, size)` | Get barcode type string |
| `LpObject_GetDataChildIDs(doc, index, buf, size)` | Get data child ID list |

### Variable Operations

| Function | Description |
|----------|-------------|
| `LpObject_GetVarCount(doc, index)` | Get variable count |
| `LpObject_GetVarInfo(doc, idx, varIdx, ...)` | Get variable info (name, data, ID, type) |
| `LpObject_SetVariable(doc, index, name, value)` | Set variable on a single object |
| `LpObject_SetVariableAll(doc, name, value)` | Set variable on all matching objects |

### Rendering & Printing

| Function | Description |
|----------|-------------|
| `LpLabelDoc_Render(doc, printer, pageIndex, &pixels, &w, &h, &stride)` | Render to pixels, caller must `LpFree` |
| `LpLabelDoc_SavePreview(doc, printer, filePath)` | Render and save as BMP |
| `LpLabelDoc_Print(doc, printer)` | Print (includes RFID writing) |
| `LpLabelDoc_PrintBlankPage(doc, printer, printErrorFlag)` | Print blank page |

---

## 7. RFID Read/Write

### UHF Tag Read

```c
int LpPrinter_ReadUHFTag(LP_PRINTER printer, int area, int feed,
                          int timeoutMs, char* buf, int bufSize);
```

| Parameter | Description |
|-----------|-------------|
| area | 0=TID, 1=EPC, 2=TID+EPC, 3=USER |
| feed | Paper feed after read: 0=original pos, 1=tear-off, 2=print line, 3=antenna position |
| timeoutMs | Timeout (ms), suggested 2000 |
| buf / bufSize | Return data buffer and size |
| Returns | >0=data length, 0=no tag read, -1=failure |

### HF Tag Read

```c
int LpPrinter_ReadHFTag(LP_PRINTER printer, int protocol, int area,
                         int startblock, int timeoutMs,
                         char* buf, int bufSize);
```

| Parameter | Description |
|-----------|-------------|
| protocol | 1=15693, 2=14443A, 3=NFC |
| area | 0=UID, 1=data area |
| startblock | Read start block address |
| timeoutMs | Timeout (ms), suggested 5000 |
| buf / bufSize | Return data buffer and size |
| Returns | >0=data length, 0=no tag read, -1=failure |

---

## 8. Memory & Error

| Function | Description |
|----------|-------------|
| `void LpFree(void* ptr)` | Free memory allocated by the DLL (pixel data from Render) |
| `int LpGetLastErrorCode(void)` | Get the last error code |
| `const char* LpGetLastErrorMessage(void)` | Get the last error message text |

---

## Printer Status Codes

| Code | Meaning |
|------|---------|
| 0 | Ready |
| 1 | Syntax error |
| 81 | Mainboard hardware fault |
| 82 | Ribbon detection error |
| 83 | Label detection error |
| 86 | Cutter detection error |
| 88 | Printer paused |
| 89 | Label out |
| 90 | RFID write error |
| 91/92 | RFID signal calibration failed |
| 96 | Peeler waiting |
| 99/120 | Printer upgrade completed |
| 112 | No tag detected |
| 113 | Multiple tags detected |
| 116 | Duplicate tag detected |
