IAttachmentExecute interface

Exposes methods that work with client applications to present a user environment that provides safe download and exchange of files through email and messaging attachments.

Methods

The IAttachmentExecute interface has these methods.

Method Description
IAttachmentExecute::CheckPolicy Provides a Boolean test that can be used to make decisions based on the attachment's execution policy.
IAttachmentExecute::ClearClientState Removes any stored state that is based on the client's GUID. An example might be a setting based on a checked box that indicates a prompt should not be displayed again for a particular file type.
IAttachmentExecute::Execute Executes an action on an attachment.
IAttachmentExecute::Prompt Presents a prompt UI to the user.
IAttachmentExecute::Save Saves the attachment.
IAttachmentExecute::SaveWithUI Presents the user with explanatory error UI if the save action fails.
IAttachmentExecute::SetClientGuid Specifies and stores the GUID for the client.
IAttachmentExecute::SetClientTitle Specifies and stores the title of the prompt window.
IAttachmentExecute::SetFileName Specifies and stores the proposed name of the file.
IAttachmentExecute::SetLocalPath Sets and stores the path to the file.
IAttachmentExecute::SetReferrer Sets the security zone associated with the attachment file based on the referring file.
IAttachmentExecute::SetSource Sets an alternate path or URL for the source of a file transfer.

Remarks

This interface assumes the following:

  • The client has policies or settings for attachment support and behavior.
  • The client interacts with the user.
The IID for this interface is IID_IAttachmentExecute.

Here is an example of how an email client might use 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;

}

Requirements

   
Windows version Windows XP with SP2 [desktop apps only] Windows Server 2003 [desktop apps only]
Target Platform Windows
Header shobjidl_core.h