MappingRecognizeText function (elscore.h)

Article
02/22/2024

Calls upon an ELS service to recognize text. For example, the Microsoft Language Detection service will attempt to recognize the language in which the input text is written.

Syntax

HRESULT MappingRecognizeText(
  [in]           PMAPPING_SERVICE_INFO pServiceInfo,
  [in]           LPCWSTR               pszText,
  [in]           DWORD                 dwLength,
  [in]           DWORD                 dwIndex,
  [in, optional] PMAPPING_OPTIONS      pOptions,
  [in, out]      PMAPPING_PROPERTY_BAG pbag
);

Parameters

[in] pServiceInfo

Pointer to a MAPPING_SERVICE_INFO structure containing information about the service to use in text recognition. The structure must be one of the structures retrieved by a previous call to MappingGetServices. This parameter cannot be set to NULL.

[in] pszText

Pointer to the text to recognize. The text must be UTF-16, but some services have additional requirements for the input format. This parameter cannot be set to NULL.

[in] dwLength

Length, in characters, of the text specified in pszText.

[in] dwIndex

Index inside the specified text to be used by the service. This value should be between 0 and dwLength-1. If the application wants to process the entire text, it should set this parameter to 0.

[in, optional] pOptions

Pointer to a MAPPING_OPTIONS structure containing options that affect the result and behavior of text recognition. The application does not have to specify values for all structure members. This parameter can be set to NULL to use the default mapping options.

[in, out] pbag

Pointer to a MAPPING_PROPERTY_BAG structure in which the service stores its results. On input, the application passes a structure with only the size provided, and the other members set to 0. On output, the structure is filled with information produced by the service during text recognition. This parameter cannot be set to NULL.

Return value

Returns S_OK if successful. The function returns an error HRESULT value if it does not succeed.

Remarks

The type of text to recognize depends on the service type used by the application. For more information, see Requesting Text Recognition.

Warning The data referred to by pszText and pOptions must remain valid until the property bag structure passed by pBag is freed via

MappingFreePropertyBag. This is because both synchronous and asynchronous calls to

MappingRecognizeText and MappingDoAction will attempt to use the data passed to the initial

call to MappingRecognizeText.

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 R2 [desktop apps \| UWP apps]
Target Platform	Windows
Header	elscore.h
Library	Elscore.lib
DLL	Elscore.dll