IAttachmentExecute Interface ()

IAttachmentExecute Interface

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

IAttachmentExecute Members

CheckPolicy Provides a Boolean test that can be used to make decisions based on the attachment's execution policy.
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.
Execute Executes an action on an attachment.
Prompt Presents a prompt user interface (UI) to the user.
Save Saves the attachment.
SaveWithUI Presents the user with explanatory error UI if the save action fails.
SetClientGuid Specifies and stores the GUID for the client.
SetClientTitle Specifies and stores the title of the prompt window.
SetFileName Specifies and stores the proposed name of the file.
SetLocalPath Sets and stores the path to the file.
SetReferrer Sets the security zone associated with the attachment file based on the referring file.
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 e-mail 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 e-mail 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 e-mail 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 e-mail 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;
}

Interface Information

Minimum DLL Version shdocvw.dll
Custom Implementation No
Inherits from IUnknown
Minimum operating systems Windows XP Service Pack 2 (SP2)

Product Families

Resources

About Microsoft

Popular Places

Popular Searches

Popular Downloads

CheckPolicy	Provides a Boolean test that can be used to make decisions based on the attachment's execution policy.
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.
Execute	Executes an action on an attachment.
Prompt	Presents a prompt user interface (UI) to the user.
Save	Saves the attachment.
SaveWithUI	Presents the user with explanatory error UI if the save action fails.
SetClientGuid	Specifies and stores the GUID for the client.
SetClientTitle	Specifies and stores the title of the prompt window.
SetFileName	Specifies and stores the proposed name of the file.
SetLocalPath	Sets and stores the path to the file.
SetReferrer	Sets the security zone associated with the attachment file based on the referring file.
SetSource	Sets an alternate path or URL for the source of a file transfer.

Minimum DLL Version	shdocvw.dll
Custom Implementation	No
Inherits from	IUnknown
Minimum operating systems	Windows XP Service Pack 2 (SP2)