セーフ配列を使用するためのベスト プラクティス

Microsoft UI オートメーション API の多くのインターフェイス メソッドは、SAFEARRAY データ型のセーフ配列と呼ばれる引数を受け取ります。 このトピックでは、UI オートメーション アプリケーションで安全な配列を使用するためのベスト プラクティスについて説明します。

クライアント

UI オートメーション クライアント API メソッドで使用されるすべての安全な配列は、0 から始まる 1 次元配列です。 UI オートメーション クライアント メソッドのセーフ配列を作成するには、SafeArrayCreateVector 関数を使用し、セーフ配列の読み取りと書き込みを行うには、SafeArrayGetElement 関数と SafeArrayPutElement 関数を使用します。 セーフ配列の使用が完了したら、セーフ配列を作成した場合でも、UI オートメーション クライアント メソッドから受け取った場合でも、SafeArrayDestroy 関数を使用して必ず破棄します。

GetCurrentPropertyValue などのプロパティ取得メソッドを含むいくつかのUI オートメーションメソッドは、POINT または UiaRect 構造体を含むことができる VARIANT を取得します。 POINT は、インデックス 0 の x メンバーとインデックス 1 の y メンバーを持つ doubles (VT_R8) の安全な配列として VARIANT にパックされます。 同様に、UiaRect は、それぞれインデックス 0 から 3 の左、および高さのメンバーを持つ doubles の安全な配列として VARIANT にパックされます。 UiaRect 構造体の配列の場合、セーフ配列には、UiaRect ごとに 4 つの doubles のシーケンシャル配列が含まれます。 最初の UiaRect高さのメンバーはインデックス 0 から 3 を占め、2 番目の四角形のメンバーはインデックス 4 から 7 を占めます。

IUIAutomation インターフェイスには、SAFEARRAY と他のさまざまなデータ型の間で変換するための次のメソッドが含まれています。

メソッド 説明
IUIAutomation::IntNativeArrayToSafeArray 整数の配列を SAFEARRAY に変換します。
IUIAutomation::IntSafeArrayToNativeArray 整数の SAFEARRAY を 配列に変換します。
IUIAutomation::SafeArrayToRectNativeArray 四角形座標を含む SAFEARRAY をRECT 型の配列に変換します。

 

プロバイダー

プロバイダーは、プロバイダーから情報を取得するために呼び出しをUI オートメーションする多数のインターフェイス メソッドを実装する必要があります。 多くの場合、この情報は値の配列で構成されます。 配列をUI オートメーションに返すには、プロバイダーは配列を SAFEARRAY 構造体にパックする必要があります。 配列要素は、想定されるデータ型である必要があり、予想される順序で指定する必要があります。

概念

UI オートメーション プロパティの概要

UI オートメーションの基礎