IMSProvider::Logon

  • [アーティクル]

適用対象: Outlook 2013 | Outlook 2016

MAPI をメッセージ ストア プロバイダーの 1 つのインスタンスにログに記録します。

HRESULT Logon(
  LPMAPISUP lpMAPISup,
  ULONG_PTR ulUIParam,
  LPSTR lpszProfileName,
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulFlags,
  LPCIID lpInterface,
  ULONG FAR * lpcbSpoolSecurity,
  LPBYTE FAR * lppbSpoolSecurity,
  LPMAPIERROR FAR * lppMAPIError,
  LPMSLOGON FAR * lppMSLogon,
  LPMDB FAR * lppMDB
);

パラメーター

lpMAPISup

[in]メッセージ ストアの現在の MAPI サポート オブジェクトへのポインター。

ulUIParam

[in]このメソッドが表示するダイアログ ボックスまたはウィンドウの親ウィンドウへのハンドル。

lpszProfileName

[in]ストア プロバイダーのログオンに使用されるプロファイルの名前を含む文字列へのポインター。 この文字列は、ダイアログ ボックスに表示したり、ログ ファイルに書き込んだり、単に無視したりできます。 ulFlags パラメーターに MAPI_UNICODE フラグが設定されている場合は、Unicode 形式にする必要があります。

cbEntryID

[in] lpEntryID パラメーターによって指されるエントリ識別子のサイズ (バイト単位)。

lpEntryID

[in]メッセージ ストアのエントリ識別子へのポインター。 lpEntryID で null を渡すことは、メッセージ ストアがまだ選択されておらず、ユーザーがメッセージ ストアを選択できるようにするダイアログ ボックスを表示できることを示します。

ulFlags

[in]ログオンの実行方法を制御するフラグのビットマスク。 次のフラグを設定できます。

MAPI_DEFERRED_ERRORS

基になるオブジェクトが呼び出し元の実装で使用できない場合でも、呼び出しは成功できます。 オブジェクトが使用できない場合は、オブジェクトの後続の呼び出しでエラーが発生する可能性があります。

MAPI_UNICODE

渡された文字列は Unicode 形式です。 MAPI_UNICODEが設定されていない場合、文字列は ANSI 形式です。

MDB_NO_DIALOG

ログオン ダイアログ ボックスが表示されないようにします。 このフラグが設定されている場合、ログオンが失敗した場合MAPI_E_LOGON_FAILEDエラー値が返されます。 このフラグが設定されていない場合、メッセージ ストア プロバイダーは、名前またはパスワードの修正、ディスクの挿入、またはストアへの接続を確立するために必要なその他のアクションの実行をユーザーに求めることができます。

MDB_NO_MAIL

メッセージ ストアは、メールの送受信には使用しないでください。 このフラグは、このメッセージ ストアが開かれていることを MAPI スプーラーに通知しないように MAPI に通知します。 このフラグが設定されていて、メッセージ ストアがトランスポート プロバイダーと緊密に結合されている場合、プロバイダーは IMAPISupport::SpoolerNotify メソッドを呼び出す必要はありません。

MDB_TEMPORARY

ダイアログ ボックスを使用せずにプロファイル セクションからプログラムで情報を取得できるように、ストアにログを記録します。 このフラグは、ストアをメッセージ ストア テーブルに追加しないようにし、ストアを永続的にできないことを MAPI に指示します。 このフラグが設定されている場合、メッセージ ストア プロバイダーは IMAPISupport::ModifyProfile メソッドを呼び出す必要はありません。

MDB_WRITE

読み取り/書き込みアクセス許可を要求します。

lpInterface

[in]ログオンするメッセージ ストアのインターフェイス識別子 (IID) へのポインター。 null を渡すと、メッセージ ストア (IMsgStore) の MAPI インターフェイスが返されます。 lpInterface パラメーターは、メッセージ ストアに適したインターフェイス (IID_IUnknownやIID_IMAPIPropなど) の識別子に設定することもできます。

lpcbSpoolSecurity

[out] lppbSpoolSecurity パラメーターの検証データのサイズ (バイト単位) をストア プロバイダーが返す変数へのポインター。

lppbSpoolSecurity

