Notice: This documentation is archived. For the latest product features and documentation, please visit Dynamsoft Capture Vision Documentation.

C Functions

Initialization

Method	Description
`DLR_CreateInstance`	Creates a Dynamsoft Label Recognizer instance.
`DLR_DestroyInstance`	Destroys an instance of Dynamsoft Label Recognizer.
`DLR_InitLicense`	Sets the license and activates the SDK.

DLR_CreateInstance

Create an instance of Dynamsoft Label Recognizer.

void* DLR_CreateInstance ()	

Return value

Returns an instance of Dynamsoft Label Recognizer. If failed, returns NULL.

Code Snippet

void* recognizer = DLR_CreateInstance();
DLR_DestroyInstance(recognizer);

DLR_DestroyInstance

Destroy the instance of Dynamsoft Label Recognizer.

void DLR_DestroyInstance (void* recognizer)	

Parameters

[in] recognizer Handle of the Dynamsoft Label Recognizer instance.

Code Snippet

void* recognizer = DLR_CreateInstance();
DLR_DestroyInstance(recognizer);

DLR_InitLicense

Sets product key and activate the SDK.

int DLR_InitLicense (const char* pLicense, char errorMsgBuffer[], const int errorMsgBufferLen)

Parameters

[in] pLicense The product keys. [in, out] errorMsgBuffer The buffer is allocated by caller and the recommending length is 256. The error message will be copied to the buffer.
[in] errorMsgBufferLen The length of allocated buffer.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_DestroyInstance(recognizer);

Setting

Method	Description
`DLR_GetRuntimeSettings`	Gets the current settings and saves it into a struct.
`DLR_UpdateRuntimeSettings`	Updates runtime settings with a given struct.
`DLR_UpdateRuntimeSettingsFromString`	Updates runtime settings with the settings in a given JSON string.
`DLR_ResetRuntimeSettings`	Resets the runtime settings.
`DLR_AppendSettingsFromString`	Appends LabelRecognizerParameter settings in a string to the SDK object.
`DLR_AppendSettingsFromFile`	Appends LabelRecognizerParameter settings in a file to the SDK object.
`DLR_OutputSettingsToFile`	Outputs LabelRecognizerParameter settings into a file (JSON file).
`DLR_OutputSettingsToString`	Output runtime settings to a string.
`DLR_ClearAppendedSettings`	Clears appended LabelRecognizerParameter settings.
`DLR_UpdateReferenceRegionFromBarcodeResults`	Updates reference region which is defined with source type LST_BARCODE.
`DLR_GetModeArgument`	Get argument value for the specified mode parameter.
`DLR_SetModeArgument`	Set argument value for the specified mode parameter.

DLR_GetRuntimeSettings

Get current settings and save them into a DLR_RuntimeSettings struct.

int DLR_GetRuntimeSettings (void* recognizer, DLR_RuntimeSettings* settings)

Parameters

[in] recognizer Handle of the label recognition instance.
[in,out] settings The struct of runtime settings.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_RuntimeSettings settings;
int errorCode = DLR_GetRuntimeSettings(recognizer, &settings);
DLR_DestroyInstance(recognizer);

DLR_UpdateRuntimeSettings

Update runtime settings with a given DLR_RuntimeSettings struct.

int DLR_UpdateRuntimeSettings (void* recognizer, DLR_RuntimeSettings* settings, char errorMsgBuffer[], const int errorMsgBufferLen)

Parameters

[in] recognizer Handle of the label recognition instance.
[in] settings The struct of runtime settings.
[in,out] errorMsgBuffer The buffer is allocated by caller and the recommended length is 256.The error message will be copied to the buffer.
[in] errorMsgBufferLen The length of the allocated buffer.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_RuntimeSettings settings;
int errorCode = DLR_GetRuntimeSettings(recognizer, &settings);
settings.maxThreadCount = 4;
DLR_UpdateRuntimeSettings(recognizer, &settings, errorMessage, 256);
DLR_DestroyInstance(recognizer);

DLR_UpdateRuntimeSettingsFromString

Updates runtime settings with the parameters obtained from a JSON string.

int DLR_UpdateRuntimeSettingsFromString (void* recognizer, const char* content, char errorMsgBuffer[], const int errorMsgBufferLen)

Parameters [in] recognizer Handle of the label recognition instance.
[in] content A JSON string that represents the content of the settings.
[in,out] errorMsgBuffer The buffer is allocated by caller and the recommending length is 256. The error message will be copied to the buffer.
[in] errorMsgBufferLen The length of allocated buffer.

Return Value
Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();

