IAttachmentExecute

クライアントアプリケーションと連携し、電子メールやメッセージングの添付ファイルを通じて安全なファイルのダウンロードと交換を提供するユーザー環境を提示するためのメソッドを公開します。

このインターフェイスは、次のことを前提としています。

• クライアントが添付ファイルのサポートと動作に関するポリシーまたは設定を持っていること。
• クライアントがユーザーと対話すること。

以下は、電子メールクライアントが IAttachmentExecute をどのように使用するかの例です。

// CClientAttachmentInfo, defined by the client, implements all the
// necessary client functionality concerning attachments. 
class CClientAttachmentInfo;  

// Creates an instance of IAttachmentExecute
HRESULT CreateAttachmentServices(IAttachmentExecute **ppae)
{
    // Assume that CoInitialize has already been called for this thread.
    HRESULT hr = CoCreateInstance(CLSID_AttachmentServices, 
                                  NULL, 
                                  CLSCTX_INPROC_SERVER, 
                                  IID_IAttachmentExecute, 
                                  (void**)&pAttachExec);

    if (SUCCEEDED(hr))
    {
        // Set the client's GUID.

        // UUID_ClientID should be created using uuidgen.exe and 
        // defined internally.
        (*ppae)->SetClientGuid(UUID_ClientID);
        
        // You also could call SetClientTitle at this point, but it is
        // not required.
    }
    return hr;
}

BOOL IsAttachmentBlocked(CClientAttachmentInfo *pinfo)
{
    // Assume that a client function has copied the file from the mail store 
    // into a temporary file.
    PWSTR pszFileName;

    // GetFileName is a method in this class for which we do not provide
    // an implementation here.
    HRESULT hr = pinfo->GetFileName(&pszFileName);
    if (SUCCEEDED(hr))
    {
        IAttachmentExecute *pExecute;

        hr = CreateAttachmentServices(&pExecute);
        if (SUCCEEDED(hr))
        {
            hr = pExecute->SetFileName(pszFileName);

            // Do not call SetLocalPath since we do not have the local path yet.
            // Do not call SetSource since email sources are not verifiable.
            // Do not call SetReferrer since we do not have a better zone 
            // than the default (Restricted sites).

            // Check for a policy regarding the file.
            if (SUCCEEDED(hr))
            {
                hr = pExecute->CheckPolicy();
            }
            pExecute->Release();
        }
        LocalFree(pszFileName);
    }
    return FAILED(hr);
}
    
HRESULT OnDoubleClickAttachment(HWND hwnd, CClientAttachmentInfo *pinfo)
{
    // Assume that a client function has copied the file from the mail store 
    // into a temporary file.
    PWSTR pszTempFile;

    // CopyToTempFile is a method in this class for which we do not provide
    // an implementation here.
    HRESULT hr = pinfo->CopyToTempFile(&pszTempFile);
    if (SUCCEEDED(hr))
    {
        IAttachmentExecute *pExecute;

        hr = CreateAttachmentServices(&pExecute);
        if (SUCCEEDED(hr))
        {
            hr = pExecute->SetLocalPath(pszTempFile);

            // Do not call SetFileName since we already have the local path.
            // Do not call SetSource since email sources are not verifiable.
            // Do not call SetReferrer since we do not have a better zone 
            // than the default (Restricted sites).

            if (SUCCEEDED(hr))
            {
                hr = pExecute->Execute(hwnd, NULL, NULL);
            }
            pExecute->Release();
        }
        LocalFree(pszTempFile);
    }
    return hr;
}

HRESULT OnSaveAttachment(HWND hwnd, CClientAttachmentInfo *pinfo)
{
    // Assume that a client function has copied the file from the mail store 
    // into a location selected by the user.
    PWSTR pszUserFile;

    // CopyToUserFile is a method in this class for which we do not provide
    // an implementation here.
    HRESULT hr = pinfo->CopyToUserFile(hwnd, &pszUserFile);
    if (SUCCEEDED(hr))
    {
        IAttachmentExecute *pExecute;

        hr = CreateAttachmentServices(&pExecute);
        if (SUCCEEDED(hr))
        {
            hr = pExecute->SetLocalPath(pszTempFile);

            // Do not call SetFileName since we have the local path.
            // Do not call SetSource since email sources are not verifiable.
            // Do not call SetReferrer since we do not have a better zone 
            // than the default (Restricted sites).

            if (SUCCEEDED(hr))
            {
                hr = pExecute->Save();
            }
            pExecute->Release();
        }
        LocalFree(pszUserFile);
    }
    return hr;
}

