Zint: Manual

5. Using the API

Zint has been written using the C language and has an API for use with C/C++ language programs. A Qt interface is available in the backend_qt sub-directory, and a Tcl interface is available in the backend_tcl sub-directory.

The libzint API has been designed to be very similar to that used by the GNU Barcode package. This allows easy migration from GNU Barcode to Zint. Zint, however, uses none of the same function names or option names as GNU Barcode. This allows you to use both packages in your application without conflict if you wish.

5.1 Creating and Deleting Symbols

The symbols manipulated by Zint are held in a zint_symbol structure defined in zint.h. These symbols are created with the ZBarcode_Create() function and deleted using the ZBarcode_Delete() function. For example the following code creates and then deletes a symbol:

#include <stdio.h>
#include <zint.h>
int main()
{
    struct zint_symbol *my_symbol;
    my_symbol = ZBarcode_Create();
    if (my_symbol != NULL)
    {
        printf("Symbol successfully created!\n");
    }
    ZBarcode_Delete(my_symbol);
    return 0;
}

When compiling this code it will need to be linked with the libzint library using the -lzint option:

gcc -o simple simple.c –lzint

5.2 Encoding and Saving to File

To encode data in a barcode use the ZBarcode_Encode() function. To write the symbol to a file use the ZBarcode_Print() function. For example the following code takes a string from the command line and outputs a Code 128 symbol in a PNG file named out.png (or a GIF file called out.gif if libpng is not present) in the current working directory:

#include <zint.h>
int main(int argc, char **argv)
{
    struct zint_symbol *my_symbol;
    my_symbol = ZBarcode_Create();
    ZBarcode_Encode(my_symbol, argv[1], 0);
    ZBarcode_Print(my_symbol, 0);
    ZBarcode_Delete(my_symbol);
    return 0;
}

This can also be done in one stage using the ZBarcode_Encode_and_Print() function as shown in the next example:

#include <zint.h>
int main(int argc, char **argv)
{
    struct zint_symbol *my_symbol;
    my_symbol = ZBarcode_Create();
    ZBarcode_Encode_and_Print(my_symbol, argv[1], 0, 0);
    ZBarcode_Delete(my_symbol);
    return 0;
}

Note that when using the API, the input data is assumed to be Latin-1 or binary unless the input_mode field is set - see section 5.10 for details.

5.3 Encoding and Printing Functions in Depth

The functions for encoding and printing barcodes are defined as:

int ZBarcode_Encode(struct zint_symbol *symbol, const unsigned char *source, int length);
int ZBarcode_Encode_File(struct zint_symbol *symbol, const char *filename);
int ZBarcode_Print(struct zint_symbol *symbol, int rotate_angle);
int ZBarcode_Encode_and_Print(struct zint_symbol *symbol, const unsigned char *source, int length, int rotate_angle);
int ZBarcode_Encode_File_and_Print(struct zint_symbol *symbol, const char *filename, int rotate_angle);

In these definitions "length" can be used to set the length of the input string. This allows the encoding of NUL (ASCII 0) characters in those symbologies which allow this. A value of 0 will disable this usage and Zint will encode data up to the first NUL character in the input string.

The "rotate_angle" value can be used to rotate the image when outputting. Valid values are 0, 90, 180 and 270.

The ZBarcode_Encode_File() and ZBarcode_Encode_File_and_Print() functions can be used to encode data read directly from a text file where the filename is given in the "filename" string.

If printing more than one barcode, the zint_symbol structure may be re-used by calling the ZBarcode_Clear() function after each barcode to free any output buffers allocated. The symbol structure input fields must be reset.

5.4 Buffering Symbols in Memory (raster)

In addition to saving barcode images to file Zint allows you to access a representation of the resulting bitmap image in memory. The following functions allow you to do this:

int ZBarcode_Buffer(struct zint_symbol *symbol, int rotate_angle);
int ZBarcode_Encode_and_Buffer(struct zint_symbol *symbol, const unsigned char *source, int length, int rotate_angle);
int ZBarcode_Encode_File_and_Buffer(struct zint_symbol *symbol, const char *filename, int rotate_angle);

