C Functions

Initialization Functions Summary

Setting Functions Summary

Recognizing Functions Summary

Result Functions Summary

General Functions Summary

Initialization Functions Details

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

DC_GetIdleInstancesCount

Gets available instances count when charging by concurrent instances count.

int DC_GetIdleInstancesCount()

Return Value

Returns available instances count.

• 0: There is no space for new instance
• -1: The available count needs to be updated from server by calling DC_InitLicense.
• N ( N > 0 ): N more instances can be created.

Code Snippet

//...
int count = DC_GetIdleInstancesCount();
if(count > 0)
{
  //create instance and process further
}
if(count < 0)
{
  //call DC_InitLicense
  //create instance and process further
}
if(count = 0)
{
  //waiting for available instances 
}

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

DC_InitLicense

Sets product key and activate the SDK.

int DC_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];
DC_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

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

Setting Functions Details

DLR_SetCharacterModelDefaultPath

Set default directory path of the character models.

int DLR_SetCharacterModelDefaultPath (void* recognizer, const char* modelPath, char errorMsgBuffer[], const int errorMsgBufferLen)

Parameters [in] recognizer Handle of the label recognition instance.
[in] modelPath The full directory path of character models.
[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];
DC_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_SetCharacterModelDefaultPath(recognizer, "C:\\CharacterModel", errorMessage, 256);
DLR_DestroyInstance(recognizer);

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];
DC_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];
DC_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_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];
DC_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_InitRuntimeSettings

Initializes a new setting to the current label recognizer instance via template string.

int DLR_InitRuntimeSettings(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];
DC_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_InitRuntimeSettings(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_InitRuntimeSettingsFromFile

Initializes a new setting to the current label recognizer instance via template file.

int DLR_InitRuntimeSettingsFromFile(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];
DC_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

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

DLR_OutputRuntimeSettings

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

int DLR_OutputRuntimeSettings (void* recognizer, const char* pSettingsName, char** content)

Parameters

[in] recognizer Handle of the label recognition instance.
[in] pSettingsName A unique name for declaring current runtime settings.
[in,out] content The output string which stores the contents of current settings. If not needed, it should be freed via DLR_FreeString.

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];
DC_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
char *content = NULL;
DLR_OutputRuntimeSettings(recognizer, "currentRuntimeSettings", &content);
DLR_FreeString(&content);
DLR_DestroyInstance(recognizer);

DLR_OutputRuntimeSettingsToFile

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

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

Parameters

[in] recognizer Handle of the label recognition instance.
[in] templateName A unique name for declaring current runtime settings.
[in] filePath The path of the output file which stores current 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];
DC_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_InitRuntimeSettings(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_OutputRuntimeSettingsToFile(recognizer, "P1", "C:\\Program Files (x86)\\Dynamsoft\\{Version number}\\Templates\\CurrentRuntimeSettings.json");
DLR_DestroyInstance(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];
DC_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_InitRuntimeSettings(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];
DC_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];
DC_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 Functions Details

DLR_RecognizeBuffer

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

int DLR_RecognizeBuffer(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];
DC_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();

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

DLR_RecognizeFile

Recognizes text from a specified image file.

int DLR_RecognizeFile (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];
DC_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
int errorCode = DLR_RecognizeFile(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];
DC_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 Functions Details

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_RecognizeBuffer / DLR_RecognizeFile. 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];
DC_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

void* recognizer = DLR_CreateInstance();
DLR_ResultArray * results = NULL;
int errorCode = DLR_RecognizeFile(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];
DC_InitLicense("t0260NwAAAHV***************", errorMessage, 256);

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

General Functions Details

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

DLR_FreeString

Free the allocated string memory.

void DLR_FreeString(char** str)

Parameters

[in] str The allocated string memory.

Code Snippet

void* recognizer = DLR_CreateInstance();
char *content = NULL;
DLR_OutputRuntimeSettings(recognizer, "", &content);
DLR_FreeString(&content);
DLR_DestroyInstance(recognizer);