const char* strJson = "{\"LabelRecognizerParameter\":{\"Name\":\"P1\", \"RegionPredetectionModes\":[{\"Mode\":\"RPM_GENERAL_HSV_CONTRAST\"}], \"ReferenceRegionNameArray\": [\"R1\"]},\"ReferenceRegion\":{\"Name\":\"R1\",\"Localization\":{\"SourceType\":\"LST_PREDETECTED_REGION\",\"RegionPredetectionModesIndex\":0},\"TextAreaNameArray\":[\"T1\"]},\"TextArea\":{\"Name\":\"T1\",\"CharacterModelName\":\"Number\"}}";

DLR_UpdateRuntimeSettingsFromString(recognizer, strJson, errorMessage, 256);
DLR_DestroyInstance(recognizer);

DLR_ResetRuntimeSettings

Reset all runtime settings to default values.

int DLR_ResetRuntimeSettings (void* recognizer)

Parameters

[in] recognizer Handle of the label recognition instance.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_RuntimeSettings settings;
int errorCode = DLR_GetRuntimeSettings(recognizer, &settings);
settings.maxThreadCount = 4;
DLR_UpdateRuntimeSettings(recognizer, &settings);
DLR_ResetRuntimeSettings(recognizer);
DLR_DestroyInstance(recognizer);

DLR_AppendSettingsFromString

Append a new template string to the current label recognition instance.

int DLR_AppendSettingsFromString (void* recognizer, const char* content, char errorMsgBuffer[], const int errorMsgBufferLen)

Parameters

[in] recognizer Handle of the label recognition instance.
[in] content A JSON string that represents the content of the settings.
[in,out] errorMsgBuffer The buffer is allocated by caller and the recommending length is 256. The error message will be copied to the buffer.
[in] errorMsgBufferLen The length of allocated buffer.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_AppendSettingsFromString(recognizer, "{\"LabelRecognizerParameter\":{\"Name\":\"P1\", \"RegionPredetectionModes\":[{\"Mode\":\"RPM_GENERAL_HSV_CONTRAST\"}], \"ReferenceRegionNameArray\": [\"R1\"]},\"ReferenceRegion\":{\"Name\":\"R1\",\"Localization\":{\"SourceType\":\"LST_PREDETECTED_REGION\",\"RegionPredetectionModesIndex\":0},\"TextAreaNameArray\":[\"T1\"]},\"TextArea\":{\"Name\":\"T1\",\"CharacterModelName\":\"Number\"}}", errorMessage, 256);
DLR_DestroyInstance(recognizer);

DLR_AppendSettingsFromFile

Appends LabelRecognizerParameter settings in a file to the SDK object.

int DLR_AppendSettingsFromFile (void* recognizer, const char* filePath, char errorMsgBuffer[], const int errorMsgBufferLen)

Parameters

[in] recognizer Handle of the label recognition instance.
[in] filePath The settings file path.
[in,out] errorMsgBuffer The buffer is allocated by caller and the recommending length is 256. The error message will be copied to the buffer.
[in] errorMsgBufferLen The length of allocated buffer.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_AppendSettingsFromFile(recognizer, "your file path", errorMessage, 256);
DLR_DestroyInstance(recognizer);

DLR_OutputSettingsToFile

Outputs runtime settings and save them into a settings file (JSON file).

int DLR_OutputSettingsToFile (void* recognizer, const char* filePath, const char* templateName)

Parameters

[in] recognizer Handle of the label recognition instance.
[in] filePath The path of the output file which stores current settings.
[in] templateName A unique name for declaring current runtime settings.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_AppendSettingsFromString(recognizer, "{\"LabelRecognizerParameter\":{\"Name\":\"P1\", \"RegionPredetectionModes\":[{\"Mode\":\"RPM_GENERAL_HSV_CONTRAST\"}], \"ReferenceRegionNameArray\": [\"R1\"]},\"ReferenceRegion\":{\"Name\":\"R1\",\"Localization\":{\"SourceType\":\"LST_PREDETECTED_REGION\",\"RegionPredetectionModesIndex\":0},\"TextAreaNameArray\":[\"T1\"]},\"TextArea\":{\"Name\":\"T1\",\"CharacterModelName\":\"Number\"}}", errorMessage, 256);
DLR_OutputSettingsToFile(recognizer, "C:\\Program Files (x86)\\Dynamsoft\\{Version number}\\Templates\\CurrentRuntimeSettings.json", "currentRuntimeSettings");
DLR_DestroyInstance(recognizer);

DLR_OutputSettingsToString

Outputs runtime settings and save them into a settings file (JSON file).

int DLR_OutputSettingsToString (void* recognizer, char content[], const int contentLen, const char* pSettingsName)

Parameters

