IXPProvider::TransportLogon
適用対象: Outlook 2013 | Outlook 2016
クライアント アプリケーションがトランスポート プロバイダーにログオンするセッションを確立します。
HRESULT TransportLogon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG FAR * lpulFlags,
LPMAPIERROR FAR * lppMAPIError,
LPXPLOGON FAR * lppXPLogon
);
パラメーター
lpMAPISup: [in] このセッションの MAPI 内のコールバック関数のトランスポート プロバイダーのサポート オブジェクトへのポインター。 このオブジェクトは、トランスポート プロバイダーによって解放されるまで有効なままになります。
ulUIParam: [in] このメソッドが表示するダイアログ ボックスまたはウィンドウの親ウィンドウを処理します。 ulUIParam パラメーターは、たとえば、lpulFlags パラメーターで LOGON_SETUP フラグが設定されている場合など、null 以外にすることができます。
lpszProfileName: [in] ユーザーのプロファイル名へのポインター。 lpszProfileName パラメーターは、主にダイアログ ボックスを表示する必要がある場合に使用されます。
lpulFlags: [in, out] ログオン セッションの確立方法を制御するフラグのビットマスク。 MAPI スプーラーによる入力では、次のフラグを設定できます。
LOGON_NO_CONNECT: ユーザー アカウントは、メッセージの送受信以外の目的で、このトランスポート プロバイダーにログオンしています。 トランスポート プロバイダーは、他のメッセージング システムへの接続を試行しないでください。
LOGON_NO_DIALOG: 現在保存されているユーザー資格情報が無効であるか、ログオンに不十分な場合でも、ダイアログ ボックスは表示されません。
LOGON_NO_INBOUND: トランスポート プロバイダーは、メッセージの受信のために初期化する必要がないため、受信メッセージを受け入れる必要はありません。 MAPI スプーラーは、後で IXPLogon::TransportNotify メソッドを使用して、受信メッセージ処理を有効にするためにトランスポート プロバイダーに通知できます。
LOGON_NO_OUTBOUND: MAPI スプーラーでは何も提供されないため、トランスポート プロバイダーはメッセージを送信するために初期化する必要はありません。 IXPLogon::AddressTypes メソッドを呼び出すことができるように、メッセージの合成中にクライアント アプリケーションがリモート プロバイダーへの接続を必要とする場合、トランスポート プロバイダーは接続を確立する必要があります。 MAPI スプーラーは TransportNotify を使用して、送信操作を開始できる場合にトランスポート プロバイダーに通知できます。
MAPI_UNICODE: プロファイル名の渡された文字列は Unicode 形式です。 MAPI_UNICODE フラグが設定されていない場合、文字列は ANSI 形式です。
次のフラグは、トランスポート プロバイダーによって出力に設定できます。
LOGON_SP_IDLE: MAPI スプーラーがアイドル時間処理のためにトランスポート プロバイダーの IXPLogon::Idle メソッドを頻繁に呼び出すように要求します。
LOGON_SP_POLL: MAPI スプーラーが、返されたログオン オブジェクトの IXPLogon::P oll メソッドを頻繁に呼び出して、新しいメッセージをチェックするように要求します。 このフラグが設定されていない場合、MAPI スプーラーは、トランスポート プロバイダーが IMAPISupport::SpoolerNotify メソッドを使用して、処理する新しいメッセージがあることをスプーラーに通知する場合にのみ、新しいメッセージをチェックします。 トランスポート プロバイダーは、このフラグを設定せず、MAPI スプーラーにメッセージ受信を通知しないことによって、実質的に送信専用になります。
LOGON_SP_RESOLVE: MAPI スプーラーがこのトランスポート プロバイダーでサポートされていない受信者のすべてのメッセージ アドレスを完全に解決するように要求します。 そのため、トランスポート プロバイダーは、すべての受信者の応答パスを構築できます。
MAPI_UNICODE: MAPIERROR 構造体で返される文字列 (存在する場合) は Unicode 形式です。 MAPI_UNICODE フラグが設定されていない場合、文字列は ANSI 形式です。
lppMAPIError: [out] エラーのバージョン、コンポーネント、コンテキスト情報を含む、返された MAPIERROR 構造体へのポインターへのポインター (存在する場合)。 返す MAPIERROR 構造体がない場合は、lppMAPIError パラメーターを NULL に設定できます。
lppXPLogon: [out] 返されたトランスポート プロバイダー ログオン オブジェクトへのポインターへのポインター。
戻り値
S_OK: 呼び出しが成功し、期待される値または値が返されました。
MAPI_E_FAILONEPROVIDER: このプロバイダーはログオンできませんが、このエラーはサービスを無効にしないでください。
MAPI_E_UNCONFIGURED: プロファイルにログオンを完了するための十分な情報が含まれていません。 MAPI は、プロバイダーのメッセージ サービス エントリ ポイント関数を呼び出します。
MAPI_E_UNKNOWN_CPID: プロバイダーはクライアントのコード ページをサポートできません。
MAPI_E_UNKNOWN_LCID: プロバイダーはクライアントのロケール情報をサポートできません。
MAPI_E_USER_CANCEL: ユーザーは通常、ダイアログ ボックスの [キャンセル] ボタンをクリックして操作を 取り消 しました。
注釈
MAPI スプーラーは 、IXPProvider::TransportLogon メソッドを呼び出して、ユーザーのログオン セッションを確立します。
ほとんどのトランスポート プロバイダーは、lpMAPISup パラメーターによって指されるサポート オブジェクトで提供される IMAPISupport::OpenProfileSection メソッドを使用して、ユーザー ID 情報、サーバー アドレス、資格情報を保存および取得します。 OpenProfileSection を使用すると、トランスポート プロバイダーは任意の情報を保存し、特定のリソースへのログオンに関連付けることができます。 たとえば、プロバイダーは OpenProfileSection を使用して、特定のセッションに関連付けられているアカウント名とパスワード、そのセッションのリソースにアクセスするために必要なサーバー名やその他の必要な情報を保存できます。 MAPI は、外部アクセスからリソースに関連付けられている情報を非表示にします。 lpMAPISup を使用して使用できるプロファイル セクションは、MAPI スプーラーによって管理されるため、このユーザー コンテキストに関連するデータは、他のコンテキストのデータから分離されます。
トランスポート プロバイダーは、サポート オブジェクトで IUnknown::AddRef メソッドを呼び出し、プロバイダー ログオン オブジェクトの一部としてこのオブジェクトへのポインターのコピーを保持する必要があります。
lpszProfileName のプロファイル表示名は、トランスポート プロバイダーがエラー メッセージまたはログオン ダイアログ ボックスで使用できるように提供されます。 プロバイダーがこの名前を保持する場合は、プロバイダーによって割り当てられたストレージにコピーする必要があります。
他のサービス プロバイダーと緊密に結合されているトランスポート プロバイダーは、コンパニオン プロバイダー間の操作に必要な適切な資格情報を確立するために、ログオン時に追加の作業を行う必要がある場合があります。
通常、トランスポート プロバイダーは、ユーザーが最初にプロファイルにログオンしたときに開かれます。 したがって、プロファイルへの最初のログオンは通常、メッセージ ストアにログオンする前に行われるため、MAPI スプーラーは通常、lpulFlags に設定されたLOGON_NO_INBOUNDフラグとLOGON_NO_OUTBOUND フラグの両方で TransportLogon を呼び出します。 その後、プロファイル セッションで適切なメッセージ ストアを使用できる場合、MAPI スプーラーは TransportNotify を呼び出して、トランスポート プロバイダーの受信および送信操作を開始します。
lpulFlags でLOGON_NO_CONNECT フラグを渡すと、トランスポート プロバイダーのオフライン操作が通知されます。 このフラグは、外部接続を行う必要がないことを示します。トランスポート プロバイダーが外部接続なしでセッションを確立できない場合は、ログオンのエラー値を返す必要があります。
システムがアイドル時間を使用するように設計されている場合、トランスポート プロバイダーは、初期化時に lpulFlags でLOGON_SP_IDLE フラグを設定する必要があります。 このような時刻は、自動メッセージのダウンロード、時間指定メッセージのダウンロード、時間指定メッセージの送信などの自動操作を処理するためによく使用されます。 このフラグが設定されている場合、MAPI スプーラーは、このような操作を開始するためにシステムのアイドル時間が発生したときに アイドル を呼び出します。 MAPI スプーラーは、設定された間隔で アイドルを 呼び出しません。実際のアイドル時間中にのみ呼び出されます。 そのため、プロバイダーは 、Idle メソッドを呼び出す頻度を想定して作業しないでください。 アイドル時間操作をサポートするプロバイダーは、プロバイダー のプロパティ シートで、そのユーザーインターフェイスの構成ユーザー インターフェイスを指定する必要があります。
トランスポート プロバイダーのログオンが成功した場合、プロバイダーは lppXPLogon パラメーターにログオン オブジェクトへのポインターを返す必要があります。 MAPI スプーラーは、追加のプロバイダー アクセスにこのオブジェクトを使用します。 TransportLogon にログオン ダイアログ ボックスが表示され、ユーザーが通常、ダイアログ ボックスの [キャンセル] ボタンをクリックしてログオンを取り消した場合、プロバイダーはMAPI_E_USER_CANCELを返す必要があります。
TransportLogon から返されるほとんどのエラー値では、MAPI はプロバイダーが属するメッセージ サービスを無効にします。 MAPI は、MAPI セッションの残りの部分について、そのサービスに属するプロバイダーを呼び出しません。 これに対し、 TransportLogon がログオンからMAPI_E_FAILONEPROVIDERエラー値を返す場合、MAPI はプロバイダーが属するメッセージ サービスを無効にしません。 TransportLogon は、セッションの残りの部分でサービスを無効にすることを保証しないエラーが発生した場合は、MAPI_E_FAILONEPROVIDERを返す必要があります。
プロバイダーがログオンからMAPI_E_UNCONFIGUREDを返した場合、MAPI はプロバイダーのメッセージ サービス エントリ関数を呼び出し、ログオンを再試行します。 MAPI はコンテキストとしてMSG_SERVICE_CONFIGUREを渡して、サービス自体を構成する機会を提供します。 クライアントがログオン時にユーザー インターフェイスを許可することを選択した場合、サービスは構成プロパティ シートを表示して、ユーザーが構成情報を入力できるようにします。
プロバイダーは、必要なすべての情報がプロファイルに含まれていないことを検出した場合は、MAPI がプロバイダーのメッセージ サービス エントリ ポイント関数を呼び出すようにMAPI_E_UNCONFIGUREDを返す必要があります。