5. Using the API

Zint has been written using the C language and currently only has an API for use with C language programs.

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 <stdio.h>
#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 <stdio.h>
#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;
}

Input data should be Unicode (UTF-8) formatted.

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, unsigned char *input, int length);

int ZBarcode_Encode_File(struct zint_symbol *symbol, char *filename);

int ZBarcode_Print(struct zint_symbol *symbol, int rotate_angle);

int ZBarcode_Encode_and_Print(struct zint_symbol *symbol, unsigned char *input, int length, int rotate_angle);

int ZBarcode_Encode_File_and_Print(struct zint_symbol *symbol, 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 NULL (ASCII 0) characters in those symbologies which allow this. A value of 0 will disable this function and Zint will encode data up to the first NULL character in the input string.

The "rotate_angle" value can be used to rotate the image when outputting as a raster image. 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.

5.4 Buffering Symbols in Memory

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 ZBarcide_Encode_and_Buffer(struct zint_symbol *symbol, unsigned char *input, int length, int rotate_angle);

int ZBarcode_Encode_File_and_Buffer(struct zint_symbol *symbol, 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 a 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 raster image. The pixel data can be extracted from the character 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;
            unsigned int red, blue, green;
            for (row = 0; row < my_symbol->bitmap_height; row++) {
            for (col = 0; col < my_symbol->bitmap_width; col++) {
                    red = my_symbol->bitmap[i];
                    green = my_symbol->bitmap[i + 1];
                    blue = my_symbol->bitmap[i + 2];
                    render_pixel(row, col, red, green, blue);
                    i += 3;
                }
            }
        

5.5 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 <stdio.h>
#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;
    ZBarcode_Encode_and_Print(my_symbol, argv[1], 0, 0);
    ZBarcode_Delete(my_symbol);
    return 0;
}

5.6 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:

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 error occurred */
        printf("%s\n", my_symbol->errtxt);
    }
    if(error > WARN_INVALID_OPTION)
    {
    /* 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: malformed foreground colour target

5.7 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;

5.8 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 add them together when adjusting this value:

my_symbol->output_options += BARCODE_BIND + READER_INIT;

5.9 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.

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

my_symbol->input_mode = UNICODE_MODE + ESCAPE_MODE;

whereas

my_symbol->input_mode = DATA_MODE + GS1_MODE;

is not valid. Permissible escape sequences are listed in section 4.1.

5.10 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");
} else {
    printf("PDF417 not available");
}

[1] This value is ignored for Australia Post 4-State Barcodes, PostNet, PLANET, USPS OneCode, RM4SCC, PDF417, Data Matrix, Maxicode, QR Code, rMQR, GS1 DataBar-14 Stacked, PDF417 and MicroPDF417 - all of which have a fixed height.

[2] This value is ignored for Code 16k, Codablock-F and ITF-14 symbols.