The arguments here are the same as above. The difference is that instead of saving the image to file it is placed in an unsigned character array. The "bitmap" pointer is set to the first memory location in the array and the values "barcode_width" and "barcode_height" indicate the size of the resulting image in pixels. Rotation and colour options can be used at the same time as using the buffer functions in the same way as when saving to a file. The pixel data can be extracted from the array by the method shown in the example below where render_pixel() is assumed to be a function for drawing a pixel on the screen implemented by the external application:

int row, col, i = 0;
int red, blue, green;

for (row = 0; row < my_symbol->bitmap_height; row++) {
     for (col = 0; col < my_symbol->bitmap_width; col++) {
          red = (int) my_symbol->bitmap[i];
          green = (int) my_symbol->bitmap[i + 1];
          blue = (int) my_symbol->bitmap[i + 2];
          render_pixel(row, col, red, green, blue);
          i += 3;
     }
}

Where speed is important, the buffer can be returned instead in a more compact intermediate form using the output option OUT_BUFFER_INTERMEDIATE. Here each byte is an ASCII value: '1' for foreground colour and '0' for background colour, except for Ultracode, which uses colour codes: 'W' for white, 'C' for cyan, 'B' for blue, 'M' for magenta, 'R' for red, 'Y' for yellow, 'G' from green, and 'K' for black. The loop for accessing the data is then:

int row, col, i = 0;

for (row = 0; row < my_symbol->bitmap_height; row++) {
     for (col = 0; col < my_symbol->bitmap_width; col++) {
          render_pixel(row, col, my_symbol->bitmap[i]);
          i++;
     }
}

5.5 Buffering Symbols in Memory (vector)

Symbols can also be saved to memory in a vector representation as well as a bitmap one. The following functions, exactly analogous to the ones above, allow you to do this:

int ZBarcode_Buffer_Vector(struct zint_symbol *symbol, int rotate_angle);
int ZBarcode_Encode_and_Buffer_Vector(struct zint_symbol *symbol, const unsigned char *source, int length, int rotate_angle);
int ZBarcode_Encode_File_and_Buffer_Vector(struct zint_symbol *symbol, const char *filename, int rotate_angle);

Here the "vector" pointer is set to a header which contains pointers to lists of structures representing the various elements of the barcode: rectangles, hexagons, strings and circles. To draw the barcode, each of the element types is iterated in turn, and using the information stored is drawn by a rendering system. For instance, to draw a barcode using a rendering system with prepare_canvas(), draw_rect(), draw_hexagon(), draw_string(), and draw_circle() routines available:

struct zint_vector_rect *rect;
struct zint_vector_hexagon *hexagon;
struct zint_vector_string *string;
struct zint_vector_circle *circle;

prepare_canvas(symbol->vector->width, symbol->vector->height, symbol->scale,
                symbol->fgcolour, symbol->bgcolor, rotate_angle);

rect = symbol->vector->rectangles;
while (rect) {
    draw_rect(rect->x, rect->y, rect->width, rect->height, rect->colour);
    rect = rect->next;
}

hexagon = symbol->vector->hexagons;
while (hexagon) {
    draw_hexagon(hexagon->x, hexagon->y, hexagon->diameter, hexagon->rotation):
    hexagon = hexagon->next;
}

string = symbol->vector->strings;
while (string) {
    draw_string(string->x, string->y, string->fsize, string->rotation,
                string->halign, string->text, string->length):
    string = string->next;
}

circle = symbol->vector->circles;
while (circle) {
    draw_circle(circle->x, circle->y, circle->diameter, circle->colour):
    circle = circle->next;
}      
    

5.6 Setting Options

So far our application is not very useful unless we plan to only make Code 128 symbols and we don't mind that they only save to out.png. As with the CLI program, of course, these options can be altered. The way this is done is by altering the contents of the zint_symbol structure between the creation and encoding stages. The zint_symbol structure consists of the following variables:

