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



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)

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 Code

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_ITF14

ITF-14

75

BARCODE_NVE18

NVE-18

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

100

BARCODE_TELEPEN_NUM

Telepen Numeric

101

BARCODE_MSI_10

MSI Plessey + mod 10

102

BARCODE_MSI_10_10

MSI Plessey + mod 10 + mod 10

103

BARCODE_MSI_11

MSI Plessey + mod 11

104

BARCODE_MSI_11_10

MSI Plessey + mod 11 + mod 10

105

BARCODE_CODE39_43

Code 39 + mod 43

106

BARCODE_EXCODE39_43

Extended Code 39 + mod 43

107

BARCODE_AZTEC

Aztec Code

110

BARCODE_EANX_CC

Composite Symbol with EAN linear component

111

BARCODE_EAN128_CC

Composite Symbol with GS1-128 linear component

112

BARCODE_RSS14_CC

Composite Symbol with GS1 DataBar-14 linear component

113

BARCODE_RSS_LTD_CC

Composite Symbol with GS1 DataBar Limited component

114

BARCODE_RSS_EXP_CC

Composite Symbol with GS1 DataBar Extended component

115

BARCODE_UPCA_CC

Composite Symbol with UPC A linear component

116

BARCODE_UPCE_CC

Composite Symbol with UPC E linear component

117

BARCODE_RSS14STACK_CC

Composite Symbol with GS1 DataBar-14 Stacked component

118

BARCODE_RSS14_OMNI_CC

Composite Symbol with GS1 DataBar-14 Stacked Omnidirectional component

119

BARCODE_RSS_EXPSTACK_CC

Composite Symbol with GS1 DataBar Expanded Stacked component

120

BARCODE_KIX

Dutch Post KIX Code

121

BARCODE_CODE32

Code 32



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



[1] This value is ignored for Australia Post 4-State Barcodes, PostNet, PLANET, USPS OneCode, RM4SCC, PDF417, Data Matrix, Maxicode, QR Code and GS1 DataBar-14 Stacked - 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