IMAPIProp::GetProps
適用対象: Outlook 2013 | Outlook 2016
オブジェクトの 1 つ以上のプロパティのプロパティ値を取得します。
HRESULT GetProps(
LPSPropTagArray lpPropTagArray,
ULONG ulFlags,
ULONG FAR * lpcValues,
LPSPropValue FAR * lppPropArray
);
パラメーター
lpPropTagArray
[in]値を取得するプロパティを識別するプロパティ タグの配列へのポインター。 lpPropTagArray パラメーターは NULL で、オブジェクトのすべてのプロパティの値を返す必要があることを示すか、1 つ以上のプロパティ タグを含む SPropTagArray 構造体を指す必要があります。
ulFlags
[in]型がPT_UNSPECIFIEDプロパティの形式を示すフラグのビットマスク。 次のフラグを設定できます。
MAPI_UNICODE
これらのプロパティの文字列値は、Unicode 形式で返す必要があります。 MAPI_UNICODE フラグが設定されていない場合は、文字列値を ANSI 形式で返す必要があります。
lpcValues
[out] lppPropArray パラメーターによって指されるプロパティ値の数へのポインター。 lppPropArray が NULL の場合、lpcValues パラメーターの内容は 0 です。
lppPropArray
[out]取得したプロパティ値へのポインターへのポインター。
戻り値
S_OK
プロパティ値が正常に取得されました。
MAPI_W_ERRORS_RETURNED
呼び出しは全体的に成功しましたが、1 つ以上のプロパティにアクセスできませんでした。 使用できない各プロパティのプロパティ値の aulPropTag メンバーには、PT_ERRORのプロパティ型と 0 の識別子があります。 この警告が返されたら、呼び出しは成功として処理する必要があります。 この警告をテストするには、 HR_FAILED マクロを使用します。 詳細については、「 エラー処理にマクロを使用する」を参照してください。
MAPI_E_INVALID_PARAMETER
lpPropTagArray が指す SPropTagArray 構造体の cValues メンバーに 0 が渡されました。
注釈
IMAPIProp::GetProps メソッドは、オブジェクトの 1 つ以上のプロパティのプロパティ値を取得します。
プロパティ値は、要求された順序と同じ順序で返されます (つまり、 lpPropTagArray が指すプロパティ タグ配列のプロパティの順序は、 lppPropArray が指すプロパティ値構造体の配列内の順序と一致します)。
プロパティ タグ配列の aulPropTag メンバーで指定されたプロパティ型は、各プロパティ値構造体の Value メンバーで返される値の型を示します。 ただし、呼び出し元がプロパティの型がわからない場合は、代わりに aulPropTag メンバーの型を PT_UNSPECIFIED に設定できます。 値を取得する際に、 GetProps は 、 プロパティのプロパティ値構造体の aulPropTag メンバーに正しい型を設定します。
lpPropTagArray の SPropTagArray でプロパティ型が指定されている場合、lppPropArray で返される SPropValue のプロパティ値には、代わりにエラー値が返されない限り、要求された型と完全に一致する型があります。
文字列プロパティには、Unicode 形式を表すPT_UNICODEと ANSI 形式を表すPT_STRING8の 2 種類のいずれかを指定できます。 MAPI_UNICODE フラグが ulFlags パラメーターに設定されている場合、 GetProps が 文字列プロパティの適切な形式を決定できない場合は常に、その値を Unicode 形式で返します。 GetProps は、次の状況では、正確な文字列プロパティの種類を決定できません。
lpPropTagArray パラメーターを NULL に設定して、すべてのプロパティを要求します。
aulPropTag メンバーには、プロパティ タグ配列のプロパティ型としてPT_UNSPECIFIED値が含まれます。
オブジェクトのすべてのプロパティを取得するために lpPropTagArray パラメーターを NULL に設定し、プロパティが存在しない場合、 GetProps は次の処理を行います。
S_OKを返します。
プロパティ値構造体の cValues メンバーの count 値を 0 に設定します。
lpcValues の内容を 0 に設定します。
lppPropArray を NULL に設定します。
GetProps は、cValues が 0 に設定された複数値プロパティを返す必要があります。
実装に関するメモ
MAPIAllocateBuffer 関数を呼び出して、lpPropTagArray が指す SPropValue 構造体に最初にメモリを割り当てます。MAPIAllocateMore を呼び出して、構造体のメンバーに必要な追加のメモリを割り当てます。
1 つ以上の要求されたプロパティの値を取得できない場合は、MAPI_W_ERRORS_RETURNEDを返します。 プロパティ値構造体で、 aulPropTag メンバーの型を PT_ERROR に設定し、 Value メンバーをエラーを説明する状態コードに設定します。 たとえば、文字列を Unicode に変換する必要があり、Unicode をサポートしていない場合は、 Value メンバーを MAPI_E_BAD_CHARWIDTH に設定します。 プロパティが大きすぎる場合は、MAPI_E_NOT_ENOUGH_MEMORYに設定します。 オブジェクトが プロパティをサポートしていない場合は、MAPI_E_NOT_FOUNDに設定します。
GetProps メソッドのリモート トランスポート プロバイダーの実装は、呼び出し元によって要求されたプロパティのフォルダーのプロパティ値を返す必要があります。 実装では、次の操作を行う必要があります。
呼び出し元に返すプロパティ値配列を割り当て、その目的のために渡されたプロパティ値ポインター パラメーターにそのアドレスを格納します。
GetProps に渡されるプロパティ タグの配列に従って、フォルダーのプロパティからプロパティ値配列のプロパティ タグにプロパティ タグをコピーします。
GetProps に渡されるすべてのプロパティ タグに対してプロパティの種類が設定されていることを確認します。 呼び出し元は、PT_UNSPECIFIEDのプロパティ型を渡すことができます。その場合、 GetProps はその プロパティ タグの正しいプロパティ型を設定する必要があります。
タグに従って、プロパティ値配列内の各プロパティの値を設定します。 たとえば、呼び出し元によって要求されたプロパティ タグが PR_OBJECT_TYPE (PidTagObjectType) の場合、 GetProps は 値を MAPI_FOLDER に設定できます。
実装で処理されないプロパティ タグを呼び出し元が渡す場合は、プロパティ タグをそれらのプロパティのPT_ERRORに設定し、プロパティ値を MAPI_E_NOT_FOUND に設定できます。
エラーが発生しなかった場合はS_OK、エラーが発生した場合はMAPI_W_ERRORS_RETURNEDを返します。
リモート トランスポート プロバイダーの GetProps メソッドの実装では、少なくとも次のプロパティをサポートする必要があります。
PR_ACCESS (PidTagAccess)
PR_ACCESS_LEVEL (PidTagAccessLevel)
PR_ASSOC_CONTENT_COUNT (PidTagAssociatedContentCount)
PR_CONTENT_COUNT (PidTagContentCount)
PR_CREATION_TIME (PidTagCreationTime)
PR_DISPLAY_NAME (PidTagDisplayName)
PR_DISPLAY_TYPE (PidTagDisplayType)
PR_FOLDER_TYPE (PidTagFolderType)
PR_OBJECT_TYPE
PR_SUBFOLDERS (PidTagSubfolders)
呼び出し側への注意
PT_OBJECT型のプロパティについては、 GetProps ではなく IMAPIProp::OpenProperty メソッドを呼び出 します。
セキュリティで保護されたプロパティの場合は、lppPropTagArray パラメーターを NULL に設定して GetProps を呼び出して取得することは想定しないでください。 GetProps を呼び出すときは、そのプロパティ タグ配列の aulPropTag メンバーで、セキュリティで保護されたプロパティの識別子を明示的に設定する必要があります。 セキュリティで保護されたプロパティを使用できるタイミングと方法は、サービス プロバイダーによって行われます。
返された SPropValue 構造体を解放するには、GetProps がS_OKまたはMAPI_W_ERRORS_RETURNEDを返す場合にのみ MAPIFreeBuffer 関数を呼び出します。
GetProps が 1 つ以上のプロパティにアクセスできなかったためにMAPI_W_ERRORS_RETURNEDを返す場合は、返されたプロパティのプロパティ タグをチェックします。 失敗したプロパティのプロパティ値の構造には、次の値が設定されます。
aulPropTag メンバーのプロパティ型は、PT_ERRORに設定されます。
Value メンバーのプロパティ値は、エラーの状態コード (MAPI_E_NOT_FOUNDなど) に設定されます。
プロパティ値構造体で返されるプロパティが大きすぎて便利でないために失敗するプロパティには、 Value メンバーがMAPI_E_NOT_ENOUGH_MEMORYに設定されています。 通常、これは、プロパティの値が 4 KB 以上の場合、PT_STRING8、PT_UNICODE、またはPT_BINARY型の文字列またはバイナリ プロパティで発生します。 IMAPIProp::OpenProperty を呼び出して、大きなプロパティを取得します。
GetProps のすべての実装で、文字列の Unicode 形式と ANSI 形式の両方がサポートされているわけではありません。 特定のプロパティで文字列形式の変換が必要で 、GetProps でサポートできない場合、プロパティの Value メンバーは MAPI_E_BAD_CHARWIDTH に設定されます。
PST が SharePoint PST の場合にチェックするには、IMAPISession::OpenMsgStore を使用して PST をマウントし、このプロパティを要求するメッセージ ストア オブジェクトで GetProps を呼び出します。 存在する場合は、PST が SharePoint 用に構成されていると仮定できます。構成されていない場合は、PST が SharePoint PST として構成されていません。
GetProps を使用してプロパティにアクセスする方法の詳細については、「MAPI プロパティの取得」を参照してください。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| MAPIFunctions.cpp |
GetPropsNULL |
MFCMAPI では 、IMAPIProp::GetProps メソッドを使用して、NULL または IMAPIProp::GetPropList メソッドによって返される配列を lpPropTagArray パラメーターに渡すことで、オブジェクトのすべてのプロパティを取得します。 |