IContextNode::GetPropertyData method

Retrieves application-specific data or other property data for the specified identifier.

Syntax


HRESULT GetPropertyData(
  [in]      const GUID  *pPropertyDataId,
  [in, out]       ULONG *pulPropertyDataSize,
  [out]           BYTE  **ppbPropertyData
);

Parameters

pPropertyDataId [in]

The identifier for the data.

pulPropertyDataSize [in, out]

The size of the data in bytes. The value that is passed in is not used.

ppbPropertyData [out]

A pointer to an 8-bit unsigned integer array that contains the property data.

Return value

For a description of the return values, see Classes and Interfaces - Ink Analysis.

Remarks

Caution  To avoid a memory leak, use CoTaskMemFree to release the memory from *ppbPropertyData when you no longer need the information.
 

In addition to retrieving application-specific data that was added with IContextNode::AddPropertyData, this method is used to retrieve common properties that are described by the Context Node Properties constants.

The string-type properties include:

  • GUID_CNP_RECOGNIZEDSTRING
  • GUID_CNP_SHAPENAME
  • GUID_AHP_ANALYSISHINTNAME
  • GUID_AHP_PREFIXTEXT
  • GUID_AHP_SUFFIXTEXT
  • GUID_AHP_FACTOID

The return value is WCHAR*. If you cast the *ppbPropertyData parameter to WCHAR* its returned length is (length of the string + 1) * sizeof(WCHAR).

The Boolean-type properties include:

  • GUID_AHP_OVERRIDELANGUAGEID
  • GUID_AHP_COERCETOFACTOID
  • GUID_AHP_WORDMODE

The return value is VARIANT_BOOL. If you cast the *ppbPropertyData parameter to VARIANT_BOOL* its returned length is sizeof(VARIANT_BOOL).

GUID_AHP_GUIDE is a guide-type property. The return value is InkAnalysisRecognitionGuide*. If you cast the *ppbPropertyData parameter to InkAnalysisRecognitionGuide* its returned length is sizeof(InkAnalysisRecognitionGuide).

Integer-type properties include:

  • GUID_CNP_LINENUMBER
  • GUID_CNP_POINTSPERINCH
  • GUID_CNP_CONFIDENCELEVEL
  • GUID_CNP_CONFIRMATION
  • GUID_CNP_MAXIMUMSTROKECOUNT
  • GUID_CNP_SEGMENTATION
  • GUID_CNP_ALIGNMENTLEVEL

The return value is LONG*. If you cast the *ppbPropertyData parameter to LONG* its returned length is sizeof(LONG).

Line metrics-type properties include:

  • GUID_CNP_ASCENDERS
  • GUID_CNP_DESCENDERS
  • GUID_CNP_BASELINE
  • GUID_CNP_MIDLINE

The return value is LONG*. If you cast the *ppbPropertyData parameter to LONG* its returned length is sizeof(LONG)*4, signifying the (x, y) values for the starting points followed by the (x, y) values for the ending points.

GUID_CNP_TEXTRECOGNIZERID is a GUID property. The return value is GUID*. If you cast the *ppbPropertyData parameter to GUID* its returned length is sizeof(GUID).

GUID_CNP_ROTATEDBOUNDINGBOX is a rotated bounding box property. The return value is LONG*. If you cast the *ppbPropertyData parameter to LONG* its returned length is sizeof(LONG)*8, signifying the (x, y) values for the four corners of the box.

GUID_CNP_HOTPOINT is a hot point property. The return value is LONG*. If you cast the *ppbPropertyData parameter to LONG* its returned length is sizeof(LONG)*2, signifying the (x, y) values for the point.

GUID_AHP_WORDLIST is a word list property. The return value is WCHAR*. If you cast the *ppbPropertyData parameter to WCHAR* its returned length is n * sizeof(WCHAR), where n is the sum of the string lengths of the number of strings in the list plus 1 for each NULL termination character for each string.

Examples

This example shows a method that accesses the AlignmentLevel context node property of a Paragraph context node type.


// Checks a paragraph context node's alignment level property.
// Only paragraph type context nodes contain the alignment level property.
HRESULT CMyClass::ExploreParagraphNode(
    IContextNode *pParagraphNode)
{
    // Get the AlignmentLevel property data for the paragraph.
    LONG * alignmentLevel = NULL;
    ULONG ulDataLen = 0;

    HRESULT hr = pParagraphNode->GetPropertyData(
        (const GUID*)&GUID_CNP_ALIGNMENTLEVEL,
        &ulDataLen,
        (BYTE**)&alignmentLevel);

    if( FAILED(hr) ||
        ulDataLen != sizeof(LONG) ||
        alignmentLevel == NULL )
    {
        // Insert code that handles an error here.
    }
    else
    {
        // Insert code that uses the alignment level here.
    }

    // Free the memory allocated for the property data.
    ::CoTaskMemFree(alignmentLevel);

    return hr;
}


Requirements

Minimum supported client

Windows XP Tablet PC Edition [desktop apps only]

Minimum supported server

None supported

Header

IACom.h (also requires IACom_i.c)

DLL

IACom.dll

See also

IContextNode
IContextNode::AddPropertyData
IContextNode::RemovePropertyData
IContextNode::GetPropertyDataIds
IContextNode::ContainsPropertyData
IContextNode::LoadPropertiesData
IContextNode::SavePropertiesData
Ink Analysis Reference

 

 

Show: