IMAPISession::QueryIdentity
適用対象: Outlook 2013 | Outlook 2016
セッションのプライマリ ID を提供する オブジェクトのエントリ識別子を返します。
HRESULT QueryIdentity(
ULONG FAR * lpcbEntryID,
LPENTRYID FAR * lppEntryID
);
パラメーター
lpcbEntryID
[out] lppEntryID パラメーターによって指されるエントリ識別子のバイト数へのポインター。
lppEntryID
[out]プライマリ ID を提供するオブジェクトのエントリ識別子へのポインターへのポインター。
戻り値
S_OK
プライマリ ID が正常に返されました。
MAPI_W_NO_SERVICE
呼び出しは成功しましたが、セッションのプライマリ ID はありません。 この警告が返されたら、呼び出しは成功として処理する必要があります。 この警告をテストするには、 HR_FAILED マクロを使用します。 詳細については、「 エラー処理にマクロを使用する」を参照してください。
注釈
IMAPISession::QueryIdentity メソッドは、現在のセッションのプライマリ ID を取得し、lppEntryID パラメーターを使用して値を返します。 プライマリ ID は、セッションのユーザーを表すオブジェクト (通常はメッセージング ユーザー) です。 lppEntryID は 、IMailUser オブジェクトのプライマリ ID を返します。これは PidTagEntryID プロパティとしても格納されます。 lppEntryID で返される値を使用して、IMAPISession::OpenEntry を使用して IMailUser オブジェクトを開くことができます。
複数のメッセージ サービスの多くのサービス プロバイダーは、セッションのプライマリ ID を提供できますが、MAPI は 1 つのサービス プロバイダーを指定します。 プライマリ ID を提供するサービス プロバイダーは、次の項目を設定します。
PR_RESOURCE_FLAGS (PidTagResourceFlags) プロパティのSTATUS_PRIMARY_IDENTITY フラグ。
PR_IDENTITY_DISPLAY (PidTagIdentityDisplay) プロパティ。
PR_IDENTITY_ENTRYID (PidTagIdentityEntryId) プロパティ。
PR_IDENTITY_SEARCH_KEY (PidTagIdentitySearchKey) プロパティ。
プライマリ ID を提供するサービス プロバイダーがメッセージ サービスに属している場合、メッセージ サービス内の他のサービス プロバイダーも PR_IDENTITY プロパティを設定します。 これらのプロパティは、セッションの状態テーブルに発行されます。
可能であれば、 QueryIdentity は、STATUS_PRIMARY_IDENTITYでタグ付けされた状態行から 、PR_IDENTITY_ENTRYID プロパティの値を返します。 PR_IDENTITY_ENTRYID プロパティがプライマリ ID 行に存在しない場合、QueryIdentity は、その行の他の情報と共に構築された 1 回限りのエントリ識別子を返します。
STATUS_PRIMARY_IDENTITY フラグが状態テーブル内のすべての PR_RESOURCE_FLAG 列に存在しない場合、 QueryIdentity は最初に見つかったエントリ識別子を返します。 返す適切なエントリ識別子がない場合、 QueryIdentity は警告MAPI_W_NO_SERVICEで成功し、ハードコーディングされたエントリ識別子に lppEntryID をポイントします。
呼び出し側への注意
IMsgServiceAdmin::SetPrimaryIdentity メソッドを呼び出して、セッションのプライマリ ID を指定するタスクをメッセージ サービスに割り当てることができます。
プライマリ ID を取得するもう 1 つの方法は、PR_RESOURCE_FLAGS列が STATUS_PRIMARY_IDENTITY に設定されている行の状態テーブルを検索することです。 ID 情報を取得するこの代替方法の詳細については、「 状態テーブルと状態オブジェクト」を参照してください。
QueryIdentity によって返されるプライマリ ID のエントリ識別子の使用が完了したら、MAPIFreeBuffer 関数を呼び出してメモリを解放します。
一般的な ID の詳細については、「 MAPI プライマリ ID」を参照してください。
MAPI セッション ID の取得の詳細については、「 プライマリ ID とプロバイダー ID の取得」を参照してください。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| MainDlg.cpp |
CMainDlg::OnQueryIdentity |
MFCMAPI では、 IMAPISession::QueryIdentity メソッドを使用して、セッションのプライマリ ID のアドレス帳エントリを開きます。 |