Variable Name Type Meaning Default Value
symbology integer Symbology to use (see section 5.8). BARCODE_CODE128
height integer Symbol height, excluding fixed width-to-height symbols. [1] 50
whitespace_width integer Horizontal Whitespace width. 0
whitespace_height integer Vertical Whitespace height. 0
boder_width integer Border width. 0
output_options integer Set various output file parameters (see section 5.9). (none)
fgcolour character string Foreground (ink) colour as RGB/RGBA hexadecimal string. Must be 6 or 8 characters followed by terminating \0 character. “000000”
bgcolour character string Background (paper) colour as RGB/RGBA hexadecimal string. Must be 6 or 8 characters followed by terminating \ 0 character. “ffffff”
fgcolor character string Points to fgcolour allowing alternate spelling.
bgcolor character string Points to bgcolour allowing alternate spelling.
outfile character string Contains the name of the file to output a resulting barcode symbol to. Must end in .png, .gif, .bmp, .emf, .eps, .pcx, .svg, .tif or .txt “out.png”
scale float Scale factor for adjusting size of image. 1.0
option_1 integer Symbology specific options. -1
option_2 integer Symbology specific options. 0
option_3 integer Symbology specific options. 0
show_hrt integer Set to 0 to hide text. 1
input_mode integer Set encoding of input data (see section 5.10) DATA_MODE
eci integer Extended Channel Interpretation mode 0 (none)
text unsigned character string Human readable text, which usually consists of the input data plus one or more check digits. Uses UTF-8 formatting. "" (empty)
primary character string Primary message data for more complex symbols. "" (empty)
dot_size float Size of dot used in dotty mode. 4.0/5.0
rows integer Number of rows used by the symbol or, if using barcode stacking, the row to be used by the next symbol. (output only)
width integer Width of the generated symbol. (output only)
encoding_data array of character strings Representation of the encoded data. (output only)
row_height array of integers Representation of the height of a row. (output only)
errtxt character string Error message in the event that an error occurred. (output only)
bitmap pointer unsigned to character array Pointer to stored bitmap image. (output only)
bitmap_width Integer Width of stored bitmap image (in pixels). (output only)
bitmap_height Integer Height of stored bitmap image (in pixels). (output only)
alphamap pointer unsigned to character array Pointer to array representing alpha channel (or NULL if no alpha channel needed). (output only)
bitmap_byte_length Integer Size of BMP bitmap data. (output only)
vector pointer to vector sctructure Pointer to vector header containing pointers to vector elements. (output only)
warn_level Integer Affects error/warning value returned by Zint API. WARN_DEFAULT
Variable Name Type/Meaning/Default
symbology Type: integer
Meaning: Symbology to use (see section 5.8).
Value BARCODE_CODE128
height Type: integer
Meaning: Symbol height, excluding fixed width-to-height symbols. [1]
Value Symbol Dependent
whitespace_width Type: integer
Meaning: Horizontal whitespace width.
Value: 0
whitespace_height Type: integer
Meaning: Vertical whitespace height.
Value: 0
boder_width Type: integer
Meaning: Border width.
Value 0
output_options Type: integer
Meaing: Set various output file parameters (see section 5.9). [2]
Value (none)
fgcolour Type: character string
Meaning: Foreground (ink) colour as RGB/RGBA hexadecimal string. Must be 6 or 8 characters followed by terminating \0 character.
Value “000000”
bgcolour Type: character string
Meaning: Background (paper) colour as RGB/RGBA hexadecimal string. Must be 6 or 8 characters followed by terminating \ 0 character.
Value: “ffffff”
outfile Type: character string
Meaning: Contains the name of the file to output a resulting barcode symbol to. Must end in .png, .gif, .bmp, .emf, .eps, .pcx, .svg, .tif or .txt
Value: “out.png”
scale Type: float
Meaning: Scale factor for adjusting size of image.
Value 1.0
option_1 Type: integer
Meaning: Symbology specific options.
Value: -1
option_2 Type: integer
Meaning Symbology specific options.
Value: 0
option_3 Type: integer
Meaning: Symbology specific options.
Value 0
show_hrt Type: integer
Meaning: Set to 0 to hide text.
Value: 1
input_mode Type: integer
Meaning: Set encoding of input data (see section 5.9)
Value: DATA_MODE
eci Type: integer
Meaning: Extended Channel Interpretation mode
Value: 0 (none)
text Type: unsigned character string
Meaning: Human readable text, which usually consists of the input data plus one or more check digits. Uses UTF-8 formatting.
Value: "" (empty)
primary Type: character string
Meaning: Primary message data for more complex symbols.
Value: "" (empty)
dot_size Type: float
Meaning: Size of dot used in dotty mode.
Value: 4.0/5.0
rows Type: integer
Meaning: Number of rows used by the symbol or, if using barcode stacking, the row to be used by the next symbol.
Value: (output only)
width Type: integer
Meaning: Width of the generated symbol.
Value: (output only)
encoding_data Type: array of character strings
Meaning: Representation of the encoded data.
Value: (output only)
row_height Type: array of integers
Meaning: Representation of the height of a row.
Value: (output only)
errtxt Type: character string
Meaning: Error message in the event that an error occurred.
Value: (output only)
bitmap Type: pointer unsigned to character array
Meaning: Pointer to stored bitmap image.
Value: (output only)
bitmap_width Type: Integer
Meaning: Width of stored bitmap image (in pixels).
Value: (output only)
bitmap_height Type: Integer
Meaning: Height of stored bitmap image (in pixels).
Value: (output only)
alphamap Type: Pointer to unsigned character array
Meaning: Pointer to array representing alpha channel (or NULL if no alpha channel needed).
Value: (output only)
bitmap_byte_length Type: Integer
Meaning: Size of BMP bitmap data.
Value: (output only)
vector Type: Pointer to vector structure
Meaning: Pointer to vector header containing pointers to vector elements.
Value: (output only)
warn_level Type: Integer
Meaning: Affects error/warning value returned by Zint API.
Value: WARN_DEFAULT
[1]
This value is ignored for Aztec (including HIBC and Aztec Rune), Code One, Data Matrix (including HIBC), DotCode, Grid Matrix, Han Xin, MaxiCode, QR Code (including HIBC, Micro QR, rMQR and UPNQR), and Ultracode - all of which have a fixed width-to-height ratio (or, in the case of Code One, a fixed height).

