Chapter 5. Encoder DLL API Reference

Creating PDF417 barcodes using DLL APIs involves three steps. The first step is to call PDF417Encode with data to encode and the PDF417 options. If this step succeeds, a pointer is returned from which you can query the attributes of the barcode created, or paint the barcode into an image file. Finally, you should call DestroyPDF417Result to release the memory resource used by the encoder result object.

For the meanings of PDF417 barcode attributes, such as rows, columns, aspect ratio and security level, see Chapter 2, Overview.

Table 5.1. List of Enumerations

EnumerationComment
ImageTypeEnumImage formats supported by the encoder.

Table 5.2. List of Functions

FunctionComment
PDF417EncodeEncodes data and returns a pointers that points to encoder result object.
PDF417Encode2Abbreviated version of PDF417Encode.
DestroyPDF417EncodeResultReleases all resources allocated to the encoder result object.
PDF417ResultGetNumRowsRetrieves the number of rows of the PDF417 barcode created.
PDF417ResultGetNumColsRetrieves the number of data columns of the PDF417 barcode created.
PDF417ResultGetSecurityLevelRetrieves the security level of the PDF417 barcode created.
PDF417ResultGetAspectRatioRetrieves the actual aspect ratio of the PDF417 barcode created.
PDF417ResultGetBarcodeStringRetrieves the barcode string that becomes a PDF417 symbol after being formated with a PDF417 font.
PDF417ResultGetBarcodeString2Returns barcode string without requiring user to preallocate the buffer.
PDF417GetErrorMessageRetrieves a string that describes the error.
PaintPDF417ImageRasterWrites the PDF417 barcode in raster image format specified to a disk file.
PaintPDF417ImageVectorWrites the PDF417 barcode in vector image format specified to a disk file.
PaintPDF417ImageClipboardCreates a Windows Enhanced Meta File object and place it into the clipboard.

5.1. ImageTypeEnum

Image formats supported by the encoder.

  enum ImageTypeEnum {
      IMAGE_PNG=0,
      IMAGE_SVG=1,
      IMAGE_EMF=2,
      IMAGE_EPS=3,
      IMAGE_BMP=4
  };

Remarks

The ImageTypeEnum enum has the following values:

Table 5.3. ImageTypeEnum Enumeration

ConstantValueComment
IMAGE_PNG0PNG (Portable Network Graphics).
IMAGE_SVG1SVG (Scalable Vector Graphics).
IMAGE_EMF2EMF (Windows Enhanced MetaFile).
IMAGE_EPS3EPS (Encapsulated PostScript).
IMAGE_BMP4BMP (Windows Bitmap).

PNG and BMP are raster formats, which store color information of individual pixels. SVG, EMF and EPS are vector graphics formats and contains drawing commands instead. If you are using raster graphic format, one pixel should be mapped to one or integral times pixels on the printer. If you are using vector graphics format, the drawing units should map to integral times pixels on the printer. They are referenced in the PaintPDF417ImageRaster function and PaintPDF417ImageVector function.

5.2. PDF417Encode

The PDF417Encode function encodes data and returns a pointers that points to encoder result object.

  int __stdcall  PDF417Encode(
      const char * dataToEncode,
      int numRows,
      int numCols,
      int securityLevel,
      int fullsizePDF,
      double aspectRatio,
      double yHeight,
      void ** ppResult
  );

Parameters

dataToEncode

[in] Pointer to a null-terminated string containing the data to be encoded. You can use tilde codes to encode control characters such as NUL, as well as advanced features such as ECI and MacroPDF417. For more information, see Section 2.2.1, “Input Format”.

numRows

[in] An integer that indicates the number of rows desired in the barcode created. Valid values are between 3 and 90, or 0 for automatic selection.

numCols

[in] An integer that indicates the number of data columns desired in the barcode created. Valid values are between 1 and 30, or 0 for automatic selection.

securityLevel

