Chapter 8. Encoder DLL API Reference

Creating QR Code barcodes using DLL APIs involves three steps. The first step is to call QRCodeEncode or QRCodeEncode2 with data to encode and size option. If this step succeeded, a pointer is returned from which you can query the attributes of the barcode created, paint the barcode into an image file, or obtain the barcode string. Finally, you should call DestroyQRCodeEncodeResult to release the memory resource used by the encoder result object.

Table 8.1. List of Enumerations

EnumerationComment
ImageTypeEnumImage formats supported by the encoder.

Table 8.2. List of Functions

FunctionComment
QRCodeEncodeEncodes data and returns a pointer that points to encoder result object.
QRCodeEncode2Abbreviated version of QRCodeEncode.
QRCodeEncode2WThe function QRCodeEncode2W is used to encode unicode strings into QR Code in a way compliant with ZXing reader.
MicroQRCodeEncodeEncodes data in Micro QR Code and returns a pointer that points to encoder result object.
MicroQRCodeEncode2Abbreviated version of MicroQRCodeEncode.
HIBC_QRCodeEncodeEncodes data and returns a pointer that points to encoder result object.
HIBC_QRCodeEncode2Abbreviated version of QRCodeEncode.
QRCodeResultGetVersionRetrieves the size ID of the QRCode barcode created.
QRCodeResultGetBarcodeStringRetrieves the barcode string that becomes a QRCode symbol after being formatted with a QRCode font.
DestroyQRCodeEncodeResultReleases all resources allocated to the encoder result object.
PaintQRCodeImageRasterWrites the QRCode barcode in raster image format specified to a disk file.
PaintQRCodeImageVectorWrites the QRCode barcode in vector image format specified to a disk file.
PaintQRCodeImageRaster2Writes the QRCode barcode in raster image format specified to IStream object.
PaintQRCodeImageVector2Writes the QRCode barcode in vector image format specified to an IStream object.
PaintQRCodeImageEMFCreates a Windows Enhanced Meta File object and returns the handle.
QRCodeGetErrorMessageRetrieves a string that describes the error.
QRCodeResultGetBarcodeString2Returns barcode string without requiring user to preallocate the buffer.
PaintQRCodeImageClipboardCreates a Windows Enhanced Meta File object and place it into the clipboard.
QRCodeGetParityCalculates the parity value based on the whole data encoded and split into multiple symbols.

8.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 8.3. ImageTypeEnum Enumeration

