| Customize Help
| Save Settings

McodeWrite


Function Map
Syntax
Description
Parameters
- ModelCodeId
- ImageBufId
Table: For specifying the image buffer
- StringPtr
Table: For specifying the string of the code
- ControlFlag
Table: For specifying the function's control flag
- WriteResultCodeId
Table: For specifying the write result buffer
Remarks
Compilation information
Synopsis
Encode an ASCII string into a symbol.
Syntax
void McodeWrite(
MIL_ID ModelCodeId, //in
MIL_ID ImageBufId, //in
MIL_CONST_TEXT_PTR StringPtr, //in
MIL_INT64 ControlFlag, //in
MIL_ID WriteResultCodeId //in
)
Description

This function encodes a null-terminated ASCII string into a symbol (code) using the code type and encoding scheme, specified by the code model, and draws the code into a specified image.

For a given code model and string, you can inquire the minimum buffer size required to draw the code, using McodeWrite() with its ImageBufId parameter set to M_NULL, and then using McodeGetResult() with M_WRITE_SIZE_X and M_WRITE_SIZE_Y.

The control type settings of the specified code model determine how to perform the operation. Before performing a McodeWrite() operation, you must set certain controls, using McodeControl(), specifically:

Control

Notes

M_CELL_NUMBER_X, M_CELL_NUMBER_Y

Specifies the number of cells in the X and Y directions. Improves the robustness of the operation, for 2D code types only. If these settings are set to M_DEFAULT, then the number of cells will be selected automatically so as to minimize the size of the resulting code.

M_CELL_SIZE_MODE

Specifies how to establish the cell size.
M_CELL_SIZE_VALUE

Specifies the cell size to use when M_CELL_SIZE_MODE is set to M_USER_DEFINED.
M_DOT_SHAPE

Specifies the shape in which to draw cells.
M_DOT_SIZE

Specifies the size of the dot (or square) in which to draw cells.

M_ENCODING

Specifies the encoding scheme. This control type must be set for code types where M_ANY is not supported as the encoding scheme.

M_ERROR_CORRECTION

Specifies the type of error correction. This control type must be set for code types where M_ANY is not a supported error correction type.

M_FOREGROUND_VALUE

Specifies the foreground color of the code. This control type is essential for all code types.

If you have associated the target image with a camera calibration context, you can specify that certain input settings be interpreted in world units. To do so, use McodeControl() with M_CELL_SIZE_INPUT_UNITS set to M_WORLD. Note that if you set this constant to M_WORLD but you don't pass McodeWrite() a calibrated target image, the function will generate an error.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.
Parameters
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.
Parameters
ModelCodeId

Specifies the identifier of the code model.

ImageBufId

Specifies the 8-bit unsigned 1-band image buffer in which to write the symbol. Set this parameter to one of the following.

function map For specifying the image buffer
Click to summarizeValue Description
Click to summarize M_NULL

Allows you to inquire about the minimum buffer size required. Using this value means that McodeWrite() will not write into an image buffer.

After calling McodeWrite() with M_NULL, call McodeGetResult() to retrieve the minimum width (M_WRITE_SIZE_X) and height (M_WRITE_SIZE_Y) required for the image buffer.

(summarize)
Click to summarize MIL image buffer identifier

Specifies that McodeWrite() will write into the image buffer, and in which image buffer to write. This buffer must be 8-bit unsigned. In addition, it should be large enough to hold the symbol.

(summarize)
StringPtr

Specifies the address of the string to be encoded.

function map For specifying the string of the code
Click to summarizeValue Description
Click to summarize M_NULL

Specifies that a sample string will be encoded. This can be used if you need to test or use the functionality of McodeWrite() without needing to encode a specific string (for example, to draw the code type on a button in an interface). The sample string that is encoded depends on the control values set by McodeControl().

(summarize)
Click to summarize MIL_TEXT("String") 1

Specifies the address of the string. You need to know the string specifications of the code to write.

Note the following restrictions for certain code types:

  • If the code type is a Codabar code, the string must be numeric, but can contain the following ASCII characters: minus (-), dollar sign ($), colon (:), forward slash (/), period (.), and plus (+). In addition, the string must start and end with any of the following characters: a, b, c, or d.

  • If the code type is an Interleaved 2 of 5 code, the string must have an even number of characters.

  • If the code type is a Maxicode code, with M_ENCODING set to M_ENC_MODE2 or M_ENC_MODE3, the string must respect the structured carrier message format (the portion of the string that contains postal code, country code, and class of service information).

  • If the code type is a composite code, the string must be passed in the following format: 1D string|2D string, where | is used as the separator.

  • If the code type uses an M_ENC_MODE2 or M_ENC_MODE3 encoding scheme, the string is truncated so that only the string that can fit in a single code is written. MIL does not support a Structured Append sequence of separate but logically linked ECC 200 codes.

  • If the code type is a composite code, the FNC1 separator is represented by the unprintable character with ASCII value 29.

In addition, add parentheses around the application identifiers in your string. Note that this is required by the McodeWrite() operation; the parentheses are not actually coded.

(summarize)

1 If you are passing the value in a variable, don't enclose it in MIL_TEXT().

ControlFlag

Specifies the function's control flag. This parameter can be set to one or more of the following value: (for example, M_ESCAPE_SEQUENCE + M_GS1_FORMAT).

function map For specifying the function's control flag
Click to summarizeValue Description
Click to summarize M_DEFAULT

Specifies that the string to encode does not use ASCII character codes for unprintable characters. Unprintable characters are not encoded. In addition, the string is not written in GS1 format.

This value cannot be combined with any other value.

(summarize)
Click to summarize M_ESCAPE_SEQUENCE

Specifies that the string to encode uses ASCII character codes for unprintable characters.

You must use a code type that supports unprintable characters specified using ASCII codes. When typing the string to encode, the unprintable character's ASCII character code must be in hexadecimal format, preceded by \x (for example, \x0D for ASCII 13, which is the carriage return).

Note that if you want to encode the "\" character in escape sequence mode, type "\\".

(summarize)
Click to summarize M_GS1_FORMAT

Specifies that the string should be written as a GS1 code.

This value is only available when dealing with M_AZTEC, M_DATAMATRIX, M_CODE128, M_EAN14, M_GS1_128, and M_QRCODE code types.

(summarize)
WriteResultCodeId

Specifies the identifier of the code write result buffer. The result buffer must have been allocated using McodeAllocResult() with M_CODE_WRITE_RESULT. Set this parameter to one of the following.

function map For specifying the write result buffer
Click to summarizeValue Description
Click to summarize MIL write result buffer identifier

Specifies the identifier of the write result buffer.
Remark
Compilation information
Header Include mil.h.
Library Use mil.lib; milcode.lib.
DLL Requires mil.dll; milcode.dll.
NULL UNSIGNED NULL DEFAULT ESCAPE SEQUENCE GS1 FORMAT