[out]返された検証データへのポインターへのポインター。 この検証データは、 IMSProvider::SpoolerLogon メソッドが MAPI スプーラーをメッセージ ストア プロバイダーと同じストアにログに記録できるように提供されます。

lppMAPIError

[out]エラーのバージョン、コンポーネント、コンテキスト情報を含む、返された MAPIERROR 構造体へのポインター (存在する場合)。 返す MAPIERROR 構造体がない場合は、lppMAPIError パラメーターを null に設定できます。

lppMSLogon

[out]MAPI がログオンするためのメッセージ ストア ログオン オブジェクトへのポインター。

lppMDB

[out]MAPI スプーラーとクライアント アプリケーションがログオンするメッセージ ストア オブジェクトへのポインターへのポインター。

戻り値

S_OK

�ʘb���������A�\�������l�܂��͒l���Ԃ���܂��B

MAPI_E_FAILONEPROVIDER

このプロバイダーはログオンできませんが、このエラーはサービスを無効にしないでください。

MAPI_E_LOGON_FAILED

ログオン セッションを確立できませんでした。

MAPI_E_UNCONFIGURED

プロファイルには、ログオンを完了するための十分な情報が含まれていません。 この値が返されると、MAPI はメッセージ ストア プロバイダーのメッセージ サービス エントリ ポイント関数を呼び出します。

MAPI_E_USER_CANCEL

ユーザーは通常、ダイアログ ボックスの [キャンセル] ボタンをクリックして操作を 取り消 しました。

MAPI_E_UNKNOWN_CPID

サーバーは、クライアントのコード ページをサポートするように構成されていません。

MAPI_E_UNKNOWN_LCID

サーバーは、クライアントのロケール情報をサポートするように構成されていません。

MAPI_W_ERRORS_RETURNED

呼び出しは成功しましたが、メッセージ ストア プロバイダーにエラー情報が表示されます。 この警告が返されたら、呼び出しは成功として処理する必要があります。 この警告をテストするには、 HR_FAILED マクロを使用します。 詳細については、「 エラー処理にマクロを使用する」を参照してください。 プロバイダーからエラー情報を取得するには、 IMAPISession::GetLastError メソッドを呼び出します。

注釈

MAPI は IMSProvider::Logon メソッドを呼び出して、メッセージ ストアへのアクセスを取得するために必要な処理の大部分を実行します。 メッセージ ストア プロバイダーは、特定のストアにアクセスするために必要なユーザー資格情報を検証し、MAPI スプーラーとクライアント アプリケーションがログオンできる lppMDB パラメーターでメッセージ ストア オブジェクトを返します。

プロバイダーは、クライアントおよび MAPI スプーラー用に返されたメッセージ ストア オブジェクトに加えて、開いているストアの制御に使用する MAPI のメッセージ ストア ログオン オブジェクトも返します。 メッセージ ストア ログオン オブジェクトとメッセージ ストア オブジェクトは、それぞれが他方に影響を与えるように、メッセージ ストア プロバイダー内で緊密にリンクする必要があります。 ストア オブジェクトとログオン オブジェクトの使用は同一である必要があります。ログオン オブジェクトとストア オブジェクトの間には、オブジェクトが 2 つのインターフェイスを公開する 1 つのオブジェクトであるかのように動作するように、1 対 1 の対応が必要です。 2 つのオブジェクトも一緒に作成し、一緒に解放する必要があります。

MAPI によって作成され、 lpMAPISup パラメーターでプロバイダーに渡される MAPI サポート オブジェクトは、プロバイダーが必要とする MAPI の関数へのアクセスを提供します。 これには、プロファイル情報の保存と取得、アドレス帳へのアクセスなどの関数が含まれます。 lpMAPISup ポインターは、開くストアごとに異なる場合があります。 ログオン後のメッセージ ストアの呼び出しの処理中に、ストア プロバイダーは、そのストアに固有の lpMAPISup 変数を使用する必要があります。 メッセージ ストアを開き、メッセージ ストア ログオン オブジェクトの作成に成功する Logon 呼び出しの場合、プロバイダーは MAPI サポート オブジェクトへのポインターをストア ログオン オブジェクトに保存し、 IUnknown::AddRef メソッドを呼び出してサポート オブジェクトの参照を追加する必要があります。