[in] An integer value that corresponds to the security level desired. Valid values are between 0 and 9. If 9 is specified, the program will select a security level based on the data encoded, based on the method described in the standard. Note: The security level in the result can be higher than specified, 10:30 PM 2/20/2010 but will never be lower. When the program finds that there is room for additional security codewords in the symbol, it will increase the security level automatically. To find out the actual security level in the symbol created, use PDF417ResultGetSecurityLevel function.

fullsizePDF

[in] An integer value that indicates whether to produce full-sized PDF417 symbol, or a compact version. If the value is 0, compact PDF symbols are produced.

aspectRatio

[in] The aspect ratio of the symbol desired. If 0 is specified, the program does not use it as a criteria.

yHeight

[in] The ratio of module height vs. module width. When you are createing barcodes using the fonts, use the value that match the font. For example, the yHeight for font 'MRV PDF417 N3' is 3.1.

ppResult

A pointer to a pointer that points to the encode result created. Use this pointer to discover the actual attributes of the symbol created, or create image files.

Return Values

If the function succeeded, the return value is 0. If the function failed, it returns the error code. You can call function PDF417GetErrorMessage to obtain the description of the error.

Remarks

This function encodes the data according to the parameter specified, and returns a pointer from which you can retrieve the encoding result.

5.3. PDF417Encode2

The function PDF417Encode2 is an abbreviated version of PDF417Encode.

  void *__stdcall    PDF417Encode2(
      const char * dataToEncode,
      int numRows,
      int numCols,
      int securityLevel,
      int fullsizePDF,
      double aspectRatio,
      double yHeight
  );

Parameters

dataToEncode

[in] Pointer to a null-terminated string containing the data to be encoded. You can use tilde codes to encode control characters such as NUL, as well as advanced features such as ECI and MacroPDF417. For more information, see Section 2.2.1, “Input Format”.

numRows

[in] An integer that indicates the number of rows desired in the barcode created. Valid values are between 3 and 90, or 0 for automatic selection.

numCols

[in] An integer that indicates the number of data columns desired in the barcode created. Valid values are between 1 and 30, or 0 for automatic selection.

securityLevel

[in] An integer value that corresponds to the security level desired. Valid values are between 0 and 9. If 9 is specified, the program will select a security level based on the data encoded, based on the method described in the standard. Note: The security level in the result can be higher than specified. but will never be lower. When the program finds that there is room for additional security codewords in the symbol, it will increase the security level automatically. To find out the actual security level in the symbol created, use PDF417ResultGetSecurityLevel function.

fullsizePDF

[in] An integer value that indicates whether to produce full-sized PDF417 symbol, or a compact version. If the value is 0, compact PDF symbols are produced.

aspectRatio

[in] The aspect ratio of the symbol desired. If 0 is specified, the program does not use it as a criteria.

yHeight

[in] The ratio of module height vs. module width. When you are createing barcodes using the fonts, use the value that match the font. For example, the yHeight for font 'MRV PDF417 N3' is 3.1.

Return Values

If the function failed, the return value is 0 (NULL). If it succeeds, it returns a pointer that points to the result object. You should release the encoder result object by calling function DestroyPDF417EncodeResult.

Remarks

In this function, a pointer is returned instead of status code. A non-null return value indicates that no error occured. The pointer associated resource must be released by calling DestroyPDF417EncodeResult.

The function PDF417Encode2 is an abbreviated version of PDF417Encode.

5.4. DestroyPDF417EncodeResult

The DestroyPDF417EncodeResult function releases all resources allocated to the encoder result object.

  void __stdcall DestroyPDF417EncodeResult(
      void * pResult
  );

Parameters

pResult

[in] Pointer to the encoder result object.

Remarks

After the object is destroyed, the specific pointer pResult is no longer valid.

5.5. PDF417ResultGetNumRows

