using System;
using System.Runtime.InteropServices;
namespace Vanara.PInvoke
{
public static partial class Shell32
{
///
/// Provides a set of flags to be used with IAttachmentExecute::Prompt to indicate the action to be performed upon user confirmation.
///
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/ne-shobjidl_core-attachment_action typedef enum
// ATTACHMENT_ACTION { ATTACHMENT_ACTION_CANCEL, ATTACHMENT_ACTION_SAVE, ATTACHMENT_ACTION_EXEC } ;
[PInvokeData("shobjidl_core.h", MSDNShortId = "NE:shobjidl_core.ATTACHMENT_ACTION")]
public enum ATTACHMENT_ACTION
{
/// Cancel
ATTACHMENT_ACTION_CANCEL,
/// Save
ATTACHMENT_ACTION_SAVE,
/// Execute
ATTACHMENT_ACTION_EXEC,
}
/// Provides a set of flags to be used with IAttachmentExecute::Prompt to indicate the type of prompt UI to display.
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/ne-shobjidl_core-attachment_prompt typedef enum
// ATTACHMENT_PROMPT { ATTACHMENT_PROMPT_NONE, ATTACHMENT_PROMPT_SAVE, ATTACHMENT_PROMPT_EXEC, ATTACHMENT_PROMPT_EXEC_OR_SAVE } ;
[PInvokeData("shobjidl_core.h", MSDNShortId = "NE:shobjidl_core.ATTACHMENT_PROMPT")]
public enum ATTACHMENT_PROMPT
{
/// Do not use.
ATTACHMENT_PROMPT_NONE,
/// Displays a prompt asking whether the user would like to save the attachment.
ATTACHMENT_PROMPT_SAVE,
/// Displays a prompt asking whether the user would like to execute the attachment.
ATTACHMENT_PROMPT_EXEC,
/// Displays a prompt giving the user a choice of executing or saving the attachment.
ATTACHMENT_PROMPT_EXEC_OR_SAVE,
}
///
/// 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.
///
///
/// 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.
///
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nn-shobjidl_core-iattachmentexecute
[PInvokeData("shobjidl_core.h", MSDNShortId = "NN:shobjidl_core.IAttachmentExecute")]
[ComImport, Guid("73db1241-1e85-4581-8e4f-a81e1d0f8c57"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), CoClass(typeof(AttachmentServices))]
public interface IAttachmentExecute
{
/// Specifies and stores the title of the prompt window.
///
/// Type: LPCWSTR
/// A pointer to a string that contains the title text.
///
///
/// If IAttachmentExecute::SetClientTitle is not called, a default title of File Download is used in the prompt's
/// title bar.
///
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-iattachmentexecute-setclienttitle HRESULT
// SetClientTitle( LPCWSTR pszTitle );
void SetClientTitle([MarshalAs(UnmanagedType.LPWStr)] string pszTitle);
/// Specifies and stores the GUID for the client.
///
/// Type: REFGUID
/// The GUID that represents the client.
///
///
/// A user can choose not to display certain prompts. That information is stored in the registry on a per-client basis, indexed
/// by guid.
///
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-iattachmentexecute-setclientguid HRESULT
// SetClientGuid( REFGUID guid );
void SetClientGuid(in Guid guid);
/// Sets and stores the path to the file.
///
/// Type: LPCWSTR
/// A pointer to a string that contains the local path where the attachment file is to be stored.
///
///
/// Calling IAttachmentExecute::SetLocalPath is required.
///
/// When the attachment is approved for execution by the user (either through policy or prompt), the path specified by this
/// method is used. If only IAttachmentExecute::SetFileName was called before calling IAttachmentExecute::CheckPolicy and
/// IAttachmentExecute::Prompt, that trust could be revoked if the assumed local path was different from that set by
/// IAttachmentExecute::SetLocalPath. Trust can be granted by various Zone APIs, antivirus services, file type
/// information, policies as well as other system trust providers.
///
/// IAttachmentExecute::SetLocalPath must be called before calling IAttachmentExecute::Execute.
///
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-iattachmentexecute-setlocalpath HRESULT
// SetLocalPath( LPCWSTR pszLocalPath );
void SetLocalPath([MarshalAs(UnmanagedType.LPWStr)] string pszLocalPath);
/// Specifies and stores the proposed name of the file.
///
/// Type: LPCWSTR
/// A pointer to a string that contains the file name.
///
///
/// No path information should be included at pszFileName, just the file's name.
///
/// IAttachmentExecute::SetFileName can be used by the calling application to check the validity of the file name before
/// copying the file locally. The file name is checked for name collisions against other files stored at the local path location.
///
/// IAttachmentExecute::SetFileName is optional.
///
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-iattachmentexecute-setfilename HRESULT
// SetFileName( LPCWSTR pszFileName );
void SetFileName([MarshalAs(UnmanagedType.LPWStr)] string pszFileName);
/// Sets an alternate path or URL for the source of a file transfer.
///
/// Type: LPCWSTR
/// A pointer to a string containing the path or URL to use as the source.
///
///
///
/// The path or URL declared here is used as the primary zone determinant. The policy under which the attachment is handled is
/// based partially on the perceived zone. If pszSource is NULL, the default is Restricted Zone.
///
/// Calling IAttachmentExecute::SetSource is optional.
/// The path or URL declared here can also be used in the prompt UI as the From field.
/// The path or URL declared here can also be sent to handlers that can process URLs.
///
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-iattachmentexecute-setsource HRESULT
// SetSource( LPCWSTR pszSource );
void SetSource([MarshalAs(UnmanagedType.LPWStr)] string pszSource);
/// Sets the security zone associated with the attachment file based on the referring file.
///
/// Type: LPCWSTR
/// A pointer to a string containing the path of the referring file.
///
///
///
/// IAttachmentExecute::SetReferrer and IAttachmentExecute::SetSource have similar functionality. If both are set, the
/// least-trusted zone of the two is used.
///
///
/// IAttachmentExecute::SetReferrer is used by container files to indicate indirect inheritance and avoid zone elevation.
/// It can also be used with shortcut files to limit elevation based on parameters.
///
/// Calling IAttachmentExecute::SetReferrer is optional.
/// IAttachmentExecute::SetReferrer is only used to determine the security zone and its associated policies.
///
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-iattachmentexecute-setreferrer HRESULT
// SetReferrer( LPCWSTR pszReferrer );
void SetReferrer([MarshalAs(UnmanagedType.LPWStr)] string pszReferrer);
/// Provides a Boolean test that can be used to make decisions based on the attachment's execution policy.
///
/// Type: HRESULT
/// Returns one of the following values.
///
///
/// Value
/// Meaning
///
/// -
/// S_OK
/// Enable
///
/// -
/// S_FALSE
/// Prompt
///
/// -
/// Any other failure code
/// Disable
///
///
///
///
///
/// IAttachmentExecute::CheckPolicy examines a set of properties known collectively as evidence. Anything used to
/// determine trust level is considered evidence. These properties are set using the following methods.
///
///
/// -
/// IAttachmentExecute::SetFileName
///
/// -
/// IAttachmentExecute::SetLocalPath
///
/// -
/// IAttachmentExecute::SetReferrer
///
/// -
/// IAttachmentExecute::SetSource
///
///
///
/// The information returned by IAttachmentExecute::CheckPolicy enables an application to modify its UI appropriately for
/// the situation.
///
///
/// IAttachmentExecute::CheckPolicy requires the application first to call either IAttachmentExecute::SetFileName or IAttachmentExecute::SetLocalPath.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-iattachmentexecute-checkpolicy HRESULT CheckPolicy();
[PreserveSig]
HRESULT CheckPolicy();
/// Presents a prompt UI to the user.
///
/// Type: HWND
/// A handle to the parent window.
///
///
/// Type: ATTACHMENT_PROMPT
/// A member of the ATTACHMENT_PROMPT enumeration that indicates what type of prompt UI to display to the user.
///
///
/// Type: ATTACHMENT_ACTION*
/// A member of the ATTACHMENT_ACTION enumeration that indicates the action to be performed upon user confirmation.
///
///
/// You must call IAttachmentExecute::SetFileName or IAttachmentExecute::SetLocalPath before calling IAttachmentExecute::Prompt.
///
/// IAttachmentExecute::Prompt can be called by the application to force UI presentation before the file has been copied
/// to disk.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-iattachmentexecute-prompt HRESULT Prompt(
// HWND hwnd, ATTACHMENT_PROMPT prompt, ATTACHMENT_ACTION *paction );
void Prompt([In] HWND hwnd, [In] ATTACHMENT_PROMPT prompt, out ATTACHMENT_ACTION paction);
/// Saves the attachment.
///
///
/// Before calling IAttachmentExecute::Save, you must call IAttachmentExecute::SetLocalPath with a valid path. The file
/// should be copied to that local path before IAttachmentExecute::Save is called.
///
///
/// IAttachmentExecute::Save should always be called if the local path declared in IAttachmentExecute::SetLocalPath is
/// not the path of a temporary directory.
///
///
/// IAttachmentExecute::Save may run virus scanners or other trust services to validate the file before saving it. Note
/// that these services can delete or alter the file.
///
/// IAttachmentExecute::Save may attach evidence to the local path in its NTFS alternate data stream (ADS).
///
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-iattachmentexecute-save HRESULT Save();
void Save();
/// Executes an action on an attachment.
///
/// Type: HWND
/// The handle of the parent window.
///
///
/// Type: LPCWSTR
///
/// A pointer to a null-terminated string that contains a verb specifying the action to be performed on the file. See the
/// lpOperation parameter in ShellExecute for valid strings. This value can be NULL.
///
///
///
/// Type: HANDLE*
/// A pointer to a handle to the source process, used for synchronous operation. This value can be NULL.
///
///
///
/// Before calling IAttachmentExecute::Execute, IAttachmentExecute::SetLocalPath must be called with a valid local path
/// and the file must be copied to that location.
///
///
/// If a prompt is indicated, IAttachmentExecute::Execute calls IAttachmentExecute::Prompt using the
/// ATTACHMENT_ACTION_EXEC value.
///
///
/// IAttachmentExecute::Execute may run virus scanners or other trust services to validate the file before executing it.
/// Note that these services can delete or alter the file.
///
/// IAttachmentExecute::Execute may attach evidence to the local path in its NTFS alternate data stream (ADS).
///
/// If phProcess is not NULL, IAttachmentExecute::Execute operates as a synchronous process and returns an
/// HPROCESS, if available. If phProcess is NULL, IAttachmentExecute::Execute operates as an asynchronous
/// process. This implies that the calling application has a message pump and a long-lived window.
///
///
/// If the handle pointed to by phProcess is non- NULL when the method returns, the calling application is responsible
/// for calling CloseHandle to free the handle when it is no longer needed.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-iattachmentexecute-execute HRESULT Execute(
// HWND hwnd, LPCWSTR pszVerb, HANDLE *phProcess );
void Execute([In] HWND hwnd, [Optional, MarshalAs(UnmanagedType.LPWStr)] string pszVerb, [Out, Optional] out HPROCESS phProcess);
/// Presents the user with explanatory error UI if the save action fails.
///
/// Type: HWND
/// The handle of the parent window.
///
///
/// IAttachmentExecute::SaveWithUI does not call IAttachmentExecute::Prompt.
///
/// Before calling IAttachmentExecute::SaveWithUI, you must call IAttachmentExecute::SetLocalPath with a valid path. The
/// file is copied to that local path before IAttachmentExecute::SaveWithUI is called.
///
///
/// IAttachmentExecute::SaveWithUI may run virus scanners or other trust services to validate the file before saving it.
/// Note that these services can delete or alter the file.
///
/// IAttachmentExecute::SaveWithUI may attach evidence to the local path in its NTFS alternate data stream (ADS).
///
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-iattachmentexecute-savewithui HRESULT
// SaveWithUI( HWND hwnd );
void SaveWithUI([In] HWND hwnd);
///
/// 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::SetClientGuid must be called before using IAttachmentExecute::ClearClientState.
// https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-iattachmentexecute-clearclientstate HRESULT ClearClientState();
void ClearClientState();
}
/// CLSID_AttachmentServices
[ComImport, Guid("4125dd96-e03a-4103-8f70-e0597d803b9c"), ClassInterface(ClassInterfaceType.None)]
public class AttachmentServices { }
}
}