To alter these values use the syntax shown in the example below. This code has the same result as the previous example except the output is now taller and plotted in green.

#include <zint.h>
#include <string.h>
int main(int argc, char **argv)
{
    struct zint_symbol *my_symbol;
    my_symbol = ZBarcode_Create();
    strcpy(my_symbol->fgcolour, "00ff00");
    my_symbol->height = 400.0f;
    ZBarcode_Encode_and_Print(my_symbol, argv[1], 0, 0);
    ZBarcode_Delete(my_symbol);
    return 0;
}

Background removal for PNG, GIF, SVG, EMF and EPS files can be achieved by setting the background alpha to "00" where the values for R, G and B will be ignored:

strcpy(my_symbol->bgcolour, "55555500");

5.7 Handling Errors

If errors occur during encoding an integer value is passed back to the calling application. In addition the errtxt value is used to give a message detailing the nature of the error. The errors generated by Zint are given in the table below:

Return Value Meaning
ZINT_WARN_INVALID_OPTION One of the values in zint_struct was set incorrectly but Zint has made a guess at what it should have been and generated a barcode accordingly.
ZINT_WARN_USES_ECI Zint has automatically inserted an ECI character. The symbol may not be readable with some readers.
ZINT_WARN_NONCOMPLIANT The symbol was created but is not compliant with certain standards set in its specification (e.g. height, GS1 AI data lengths).
ZINT_ERROR Marks the divide between warnings and errors. For return values greater than or equal to this no symbol (or only an incomplete symbol) is generated.
ZINT_ERROR_TOO_LONG The input data is too long or too short for the selected symbology. No symbol has been generated.
ZINT_ERROR_INVALID_DATA The data to be encoded includes characters which are not permitted by the selected symbology (e.g. alphabetic characters in an EAN symbol). No symbol has been generated.
ZINT_ERROR_INVALID_CHECK Data with an incorrect check digit has been entered. No symbol has been generated.
ZINT_ERROR_INVALID_OPTION One of the values in zint_struct was set incorrectly and Zint was unable to guess what it should have been. No symbol has been generated.
ZINT_ERROR_ENCODING_PROBLEM A problem has occurred during encoding of the data. This should never happen. Please contact the developer if you encounter this error.
ZINT_ERROR_FILE_ACCESS Zint was unable to open the requested output file. This is usually a file permissions problem.
ZINT_ERROR_MEMORY Zint ran out of memory. This should only be a problem with legacy systems.
ZINT_ERROR_FILE_WRITE Zint failed to write all contents to the requested output file. This should only occur if the output device becomes full.
ZINT_ERROR_USES_ECI Returned if warn level set to WARN_FAIL_ALL and ZINT_WARN_USES_ECI occurs.
ZINT_ERROR_NONCOMPLIANT Returned if warn level set to WARN_FAIL_ALL and ZINT_WARN_NONCOMPLIANT occurs.