[in] recognizer Handle of the label recognition instance.
[in,out] content The output string which stores the contents of current settings.
[in] contentLen The length of output string.
[in] pSettingsName A unique name for declaring current runtime settings.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
char conent[2048] = {0};
DLR_OutputSettingsToString(recognizer, content, 2048, "currentRuntimeSettings");
DLR_DestroyInstance(recognizer);

DLR_ClearAppendedSettings

Clear all appended parameter settings of the current label recognition instance.

void DLR_ClearAppendedSettings (void* recognizer)	

Parameters

[in] recognizer Handle of the Dynamsoft Label Recognizer instance.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_ClearAppendedSettings(recognizer);

DLR_UpdateReferenceRegionFromBarcodeResults

Updates reference region which is defined with source type DLR_LST_BARCODE.

int DLR_UpdateReferenceRegionFromBarcodeResults (void* recognizer, const BarcodeResultArray* barcodeResults, const char* templateName)

Parameters

[in] recognizer Handle of the Dynamsoft Label Recognizer instance.
[in] barcodeResults The barcode results used to localize reference region. See also BarcodeResultArray. [in] templateName The template name. A template name is the value of key LabelRecognizerParameter.Name defined in JSON formatted settings. If no template name is specified, current runtime settings will be used.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_AppendSettingsFromString(recognizer, "{\"LabelRecognizerParameter\":{\"Name\":\"P1\", \"RegionPredetectionModes\":[{\"Mode\":\"RPM_GENERAL_HSV_CONTRAST\"}], \"ReferenceRegionNameArray\": [\"R1\"]},\"ReferenceRegion\":{\"Name\":\"R1\",\"Localization\":{\"SourceType\":\"LST_BARCODE\"},\"TextAreaNameArray\":[\"T1\"]},\"TextArea\":{\"Name\":\"T1\",\"CharacterModelName\":\"Number\"}}", errorMessage, 256);
//Get barcodeResults from Dynamsoft Barcode Reader SDK
DLR_UpdateReferenceRegionFromBarcodeResults(recognizer, barcodeResults, "P1");
DLR_DestroyInstance(recognizer);

DLR_SetModeArgument

Set argument value for the specified mode parameter.

int DLR_SetModeArgument (void* recognizer, const char* modesName, const int index, const char* argumentName, const char* argumentValue, char errorMsgBuffer[],  const int errorMsgBufferLen)	

Parameters

[in] recognizer Handle of the label recognition instance.
[in] modesName The mode parameter name to set argument.
[in] index The array index of mode parameter to indicate a specific mode.
[in] argumentName The name of the argument to set.
[in] argumentValue The value of the argument to set.
[in,out] errorMsgBuffer The buffer is allocated by the caller and the recommended length is 256. The error message will be copied to the buffer.
[in] errorMsgBufferLen The length of the allocated buffer.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Remark

Check follow link for available modes and arguments:

RegionPredetectionModes

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_RuntimeSettings settings;
int errorCode = DLR_GetRuntimeSettings(recognizer, &settings);
settings.furtherModes.regionPredetectionModes[0] = RPM_GENERAL_RGB_CONTRAST;
DLR_UpdateRuntimeSettings(recognizer, &settings, errorMessage, 256);
DLR_SetModeArgument(recognizer, "RegionPredetectionModes", 0, "AspectRatioRange", "100", errorMessage, 256);
DLR_DestroyInstance(recognizer);

DLR_GetModeArgument

Get argument value for the specified mode parameter.

int DLR_GetModeArgument (void* recognizer, const char* modesName, const int index, const char* argumentName, char valueBuffer[], const int valueBufferLen, char errorMsgBuffer[], const int errorMsgBufferLen)	

Parameters

[in] recognizer Handle of the label recognition instance.
[in] modesName The mode parameter name to get argument.
[in] index The array index of mode parameter to indicate a specific mode.
[in] argumentName The name of the argument to get.
[in,out] valueBuffer The buffer is allocated by caller and the recommended length is 480. The argument value would be copied to the buffer.
[in] valueBufferLen The length of allocated buffer.
[in,out] errorMsgBuffer The buffer is allocated by the caller and the recommended length is 256. The error message will be copied to the buffer.
[in] errorMsgBufferLen The length of the allocated buffer.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Remark

Check follow link for available modes and arguments:

RegionPredetectionModes

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_RuntimeSettings settings;
int errorCode = DLR_GetRuntimeSettings(recognizer, &settings);
settings.furtherModes.regionPredetectionModes[0] = RPM_GENERAL_RGB_CONTRAST;
DLR_UpdateRuntimeSettings(recognizer, &settings, errorMessage, 256);
DLR_SetModeArgument(recognizer, "RegionPredetectionModes", 0, "AspectRatioRange", "100", errorMessage, 256);
DLR_GetModeArgument(recognizer, "RegionPredetectionModes", 0, "AspectRatioRange", argumentValue, 480, errorMessage, 256);
DLR_DestroyInstance(recognizer);

