PrintSpirit Dynamic Link Library API Reference

The PrintSpirit Dynamic Link Library is one of the PrintSpirit Open Platform secondary development tools, encapsulated in libspirit.dll (Windows) or libspirit.so (Linux). It can be directly called by C/C++ or further wrapped into C#, Java, and other languages to simplify barcode label printing and label editing feature development in desktop applications.

1. Usage Instructions

1.1 Calling Convention

All APIs use the __cdecl calling convention with UTF-8 string encoding.

1.2 Memory Management Rules

1. Pointers returned by GetSpiritError, SpiritPrnLst, and SpiritPrnInfo must be released using SpiritFree
2. Temporary memory returned by other APIs is managed internally by the library and does not require manual release
3. Incoming parameter memory is managed by the caller

1.3 Error Codes

Return value 0 indicates success. Values <0 indicate errors. Use GetSpiritError() to retrieve specific error messages.

1.4 Example Code

 1#include <stdio.h>
 2#include "libspirit.h"
 3
 4int main() {
 5
 6    SpiritInit();
 7    // Print label
 8    if (Print("/tmp/xxxx1.psl", "{}", "{\"printer\":\"Spirit Image\"}")<0) {
 9       char * err = GetSpiritError();
10       printf("Print Error %s\n", err);
11       SpiritFree(err);
12    }
13    
14    // Edit label
15    if (SpiritEdit("/tmp/xxxx1.psl")<0) {
16       char * err = GetSpiritError();
17       printf("Edit Label Error %s\n", err);
18       SpiritFree(err);
19    }
20    
21    SpiritDeInit();        
22    
23    return 0;
24}

2. API Reference

2.1 Initialization & Cleanup

 1/**
 2 * Initialize Spirit library
 3 * Must be called before other APIs
 4 */
 5void SpiritInit();
 6
 7/**
 8 * Release Spirit library resources
 9 * Call before program exit
10 */
11void SpiritDeInit();

2.2 Error Handling

 1/**
 2 * Get last error message
 3 * @return UTF-8 encoded error string (requires SpiritFree release)
 4 */
 5const char* GetSpiritError();
 6
 7/**
 8 * Free memory allocated by Spirit library
 9 * @param p Memory pointer allocated by Spirit library
10 */
11void SpiritFree(void* p);

2.3 Print Control

 1/**
 2 * Execute print job
 3 * @param tpid Template ID
 4 * @param vars JSON variables (UTF-8)
 5 * @param opts JSON print options (UTF-8)
 6 * @return 0 success, negative for failure
 7 */
 8int Print(const char* tpid, const unsigned char* vars, const unsigned char* opts);
 9
10/**
11 * Reset printer
12 * @param p Printer name
13 * @return 0 success, negative for failure
14 */
15int ResetPrinter(const char* p);

2.4 Label Designer API

 1/**
 2 * Open label designer to edit label file
 3 * @param file Label file path (UTF-8)
 4 * @return 0 success, negative for failure
 5 */
 6int SpiritEdit(const unsigned char* file);
 7
 8/**
 9 * Create new label
10 * @param file Save path (UTF-8)
11 * @param name Label name (UTF-8)
12 * @param memo Label memo (UTF-8)
13 * @param width Label width (mm)
14 * @param height Label height (mm)
15 * @param dpi Print DPI
16 * @param ref_label Reference label path (UTF-8, optional)
17 * @return 0 success, negative for failure
18 */
19int SpiritNewLabel(const unsigned char* file, const unsigned char* name, 
20                 const unsigned char* memo, int width, int height, 
21                 int dpi, const unsigned char* ref_label);

2.5 License Management

1/**
2 * Install license
3 * @param key License key
4 * @return 0 success, negative for failure
5 */
6int SpiritInstallLicense(const char* key);

2.6 Printer Management

 1/**
 2 * Get printer list
 3 * @return JSON printer list (UTF-8, requires SpiritFree release)
 4 *         Format: [{"name":"...","type":"...","act":true/false},...]
 5 */
 6const char* SpiritPrnLst();
 7
 8/**
 9 * Get printer details
10 * @param prn Printer name
11 * @return JSON printer info (UTF-8, requires SpiritFree release)
12 */
13const char* SpiritPrnInfo(const char* prn);

Note:

• Returned format is JSON
• Returned pointers must be released with SpiritFree()

3. Data Type Specifications

3.1 Printer Information (JSON)

 1{
 2  "name": "Printer name",
 3  "output_dir": "Output directory (valid for virtual printers like Spirit Image/PDF)",
 4  "paper": [
 5    {
 6      "name": "Paper name",
 7      "w": width,
 8      "h": height,
 9      "cols": columns,
10      "rows": rows,
11      "gapX": horizontal gap,
12      "gapY": vertical gap,
13      "marginTop": top margin,
14      "marginLeft": left margin
15    }
16  ]
17}

3.2 Print Options (JSON)

 1{
 2  "printer": "Printer name",
 3  "type": "Printer type (ZPL/CPCL/TSPL/ESCPOS)",
 4  "row": row count,
 5  "col": column count,
 6  "gapX": horizontal gap,
 7  "gapY": vertical gap,
 8  "quality": quality level (0-2),
 9  "flush": immediate flush (true/false)
10}
11
12Note: 
13- "printer" can be "Spirit Image" (built-in virtual printer for barcode/QR generation)
14- "type" indicates printer language (e.g., ZPL for Zebra printers)