To catch errors use an integer variable as shown in the code below:

#include <stdio.h>
#include <zint.h>
#include <string.h>
int main(int argc, char **argv)
{
    struct zint_symbol *my_symbol;
    int error = 0;
    my_symbol = ZBarcode_Create();
    strcpy(my_symbol->fgcolour, "nonsense");
    error = ZBarcode_Encode_and_Print(my_symbol, argv[1], 0, 0);
    if (error != 0)
    {
        /* some warning or error occurred */
        printf("%s\n", my_symbol->errtxt);
    }
    if (error >= ZINT_ERROR)
    {
        /* stop now */
        ZBarcode_Delete(my_symbol);
        return 1;
    }
    /* otherwise carry on with the rest of the application */
    ZBarcode_Delete(my_symbol);
    return 0;
}

This code will exit with the appropriate message:

Error 653: Malformed foreground colour target

To treat all warnings as errors, set symbol->warn_level to WARN_FAIL_ALL.

5.8 Specifying a Symbology

Symbologies can be specified by number or by name as shown in the following table. For example

symbol->symbology = BARCODE_LOGMARS;

means the same as

symbol->symbology = 50;
Value Name Barcode Name
1 BARCODE_CODE11 Code 11
2* BARCODE_C25STANDARD Standard Code 2 of 5
3 BARCODE_C25INTER Interleaved 2 of 5
4 BARCODE_C25IATA Code 2 of 5 IATA
6 BARCODE_C25LOGIC Code 2 of 5 Data Logic
7 BARCODE_C25IND Code 2 of 5 Industrial
8 BARCODE_CODE39 Code 3 of 9 (Code 39)
9 BARCODE_EXCODE39 Extended Code 3 of 9 (Code 39+)
13 BARCODE_EANX EAN
14 BARCODE_EANX_CHK EAN + Check Digit
16* BARCODE_EAN128 GS1-128 (UCC.EAN-128)
18 BARCODE_CODABAR Codabar
20 BARCODE_CODE128 Code 128 (automatic subset switching)
21 BARCODE_DPLEIT Deutshe Post Leitcode
22 BARCODE_DPIDENT Deutshe Post Identcode
23 BARCODE_CODE16K Code 16K
24 BARCODE_CODE49 Code 49
25 BARCODE_CODE93 Code 93
28 BARCODE_FLAT Flattermarken
29* BARCODE_DBAR_OMN GS1 DataBar Omnidirectional (including GS1 DataBar Truncated)
30* BARCODE_DBAR_LTD GS1 DataBar Limited
31* BARCODE_DBAR_EXP GS1 DataBar Extended
32 BARCODE_TELEPEN Telepen Alpha
34 BARCODE_UPCA UPC-A
35 BARCODE_UPCA_CHK UPC-A + Check Digit
37 BARCODE_UPCE UPC-E
38 BARCODE_UPCE_CHK UPC-E + Check Digit
40 BARCODE_POSTNET PostNet
47 BARCODE_MSI_PLESSEY MSI Plessey
49 BARCODE_FIM FIM
50 BARCODE_LOGMARS LOGMARS
51 BARCODE_PHARMA Pharmacode One-Track
52 BARCODE_PZN PZN
53 BARCODE_PHARMA_TWO Pharmacode Two-Track
55 BARCODE_PDF417 PDF417
56* BARCODE_PDF417COMP Compact PDF417 (Truncated PDF417)
57 BARCODE_MAXICODE Maxicode
58 BARCODE_QRCODE QR Code
60 BARCODE_CODE128B Code 128 (Subset B)
63 BARCODE_AUSPOST Australia Post Standard Customer
66 BARCODE_AUSREPLY Australia Post Reply Paid
67 BARCODE_AUSROUTE Australia Post Routing
68 BARCODE_AUSREDIRECT Australia Post Redirection
69 BARCODE_ISBNX ISBN (EAN-13 with verification stage)
70 BARCODE_RM4SCC Royal Mail 4 State (RM4SCC)
71 BARCODE_DATAMATRIX Data Matrix (ECC200)
72 BARCODE_EAN14 EAN-14
73 BARCODE_VIN Vehincle Identification Number
74 BARCODE_CODABLOCKF Codablock-F
75 BARCODE_NVE18 NVE-18 (SSCC-18)
76 BARCODE_JAPANPOST Japanese Postal Code
77 BARCODE_KOREAPOST Korea Post
79* BARCODE_DBAR_STK GS1 DataBar-14 Stacked
80* BARCODE_DBAR_OMNSTK GS1 DataBar-14 Stacked Omnidirectional
81* BARCODE_DBAR_EXPSTK GS1 DataBar Expanded Stacked
82 BARCODE_PLANET PLANET
84 BARCODE_MICROPDF417 MicroPDF417
85* BARCODE_USPS_IMAIL USPS Intelligent Mail (OneCode)
86 BARCODE_PLESSEY Plessey Code
87 BARCODE_TELEPEN_NUM Telepen Numeric
89 BARCODE_ITF14 ITF-14
90 BARCODE_KIX Dutch Post KIX Code
92 BARCODE_AZTEC Aztec Code
93 BARCODE_DAFT DAFT Code
96 BARCODE_DPD DPD Code
97 BARCODE_MICROQR Micro QR Code
98 BARCODE_HIBC_128 HIBC Code 128
99 BARCODE_HIBC_39 HIBC Code 39
102 BARCODE_HIBC_DM HIBC Data Matrix ECC200
104 BARCODE_HIBC_QR HIBC QR Code
106 BARCODE_HIBC_PDF HIBC PDF417
108 BARCODE_HIBC_MICPDF HIBC MicroPDF417
112 BARCODE_HIBC_AZTEC HIBC Aztec Code
115 BARCODE_DOTCODE DotCode
116 BARCODE_HANXIN Han Xin (Chinese Sensible) Code
121 BARCODE_MAILMARK Royal Mail 4-State Mailmark
128 BARCODE_AZRUNE Aztec Runes
129 BARCODE_CODE32 Code 32
130 BARCODE_EANX_CC Composite Symbol with EAN linear component
131* BARCODE_GS1_128_CC Composite Symbol with GS1-128 linear component
132* BARCODE_DBAR_OMN_CC Composite Symbol with GS1 DataBar-14 linear component
133* BARCODE_DBAR_LTD_CC Composite Symbol with GS1 DataBar Limited component
134* BARCODE_DBAR_EXP_CC Composite Symbol with GS1 DataBar Extended component
135 BARCODE_UPCA_CC Composite Symbol with UPC A linear component
136 BARCODE_UPCE_CC Composite Symbol with UPC E linear component
137* BARCODE_DBAR_STK_CC Composite Symbol with GS1 DataBar-14 Stacked component
138* BARCODE_DBAR_OMNSTK_CC Composite Symbol with GS1 DataBar-14 Stacked Omnidirectional component
139* BARCODE_DBAR_EXPSTK_CC Composite Symbol with GS1 DataBar Expanded Stacked component
140 BARCODE_CHANNEL Channel Code
141 BARCODE_CODEONE Code One
142 BARCODE_GRIDMATRIX Grid Matrix
143 BARCODE_UPNQR UPNQR (Univerzalni Plačilni Nalog QR)
144 BARCODE_ULTRA Ultracode
145 BARCODE_RMQR Rectangular Micro QR Code (rMQR)