ConstantValueComment
IMAGE_PNG= 0PNG (Portable Network Graphics)
IMAGE_SVG= 1SVG (Scalable Vector Graphics)
IMAGE_EMF= 2EMF (Windows Enhanced MetaFile)
IMAGE_EPS= 3EPS (Encapsulated PostScript)
IMAGE_BMP= 4BMP (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.

8.2. QRCodeEncode

The QRCodeEncode function encodes data and returns a pointer that points to encoder result object.

  int __stdcall  QRCodeEncode(
      const char * dataToEncode,
      int versionRequested,
      int ecLevel,
      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 structural append. For more information, see Section 2.2, “Input Format”.

versionRequested

[in] An integer value that corresponds to the size ID of the QRCode barcode. QR Code has a total of 40 different sizes, ranging between 1 and 40. If 0 is specified, the encoder will select the minimum size that can have the data encoded. Note: after version 5.2 this parameter is updated to include modifier byte, which can be used to fine tune the encoder behavior. See Appendix C, Version ID Parameter (updated in version 5.2)

ecLevel

[in] An integer that sets the error correction level in the barcode. Valid values are 0, 1, 2 and 3, which correspond to Level L, M, Q and H respectively.

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

8.3. QRCodeEncode2

The function QRCodeEncode2 is an abbreviated version of QRCodeEncode.

  void *__stdcall    QRCodeEncode2(
      const char * dataToEncode,
      int versionRequested,
      int ecLevel
  );

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. For more information, see Section 2.2, “Input Format”.

versionRequested

[in] An integer value that corresponds to the size ID of the QRCode barcode. QR Code has a total of 40 different sizes, ranging between 1 and 40. If 0 is specified, the encoder will select the minimum size that can have the data encoded.

ecLevel

[in] An integer that sets the error correction level in the barcode. Valid values are 0, 1, 2 and 3, which correspond to Level L, M, Q and H respectively.

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

Remarks

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

8.4. QRCodeEncode2W

The function QRCodeEncode2W is used to encode unicode strings into QR Code in a way compliant with ZXing reader.

  void *__stdcall    QRCodeEncode2W(
      const wchar_t * dataToEncode,
      int versionRequested,
      int ecLevel
  );

Parameters

dataToEncode

[in] Pointer to a null-terminated UTF16 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. For more information, see Section 2.2, “Input Format”.

versionRequested

[in] An integer value that corresponds to the size ID of the QRCode barcode. QR Code has a total of 40 different sizes, ranging between 1 and 40. If 0 is specified, the encoder will select the minimum size that can have the data encoded.

ecLevel

[in] An integer that sets the error correction level in the barcode. Valid values are 0, 1, 2 and 3, which correspond to Level L, M, Q and H respectively.

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

Remarks

Read Section 2.2.6, “Unicode String Support” for more information. QR Code does not natively support unicode. Use of this feature require special support of a reader.

8.5. MicroQRCodeEncode

The MicroQRCodeEncode function encodes data in Micro QR Code and returns a pointer that points to encoder result object.

  int __stdcall  MicroQRCodeEncode(
      const char * dataToEncode,
      int versionRequested,
      int ecLevel,
      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. For more information, see Section 2.2, “Input Format”.

versionRequested

[in] An integer value that corresponds to the size ID of the QRCode barcode. Micro QR Code has a total of 4 sizes: 1, 2, 3 and 4. If 0 is specified, the encoder selects the minimum version that can accomodate the data. If value greater than 4 is specified, the encoder uses 4.

ecLevel

[in] An integer that sets the error correction level in the barcode. Valid values are 0, 1, 2 and 3, which correspond to Level E, L, M and Q. respectively. Not all version/eclevel combinations are possible. If ecLevel is not possible, a lower level is used. If the error correction level is not achieveable in the version requested, the symbol version is bumped up.

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

8.6. MicroQRCodeEncode2

The function MicroQRCodeEncode2 is an abbreviated version of MicroQRCodeEncode.

  void *__stdcall    MicroQRCodeEncode2(
      const char * dataToEncode,
      int versionRequested,
      int ecLevel
  );

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. For more information, see Section 2.2, “Input Format”.

versionRequested

[in] An integer value that corresponds to the size ID of the QRCode barcode. Micro QR Code has a total of 4 sizes: 1, 2, 3 and 4. If 0 is specified, the encoder selects the minimum version that can accomodate the data. If value greater than 4 is specified, the encoder uses 4.

ecLevel

[in] An integer that sets the error correction level in the barcode. Valid values are 0, 1, 2 and 3, which correspond to Level E, L, M and Q. respectively. Not all version/eclevel combinations are possible. If ecLevel is not possible, a lower level is used. If the error correction level is not achieveable in the version requested, the symbol version is bumped up.

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

Remarks

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

8.7. HIBC_QRCodeEncode

The HIBC_QRCodeEncode function encodes data and returns a pointer that points to encoder result object.

  int __stdcall  HIBC_QRCodeEncode(
      const char * dataToEncode,
      int versionRequested,
      int ecLevel,
      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 structural append. For more information, see Section 2.2, “Input Format”.

versionRequested

[in] An integer value that corresponds to the size ID of the QRCode barcode. QR Code has a total of 40 different sizes, ranging between 1 and 40. If 0 is specified, the encoder will select the minimum size that can have the data encoded.

ecLevel

[in] An integer that sets the error correction level in the barcode. Valid values are 0, 1, 2 and 3, which correspond to Level L, M, Q and H respectively.

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

8.8. HIBC_QRCodeEncode2

The function HIBC_QRCodeEncode2 is an abbreviated version of QRCodeEncode.

  void *__stdcall    HIBC_QRCodeEncode2(
      const char * dataToEncode,
      int versionRequested,
      int ecLevel
  );

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. For more information, see Section 2.2, “Input Format”.

versionRequested

[in] An integer value that corresponds to the size ID of the QRCode barcode. QR Code has a total of 40 different sizes, ranging between 1 and 40. If 0 is specified, the encoder will select the minimum size that can have the data encoded.

ecLevel

[in] An integer that sets the error correction level in the barcode. Valid values are 0, 1, 2 and 3, which correspond to Level L, M, Q and H respectively.

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

Remarks

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

8.9. QRCodeResultGetVersion

The QRCodeResultGetSizeID function retrieves the size ID of the QRCode barcode created.

  int __stdcall  QRCodeResultGetVersion(
      void * pEncodeResult
  );

Parameters

pEncodeResult

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

Return Values

The actual version of the barcode.

8.10. QRCodeResultGetBarcodeString

The QRCodeResultGetBarcodeString function retrieves the barcode string that becomes a QRCode symbol after being formatted with a QRCode font.

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

Parameters

pEncodeResult

[in] The pointer that points to the encoding result object, returned from QRCodeEncode or QRCodeEncode2 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 function fails due to insufficient storage, it returns 0.

Remarks

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

8.11. DestroyQRCodeEncodeResult

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

  void __stdcall DestroyQRCodeEncodeResult(
      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.

8.12. PaintQRCodeImageRaster

The PaintQRCodeImageRaster function writes the QRCode barcode in raster image format specified to a disk file.

  int __stdcall  PaintQRCodeImageRaster(
      void * pEncodeResult,
      const wchar_t * wszFilename,
      int pixelsPerModule,
      int forecolor,
      int backcolor,
      int imageType
  );

Parameters

pEncodeResult

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

wszFilename

[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 color space.

backcolor

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

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

8.13. PaintQRCodeImageVector

The PaintQRCodeImageVector function writes the QRCode barcode in vector image format specified to a disk file.

  int __stdcall  PaintQRCodeImageVector(
      void * pEncodeResult,
      const wchar_t * wszFilename,
      int module_width_hm,
      int target_dpi,
      int forecolor,
      int backcolor,
      int imageType
  );

Parameters

pEncodeResult

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

wszFilename

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

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 color space.

backcolor

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

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

8.14. PaintQRCodeImageRaster2

The PaintQRCodeImageRaster function writes the QRCode barcode in raster image format specified to IStream object.

  int __stdcall  PaintQRCodeImageRaster2(
      void * pEncodeResult,
      IStream * ostream,
      int pixelsPerModule,
      int forecolor,
      int backcolor,
      int imageType
  );

Parameters

pEncodeResult

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

ostream

[in] Pointer to an IStream object.

pixelsPerModule

[in] Number pixels per module with.

forecolor

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

backcolor

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

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

8.15. PaintQRCodeImageVector2

The PaintQRCodeImageVector function writes the QRCode barcode in vector image format specified to an IStream object.

  int __stdcall  PaintQRCodeImageVector2(
      void * pEncodeResult,
      IStream * ostream,
      int module_width_hm,
      int target_dpi,
      int forecolor,
      int backcolor,
      int imageType
  );

Parameters

pEncodeResult

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

ostream

[in] Pointer to an IStream 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 color space.

backcolor

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

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

8.16. PaintQRCodeImageEMF

The PaintQRCodeImageClipboard function Creates a Windows Enhanced Meta File object and returns the handle.

  HENHMETAFILE __stdcall PaintQRCodeImageEMF(
      void * pEncodeResult,
      int module_len_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 color space.

backcolor

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

Return Values

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

Remarks

The caller should destroy this handle after using.

8.17. QRCodeGetErrorMessage

The QRCodeGetErrorMessage function retrieves a string that describes the error.

  const char *__stdcall  QRCodeGetErrorMessage(
      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.

8.18. QRCodeResultGetBarcodeString2

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

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

Parameters

pEncodeResult

[in] The pointer that points to the encoding result object, returned from QRCodeEncode or QRCodeEncode2 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

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 QRCodeResultBarcodeString2 is made.

8.19. PaintQRCodeImageClipboard

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

  int __stdcall  PaintQRCodeImageClipboard(
      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 color space.

backcolor

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

Return Values

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

8.20. QRCodeGetParity

The QRCodeGetParity function calculates the parity value based on the whole data encoded and split into multiple symbols.

  int __stdcall  QRCodeGetParity(
      const char * dataToEncode
  );

Parameters

dataToEncode

[in] Pointer to a null-terminated string containing the data to be encoded. You must pass the full data string to this parameter. Subsequent calls should use ~2[seqno][symbol, parity] plus data that each symbol encodes.

Return Values

The parity value that groups the symbols. It should be between 0 and 255.

Remarks

The QR Code structural append features allows data to be split across multiple symbols ( < 16). A SA capable scanner reads the symbols one and one, and emits the data after all the symbols are read. Symbols belong to the same cluster share the same parity value, which is calculate based on the full data.