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 <zint.h>
#include <stdio.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 8-bit binary unless the input_mode variable in the zint_symbol structure is set - see 5.10 Setting the Input Mode 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, which must be present.

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 NUL-terminated 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 zint_symbol input variables 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 a 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 with 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 also uses colour codes: 'W' for white, 'C' for cyan, 'B' for blue, 'M' for magenta, 'R' for red, 'Y' for yellow, 'G' for 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(my_symbol->vector->width, my_symbol->vector->height,
               my_symbol->scale, my_symbol->fgcolour, my_symbol->bgcolor,
               rotate_angle);

for (rect = my_symbol->vector->rectangles; rect; rect = rect->next) {
    draw_rect(rect->x, rect->y, rect->width, rect->height,
              rect->colour);
}
for (hexagon = my_symbol->vector->hexagons; hexagon; hexagon = hexagon->next) {
    draw_hexagon(hexagon->x, hexagon->y, hexagon->diameter,
                 hexagon->rotation);
}
for (string = my_symbol->vector->strings; string; string = string->next) {
    draw_string(string->x, string->y, string->fsize,
                string->rotation, string->halign,
                string->text, string->length);
}
for (circle = my_symbol->vector->circles; circle; circle = circle->next) {
    draw_circle(circle->x, circle->y, circle->diameter,
                circle->width, circle->colour);
}

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:

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 EMF, EPS, GIF, PNG, SVG and TIF 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 a non-zero integer value is passed back to the calling application. In addition the errtxt variable is used to give a message detailing the nature of the error. The errors generated by Zint are given in the table below:

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

#include <zint.h>
#include <stdio.h>
#include <string.h>
int main(int argc, char **argv)
{
    struct zint_symbol *my_symbol;
    int error;
    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 'NONSENSE' (hexadecimal only)

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 Table. For example

symbol->symbology = BARCODE_LOGMARS;

means the same as

symbol->symbology = 50;

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;

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.

The default mode is DATA_MODE. (Note that this differs from the default for the CLI and GUI, which is UNICODE_MODE.)

DATA_MODE, UNICODE_MODE and GS1_MODE are mutually exclusive, whereas ESCAPE_MODE, GS1PARENS_MODE, GS1NOCHECK_MODE, HEIGHTPERROW_MODE and FAST_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 Table. An example of GS1PARENS_MODE usage is given in section 6.1.10.3 GS1-128.

GS1NOCHECK_MODE is for use with legacy systems that have data that does not conform to the current GS1 standard. 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.).

For HEIGHTPERROW_MODE, see --heightperrow in section 4.4 Adjusting Height. The height variable should be set to the desired per-row value on input (it will be set to the overall height on output).

5.11 Multiple Segments

For input data requiring multiple ECIs, the following functions may be used:

int ZBarcode_Encode_Segs(struct zint_symbol *symbol,
      const struct zint_seg segs[], const int seg_count);

int ZBarcode_Encode_Segs_and_Print(struct zint_symbol *symbol,
      const struct zint_seg segs[], const int seg_count, int rotate_angle);

int ZBarcode_Encode_Segs_and_Buffer(struct zint_symbol *symbol,
      const struct zint_seg segs[], const int seg_count, int rotate_angle);

int ZBarcode_Encode_Segs_and_Buffer_Vector(struct zint_symbol *symbol,
      const struct zint_seg segs[], const int seg_count, int rotate_angle);

These are direct analogues of the previously mentioned ZBarcode_Encode(), ZBarcode_Encode_and_Print(), ZBarcode_Encode_and_Buffer() and ZBarcode_Encode_and_Buffer_Vector() respectively, where instead of a pair consisting of "source, length", a pair consisting of "segs, seg_count" is given, with segs being an array of struct zint_seg segments and seg_count being the number of elements it contains. The zint_seg structure is of the form:

struct zint_seg {
    unsigned char *source; /* Data to encode */
    int length;            /* Length of `source`. If 0, `source` must be
                              NUL-terminated */
    int eci;               /* Extended Channel Interpretation */
};

The symbology must support ECIs (see Table ). For example:

#include <zint.h>
int main(int argc, char **argv)
{
    struct zint_seg segs[] = {
        { "Κείμενο", 0, 9 },
        { "Текст", 0, 7 },
        { "文章", 0, 20 }
    };
    struct zint_symbol *my_symbol;
    my_symbol = ZBarcode_Create();
    my_symbol->symbology = BARCODE_AZTEC;
    my_symbol->input_mode = UNICODE_MODE;
    ZBarcode_Encode_Segs(my_symbol, segs, 3);
    ZBarcode_Print(my_symbol, 0);
    ZBarcode_Delete(my_symbol);
    return 0;
}

A maximum of 256 segments may be specified. Use of multiple segments with GS1 data is not currently supported.

5.12 Verifying Symbology Availability

An additional function available in the API is:

int ZBarcode_ValidID(int symbol_id);

which allows you to check whether a given symbology is available, returning a non-zero value if so. For example:

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

Another function that may be useful is:

int ZBarcode_BarcodeName(int symbol_id, char name[32]);

which copies the name of a symbology into the supplied name buffer, which should be 32 characters in length. The name is NUL-terminated, and zero is returned on success. For instance:

char name[32];
if (ZBarcode_BarcodeName(BARCODE_PDF417, name) == 0) {
    printf("%s\n", name);
}

will print BARCODE_PDF417.

5.13 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 OR-ing the flags below in the cap_flag argument and checking the return to see which are set.

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.14 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".