IContextNode::GetPropertyData method

Article
01/07/2021

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

Requirement	Value
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