プロバイダーがログオン呼び出し中にダイアログ ボックスを表示する場合は、ulUIParam パラメーターを使用する必要があります。 ただし、 ulFlags に MDB_NO_DIALOG フラグが含まれている場合は、ダイアログ ボックスを表示しないでください。 ユーザー インターフェイスを呼び出す必要があるが ulFlags で許可されていない場合、または何らかの理由でユーザー インターフェイスを表示できない場合は、プロバイダーはMAPI_E_LOGON_FAILEDを返す必要があります。 [ログオン] ダイアログ ボックスが表示され、ユーザーがログオンを取り消した場合 (通常はダイアログ ボックスの [キャンセル] ボタンをクリック) すると、プロバイダーはMAPI_E_USER_CANCELを返す必要があります。

lpEntryID パラメーターは、null または、このメッセージ ストアが以前に作成したラップされていないストア エントリ識別子を指すことができます。 lpEntryID がラップされていないエントリ識別子を指している場合、そのエントリ識別子は次のいずれかの場所から取得できます。

  • これは、ストア プロバイダーが以前にラップし、 PR_ENTRYID (PidTagEntryId) プロパティとしてプロファイル セクションに書き込んだエントリ識別子です。

  • プロバイダーが以前にラップして呼び出し元のクライアントに PR_STORE_ENTRYID (PidTagStoreEntryId) プロパティとして返したエントリ識別子を指定できます。

  • これは、プロバイダーがメッセージ ストア オブジェクトの PR_ENTRYID プロパティとして、以前にラップして呼び出し元のクライアントに返したエントリ識別子です。

いずれの場合も、エントリ識別子が現在使用されているコンピューターとは異なるコンピューターに作成されている可能性があります。

lpEntryID が null でない場合は、メッセージ ストアの識別と検索に必要なすべての情報を含める必要があります。 この情報には、ネットワーク ボリューム名、電話番号、ユーザー アカウント名などが含まれます。 エントリ識別子のデータを使用してストアへの接続を確立できない場合、ストア プロバイダーは、ユーザーが開くストアを選択できるようにするダイアログ ボックスを表示する必要があります。 ダイアログ ボックスが必要な場合があります。たとえば、サーバーの名前が変更された場合、アカウント名が変更された場合、またはネットワークの一部が使用できない場合などです。

lpEntryID が null の場合、使用するメッセージ ストアがまだ選択されていません。 プロバイダーは、ストアを指定するその他のメソッドをサポートしている場合でも、ダイアログ ボックスを表示せずにストアにアクセスできます。 たとえば、プロバイダーは初期化ファイルを確認したり、構成時にメッセージ サービスのプロファイル セクションに配置された追加のプロパティを検索したりできます。

プロバイダーは、必要なすべての情報がプロファイルに含まれていないことを検出した場合は、MAPI_E_UNCONFIGUREDを返す必要があります。 MAPI はプロバイダーのメッセージ サービス エントリ ポイント関数を呼び出して、ユーザーがストアを選択したり、ストアを作成したり、必要に応じてアカウント名とパスワードを入力したりできます。 MAPI では、新しいストアの新しいプロファイル セクションが自動的に作成されます。この新しいプロファイル セクションは、追加方法に応じて、一時的または永続的にすることができます。 ストア プロバイダーが IMAPISupport::ModifyProfile メソッドを呼び出すと、新しいプロファイル セクションが永続的になり、 IMAPISession::GetMsgStoresTable メソッドによって返されるメッセージ ストアの一覧にストアが追加されます。

lpInterface パラメーターは、新しく開いたストア オブジェクトに必要なインターフェイスの IID を指定します。 lpInterface で null を渡すと、MAPI メッセージ ストア インターフェイス IMsgStore が必要であることを指定します。 IID_IMsgStoreメッセージ ストア オブジェクトを渡すと、 IMsgStore が必要であることも指定されます。 IID_IUnknownが lpInterface で渡された場合、プロバイダーは、プロバイダーに最適な IUnknown から派生したインターフェイスを使用してストアを開く必要があります (通常は IMsgStore です)。 IID_IUnknownが渡されると、呼び出し元の実装では IUnknown::QueryInterface メソッドを使用して、ストアのオープン操作が成功した後にインターフェイスを選択します。

