COM ライブラリの使用

[アーティクル]
06/13/2023

タブレット PC マネージドライブラリリファレンスは、通常の Windows Vista SDK クラスライブラリリファレンスセクションにあります。 Microsoft Visual C++のオブジェクトモデルを提供します。 COM ライブラリのオブジェクトの大部分は、Tablet PC Managed API で見つかったオブジェクトと同じです。

ただし、標準の Microsoft Win32 環境と Microsoft .NET Frameworksoftware 開発キット (SDK) 環境の違いにより、COM API にはマネージド API で見つかったメンバーに加えて、いくつかのメンバーが含まれています。たとえば、InkRectangle オブジェクトと InkTransform オブジェクトは COM で使用されますが、FrameworkSDK には InkRectangle クラス と InkTransform クラス のネイティブ実装が用意されており、タブレット PC プラットフォームの Managed API でこれらのオブジェクトが不要になります。

Note

COM API およびインクコントロール内のオブジェクトは、Active Server Pages (ASP) で使用するようには設計されていません。

コレクションの操作

NULL 値をインデックスとして COM ライブラリ内のいずれかのコレクションオブジェクトに渡すと、呼び出しが行われると、これらの引数の値が 0 に強制されるため、コレクション内の最初の項目を受け取ります。

_NewEnum プロパティは、コレクションインターフェイスのインターフェイス定義言語 (IDL) 定義で制限付きとしてマークされます。

C++ では、ループを For... 使用して、最初にコレクションの長さを取得してコレクションを反復処理します。次の例は、pInkInkDisp オブジェクトのストロークを反復処理する方法を示しています。

IInkStrokes* pStrokes;
HRESULT result = pInk->get_Strokes(&pStrokes);
if (SUCCEEDED(result))
{
    // Loop over strokes
    long nStrokes;
    result = pStrokes->get_Count(&nStrokes);
    if (SUCCEEDED(result))
    {
        for (int i =0; i < nStrokes; i++)
        {
            IInkStrokeDisp* pStroke;
            result = pStrokes->Item(i, &pStroke);
            if (SUCCEEDED(result))
            {
              // Code that uses pStroke
              // ...
            }
        }
    }
}

パラメーター

VT_EMPTYまたはVT_NULLをインデックスとして COM ライブラリ内のいずれかのコレクションオブジェクトに渡すと、呼び出しの実行時にこれらの引数値が 0 に強制されるため、コレクション内の最初の項目を受け取ります。

IDispatch の使用

パフォーマンスを向上させるために、Tablet PC Platform COM アプリケーションプログラミングインターフェイス (API) では、名前付き引数を持つ DISPPARAMS 構造体を使用した呼び出し IDispatchImpl::Invoke はサポートされていません。 IDispatchImpl::GetIDsOfNamesもサポートされていません。代わりに、SDK ヘッダーで指定された DISPID を使用してを呼び出 Invoke します。

イベントの待機中

タブレット PC 環境はマルチスレッドです。マルチスレッドについては、COM のドキュメントを参照してください。

集計のサポート

InkEdit コントロール、InkPicture コントロール、InkDisp オブジェクト、InkOverlay オブジェクトについてのみ集計がテストされています。ライブラリ内の他のコントロールとオブジェクトの集計はテストされていません。

C++

C++ で Tablet PC SDK を使用するには、VARIANT、SAFEARRAY、BSTR などの一部の COM 概念を使用する必要があります。このセクションでは、それらを使用する方法について説明します。

VARIANT と SAFEARRAY

VARIANT 構造体は、COM オブジェクト間の通信に使用されます。基本的に、VARIANT 構造体は、多くの種類のデータを含む大規模な共用体のコンテナーです。

構造体 vt の最初のメンバーの値は、どの共用体メンバーが有効であるかを示します。 VARIANT 構造体で情報を受け取る場合は、vt メンバーをチェックして、有効なデータを含むメンバーを確認します。同様に、VARIANT 構造体を使用して情報を送信する場合は、情報を含む共用体メンバーを反映するように vt を常に設定します。

構造体を使用する前に、VariantInit COM 関数を呼び出して初期化します。構造体が完成したら、VariantClear を呼び出して VARIANT を含むメモリを解放する前に、それをクリアします。

VARIANT 構造体の詳細については、「 VARIANT および VARIANTARG データ型」を参照してください。

SAFEARRAY 構造体は、COM で配列を安全に操作する方法として提供されます。 VARIANT の parray フィールドは、SAFEARRAY へのポインターです。 SafeArrayCreateVector、SafeArrayAccessData、SafeArrayUnaccessData などの関数を使用して、VARIANT で SAFEARRAY を作成して埋めます。

SAFEARRAY データ型の詳細については、「 SafeArray データ型」を参照してください。

この C++ の例では、ポイントデータの配列から InkDisp オブジェクトの IInkStrokeDisp 、pInkStrokeDisp、 pInkを作成します。

VARIANT   var, varPK;
LONG*   plongArray=NULL;
POINT   ptArray[2]={0};
long   lSize=0;
IInkStrokeDisp* pInkStrokeDisp;

IInkDisp*   pInk;   // the object should be created correctly 
                    // elsewhere and assigned here.
HRESULT   hr=E_FAIL;

ptArray[0].x = 20;
ptArray[0].y = 100;
ptArray[1].x = 30;
ptArray[1].y = 110;
lSize = 2;   // two points

VariantInit( &var );
VariantInit( &varPK );
SAFEARRAY* psa = SafeArrayCreateVector( VT_I4, 0, lSize*2 );
if( psa )
{
  if( SUCCEEDED( hr = SafeArrayAccessData( psa, (void**)&plongArray) ))
   {
      for( long i = 0; i < lSize; i++ ) 
      {
         plongArray[2*i] = ptArray[i].x;
         plongArray[2*i+1] = ptArray[i].y;
      }
      hr = SafeArrayUnaccessData( psa );

      if ( SUCCEEDED( hr ) ) 
      {
         var.vt     = VT_ARRAY | VT_I4;
         var.parray = psa;

        // varPK (packet description) is currently reserved, so it is
        // just empty variant for now.
         pInk->CreateStroke( var, varPK, &pInkStrokeDisp );   
      }
   }
}
VariantClear( &var );
VariantClear( &varPK );

BSTR

COM でサポートされている文字列形式は BSTR です。 BSTR には 0 で終わる文字列へのポインターがありますが、文字列の長さ (ターミネータをカウントしないバイト単位) も含まれます。これは、文字列の最初の文字の直前の 4 バイトに格納されます。

BSTR の詳細については、「 BSTR データ型」を参照してください。

この C++ サンプルでは、BSTR を使用して InkRecognizerContext に factoid を設定する方法を示します。

IInkRecognizerContext* pRecognizerContext = NULL;
result = CoCreateInstance(CLSID_InkRecognizerContext, 
    NULL, CLSCTX_INPROC_SERVER,
    IID_IInkRecognizerContext, 
    (void **) &pRecognizerContext);
if SUCCEEDED(result)
{
    BSTR bstrFactoid = SysAllocString(FACTOID_DATE);
    result = pRecognizerContext->put_Factoid(bstrFactoid);
    if SUCCEEDED(result)
    {
      // Use recognizer context...
      // ...
    }
    SysFreeString(bstrFactoid);
}