The PDF417ResultGetNumRows function retrieves the number of rows of the PDF417 barcode created.

  int __stdcall  PDF417ResultGetNumRows(
      void * pEncodeResult
  );

Parameters

pEncodeResult

[in] The pointer that points to the encoding result object, returned from PDF417Encode or PDF417Encode2 functions.

Return Values

The number of data rows in the PDF417 barcode. Always succeed.

5.6. PDF417ResultGetNumCols

The PDF417ResultGetNumCols function retrieves the number of data columns of the PDF417 barcode created.

  int __stdcall  PDF417ResultGetNumCols(
      void * pEncodeResult
  );

Parameters

pEncodeResult

[in] The pointer that points to the encoding result object, returned from PDF417Encode or PDF417Encode2 functions.

Return Values

The number of data columns in the PDF417 barcode. Always succeed.

5.7. PDF417ResultGetSecurityLevel

The PDF417ResultGetSecurityLevel function retrieves the security level of the PDF417 barcode created.

  int __stdcall  PDF417ResultGetSecurityLevel(
      void * pEncodeResult
  );

Parameters

pEncodeResult

[in] The pointer that points to the encoding result object, returned from PDF417Encode or PDF417Encode2 functions.

Return Values

The actual security level in the PDF417 barcode. It should be a number bewteen 0 and 8.

Remarks

PDF417 specification defines nine different levels for security codewords, ranging between 0 and 9. In our software you can use 9 for automatic security level selection. The encoder always selects that the highest security level possible within the size constraint. To obtain the actual security level in the barcode, call function PDF417ResultGetSecurityLevel.

5.8. PDF417ResultGetAspectRatio

The PDF417ResultGetAspectRatio function retrieves the actual aspect ratio of the PDF417 barcode created.

  double __stdcall   PDF417ResultGetAspectRatio(
      void * pEncodeResult
  );

Parameters

pEncodeResult

[in] The pointer that points to the encoding result object, returned from PDF417Encode or PDF417Encode2 functions.

Return Values

The actual aspect ratio of the PDF417 barcode.

Remarks

The Aspect Ratio refers to the ratio of height to width of a bar code symbol. A code twice as high as it is wide has an aspect ration of 2; a code twice as wide as it is high has an aspect ratio of 0.5.

5.9. PDF417ResultGetBarcodeString

The PDF417ResultGetBarcodeString function retrieves the barcode string that becomes a PDF417 symbol after being formated with a PDF417 font.

  int __stdcall  PDF417ResultGetBarcodeString(
      void * pEncodeResult,
      char * buffer,
      unsigned int * maxSize,
      const char * eol
  );

Parameters

pEncodeResult

[in] The pointer that points to the encoding result object, returned from PDF417Encode or PDF417Encode2 functions.

buffer

[in] The pointer that points to a byte array that receives the string.

maxSize

[in,out] Pointer to a variable that specifies the size of the buffer pointed to by the buffer parameter, in bytes. When the function returns, this variable contains the size of the data copied to buffer.

eol

[in] Pointer to a NUL terminated string that will be appended to each row in the barcode string.

Return Values

If the function succeeded, it returns the length of the string (excluding terminating NUL character). If the funtion fails due to insufficient storage, it returns 0.

Remarks

When creating barcodes using font-based solution, you first call encoder function PDF417Encode or PDF417Encode2 to obtain a pointer that points to the result object. Then PDF417ResultGetBarcodeString is called to obtain a string that becomes PDF417 symbol after the font is applied. If memory is not an issue, allocate a large buffer with 8096 bytes to hold the largest PDF417 barcode. This size is sufficient for the largest symbol with carriage return and line feed as line ending.

5.10. PDF417ResultGetBarcodeString2

The PDF417ResultGetBarcodeString2 function returns barcode string without requiring user to preallocate the buffer.

  const char *__stdcall  PDF417ResultGetBarcodeString2(
      void * pEncodeResult,
      const char * eol
  );