IMSProvider::Logon 呼び出しは、ストアへのパスやストアにアクセスするための資格情報などの十分な情報を返して、MAPI スプーラーがダイアログ ボックスを表示せずにストア プロバイダーと同じストアにログオンできるようにする必要があります。 この情報を返すには、 lpcbSpoolSecurity パラメーターと lppbSpoolSecurity パラメーターが使用されます。 プロバイダーは、 MSProviderInit 関数の lpfAllocateBuffer パラメーター内のバッファーへのポインターを渡すことによって、このデータのメモリを割り当てます。プロバイダーは、このバッファーのサイズを lpcbSpoolSecurity に配置します。

MAPI は、必要に応じてこのバッファーを解放します。 MAPI スプーラーのストアへのログオンをプロファイル セクションの情報から単独で実行できる場合、プロバイダーは lppbSpoolSecurity で null を返し、 lpcbSpoolSecurity の情報のサイズは 0 を返すことができます。 MAPI スプーラー ログオンは、ストア ログオンとは異なるプロセスの一部として発生します。渡された情報を含むバッファーはプロセス間でコピーされるため、ストア プロバイダー プロセスと同じ MAPI スプーラー プロセスの場所にメモリ内にない可能性があります。 そのため、プロバイダーはこのバッファーにアドレスを配置しないでください。 MAPI スプーラー ログオンの詳細については、 IMSProvider::SpoolerLogon メソッドを 参照してください。

ほとんどのストア プロバイダーは、lpMAPISup パラメーターで渡されるサポート オブジェクトの IMAPISession::OpenProfileSection メソッドを使用して、ユーザーの資格情報とオプションを保存および取得します。 OpenProfileSection を使用すると、ストア プロバイダーはプロファイル セクションに追加の任意の情報を保存し、それを特定のリソースに関連付けることができます。 たとえば、ストア プロバイダーは、リソースに関連付けられているユーザー アカウント名とパスワード、そのリソースにアクセスするために必要なパスやその他の情報を保存できます。

0x67FFを介して0x6600プロパティ識別子を持つプロパティは、プロファイル セクションにプライベート データを格納するためにプロバイダーが独自に使用できるセキュリティで保護されたプロパティです。 プロファイル セクション オブジェクトのプロパティの使用方法の詳細については、 IProfSect : IMAPIProp メソッドを参照してください。

0x67FFを介して0x6600識別子を持つプロパティ内のプライベート データに加えて、ストア プロバイダーはプロファイル セクションで PR_DISPLAY_NAME (PidTagDisplayName) プロパティの情報を提供する必要があります。 プロバイダー自体の表示名 PR_DISPLAY_NAME 、ユーザーに表示される識別文字列 ("Microsoft 個人情報ストア" など) を入力して、このメッセージ ストアをアクセスできる可能性のある他のユーザーと区別できるようにする必要があります。 PR_DISPLAY_NAME 一般に、サーバー名、ユーザー アカウント名、またはパスが含まれています。

一部のプロファイル セクションのプロパティは、メッセージ ストア テーブルに表示されます。その他は、MAPI サブシステムのセットアップ、インストール、および構成中に表示されます。 通常、プロバイダーは、保存された資格情報や個人情報がまだ含まれていない新しいプロファイル セクションと、そのプロパティ情報が変更されたことを検出した場合の両方に、これらの表示されるプロパティの情報を提供します。 プロファイル セクションの詳細については、「 IMAPISupport::OpenProfileSection」を参照してください。

ユーザーに正常にログオンした後、MAPI に戻る前に、ストア プロバイダーはリソースの状態行のプロパティの配列を作成し、 IMAPISupport::ModifyStatusRow メソッドを呼び出す必要があります。

現在の MAPI セッションに対して既に開いているメッセージ ストアを開くログオン呼び出しは、前述の処理の多くをスキップします。 これらの呼び出しでは、状態行の作成、メッセージ ストア ログオン オブジェクトの返し、MAPI サポート オブジェクトの AddRef の呼び出し、MAPI スプーラー ログオンのデータの取得は行われません。 これらの呼び出しは、S_OKを返し、要求されたインターフェイスを持つメッセージ ストア オブジェクトを返します。

