/// <summary>
/// Calls 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.
/// </summary>
/// <param name="text">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.</param>
/// <param name="length">Length, in characters, of the text specified in text.</param>
/// <param name="index">Index inside the specified text to be used by the service. This value should be
/// between 0 and length-1. If the application wants to process the entire text, it should set this
/// parameter to 0.</param>
/// <param name="options">Optional. A <see cref="MappingOptions">MappingOptions</see> object containing options that affect the result and
/// behavior of text recognition. The application does not have to specify values for all object members.
/// This parameter can be set to null to use the default mapping options.</param>
/// <returns>A <see cref="MappingPropertyBag">MappingPropertyBag</see> object in which the service has stored its results. The structure is filled
/// with information produced by the service during text recognition.</returns>
public MappingPropertyBag RecognizeText(string text, int length, int index, MappingOptions options)
{
if (text == null)
{
throw new ArgumentNullException("text");
}
if (length > text.Length || length < 0)
{
throw new ArgumentOutOfRangeException("length");
}
if (index < 0)
{
throw new ArgumentOutOfRangeException("index");
}
UInt32 hResult = LinguisticException.Fail;
MappingPropertyBag bag = new MappingPropertyBag(options, text);
try
{
hResult = Win32NativeMethods.MappingRecognizeText(
_service, bag._text.AddrOfPinnedObject(), (uint)length, (uint)index,
bag._options, ref bag._win32PropertyBag);
if (hResult != 0)
{
throw new LinguisticException(hResult);
}
return(bag);
}
catch
{
bag.Dispose();
throw;
}
}
private void RunRecognizeText(object threadContext)
{
MappingRecognizeAsyncResult asyncResult = (MappingRecognizeAsyncResult)threadContext;
MappingResultState resultState = new MappingResultState();
MappingPropertyBag bag = null;
try
{
bag = this.RecognizeText(asyncResult.Text, asyncResult.Length, asyncResult.Index, asyncResult.Options);
}
catch (LinguisticException linguisticException)
{
resultState = linguisticException.ResultState;
}
asyncResult.SetResult(bag, resultState);
// Don't catch any exceptions.
try
{
asyncResult.AsyncCallback(asyncResult);
}
finally
{
Thread.MemoryBarrier();
((ManualResetEvent)asyncResult.AsyncWaitHandle).Set();
}
}
/// <summary>
/// Causes an ELS service to perform an action after text recognition has occurred. For example,
/// a phone dialer service first must recognize phone numbers and then can perform the "action"
/// of dialing a number.
/// </summary>
/// <param name="bag">A <see cref="MappingPropertyBag">MappingPropertyBag</see> object containing the results of a previous call to
/// MappingService.MappingRecognizeText. This parameter cannot be set to null.</param>
/// <param name="rangeIndex">A starting index inside the text recognition results for a recognized
/// text range. This value should be between 0 and the range count.</param>
/// <param name="actionId">The identifier of the action to perform.
/// This parameter cannot be set to null.</param>
/// <param name="asyncCallback">An application callback delegate to receive callbacks with the results from
/// the action operation. Cannot be set to null.</param>
/// <param name="callerData">Optional. Private application object passed to the callback function
/// by a service after the action operation is complete. The application must set this parameter to null
/// to indicate no private application data.</param>
/// <returns>A <see cref="MappingActionAsyncResult">MappingActionAsyncResult</see> object describing the asynchronous operation.</returns>
public MappingActionAsyncResult BeginDoAction(MappingPropertyBag bag, int rangeIndex, string actionId, AsyncCallback asyncCallback, object callerData)
{
MappingActionAsyncResult result = new MappingActionAsyncResult(callerData, asyncCallback, bag, rangeIndex, actionId);
ThreadPool.QueueUserWorkItem(this.RunDoAction, result);
return(result);
}
/// <summary>
/// Uses <see cref="Format(MappingDataRange)">Format</see> to format all the ranges of the supplied
/// MappingPropertyBag.
/// </summary>
/// <param name="bag">The property bag to convert.</param>
/// <returns>An array of strings, one per <see cref="MappingDataRange">MappingDataRange</see>.</returns>
public string[] FormatAll(MappingPropertyBag bag)
{
MappingDataRange[] dataRanges = bag.GetResultRanges();
string[] results = new string[dataRanges.Length];
for (int i = 0; i < results.Length; ++i)
{
results[i] = Format(dataRanges[i]);
}
return(results);
}
internal MappingActionAsyncResult(
object callerData,
AsyncCallback asyncCallback,
MappingPropertyBag bag,
int rangeIndex,
string actionId)
: base(callerData, asyncCallback)
{
base.SetResult(bag, new MappingResultState());
RangeIndex = rangeIndex;
ActionId = actionId;
}
/// <summary>
/// Causes an ELS service to perform an action after text recognition has occurred. For example,
/// a phone dialer service first must recognize phone numbers and then can perform the "action"
/// of dialing a number.
/// </summary>
/// <param name="bag">A <see cref="MappingPropertyBag">MappingPropertyBag</see> object containing the results of a previous call to
/// MappingService.MappingRecognizeText. This parameter cannot be set to null.</param>
/// <param name="rangeIndex">A starting index inside the text recognition results for a recognized
/// text range. This value should be between 0 and the range count.</param>
/// <param name="actionId">The identifier of the action to perform.
/// This parameter cannot be set to null.</param>
public void DoAction(MappingPropertyBag bag, int rangeIndex, string actionId)
{
if (rangeIndex < 0)
{
throw new LinguisticException(LinguisticException.E_INVALIDARG);
}
UInt32 hResult = Win32Methods.MappingDoAction(ref bag._win32PropertyBag, (uint)rangeIndex, actionId);
if (hResult != 0)
{
throw new LinguisticException(hResult);
}
}
/// <summary>
/// Uses <see cref="Format(MappingDataRange)">Format</see> to format all the ranges of the supplied
/// <see cref="MappingPropertyBag">MappingPropertyBag</see>.
/// </summary>
/// <param name="bag">The property bag to convert.</param>
/// <returns>An array of string arrays, one per <see cref="MappingDataRange">MappingDataRange</see>.</returns>
public string[][] FormatAll(MappingPropertyBag bag)
{
if (bag == null)
{
throw new ArgumentNullException("bag");
}
MappingDataRange[] dataRanges = bag.GetResultRanges();
string[][] results = new string[dataRanges.Length][];
for (int i = 0; i < results.Length; ++i)
{
results[i] = Format(dataRanges[i]);
}
return(results);
}
/// <summary>
/// Causes an ELS service to perform an action after text recognition has occurred. For example, a phone dialer service first must
/// recognize phone numbers and then can perform the "action" of dialing a number.
/// </summary>
/// <param name="bag">
/// A <see cref="MappingPropertyBag">MappingPropertyBag</see> object containing the results of a previous call to
/// MappingService.MappingRecognizeText. This parameter cannot be set to null.
/// </param>
/// <param name="rangeIndex">
/// A starting index inside the text recognition results for a recognized text range. This value should be between 0 and the range count.
/// </param>
/// <param name="actionId">The identifier of the action to perform. This parameter cannot be set to null.</param>
/// <param name="asyncCallback">
/// An application callback delegate to receive callbacks with the results from the action operation. Cannot be set to null.
/// </param>
/// <param name="callerData">
/// Optional. Private application object passed to the callback function by a service after the action operation is complete. The
/// application must set this parameter to null to indicate no private application data.
/// </param>
/// <returns>A <see cref="MappingActionAsyncResult">MappingActionAsyncResult</see> object describing the asynchronous operation.</returns>
public MappingActionAsyncResult BeginDoAction(MappingPropertyBag bag, int rangeIndex, string actionId, AsyncCallback asyncCallback, object callerData)
{
var result = new MappingActionAsyncResult(callerData, asyncCallback, bag, rangeIndex, actionId);
try
{
ThreadPool.QueueUserWorkItem(RunDoAction, result);
return(result);
}
catch
{
result.Dispose();
throw;
}
}
/// <summary>
/// Causes an ELS service to perform an action after text recognition has occurred. For example,
/// a phone dialer service first must recognize phone numbers and then can perform the "action"
/// of dialing a number.
/// </summary>
/// <param name="bag">A <see cref="MappingPropertyBag">MappingPropertyBag</see> object containing the results of a previous call to
/// MappingService.MappingRecognizeText. This parameter cannot be set to null.</param>
/// <param name="rangeIndex">A starting index inside the text recognition results for a recognized
/// text range. This value should be between 0 and the range count.</param>
/// <param name="actionId">The identifier of the action to perform.
/// This parameter cannot be set to null.</param>
public static void DoAction(MappingPropertyBag bag, int rangeIndex, string actionId)
{
if (bag == null)
{
throw new ArgumentNullException("bag");
}
if (rangeIndex < 0)
{
throw new LinguisticException(LinguisticException.InvalidArgs);
}
UInt32 hResult = Win32NativeMethods.MappingDoAction(ref bag._win32PropertyBag, (uint)rangeIndex, actionId);
if (hResult != 0)
{
throw new LinguisticException(hResult);
}
}
internal void SetResult(MappingPropertyBag bag, MappingResultState resultState)
{
_resultState = resultState;
_bag = bag;
}
