Zint Barcode Generator
Prev		Next

4. Using the API

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.

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

4.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 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]);
    ZBarcode_Print(my_symbol);
    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]);
    ZBarcode_Delete(my_symbol);
    return 0;
}

Input strings should be Unicode formatted.

4.3 Setting Options

So far our application is not very useful unless we plan to only make Code 128 barcodes and we don't mind that they only save to out.png. As with the front end 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 4.5).	BARCODE_CODE128
height	integer	Symbol height. [1]	50
whitespace_width	integer	Whitespace width.	0
boder_width	integer	Border width.	0
output_options	integer	Binding or box parameters (see section 4.6). [2]	(none)
fgcolour	character string	Foreground (ink) colour as RGB hexadecimal string. Must be 6 characters followed by terminating \0 character.	"000000"
bgcolour	character string	Background (paper) colour as RGB hexadecimal string. Must be 6 characters followed by terminating \0 character.	"ffffff"
outfile	character string	Contains the name of the file to output a resulting barcode symbol to. Must end in .PNG or .EPS	"out.png"
option_1	integer	Symbology specific options.	(automatic)
option_2	integer	Symbology specific options.	(automatic)
scale	float	Scale factor for adjusting size of image.	1.0
nullchar	char	Character to substitute for NULL	NULL
input_mode	integer	Set encoding of input data (see 4.8)	BINARY_MODE
primary	character string	Primary message data for more complex symbols.	NULL
text	character string	Human readable text, which usually consists of the input data plus one or more check digits.	NULL
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)

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]);
    ZBarcode_Delete(my_symbol);
    return 0;
}

4.4 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
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.
ERROR_TOO_LONG	The input data is too long or too short for the selected symbology. No symbol has been generated.
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.
ERROR_INVALID_CHECK	An ISBN with an incorrect check digit has been entered. No symbol has been generated.
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.
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.
ERROR_FILE_ACCESS	Zint was unable to open the requested output file. This is usually a file permissions problem.
ERROR_MEMORY	Zint ran out of memory. This should only be a problem with legacy systems.

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]);

    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

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

Numeric Value	Name	Symbology
1	BARCODE_CODE11	Code 11
2	BARCODE_C25MATRIX	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
16	BARCODE_EAN128	GS1-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
25	BARCODE_CODE93	Code 93
28	BARCODE_FLAT	Flattermarken
29	BARCODE_RSS14	GS1 DataBar-14
30	BARCODE_RSS_LTD	GS1 DataBar Limited
31	BARCODE_RSS_EXP	GS1 DataBar Expanded
32	BARCODE_TELEPEN	Telepen Alpha
34	BARCODE_UPCA	UPC A
37	BARCODE_UPCE	UPC E
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_PDF417TRUNC	PDF417 Truncated
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
72	BARCODE_EAN14	EAN-14
75	BARCODE_NVE18	NVE-18
77	BARCODE_KOREAPOST	Korea Post
79	BARCODE_RSS14STACK	GS1 DataBar-14 Stacked
80	BARCODE_RSS14STACK_OMNI	GS1 DataBar-14 Stacked Omnidirectional
81	BARCODE_RSS_EXPSTACK	GS1 DataBar Expanded Stacked
82	BARCODE_PLANET	PLANET
84	BARCODE_MICROPDF417	MicroPDF417
85	BARCODE_ONECODE	USPS 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
97	BARCODE_MICROQR	Micro QR Code
128	BARCODE_AZRUNE	Aztec Runes
129	BARCODE_CODE32	Code 32
130	BARCODE_EANX_CC	Composite Symbol with EAN linear component
131	BARCODE_EAN128_CC	Composite Symbol with GS1-128 linear component
132	BARCODE_RSS14_CC	Composite Symbol with GS1 DataBar-14 linear component
133	BARCODE_RSS_LTD_CC	Composite Symbol with GS1 DataBar Limited component
134	BARCODE_RSS_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_RSS14STACK_CC	Composite Symbol with GS1 DataBar-14 Stacked component
138	BARCODE_RSS14_OMNI_CC	Composite Symbol with GS1 DataBar-14 Stacked Omnidirectional component
139	BARCODE_RSS_EXPSTACK_CC	Composite Symbol with GS1 DataBar Expanded Stacked component

4.6 Adding Boxes and Boundary Bars

Boxes and boundary bars are handled using the output_options variable in the zint_symbol structure. To use this option simply assign a value to the output_options variable from the following table [2].

Value	Effect
0	No box or boundary bars.
BARCODE_BIND	Boundary bars above and below the symbol and between rows if stacking multiple symbols.
BARCODE_BOX	Add a box surrounding the symbol and whitespace.

4.7 Rotating the Symbol

Rotating the output is done using the ZBarcode_Encode_and_Print_Rotated() and ZBarcode_Print_Rotated() functions. These take an extra integer argument giving the angle of rotation. Valid values are 0, 90, 180 and 270 degrees measured clockwise. For example the following code generates a symbol rotated by 90 degrees. Only PNG output can be rotated in this way.

error = ZBarcode_Encode_and_Print_Rotated(my_symbol, argv[1], 90);

4.8 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
BINARY_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.
KANJI_MODE	Encodes Kanji characters in QR Code.

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

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

Prev	Home	Next
Using the Front End		Types of Symbol