プロンプトウィンドウのタイトルを指定して格納します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

IAttachmentExecute::SetClientTitle が呼び出されない場合、プロンプトのタイトルバーには既定のタイトルとして File Download が使用されます。

クライアントの GUID を指定して格納します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

ユーザーは特定のプロンプトを表示しないように選択できます。その情報は、guid をインデックスとして、クライアントごとにレジストリに格納されます。

ファイルへのパスを設定して格納します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

IAttachmentExecute::SetLocalPath の呼び出しは必須です。

添付ファイルの実行が(ポリシーまたはプロンプトを通じて)ユーザーによって承認されると、このメソッドで指定したパスが使用されます。IAttachmentExecute::CheckPolicy および IAttachmentExecute::Prompt を呼び出す前に IAttachmentExecute::SetFileName のみを呼び出していた場合、想定していたローカルパスが IAttachmentExecute::SetLocalPath で設定されたものと異なると、その信頼は取り消される可能性があります。信頼は、さまざまなゾーン API、ウイルス対策サービス、ファイル種別情報、ポリシー、およびその他のシステム信頼プロバイダーによって付与されます。

IAttachmentExecute::SetLocalPath は、IAttachmentExecute::Execute を呼び出す前に呼び出す必要があります。

ファイルの候補名を指定して格納します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は、次のものを含む HRESULT エラーコードを返します。

pszFileName にはパス情報を含めず、ファイル名のみを指定してください。

IAttachmentExecute::SetFileName は、ファイルをローカルにコピーする前に、呼び出し側アプリケーションがファイル名の妥当性を確認するために使用できます。ファイル名は、ローカルパスの場所に格納されている他のファイルとの名前の競合についてチェックされます。

IAttachmentExecute::SetFileName は省略可能です。

ファイル転送のソースとして、代替のパスまたは URL を設定します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

ここで宣言したパスまたは URL は、ゾーンを判定する主要な決定要因として使用されます。添付ファイルが処理されるポリシーは、認識されたゾーンに部分的に基づいて決まります。pszSource が NULL の場合、既定では制限付きゾーンになります。

IAttachmentExecute::SetSource の呼び出しは省略可能です。

ここで宣言したパスまたは URL は、プロンプト UI の From フィールドとしても使用できます。

ここで宣言したパスまたは URL は、URL を処理できるハンドラーに送信することもできます。

参照元ファイルに基づいて、添付ファイルに関連付けられるセキュリティゾーンを設定します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

IAttachmentExecute::SetReferrer と IAttachmentExecute::SetSource は同様の機能を持ちます。両方が設定されている場合、2 つのうち最も信頼度の低いゾーンが使用されます。

IAttachmentExecute::SetReferrer は、コンテナーファイルが間接的な継承を示し、ゾーンの昇格を回避するために使用されます。また、ショートカットファイルと共に使用して、パラメーターに基づいて昇格を制限することもできます。

IAttachmentExecute::SetReferrer の呼び出しは省略可能です。

IAttachmentExecute::SetReferrer は、セキュリティゾーンおよびそれに関連付けられたポリシーを判定するためにのみ使用されます。

添付ファイルの実行ポリシーに基づいて判断を下すために使用できるブール値のテストを提供します。

型: HRESULT

次のいずれかの値を返します。

IAttachmentExecute::CheckPolicy は、総称して evidence(エビデンス) と呼ばれる一連のプロパティを調べます。信頼レベルの判定に使用されるものはすべてエビデンスと見なされます。これらのプロパティは、次のメソッドを使用して設定されます。