Recognizing

Method	Description
`DLR_RecognizeByBuffer`	Recognizes text from memory buffer containing image pixels in defined format.
`DLR_RecognizeByFile`	Recognizes text from a specified image file.
`DLR_RecognizeFileInMemory`	Recognizes text from an image file in memory.

DLR_RecognizeByBuffer

Recognizes text from the memory buffer containing image pixels in defined format.

int DLR_RecognizeByBuffer(void* recognizer, const ImageData* imageData, const char* templateName)

Parameters

[in] recognizer Handle of the label recognition instance.
[in] imageData A struct of ImageData that represents an image.
[in] templateName The template name. A template name is the value of key LabelRecognizerParameter.Name defined in JSON formatted settings. If no template name is specified, current runtime settings will be used.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();

//Generate imageData from somewhere else
int errorCode = DLR_RecognizeByBuffer(recognizer, imageData, "");
DLR_DestroyInstance(recognizer);

DLR_RecognizeByFile

Recognizes text from a specified image file.

int DLR_RecognizeByFile (void* recognizer, const char* fileName, const char* templateName)	

Parameters

[in] recognizer Handle of the label recognition instance.
[in] fileName A string defining the file name.
[in] templateName The template name. A template name is the value of key LabelRecognizerParameter.Name defined in JSON formatted settings. If no template name is specified, current runtime settings will be used.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
int errorCode = DLR_RecognizeByFile(recognizer, "C:\\Program Files (x86)\\Dynamsoft\\{Version number}\\Images\\AllSupportedBarcodeTypes.tif", "");
DLR_DestroyInstance(recognizer);

DLR_RecognizeFileInMemory

Recognizes text from a specified image file in memory.

int DLR_RecognizeFileInMemory (void* recognizer, const unsigned char* pFileBytes, const int fileSize, const char* pTemplateName)	

Parameters
[in] recognizer Handle of the label recognition instance.
[in] pFileBytes The image file bytes in memory.
[in] fileSize The length of the file bytes in memory.
[in] pTemplateName The template name.

Return Value
Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();

unsigned char* pFileBytes;
int nFileSize = 0;
GetFileStream("C:\\Program Files (x86)\\Dynamsoft\\{Version number}\\Images\\AllSupportedBarcodeTypes.tif", &pFileBytes, &nFileSize);

int errorCode = DLR_RecognizeFileInMemory(recognizer, pFileBytes, nFileSize, "");
DLR_DestroyInstance(recognizer);

Result

Method	Description
`DLR_GetAllResults`	Gets all recognized results.
`DLR_FreeResults`	Frees memory allocated for recognized results.

DLR_GetAllResults

Get all recognized results.

int DLR_GetAllResults (void* recognizer, DLR_ResultArray** results)	

Parameters

[in] recognizer Handle of the label recognition instance.
[out] results Recognized results returned by last calling function DLR_RecognizeByBuffer / DLR_RecognizeByFile. The results is allocated by SDK and should be freed by calling function DLR_FreeResults.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call DLR_GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_ResultArray * results = NULL;
int errorCode = DLR_RecognizeByFile(recognizer, "C:\\Program Files (x86)\\Dynamsoft\\{Version number}\\Images\\AllSupportedBarcodeTypes.tif", "");
DLR_GetAllResults(recognizer, &results);
DLR_FreeResults(&results);
DLR_DestroyInstance(recognizer);

DLR_FreeResults

Free memory allocated for text results.

void DLR_FreeResults (DLR_ResultArray ** results)	

Parameters

[in] results Recognized results.

Code Snippet

char errorMessage[256];
DLR_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_InitLicense(recognizer, "t0260NwAAAHV***************");
DLR_ResultArray * results = NULL;
int errorCode = DLR_RecognizeByFile(recognizer, "C:\\Program Files (x86)\\Dynamsoft\\{Version number}\\Images\\AllSupportedBarcodeTypes.tif", "");
DLR_GetAllResults(recognizer, &results);
DLR_FreeResults(&results);
DLR_DestroyInstance(recognizer);

General

Method	Description
`DLR_GetErrorString`	Returns the error string.
`DLR_GetVersion`	Returns the version number string for the SDK.

DLR_GetErrorString

Get error message by error code.

const char* DLR_GetErrorString (int errorCode)	

Parameters

[in] errorCode The error code.

Return value

The error message.

Code Snippet

const char* errorString = DLR_GetErrorString(errorCode);

DLR_GetVersion

Get version information of SDK.

const char* DLR_GetVersion ()

Return value

The version information string.

Code Snippet

const char* versionInfo = DLR_GetVersion();