IABContainer::CreateEntry
適用対象: Outlook 2013 | Outlook 2016
メッセージング ユーザー、配布リスト、または別のコンテナーを指定できる新しいエントリを作成します。
HRESULT CreateEntry(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulCreateFlags,
LPMAPIPROP FAR * lppMAPIPropEntry
);
パラメーター
cbEntryID
[in] lpEntryID パラメーターによって指されるエントリ識別子のバイト数。
lpEntryID
[in]特定の型の新しいエントリを作成するためのテンプレートのエントリ識別子へのポインター。
ulCreateFlags
[in]エントリの作成方法を制御するフラグのビットマスク。 次のフラグを設定できます。
CREATE_CHECK_DUP_LOOSE
重複するエントリ チェックの緩やかなレベルを実行する必要があります。 緩やかな重複エントリ チェックの実装は、プロバイダー固有です。 たとえば、プロバイダーは、同じ表示名を持つ任意の 2 つのエントリとして緩やかな一致を定義できます。
CREATE_CHECK_DUP_STRICT
厳密なレベルの重複エントリ チェックを実行する必要があります。 厳密な重複エントリ チェックの実装は、プロバイダー固有です。 たとえば、プロバイダーは、厳密な一致を、同じ表示名とメッセージング アドレスの両方を持つ任意の 2 つのエントリとして定義できます。
CREATE_REPLACE
2 つが重複していると判断された場合は、既存のエントリを新しいエントリで置き換える必要があります。
lppMAPIPropEntry
[out]新しく作成されたエントリへのポインターへのポインター。
戻り値
S_OK
新しいエントリが正常に作成されました。
注釈
IABContainer::CreateEntry メソッドは、指定されたコンテナー内の特定の型の新しいエントリを作成し、エントリにさらにアクセスするためのインターフェイス実装へのポインターを返します。 新しいエントリは、コンテナーの使用可能なテンプレートの一覧から選択されたテンプレートを使用して作成されます。このテンプレートは、その 1 回限りのテーブルに発行されます。 呼び出し元は、 IMAPIProp::OpenProperty メソッドを呼び出し、 PR_CREATE_TEMPLATES (PidTagCreateTemplates) プロパティを要求することで、コンテナーの 1 回限りのテーブルにアクセスします。
実装に関するメモ
IABContainer::CreateEntry メソッドをサポートするすべてのコンテナーは変更可能である必要があります。 コンテナーの AB_MODIFIABLE フラグを PR_CONTAINER_FLAGS (PidTagContainerFlags) プロパティに設定して、変更可能であることを示します。
すべての ulCreateFlags フラグをサポートする必要があります。 ただし、これらのフラグの解釈と使用は実装固有です。つまり、実装のコンテキストでCREATE_CHECK_DUP_LOOSEとCREATE_CHECK_DUP_STRICTのセマンティクスが何を意味するかを判断できます。 エントリが重複しているかどうかを判断できない場合は、常にエントリの作成を許可します。
一部のプロバイダーでは、エントリ内の表示名、メッセージング アドレス、検索キーを照合して、厳密なエントリ チェックを実装します。他のプロバイダーは、名前とアドレスを表示するように一致を制限します。 多くの場合、ルーズ エントリ チェックは、表示名のみを確認することによって実装されます。
アドレス帳プロバイダーの実装者をホストするためのメモ
コンテナーが他のプロバイダーのテンプレートからエントリを作成できる場合、 CreateEntry の実装では、作成されたエントリに関連付けられているプロパティの一部またはすべてを格納する必要があります。 たとえば、エントリの PR_DETAILS_TABLE (PidTagDetailsTable) プロパティのストレージを指定する場合、外部プロバイダーに依存することなく詳細ダイアログ ボックスを生成できます。
コンテナーで PR_TEMPLATEID (PidTagTemplateid) プロパティをサポートするエントリを作成できる場合は、 CreateEntry の実装で次の操作を行う必要があります。
IMAPISupport::OpenTemplateID メソッドを呼び出します。 OpenTemplateID を使用すると、外部プロバイダーのコードを使用して、エントリを作成中の新しいエントリにバインドできます。 外部プロバイダーは、このバインド プロセスをサポートして、テンプレートから作成されたエントリをホスト アドレス帳プロバイダーのコンテナーに制御します。
必要な初期化を実行し、OpenTemplateID から lppMAPIPropNew パラメーターで返された外部プロバイダーのエントリのすべてのプロパティを新しいオブジェクトに設定します。
OpenTemplateID が成功した場合は、lpMAPIPropData パラメーターが指す実装に直接ではなく、lppMAPIPropNew パラメーターが指す実装にプロパティをコピーします。 外部プロバイダーからの他のエントリと同様に、オフラインで使用するために新しいエントリを初期化します。
OpenTemplateID からエラーが返された場合、CreateEntry は失敗します。 エントリの作成を許可しないでください。 外部プロバイダーはプロバイダー内のデータに関して想定できるため、外部プロバイダーに正常にバインドされていないテンプレート識別子を持つエントリを作成しないでください。
呼び出し側への注意
CreateEntry が返されると、新しいエントリのエントリ識別子にすぐにアクセスできる場合とできない場合があります。 一部のアドレス帳プロバイダーでは、新しいエントリの IMAPIProp::SaveChanges メソッドを呼び出すまで使用できません。
重複チェック フラグはパラメーターとして CreateEntry に渡されますが、 SaveChanges が呼び出されるまで、重複チェック操作は実行されません。 そのため、既に既存のエントリを作成しようとしたことを示す MAPI_E_COLLISION などの関連エラーは、CreateEntry ではなく SaveChanges によって返されます。