• IAttachmentExecute::SetFileName
• IAttachmentExecute::SetLocalPath
• IAttachmentExecute::SetReferrer
• IAttachmentExecute::SetSource

IAttachmentExecute::CheckPolicy では、アプリケーションが最初に IAttachmentExecute::SetFileName または IAttachmentExecute::SetLocalPath のいずれかを呼び出しておく必要があります。

プロンプト UI をユーザーに表示します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

IAttachmentExecute::Prompt を呼び出す前に、IAttachmentExecute::SetFileName または IAttachmentExecute::SetLocalPath を呼び出す必要があります。

IAttachmentExecute::Prompt は、ファイルがディスクにコピーされる前に UI の表示を強制するために、アプリケーションから呼び出すことができます。

添付ファイルを保存します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

IAttachmentExecute::Save を呼び出す前に、有効なパスを指定して IAttachmentExecute::SetLocalPath を呼び出す必要があります。IAttachmentExecute::Save を呼び出す前に、ファイルをそのローカルパスにコピーしておく必要があります。

IAttachmentExecute::SetLocalPath で宣言したローカルパスが一時ディレクトリのパスでない場合は、常に IAttachmentExecute::Save を呼び出す必要があります。

IAttachmentExecute::Save は、ファイルを保存する前に、ウイルススキャナーやその他の信頼サービスを実行してファイルを検証する場合があります。これらのサービスがファイルを削除または変更する可能性があることに注意してください。

IAttachmentExecute::Save は、NTFS の代替データストリーム(ADS)内で、ローカルパスに エビデンス を付加する場合があります。

添付ファイルに対してアクションを実行します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

IAttachmentExecute::Execute を呼び出す前に、有効なローカルパスを指定して IAttachmentExecute::SetLocalPath を呼び出し、ファイルをその場所にコピーしておく必要があります。

プロンプトが指示された場合、IAttachmentExecute::Execute は ATTACHMENT_ACTION_EXEC 値を使用して IAttachmentExecute::Prompt を呼び出します。

IAttachmentExecute::Execute は、ファイルを実行する前に、ウイルススキャナーやその他の信頼サービスを実行してファイルを検証する場合があります。これらのサービスがファイルを削除または変更する可能性があることに注意してください。

IAttachmentExecute::Execute は、NTFS の代替データストリーム(ADS)内で、ローカルパスに エビデンス を付加する場合があります。

phProcess が NULL でない場合、IAttachmentExecute::Execute は同期プロセスとして動作し、利用可能であれば HPROCESS を返します。phProcess が NULL の場合、IAttachmentExecute::Execute は非同期プロセスとして動作します。これは、呼び出し側アプリケーションがメッセージポンプと長寿命のウィンドウを持っていることを意味します。

メソッドが戻ったときに phProcess が指すハンドルが NULL 以外である場合、呼び出し側アプリケーションは、ハンドルが不要になった時点で CloseHandle を呼び出してハンドルを解放する責任があります。

保存アクションが失敗した場合に、説明のためのエラー UI をユーザーに表示します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

IAttachmentExecute::SaveWithUI は IAttachmentExecute::Prompt を呼び出しません。

IAttachmentExecute::SaveWithUI を呼び出す前に、有効なパスを指定して IAttachmentExecute::SetLocalPath を呼び出す必要があります。IAttachmentExecute::SaveWithUI を呼び出す前に、ファイルをそのローカルパスにコピーしておきます。

IAttachmentExecute::SaveWithUI は、ファイルを保存する前に、ウイルススキャナーやその他の信頼サービスを実行してファイルを検証する場合があります。これらのサービスがファイルを削除または変更する可能性があることに注意してください。

IAttachmentExecute::SaveWithUI は、NTFS の代替データストリーム(ADS)内で、ローカルパスに エビデンス を付加する場合があります。

クライアントの GUID に基づいて格納された状態を削除します。例としては、特定のファイル種別に対してプロンプトを再表示しないことを示すチェックボックスに基づく設定などが挙げられます。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

IAttachmentExecute::ClearClientState を使用する前に、IAttachmentExecute::SetClientGuid を呼び出す必要があります。