このような呼び出しを検出するには、プロバイダーは、このプロバイダー オブジェクトに対して既に開いているストアのメッセージ ストア プロバイダー オブジェクトにリストを保持する必要があります。 ログオン呼び出しを処理する場合、プロバイダーは開いているストアのこの一覧をスキャンし、ログオンするストアが既に開いているかどうかを判断する必要があります。 その場合、ユーザー資格情報をチェックする必要はありません。可能であれば、ダイアログ ボックスの表示を回避する必要があります。 ダイアログ ボックスを表示する必要がある場合、プロバイダーは返された情報を確認して、ストアが 2 回目に開かれたかどうかを確認する必要があります。 さらに、プロバイダーは、ログオン呼び出し処理の開始時に lpEntryID を使用して、重複する開口部を確認する必要があります。

オープン ストアにアクセスする ログオン 呼び出しの標準的な処理は次のとおりです。

  1. 要求される新しいインターフェイスが既存のストアのインターフェイスと同じ場合、ストア プロバイダーは既存のストア オブジェクトに対して AddRef を呼び出します。 それ以外の場合は、 QueryInterface を 呼び出して新しいインターフェイスを取得します。 ストアが新しいインターフェイスをサポートしていない場合、プロバイダーはエラー値MAPI_E_INTERFACE_NOT_SUPPORTEDを返す必要があります。

  2. プロバイダーは、 lppMDB 内の既存のストア オブジェクトの必要なインターフェイスへのポインターを返します。

  3. プロバイダーは、lppMSLogon で null を返します。

  4. プロバイダーは、呼び出しで渡されたサポート オブジェクトのプロファイルを開くべきではありません。 さらに、プロバイダーの一意識別子を登録したり、状態行を登録したり、MAPI スプーラー ログオン データを返したりしないでください。

  5. プロバイダーは、サポート オブジェクトへのポインターを必要としないため、サポート オブジェクトの AddRef を呼び出す必要はありません。

可能な限り、プロバイダーは ログオン 呼び出しに対して適切なエラー文字列と警告文字列を返す必要があります。 これらの文字列を返すために、プロバイダーは MAPIERROR 構造体のメンバーを設定します。 MAPI は、プロバイダーから返された場合に MAPIERROR 構造体を検索、使用、および解放します。

この MAPIERROR 構造体のメモリは、MSProviderInit 呼び出しで lpfAllocateBuffer で渡されるバッファーを使用して割り当てる必要があります。 LogonulFlags でMAPI_UNICODEが設定されている場合、返される構造体に含まれるエラー文字列は Unicode 形式にする必要があります。それ以外の場合は ANSI 文字セットに含める必要があります。

ログオンから返されるほとんどのエラー値では、MAPI は、失敗したプロバイダーが属しているメッセージ サービスを無効にします。 MAPI では、MAPI セッションの有効期間中、これらのサービスに属するプロバイダーは呼び出されません。 これに対し、 ログオンがログオン からMAPI_E_FAILONEPROVIDERエラー値を返す場合、MAPI はプロバイダーが属するメッセージ サービスを無効にしません。 セッション の有効期間中にサービス全体を無効にすることを保証しないエラーが発生した場合、ログオンはMAPI_E_FAILONEPROVIDERを返す必要があります。 たとえば、プロバイダーは、ユーザー インターフェイスの表示を許可せず、必要なパスワードを使用できない場合に、このエラーを返す可能性があります。

プロバイダーがログオンからMAPI_E_UNCONFIGUREDを返した場合、MAPI はプロバイダーのメッセージ サービス エントリ関数を呼び出し、ログオンを再試行します。 MAPI はMSG_SERVICE_CONFIGUREをコンテキストとして渡して、サービスに自身を構成する機会を与えます。 クライアントがログオン時にユーザー インターフェイスを許可することを選択した場合、サービスは構成プロパティ シートを表示して、ユーザーが構成情報を入力できるようにします。

関連項目

IMAPISession::GetMsgStoresTable

IMAPISession::OpenMsgStore

IMAPISession::OpenProfileSection

IMAPISupport::ModifyProfile

IMAPISupport::ModifyStatusRow

IMsgStore: IMAPIProp

IMSProvider::SpoolerLogon

IProfSect : IMAPIProp

MAPIERROR

MSProviderInit

IMSProvider : IUnknown