Note: Symbologies marked with an asterisk (*) in the above table used different names in Zint before version 2.9.0. For example, symbology 29 used the name "BARCODE_RSS14". These names are now deprecated but are still recognised by Zint and will continue to be supported in future versions.

5.9 Adjusting other Output Options

The output_options variable can be used to adjust various aspects of the output file. To select more than one option from the table below simply or them together when adjusting this value:

my_symbol->output_options |= BARCODE_BIND | READER_INIT;
Value Effect
0 No options selected.
BARCODE_BIND Boundary bars above and below the symbol and between rows if stacking multiple symbols. [2]
BARCODE_BOX Add a box surrounding the symbol and whitespace.
BARCODE_STDOUT Output the file to stdout.
READER_INIT Add a reader initialisation symbol to the data before encoding.
SMALL_TEXT Use a smaller font for the human readable text.
BOLD_TEXT Embolden the human readable text.
CMYK_COLOUR Select the CMYK colour space option for encapsulated PostScript and TIF files.
BARCODE_DOTTY_MODE Plot a matrix symbol using dots rather than squares.
GS1_GS_SEPARATOR Use GS instead of FNC1 as GS1 separator (Data Matrix)
OUT_BUFFER_INTERMEDIATE Return the bitmap buffer as ASCII values instead of separate colour channels (OUT_BUFFER only).
[2]
This flag is always set for Codablock-F, Code 16k and Code 49. Special considerations apply to ITF-14 - see the specific section 6.1.2.6 for that symbology.

