IABProvider::Logon
適用対象: Outlook 2013 | Outlook 2016
アクティブ セッションへの接続を確立します。
HRESULT Logon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG ulFlags,
ULONG FAR * lpulcbSecurity,
LPBYTE FAR * lppbSecurity,
LPMAPIERROR FAR * lppMAPIError,
LPABLOGON FAR * lppABLogon
);
パラメーター
lpMAPISup
[in]アドレス帳プロバイダーのサポート オブジェクトへのポインター。
ulUIParam
[in]ログオン メソッドが 表示するログオン ダイアログ ボックスの親ウィンドウへのハンドル (許可されている場合)。 ulUIParam パラメーターには、MAPILogonEx 関数の前の呼び出しで MAPI に渡されたのと同じ名前のパラメーターの値が含まれています。
lpszProfileName
[in]セッション プロファイルの名前へのポインター。
ulFlags
[in]ログオンの実行方法を制御するフラグのビットマスク。 次のフラグを設定できます。
AB_NO_DIALOG
プロバイダーは、ログオン中にダイアログ ボックスを表示しないでください。 このフラグが設定されていない場合、プロバイダーはダイアログ ボックスを表示して、構成情報が不足しているかどうかをユーザーに求めることができます。
MAPI_DEFERRED_ERRORS
ログオン プロセスが完了する前に、ログオンが正常に返されるようにします。
MAPI_UNICODE
すべての文字列は Unicode 形式である必要があります。 MAPI_UNICODE フラグが設定されていない場合、文字列は ANSI 形式である必要があります。
lpulcbSecurity
[in, out] lppbSecurity パラメーターによって指されるセキュリティ資格情報構造体のサイズ (バイト単位) へのポインター。 入力では、値は 0 以外である必要があります。出力では、値は 0 である必要があります。 どちらの場合も、ポインターは有効である必要があります。
lppbSecurity
[in, out]セキュリティ資格情報へのポインター。 入力では、値は 0 以外である必要があります。出力では、値は 0 である必要があります。 どちらの場合も、ポインターは有効である必要があります。
lppMAPIError
[out] MAPIERROR 構造体へのポインターへのポインター。 返す MAPIERROR 構造体がない場合は、lppMAPIError パラメーターを NULL に設定できます。
lppABLogon
[out]プロバイダーのログオン オブジェクトへのポインター。
戻り値
S_OK
アクティブ セッションへの接続が正常に確立されました。
MAPI_E_FAILONEPROVIDER
プロバイダーはログオンできませんが、MAPI は、プロバイダーが属するメッセージ サービス内の他のプロバイダーにログオンし続けることができます。
MAPI_E_UNCONFIGURED
プロバイダーには、ログオンを完了するための十分な情報がありません。 MAPI は、プロバイダーのメッセージ サービス エントリ関数を呼び出します。
MAPI_E_UNKNOWN_CPID
サーバーは、クライアントのコード ページをサポートするように構成されていません。
MAPI_E_UNKNOWN_LCID
サーバーは、クライアントのロケール情報をサポートするように構成されていません。
MAPI_E_USER_CANCEL
ユーザーは通常、ログオン ダイアログ ボックスの [キャンセル ] ボタンをクリックして操作をキャンセルしました。
注釈
Connectionsは、クライアントが IMAPISession::OpenAddressBook メソッドを呼び出すときに、セッション プロファイルの各アドレス帳プロバイダーで確立されます。 OpenAddressBook は、各プロバイダーの Logon メソッドを呼び出します。
lpszProfileName パラメーターが指すプロファイル名は、ulFlags パラメーターのMAPI_UNICODE フラグの有無によって示されるように、ユーザーのクライアントの文字セットに表示されます。
実装に関するメモ
Logon メソッドの実装で、IMAPISupport::SetProviderUID メソッドを呼び出して、一意の識別子または MAPIUID 構造体を登録します。 各オブジェクトには、この MAPIUID を含むエントリ識別子があります。 MAPI は MAPIUID を使用して、プロバイダーとオブジェクトを照合します。 たとえば、クライアントが IMAPISession::OpenEntry メソッドを呼び出してメッセージング ユーザーを開くと、 OpenEntry は、渡されたエントリ識別子の MAPIUID 部分を調べ、アドレス帳プロバイダーによって登録された MAPIUID と一致します。
クライアントがプロバイダーに複数回ログオンする場合は、ログオンごとに異なる MAPIUID を登録できます。 一意の MAPIUID 構造体を登録すると、MAPI は適切なプロバイダー インスタンスに要求を正しくルーティングできます。 ただし、すべてのログオン オブジェクトが 1 つの MAPIUID を共有するようにしたい場合があります。 この場合、MAPI に依存するのではなく、自分でルーティングを処理できる必要があります。 MAPIUID を作成する方法の詳細については、「サービス プロバイダーの一意識別子の登録」を参照してください。
MAPI が lpMAPISup パラメーターで Logon メソッドに渡すサポート オブジェクトは、IMAPISupport : IUnknown インターフェイスに含まれる多くのメソッドにアクセスできます。 MAPI は、プロバイダーの種類に合わせてカスタマイズされたサポート オブジェクトを作成します。 たとえば、接続を確立するときに基になるメッセージング システムまたはディレクトリ サービスにログオンする必要がある場合は、 IMAPISupport::OpenProfileSection メソッドを呼び出して、この特定のログオン セッションのセキュリティ資格情報を取得できます。
Logon が成功した場合は、サポート オブジェクトの IUnknown::AddRef メソッドを呼び出して参照カウントをインクリメントしてください。 これにより、プロバイダーは、セッションの残りの部分のサポート オブジェクト ポインターを保持できます。 この AddRef メソッドを呼び出さないと、MAPI によってプロバイダーがアンロードされます。
エラー ダイアログ ボックス、ログオン画面、またはその他のユーザー インターフェイスに 、lpszProfileName パラメーターに渡されたプロファイル名を含めることができます。 プロファイル名を使用するには、割り当てたストレージにコピーします。
ログオン オブジェクトを作成し、 lppABLogon パラメーターでポインターを返します。 MAPI では、このログオン オブジェクトを使用して 、IABLogon 実装のメソッドを呼び出します。
ログオン時にパスワードが必要な場合は、AB_NO_DIALOG フラグが設定されていない場合にのみログオン ダイアログ ボックスを表示します。 ユーザーがログオン プロセスを取り消した場合は、通常、ダイアログ ボックスの [キャンセル ] ボタンをクリックして、[ ログオン] からMAPI_E_USER_CANCELを返します。
通常、アドレス帳プロバイダーがログオンできない場合、MAPI は、失敗したプロバイダーが属するメッセージ サービスを無効にします。つまり、MAPI は、セッションの有効期間の残りの期間、サービスに属する他のプロバイダーの接続を確立しようとしません。 ただし、プロバイダーが接続を確立できず、サービス全体を無効にしない場合は、MAPI_E_FAILONEPROVIDERまたはMAPI_E_UNCONFIGUREDを返します。 MAPI は、プロバイダーが属するメッセージ サービスを無効にしません。
メッセージ サービス内の他のプロバイダーが接続を確立できないほど深刻でないエラーが発生した場合は、MAPI_E_FAILONEPROVIDERを返します。 プロファイルに必要な構成情報が見つからない場合、ユーザーにメッセージを表示するダイアログ ボックスが表示されない場合は、MAPI_E_UNCONFIGUREDを返します。 MAPI は、MSG_SERVICE_CONFIGURE ulContext パラメーターとして設定されたプロバイダーのメッセージ サービス エントリ ポイント関数を呼び出して応答し、プログラムによって、またはプロパティ シートを使用して、サービス自体を構成する機会を提供します。 メッセージ サービス エントリ ポイント関数が完了すると、MAPI はログオンを再試行します。