Parameters

pEncodeResult

[in] The pointer that points to the encoding result object, returned from PDF417Encode or PDF417Encode2 functions.

eol

[in] Pointer to a NUL terminated string that will be appended to each row in the barcode string.

Return Values

Pointer to a NUL terminated string that represents the barcode (barcode string). If the function failed due to insufficient memory, it returns NULL.

Remarks

This function was added in 4.1 release to make it easier for the caller to retrieve barcode string. The encoder result manages the buffer by itself. Caller should cache the string returned, but not the pointer, as the contents may change after another call of PDF417ResultBarcodeString2 is made.

5.11. PDF417GetErrorMessage

The PDF417GetErrorMessage function retrieves a string that describes the error.

  const char *__stdcall  PDF417GetErrorMessage(
      int errorno
  );

Parameters

errorno

[in] The error number.

Return Values

a read only string that describes the error.

Remarks

The string returned is a read only string. User should not modify the string directly.

5.12. PaintPDF417ImageRaster

The PaintPDF417ImageRaster function writes the PDF417 barcode in raster image format specified to a disk file.

  int __stdcall  PaintPDF417ImageRaster(
      void * pEncodeResult,
      const char * lpszFilename,
      int pixelsPerModule,
      int forecolor,
      int backcolor,
      int imageType
  );

Parameters

pEncodeResult

[in] Pointer that points to the encoder result object.

pszFilename

[in] Pointer to the file name for the image file to be created.

pixelsPerModule

[in] Number pixels per module with.

forecolor

[in] Value of the foreground color, in RGB colorspace.

backcolor

[in] Value of the background color, in RGB colorspace.

imageType

[in] An integer that indicates the image file format. The current version supports two formats: PNG(0) and BMP(4).

Return Values

If the function failed, it returns the error code. You can call function PDF417GetErrorMessage to obtain the description of the error.

Remarks

Note: the order of the component bytes are R, G and B, which is opposite of COLORREF type on Windows.

5.13. PaintPDF417ImageVector

The PaintPDF417ImageVector function writes the PDF417 barcode in vector image format specified to a disk file.

  int __stdcall  PaintPDF417ImageVector(
      void * pEncodeResult,
      const char * lpszFilename,
      int module_width_hm,
      int target_dpi,
      int forecolor,
      int backcolor,
      int imageType
  );

Parameters

pEncodeResult

[in] Pointer that points to the encoder result object.

module_width_hm

[in] Module width (X dimension), in the unit of high metric. 1 unit high metric = 1/1000 cm.

target_dpi

[in] The resolution of the target printer.

forecolor

[in] Value of the foreground color, in RGB colorspace.

backcolor

[in] Value of the background color, in RGB colorspace.

imageType

[in] An integer that indicates the image file format. The current version supports three formats: SVG(1), EMF(2) and EPS(3).

Return Values

If the function failed, it returns the error code. You can call function PDF417GetErrorMessage to obtain the description of the error.

Remarks

Note: the order of the component bytes are R, G and B, which is opposite of COLORREF type on Windows.

5.14. PaintPDF417ImageClipboard

The PaintPDF417ImageClipboard function Creates a Windows Enhanced Meta File object and place it into the clipboard.

  int __stdcall  PaintPDF417ImageClipboard(
      void * pEncodeResult,
      int module_width_hm,
      int target_dpi,
      int forecolor,
      int backcolor
  );

Parameters

pEncodeResult

[in] Pointer that points to the encoder result object.

module_width_hm

[in] Module width (X dimension), in the unit of high metric. 1 unit high metric = 1/1000 cm.

target_dpi

[in] The resolution of the target printer.

forecolor

[in] Value of the foreground color, in RGB colorspace.

backcolor

[in] Value of the background color, in RGB colorspace.

Return Values

If the function failed, it returns the error code. You can call function PDF417GetErrorMessage to obtain the description of the error.