5.10 Setting the Input Mode

The way in which the input data is encoded can be set using the input_mode property. Valid values are shown in the table below.

Value Effect
DATA_MODE Uses full ASCII range interpreted as Latin-1 or binary data.
UNICODE_MODE Uses pre-formatted UTF-8 input.
GS1_MODE Encodes GS1 data using FNC1 characters.
ESCAPE_MODE Process input data for escape sequences.
GS1PARENS_MODE Parentheses (round brackets) used in input data instead of square brackets to delimit GS1 Application Identifiers (parentheses must not otherwise occur in the data).
GS1NOCHECK_MODE Do not check GS1 data for validity, i.e. suppress checks for valid AIs and data lengths. Invalid characters (e.g. control characters, extended ASCII characters) are still checked for.

The default mode is DATA_MODE.

DATA_MODE, UNICODE_MODE and GS1_MODE are mutually exclusive, whereas ESCAPE_MODE, GS1PARENS_MODE and GS1NOCHECK_MODE are optional. So, for example, you can set

my_symbol->input_mode = UNICODE_MODE | ESCAPE_MODE;

or

my_symbol->input_mode = GS1_MODE | GS1PARENS_MODE | GS1NOCHECK_MODE;

whereas

my_symbol->input_mode = DATA_MODE + GS1_MODE;

is not valid. Permissible escape sequences are listed in section 4.1. An example of GS1PARENS_MODE usage is given in section 6.1.11.3.

GS1NOCHECK_MODE is for use with legacy systems that have data that does not conform to the current GS1 standard. Non-printable ASCII input is still checked for, as is the validity of GS1 data specified without AIs (e.g. linear data for GS1 DataBar Omnidirectional/Limited/etc.).

5.11 Verifying Symbology Availability

An additional function available in the API is defined as:

int ZBarcode_ValidID(int symbol_id);

This function allows you to check whether a given symbology is available. A non-zero return value indicates that the given symbology is available. For example:

if (ZBarcode_ValidID(BARCODE_PDF417) != 0) {
    printf("PDF417 available\n");
} else {
    printf("PDF417 not available\n");
}

5.12 Checking Symbology Capabilities

It can be useful for frontend programs to know the capabilities of a symbology. This can be determined using another additional function:

unsigned int ZBarcode_Cap(int symbol_id, unsigned int cap_flag);

by using the flags below in the "cap_flag" argument and checking the return to see which are set.

Value Meaning
ZINT_CAP_HRT Can the symbology print Human Readable Text?
ZINT_CAP_STACKABLE Is the symbology stackable?
ZINT_CAP_EXTENDABLE Is the symbology extendable with add-on data? (i.e. is it UPC/EAN?)
ZINT_CAP_COMPOSITE Does the symbology support composite data? (see 6.3)
ZINT_CAP_ECI Does the symbology support Extended Channel Interpretations?
ZINT_CAP_GS1 Does the symbology support GS1 data?
ZINT_CAP_DOTTY Can the symbology be outputted as dots?
ZINT_CAP_FIXED_RATIO Does the symbology have a fixed width-to-height (aspect) ratio?
ZINT_CAP_READER_INIT Does the symbology support Reader Initialisation?
ZINT_CAP_FULL_MULTIBYTE Is the ZINT_FULL_MULTIBYTE option applicable?
ZINT_CAP_MASK Is mask selection applicable?

For example:

unsigned int cap = ZBarcode_Cap(BARCODE_PDF417, ZINT_CAP_HRT | ZINT_CAP_ECI);
if (cap & ZINT_CAP_HRT) {
    printf("PDF417 supports HRT\n");
} else {
    printf("PDF417 does not support HRT\n");
}
if (cap & ZINT_CAP_ECI) {
    printf("PDF417 supports ECI\n");
} else {
    printf("PDF417 does not support ECI\n");
}

5.13 Zint Version

Lastly, the version of the Zint library linked to is returned by:

int ZBarcode_Version();

The version parts are separated by hundreds. For instance, version "2.9.1" is returned as "20901".