diff --git a/PInvoke/BITS/bits.cs b/PInvoke/BITS/bits.cs index a926d676..1cdbdb6a 100644 --- a/PInvoke/BITS/bits.cs +++ b/PInvoke/BITS/bits.cs @@ -1603,7 +1603,7 @@ namespace Vanara.PInvoke /// /// An IBackgroundCopyCallback interface pointer. To remove the current callback interface pointer, set this parameter to NULL. /// - void SetNotifyInterface([In, MarshalAs(UnmanagedType.IUnknown)] object pNotifyInterface); + void SetNotifyInterface(IBackgroundCopyCallback pNotifyInterface); /// Retrieves the interface pointer to your implementation of the IBackgroundCopyCallback interface. /// Interface pointer to your implementation of the IBackgroundCopyCallback interface. When done, release ppNotifyInterface. @@ -1873,7 +1873,7 @@ namespace Vanara.PInvoke /// /// An IBackgroundCopyCallback interface pointer. To remove the current callback interface pointer, set this parameter to NULL. /// - new void SetNotifyInterface([In, MarshalAs(UnmanagedType.IUnknown)] object pNotifyInterface); + new void SetNotifyInterface(IBackgroundCopyCallback pNotifyInterface); /// Retrieves the interface pointer to your implementation of the IBackgroundCopyCallback interface. /// Interface pointer to your implementation of the IBackgroundCopyCallback interface. When done, release ppNotifyInterface. @@ -2233,7 +2233,7 @@ namespace Vanara.PInvoke /// /// An IBackgroundCopyCallback interface pointer. To remove the current callback interface pointer, set this parameter to NULL. /// - new void SetNotifyInterface([In, MarshalAs(UnmanagedType.IUnknown)] object pNotifyInterface); + new void SetNotifyInterface(IBackgroundCopyCallback pNotifyInterface); /// Retrieves the interface pointer to your implementation of the IBackgroundCopyCallback interface. /// Interface pointer to your implementation of the IBackgroundCopyCallback interface. When done, release ppNotifyInterface. @@ -2625,7 +2625,7 @@ namespace Vanara.PInvoke /// /// An IBackgroundCopyCallback interface pointer. To remove the current callback interface pointer, set this parameter to NULL. /// - new void SetNotifyInterface([In, MarshalAs(UnmanagedType.IUnknown)] object pNotifyInterface); + new void SetNotifyInterface(IBackgroundCopyCallback pNotifyInterface); /// Retrieves the interface pointer to your implementation of the IBackgroundCopyCallback interface. /// Interface pointer to your implementation of the IBackgroundCopyCallback interface. When done, release ppNotifyInterface. @@ -3060,7 +3060,7 @@ namespace Vanara.PInvoke /// /// An IBackgroundCopyCallback interface pointer. To remove the current callback interface pointer, set this parameter to NULL. /// - new void SetNotifyInterface([In, MarshalAs(UnmanagedType.IUnknown)] object pNotifyInterface); + new void SetNotifyInterface(IBackgroundCopyCallback pNotifyInterface); /// Retrieves the interface pointer to your implementation of the IBackgroundCopyCallback interface. /// Interface pointer to your implementation of the IBackgroundCopyCallback interface. When done, release ppNotifyInterface. @@ -3343,6 +3343,517 @@ namespace Vanara.PInvoke BITS_JOB_PROPERTY_VALUE GetProperty(BITS_JOB_PROPERTY_ID PropertyId); } + /// + /// Use this interface to query or set several optional behaviors of a job. + /// To get this interface, call the IBackgroundCopyJob::QueryInterface method using as the interface identifier. + /// + /// + // https://msdn.microsoft.com/en-us/library/windows/desktop/hh446781(v=vs.85).aspx + [PInvokeData("Bits5_0.h", MSDNShortId = "hh446781", MinClient = PInvokeClient.Windows10)] + [ComImport, Guid("CF6784F7-D677-49FD-9368-CB47AEE9D1AD"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IBackgroundCopyJob6 : IBackgroundCopyJob5 + { + /// Adds multiple files to a job. + /// Number of elements in paFileSet. + /// + /// Array of BG_FILE_INFO structures that identify the local and remote file names of the files to transfer. + /// + /// Upload jobs are restricted to a single file.If the array contains more than one element, or the job already contains a file, + /// the method returns BG_E_TOO_MANY_FILES. + /// + /// + new void AddFileSet([In] uint cFileCount, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] BG_FILE_INFO[] pFileSet); + + /// Adds a single file to the job. + /// + /// Null-terminated string that contains the name of the file on the server. For information on specifying the remote name, see + /// the RemoteName member and Remarks section of the BG_FILE_INFO structure. + /// + /// + /// Null-terminated string that contains the name of the file on the client. For information on specifying the local name, see + /// the LocalName member and Remarks section of the BG_FILE_INFO structure. + /// + new void AddFile([In, MarshalAs(UnmanagedType.LPWStr)] string RemoteUrl, [In, MarshalAs(UnmanagedType.LPWStr)] string LocalName); + + /// Retrieves an IEnumBackgroundCopyFiles interface pointer that you use to enumerate the files in a job. + /// + /// IEnumBackgroundCopyFiles interface pointer that you use to enumerate the files in the job. Release ppEnumFiles when done. + /// + new IEnumBackgroundCopyFiles EnumFiles(); + + /// + /// Suspends a job. New jobs, jobs that are in error, and jobs that have finished transferring files are automatically suspended. + /// + new void Suspend(); + + /// Activates a new job or restarts a job that has been suspended. + new void Resume(); + + /// + /// Deletes the job from the transfer queue and removes related temporary files from the client (downloads) and server (uploads). + /// + new void Cancel(); + + /// Ends the job and saves the transferred files on the client. + new void Complete(); + + /// Retrieves the identifier used to identify the job in the queue. + /// GUID that identifies the job within the BITS queue. + new Guid GetId(); + + /// Retrieves the type of transfer being performed, such as a file download or upload. + /// Type of transfer being performed. For a list of transfer types, see the BG_JOB_TYPE enumeration. + new BG_JOB_TYPE GetType(); + + /// Retrieves job-related progress information, such as the number of bytes and files transferred. + /// + /// Contains data that you can use to calculate the percentage of the job that is complete. For more information, see BG_JOB_PROGRESS. + /// + new BG_JOB_PROGRESS GetProgress(); + + /// Retrieves job-related time stamps, such as the time that the job was created or last modified. + /// Contains job-related time stamps. For available time stamps, see the BG_JOB_TIMES structure. + new BG_JOB_TIMES GetTimes(); + + /// Retrieves the state of the job. + /// + /// The state of the job. For example, the state reflects whether the job is in error, transferring data, or suspended. For a + /// list of job states, see the BG_JOB_STATE enumeration. + /// + new BG_JOB_STATE GetState(); + + /// + /// Retrieves the error interface after an error occurs. + /// + /// BITS generates an error object when the state of the job is BG_JOB_STATE_ERROR or BG_JOB_STATE_TRANSIENT_ERROR.The service + /// does not create an error object when a call to an IBackgroundCopyXXXX interface method fails.The error object is available + /// until BITS begins transferring data(the state of the job changes to BG_JOB_STATE_TRANSFERRING) for the job or until your + /// application exits. + /// + /// + /// + /// Error interface that provides the error code, a description of the error, and the context in which the error occurred. This + /// parameter also identifies the file being transferred at the time the error occurred. Release ppError when done. + /// + [return: MarshalAs(UnmanagedType.Interface)] + new IBackgroundCopyError GetError(); + + /// Retrieves the identity of the job's owner. + /// + /// Null-terminated string that contains the string version of the SID that identifies the job's owner. Call the CoTaskMemFree + /// function to free ppOwner when done. + /// + [return: MarshalAs(UnmanagedType.LPWStr)] + new string GetOwner(); + + /// Specifies a display name for the job. Typically, you use the display name to identify the job in a user interface. + /// + /// Null-terminated string that identifies the job. Must not be NULL. The length of the string is limited to 256 characters, not + /// including the null terminator. + /// + new void SetDisplayName([In, MarshalAs(UnmanagedType.LPWStr)] string pDisplayName); + + /// Retrieves the display name for the job. Typically, you use the display name to identify the job in a user interface. + /// + /// Null-terminated string that contains the display name that identifies the job. More than one job can have the same display + /// name. Call the CoTaskMemFree function to free ppDisplayName when done. + /// + [return: MarshalAs(UnmanagedType.LPWStr)] + new string GetDisplayName(); + + /// Provides a description of the job. + /// + /// Null-terminated string that provides additional information about the job. The length of the string is limited to 1,024 + /// characters, not including the null terminator. + /// + new void SetDescription([In, MarshalAs(UnmanagedType.LPWStr)] string pDescription); + + /// Retrieves the description of the job. + /// + /// Null-terminated string that contains a short description of the job. Call the CoTaskMemFree function to free ppDescription + /// when done. + /// + [return: MarshalAs(UnmanagedType.LPWStr)] + new string GetDescription(); + + /// + /// Specifies the priority level of your job. The priority level determines when your job is processed relative to other jobs in + /// the transfer queue. + /// + /// + /// Specifies the priority level of your job relative to other jobs in the transfer queue. The default is BG_JOB_PRIORITY_NORMAL. + /// For a list of priority levels, see the BG_JOB_PRIORITY enumeration. + /// + new void SetPriority(BG_JOB_PRIORITY Priority); + + /// + /// Retrieves the priority level for the job. The priority level determines when the job is processed relative to other jobs in + /// the transfer queue. + /// + /// Priority of the job relative to other jobs in the transfer queue. + new BG_JOB_PRIORITY GetPriority(); + + /// Specifies the type of event notification you want to receive, such as job transferred events. + /// Set one or more of the following flags to identify the events that you want to receive. + new void SetNotifyFlags([In] BG_NOTIFY NotifyFlags); + + /// Retrieves the event notification flags for the job. + /// Identifies the events that your application receives. + new BG_NOTIFY GetNotifyFlags(); + + /// + /// Identifies your implementation of the IBackgroundCopyCallback interface to BITS. Use the IBackgroundCopyCallback interface to + /// receive notification of job-related events. + /// + /// + /// An IBackgroundCopyCallback interface pointer. To remove the current callback interface pointer, set this parameter to NULL. + /// + new void SetNotifyInterface(IBackgroundCopyCallback pNotifyInterface); + + /// Retrieves the interface pointer to your implementation of the IBackgroundCopyCallback interface. + /// Interface pointer to your implementation of the IBackgroundCopyCallback interface. When done, release ppNotifyInterface. + [return: MarshalAs(UnmanagedType.IUnknown)] + new object GetNotifyInterface(); + + /// + /// Sets the minimum length of time that BITS waits after encountering a transient error condition before trying to transfer the file. + /// + /// + /// Minimum length of time, in seconds, that BITS waits after encountering a transient error before trying to transfer the file. + /// The default retry delay is 600 seconds (10 minutes). The minimum retry delay that you can specify is 5 seconds. If you + /// specify a value less than 5 seconds, BITS changes the value to 5 seconds. If the value exceeds the no-progress-timeout value + /// retrieved from the GetNoProgressTimeout method, BITS will not retry the transfer and moves the job to the BG_JOB_STATE_ERROR state. + /// + new void SetMinimumRetryDelay([In] uint RetryDelay); + + /// + /// Retrieves the minimum length of time that the service waits after encountering a transient error condition before trying to + /// transfer the file. + /// + /// + /// Length of time, in seconds, that the service waits after encountering a transient error before trying to transfer the file. + /// + new uint GetMinimumRetryDelay(); + + /// + /// Sets the length of time that BITS tries to transfer the file after a transient error condition occurs. If there is progress, + /// the timer is reset. + /// + /// + /// Length of time, in seconds, that BITS tries to transfer the file after the first transient error occurs. The default retry + /// period is 1,209,600 seconds (14 days). Set the retry period to 0 to prevent retries and to force the job into the + /// BG_JOB_STATE_ERROR state for all errors. If the retry period value exceeds the JobInactivityTimeout Group Policy value + /// (90-day default), BITS cancels the job after the policy value is exceeded. + /// + new void SetNoProgressTimeout([In] uint RetryPeriod); + + /// + /// Retrieves the length of time that the service tries to transfer the file after a transient error condition occurs. If there + /// is progress, the timer is reset. + /// + /// Length of time, in seconds, that the service tries to transfer the file after a transient error occurs. + new uint GetNoProgressTimeout(); + + /// Retrieves the number of times BITS tried to transfer the job and an error occurred. + /// + /// Number of errors that occurred while BITS tried to transfer the job. The count increases when the job moves from the + /// BG_JOB_STATE_TRANSFERRING state to the BG_JOB_STATE_TRANSIENT_ERROR or BG_JOB_STATE_ERROR state. + /// + new uint GetErrorCount(); + + /// Specifies which proxy to use to transfer files. + /// + /// Specifies whether to use the user's proxy settings, not to use a proxy, or to use application-specified proxy settings. The + /// default is to use the user's proxy settings, BG_JOB_PROXY_USAGE_PRECONFIG. For a list of proxy options, see the + /// BG_JOB_PROXY_USAGE enumeration. + /// + /// + /// Null-terminated string that contains the proxies to use to transfer files. The list is space-delimited. For details on + /// specifying a proxy, see Remarks. + /// + /// This parameter must be NULL if the value of ProxyUsage is BG_JOB_PROXY_USAGE_PRECONFIG, BG_JOB_PROXY_USAGE_NO_PROXY, or BG_JOB_PROXY_USAGE_AUTODETECT. + /// + /// The length of the proxy list is limited to 4,000 characters, not including the null terminator. + /// + /// + /// Null-terminated string that contains an optional list of host names, IP addresses, or both, that can bypass the proxy. The + /// list is space-delimited. For details on specifying a bypass proxy, see Remarks. + /// + /// This parameter must be NULL if the value of ProxyUsage is BG_JOB_PROXY_USAGE_PRECONFIG, BG_JOB_PROXY_USAGE_NO_PROXY, or BG_JOB_PROXY_USAGE_AUTODETECT. + /// + /// The length of the proxy list is limited to 4,000 characters, not including the null terminator. + /// + new void SetProxySettings([In] BG_JOB_PROXY_USAGE ProxyUsage, [In, MarshalAs(UnmanagedType.LPWStr)] string ProxyList, [In, MarshalAs(UnmanagedType.LPWStr)] string ProxyBypassList); + + /// Retrieves the proxy information that the job uses to transfer the files. + /// + /// Specifies the proxy settings the job uses to transfer the files. For a list of proxy options, see the BG_JOB_PROXY_USAGE enumeration. + /// + /// + /// Null-terminated string that contains one or more proxies to use to transfer files. The list is space-delimited. For details + /// on the format of the string, see the Listing Proxy Servers section of Enabling Internet Functionality. Call the CoTaskMemFree + /// function to free ppProxyList when done. + /// + /// + /// Null-terminated string that contains an optional list of host names or IP addresses, or both, that were not routed through + /// the proxy. The list is space-delimited. For details on the format of the string, see the Listing the Proxy Bypass section of + /// Enabling Internet Functionality. Call the CoTaskMemFree function to free ppProxyBypassList when done. + /// + new void GetProxySettings(out BG_JOB_PROXY_USAGE pProxyUsage, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string pProxyList, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string pProxyBypassList); + + /// Changes ownership of the job to the current user. + new void TakeOwnership(); + + /// + /// Specifies a program to execute if the job enters the BG_JOB_STATE_ERROR or BG_JOB_STATE_TRANSFERRED state. BITS executes the + /// program in the context of the user who called this method. + /// + /// + /// Null-terminated string that contains the program to execute. The pProgram parameter is limited to MAX_PATH characters, not + /// including the null terminator. You should specify a full path to the program; the method will not use the search path to + /// locate the program. + /// + /// To remove command line notification, set pProgram and pParameters to NULL. The method fails if pProgram is NULL and + /// pParameters is non-NULL. + /// + /// + /// + /// Null-terminated string that contains the parameters of the program in pProgram. The first parameter must be the program in + /// pProgram (use quotes if the path uses long file names). The pParameters parameter is limited to 4,000 characters, not + /// including the null terminator. This parameter can be NULL. + /// + new void SetNotifyCmdLine([In, MarshalAs(UnmanagedType.LPWStr)] string Program, [In, MarshalAs(UnmanagedType.LPWStr)] string Parameters); + + /// Retrieves the program to execute when the job enters the error or transferred state. + /// + /// Null-terminated string that contains the program to execute when the job enters the error or transferred state. Call the + /// CoTaskMemFree function to free pProgram when done. + /// + /// + /// Null-terminated string that contains the arguments of the program in pProgram. Call the CoTaskMemFree function to free + /// pParameters when done. + /// + new void GetNotifyCmdLine([MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string pProgram, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string pParameters); + + /// Retrieves progress information related to the transfer of the reply data from an upload-reply job. + /// + /// Contains information that you use to calculate the percentage of the reply file transfer that is complete. For more + /// information, see BG_JOB_REPLY_PROGRESS. + /// + new BG_JOB_REPLY_PROGRESS GetReplyProgress(); + + /// + /// Retrieves an in-memory copy of the reply data from the server application. Call this method only if the job's type is + /// BG_JOB_TYPE_UPLOAD_REPLY and its state is BG_JOB_STATE_TRANSFERRED. + /// + /// + /// Buffer to contain the reply data. The method sets ppBuffer to NULL if the server application did not return a reply. Call the + /// CoTaskMemFree function to free ppBuffer when done. + /// + /// Size, in bytes, of the reply data in ppBuffer. + new void GetReplyData(out SafeCoTaskMemHandle ppBuffer, out ulong pLength); + + /// + /// Specifies the name of the file to contain the reply data from the server application. Call this method only if the job's type + /// is BG_JOB_TYPE_UPLOAD_REPLY. + /// + /// + /// Null-terminated string that contains the full path to the reply file. BITS generates the file name if ReplyFileNamePathSpec + /// is NULL or an empty string. You cannot use wildcards in the path or file name, and directories in the path must exist. The + /// path is limited to MAX_PATH, not including the null terminator. The user must have permissions to write to the directory. + /// BITS does not support NTFS streams. Instead of using network drives, which are session specific, use UNC paths (for example, + /// \\server\share\path\file). Do not include the \\? prefix in the path. + /// + new void SetReplyFileName([In, MarshalAs(UnmanagedType.LPWStr)] string ReplyFileName); + + /// + /// Retrieves the name of the file that contains the reply data from the server application. Call this method only if the job + /// type is BG_JOB_TYPE_UPLOAD_REPLY. + /// + /// + /// Null-terminated string that contains the full path to the reply file. Call the CoTaskMemFree function to free pReplyFileName + /// when done. + /// + [return: MarshalAs(UnmanagedType.LPWStr)] + new string GetReplyFileName(); + + /// Specifies the credentials to use for a proxy or remote server user authentication request. + /// + /// Identifies the target (proxy or server), authentication scheme, and the user's credentials to use for user authentication. + /// For details, see the BG_AUTH_CREDENTIALS structure. + /// + new void SetCredentials(ref BG_AUTH_CREDENTIALS Credentials); + + /// + /// Removes credentials from use. The credentials must match an existing target and scheme pair that you specified using the + /// IBackgroundCopyJob2::SetCredentials method. There is no method to retrieve the credentials you have set. + /// + /// Identifies whether to use the credentials for proxy or server authentication. + /// + /// Identifies the authentication scheme to use (basic or one of several challenge-response schemes). For details, see the + /// BG_AUTH_SCHEME enumeration. + /// + new void RemoveCredentials(BG_AUTH_TARGET Target, BG_AUTH_SCHEME Scheme); + + /// Replaces the beginning text of all remote names in the download job with the specified string. + /// + /// Null-terminated string that identifies the text to replace in the remote name. The text must start at the beginning of the + /// remote name. + /// + /// Null-terminated string that contains the replacement text. + new void ReplaceRemotePrefix([In, MarshalAs(UnmanagedType.LPWStr)] string OldPrefix, [In, MarshalAs(UnmanagedType.LPWStr)] string NewPrefix); + + /// Adds a file to a download job and specifies the ranges of the file you want to download. + /// + /// Null-terminated string that contains the name of the file on the server. For information on specifying the remote name, see + /// the RemoteName member and Remarks section of the BG_FILE_INFO structure. Starting with BITS 3.0, the SMB protocol is not + /// supported for ranges. + /// BITS 2.5 and 2.0: BITS supports the SMB protocol for ranges. + /// + /// + /// Null-terminated string that contains the name of the file on the client. For information on specifying the local name, see + /// the LocalName member and Remarks section of the BG_FILE_INFO structure. + /// + /// Number of elements in Ranges. + /// + /// Array of one or more BG_FILE_RANGE structures that specify the ranges to download. Do not specify duplicate or overlapping ranges. + /// + new void AddFileWithRanges([In, MarshalAs(UnmanagedType.LPWStr)] string RemoteUrl, [In, MarshalAs(UnmanagedType.LPWStr)] string LocalName, [In] uint rangeCount, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] BG_FILE_RANGE[] ranges); + + /// Specifies the owner and ACL information to maintain when using SMB to download or upload a file. + /// + /// Flags that identify the owner and ACL information to maintain when transferring a file using SMB. Subsequent calls to this + /// method overwrite the previous flags. Specify 0 to remove the flags from the job. You can specify any combination of the + /// following flags. + /// + new void SetFileACLFlags([In] BG_COPY_FILE Flags); + + /// Retrieves the flags that identify the owner and ACL information to maintain when transferring a file using SMB. + /// + /// Flags that identify the owner and ACL information to maintain when transferring a file using SMB. Flags can contain any + /// combination of the following flags. If no flags are set, Flags is zero. + /// + new BG_COPY_FILE GetFileACLFlags(); + + /// + /// Sets flags that determine if the files of the job can be cached and served to peers and if the job can download content from peers. + /// + /// + /// Flags that determine if the files of the job can be cached and served to peers and if the job can download content from + /// peers. The following flags can be set: + /// + new void SetPeerCachingFlags(BG_JOB_ENABLE_PEERCACHING Flags); + + /// + /// Retrieves flags that determine if the files of the job can be cached and served to peers and if BITS can download content for + /// the job from peers. + /// + /// + /// Flags that determine if the files of the job can be cached and served to peers and if BITS can download content for the job + /// from peers. The following flags can be set: + /// + new BG_JOB_ENABLE_PEERCACHING GetPeerCachingFlags(); + + /// Gets the integrity level of the token of the owner that created or took ownership of the job. + /// Integrity level of the token of the owner that created or took ownership of the job. + new uint GetOwnerIntegrityLevel(); + + /// + /// Gets a value that determines if the token of the owner was elevated at the time they created or took ownership of the job. + /// + /// + /// Is TRUE if the token of the owner was elevated at the time they created or took ownership of the job; otherwise, FALSE. + /// + [return: MarshalAs(UnmanagedType.Bool)] + new bool GetOwnerElevationState(); + + /// Sets the maximum time that BITS will spend transferring the files in the job. + /// + /// Maximum time, in seconds, that BITS will spend transferring the files in the job. The default is 7,776,000 seconds (90 days). + /// + new void SetMaximumDownloadTime(uint Timeout); + + /// Retrieves the maximum time that BITS will spend transferring the files in the job. + /// Maximum time, in seconds, that BITS will spend transferring the files in the job. + new uint GetMaximumDownloadTime(); + + /// A generic method for setting BITS job properties. + /// The ID of the property that is being set specified as a BITS_JOB_PROPERTY_ID enum value. + /// + /// The value of the property that is being set. In order to hold a value whose type is appropriate to the property, this value + /// is specified via the BITS_JOB_PROPERTY_VALUE union that is composed of all the known property types. + /// + new void SetProperty(BITS_JOB_PROPERTY_ID PropertyId, BITS_JOB_PROPERTY_VALUE PropertyValue); + + /// A generic method for getting BITS job properties. + /// The ID of the property that is being obtained specified as a BITS_JOB_PROPERTY_ID enum value. + /// The property value returned as a BITS_JOB_PROPERTY_VALUE union. + new BITS_JOB_PROPERTY_VALUE GetProperty(BITS_JOB_PROPERTY_ID PropertyId); + + /// Specifies a position to prioritize downloading missing data from. + /// Specifies the new position to prioritize downloading missing data from. + /// + /// + /// UpdateDownloadPosition can be requested for any download job that also meets the requirements for + /// BITS_JOB_PROPERTY_ON_DEMAND_MODE jobs. + /// + /// + /// The requirements for a BITS_JOB_PROPERTY_ON_DEMAND_MODE job is that the transfer must be a DOWNLOAD job. The + /// job must not be DYNAMIC and the server must be an HTTP or HTTPS server and the server requirements for range support + /// must all be met. For more information, see HTTP Requirements for BITS Downloads. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/bits10_1/nf-bits10_1-ibackgroundcopyfile6-updatedownloadposition + // HRESULT UpdateDownloadPosition( [in] UINT64 offset ); + void UpdateDownloadPosition(ulong offset); + + /// Adds a new set of file ranges to be prioritized for download. + /// Specifies the size of the Ranges array. + /// + /// An array of file ranges to be downloaded. Requested ranges are allowed to overlap previously downloaded (or pending) ranges. + /// Ranges are automatically split into non-overlapping ranges. + /// + /// + /// + /// RequestFileRanges can be requested for any download job that also meets the requirements for + /// BITS_JOB_PROPERTY_ON_DEMAND_MODE jobs. + /// + /// + /// The requirements for a BITS_JOB_PROPERTY_ON_DEMAND_MODE job is that the transfer must be a DOWNLOAD job. The + /// job must not be DYNAMIC and the server must be an HTTP or HTTPS server and the server requirements for range support + /// must all be met. For more information, see HTTP Requirements for BITS Downloads. + /// + /// + /// When all of the requested ranges have been downloaded the job state will be set to BG_JOB_STATE_TRANSFERRED if all of + /// the bytes of the file have been transferred. Otherwise, the job state will be set to BG_JOB_STATE_SUSPENDED. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/bits10_1/nf-bits10_1-ibackgroundcopyfile6-requestfileranges + // HRESULT RequestFileRanges( [in] DWORD rangeCount, [in] const BG_FILE_RANGE [] ranges ); + void RequestFileRanges(uint rangeCount, [In, MarshalAs(UnmanagedType.LPArray)] BG_FILE_RANGE[] ranges); + + /// Returns the set of file ranges that have been downloaded. + /// The number of elements in Ranges. + /// + /// Array of BG_FILE_RANGE structures that describes the ranges that have been downloaded. Ranges will be merged together + /// as much as possible. The ranges are ordered by offset. When done, call the CoTaskMemFree function to free Ranges. + /// + /// + /// + /// GetFilledFileRanges can be requested for any download job that also meets the requirements for + /// BITS_JOB_PROPERTY_ON_DEMAND_MODE jobs. + /// + /// + /// The requirements for a BITS_JOB_PROPERTY_ON_DEMAND_MODE job is that the transfer must be a DOWNLOAD job. The + /// job must not be DYNAMIC and the server must be an HTTP or HTTPS server and the server requirements for range support + /// must all be met. For more information, see HTTP Requirements for BITS Downloads. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/bits10_1/nf-bits10_1-ibackgroundcopyfile6-getfilledfileranges + // HRESULT GetFilledFileRanges( [out] DWORD *rangeCount, [out] BG_FILE_RANGE **ranges ); + void GetFilledFileRanges(out uint rangeCount, out SafeCoTaskMemHandle ranges); + } + /// /// /// Use this interface to specify client certificates for certificate-based client authentication and custom headers for HTTP requests. @@ -3499,6 +4010,454 @@ namespace Vanara.PInvoke BG_HTTP_SECURITY GetSecurityFlags(); } + /// + /// Use this interface to retrieve and/or to override the HTTP method used for a BITS transfer. + /// To get this interface, call the IBackgroundCopyJob::QueryInterface method using __uuidof(IBackgroundCopyJobHttpOptions2) for the interface identifier. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/bits10_2/nn-bits10_2-ibackgroundcopyjobhttpoptions2 + [PInvokeData("bits10_2.h", MSDNShortId = "NN:bits10_2.IBackgroundCopyJobHttpOptions2")] + [ComImport, Guid("B591A192-A405-4FC3-8323-4C5C542578FC"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), ComConversionLoss] + public interface IBackgroundCopyJobHttpOptions2 : IBackgroundCopyJobHttpOptions + { + /// Specifies the identifier of the client certificate to use for client authentication in an HTTPS (SSL) request. + /// + /// Identifies the location of a system store to use for looking up the certificate. For possible values, see the + /// BG_CERT_STORE_LOCATION enumeration. + /// + /// + /// Null-terminated string that contains the name of the certificate store. The string is limited to 256 characters, including + /// the null terminator. You can specify one of the following system stores or an application-defined store. The store can be a + /// local or remote store. + /// + /// + /// Value + /// Meaning + /// + /// + /// CA + /// Certification authority certificates + /// + /// + /// MY + /// Personal certificates + /// + /// + /// ROOT + /// Root certificates + /// + /// + /// SPC + /// Software Publisher Certificate + /// + /// + /// + /// + /// SHA1 hash that identifies the certificate. Use a 20 byte buffer for the hash. For more information, see Remarks. + /// + new void SetClientCertificateByID(BG_CERT_STORE_LOCATION StoreLocation, [In, MarshalAs(UnmanagedType.LPWStr)] string StoreName, [In, MarshalAs(UnmanagedType.LPArray, SizeConst = 20)] byte[] pCertHashBlob); + + /// Specifies the subject name of the client certificate to use for client authentication in an HTTPS (SSL) request. + /// + /// Identifies the location of a system store to use for looking up the certificate. For possible values, see the + /// BG_CERT_STORE_LOCATION enumeration. + /// + /// + /// Null-terminated string that contains the name of the certificate store. The string is limited to 256 characters, including + /// the null terminator. You can specify one of the following system stores or an application-defined store. The store can be a + /// local or remote store. + /// + /// + /// Value + /// Meaning + /// + /// + /// CA + /// Certification authority certificates + /// + /// + /// MY + /// Personal certificates + /// + /// + /// ROOT + /// Root certificates + /// + /// + /// SPC + /// Software Publisher Certificate + /// + /// + /// + /// + /// Null-terminated string that contains the simple subject name of the certificate. If the subject name contains multiple + /// relative distinguished names (RDNs), you can specify one or more adjacent RDNs. If you specify more than one RDN, the list is + /// comma-delimited. The string is limited to 256 characters, including the null terminator. You cannot specify an empty subject name. + /// + /// Do not include the object identifier in the name.You must specify the RDNs in the reverse order from what the certificate + /// displays. For example, if the subject name in the certificate is "CN=name1, OU=name2, O=name3", specify the subject name as + /// "name3, name2, name1". + /// + /// + new void SetClientCertificateByName(BG_CERT_STORE_LOCATION StoreLocation, [In, MarshalAs(UnmanagedType.LPWStr)] string StoreName, [In, MarshalAs(UnmanagedType.LPWStr)] string SubjectName); + + /// Removes the client certificate from the job. + new void RemoveClientCertificate(); + + /// Retrieves the client certificate from the job. + /// + /// Identifies the location of a system store to use for looking up the certificate. For possible values, see the + /// BG_CERT_STORE_LOCATION enumeration. + /// + /// + /// Null-terminated string that contains the name of the certificate store. To free the string when done, call the CoTaskMemFree function. + /// + /// + /// SHA1 hash that identifies the certificate. To free the blob when done, call the CoTaskMemFree function. + /// + /// + /// Null-terminated string that contains the simple subject name of the certificate. The RDNs in the subject name are in the + /// reverse order from what the certificate displays. Subject name can be empty if the certificate does not contain a subject + /// name. To free the string when done, call the CoTaskMemFree function. + /// + new void GetClientCertificate(out BG_CERT_STORE_LOCATION pStoreLocation, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string pStoreName, out SafeCoTaskMemHandle ppCertHashBlob, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string pSubjectName); + + /// Specifies one or more custom HTTP headers to include in HTTP requests. + /// + /// Null-terminated string that contains the custom headers to append to the HTTP request. Each header must be terminated by a + /// carriage return and line feed (CR/LF) character. The string is limited to 16,384 characters, including the null terminator. + /// To remove the custom headers from the job, set the RequestHeaders parameter to NULL. + /// + new void SetCustomHeaders([In, MarshalAs(UnmanagedType.LPWStr)] string RequestHeaders); + + /// + /// Retrieves the custom headers set by an earlier call to IBackgroundCopyJobHttpOptions::SetCustomHeaders (that is, headers + /// which BITS will be sending to the remote, not headers which BITS receives from the remote). + /// + /// + /// Null-terminated string that contains the custom headers. Each header is terminated by a carriage return and line feed (CR/LF) + /// character. To free the string when finished, call the CoTaskMemFree function. + /// + [return: MarshalAs(UnmanagedType.LPWStr)] + new string GetCustomHeaders(); + + /// + /// Sets flags for HTTP that determine whether the certificate revocation list is checked and certain certificate errors are + /// ignored, and the policy to use when a server redirects the HTTP request. + /// + /// + /// HTTP security flags that indicate which errors to ignore when connecting to the server. You can set one or more of the + /// following flags: + /// + new void SetSecurityFlags([In] BG_HTTP_SECURITY Flags); + + /// + /// Retrieves the flags for HTTP that determine whether the certificate revocation list is checked and certain certificate errors + /// are ignored, and the policy to use when a server redirects the HTTP request. + /// + /// + /// HTTP security flags that indicate which errors to ignore when connecting to the server. One or more of the following flags + /// can be set: + /// + new BG_HTTP_SECURITY GetSecurityFlags(); + + /// Overrides the default HTTP method used for a BITS transfer. + /// + /// Type: LPCWSTR + /// A pointer to a constant null-terminated string of wide characters containing the HTTP method name. + /// + /// + /// + /// BITS allows you, as the developer, to choose an HTTP method other than the default method. This increases BITS' ability to + /// interact with servers that don't adhere to the normal BITS requirements for HTTP servers. Bear the following in mind when + /// you choose a different HTTP method from the default one. + /// + /// + /// + /// BITS automatically changes the job priority to BG_JOB_PRIORITY_FOREGROUND, and prevents that priority from being changed. + /// + /// + /// + /// An error that would ordinarily be resumable (such as loss of connectivity) transitions the job to an ERROR state. You, as + /// the developer, can restart the job by calling IBackgroundCopyJob::Resume, and the job will be restarted from the beginning. + /// See Life Cycle of a BITS Job for more information on BITS job states. + /// + /// + /// + /// BITS doesn’t allow DYNAMIC_CONTENT nor ON_DEMAND_MODE jobs with SetHttpMethod. + /// + /// + /// + /// SetHttpMethod does nothing if the method name that you pass matches the default HTTP method for the transfer type. + /// For example, if you set a download job method to "GET" (the default), then the job priority won't be changed. The HTTP + /// method must be set before the first call to IBackgroundCopyJob::Resume that starts the job. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/bits10_2/nf-bits10_2-ibackgroundcopyjobhttpoptions2-sethttpmethod + // HRESULT SetHttpMethod( [in] LPCWSTR method ); + void SetHttpMethod([MarshalAs(UnmanagedType.LPWStr)] string method); + + /// + /// Retrieves a wide string containing the HTTP method name for the BITS transfer. By default, download jobs will be "GET", and + /// upload and upload-reply jobs will be "BITS_POST". + /// + /// A string containing the HTTP method name. + // https://docs.microsoft.com/en-us/windows/win32/api/bits10_2/nf-bits10_2-ibackgroundcopyjobhttpoptions2-gethttpmethod + // HRESULT GetHttpMethod( [out] LPWSTR *method ); + [return: MarshalAs(UnmanagedType.LPWStr)] + string GetHttpMethod(); + } + + /// Use this interface to set HTTP customer headers to write-only, or to set a server certificate validation callback method that you've implemented. This interface extends IBackgroundCopyJobHttpOptions2. + // https://docs.microsoft.com/en-us/windows/win32/api/bits10_3/nn-bits10_3-ibackgroundcopyjobhttpoptions3 + [PInvokeData("bits10_3.h", MSDNShortId = "NN:bits10_3.IBackgroundCopyJobHttpOptions3")] + [ComImport, Guid("8A9263D3-FD4C-4EDA-9B28-30132A4D4E3C"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), ComConversionLoss] + public interface IBackgroundCopyJobHttpOptions3 : IBackgroundCopyJobHttpOptions2 + { + /// Specifies the identifier of the client certificate to use for client authentication in an HTTPS (SSL) request. + /// + /// Identifies the location of a system store to use for looking up the certificate. For possible values, see the + /// BG_CERT_STORE_LOCATION enumeration. + /// + /// + /// Null-terminated string that contains the name of the certificate store. The string is limited to 256 characters, including + /// the null terminator. You can specify one of the following system stores or an application-defined store. The store can be a + /// local or remote store. + /// + /// + /// Value + /// Meaning + /// + /// + /// CA + /// Certification authority certificates + /// + /// + /// MY + /// Personal certificates + /// + /// + /// ROOT + /// Root certificates + /// + /// + /// SPC + /// Software Publisher Certificate + /// + /// + /// + /// + /// SHA1 hash that identifies the certificate. Use a 20 byte buffer for the hash. For more information, see Remarks. + /// + new void SetClientCertificateByID(BG_CERT_STORE_LOCATION StoreLocation, [In, MarshalAs(UnmanagedType.LPWStr)] string StoreName, [In, MarshalAs(UnmanagedType.LPArray, SizeConst = 20)] byte[] pCertHashBlob); + + /// Specifies the subject name of the client certificate to use for client authentication in an HTTPS (SSL) request. + /// + /// Identifies the location of a system store to use for looking up the certificate. For possible values, see the + /// BG_CERT_STORE_LOCATION enumeration. + /// + /// + /// Null-terminated string that contains the name of the certificate store. The string is limited to 256 characters, including + /// the null terminator. You can specify one of the following system stores or an application-defined store. The store can be a + /// local or remote store. + /// + /// + /// Value + /// Meaning + /// + /// + /// CA + /// Certification authority certificates + /// + /// + /// MY + /// Personal certificates + /// + /// + /// ROOT + /// Root certificates + /// + /// + /// SPC + /// Software Publisher Certificate + /// + /// + /// + /// + /// Null-terminated string that contains the simple subject name of the certificate. If the subject name contains multiple + /// relative distinguished names (RDNs), you can specify one or more adjacent RDNs. If you specify more than one RDN, the list is + /// comma-delimited. The string is limited to 256 characters, including the null terminator. You cannot specify an empty subject name. + /// + /// Do not include the object identifier in the name.You must specify the RDNs in the reverse order from what the certificate + /// displays. For example, if the subject name in the certificate is "CN=name1, OU=name2, O=name3", specify the subject name as + /// "name3, name2, name1". + /// + /// + new void SetClientCertificateByName(BG_CERT_STORE_LOCATION StoreLocation, [In, MarshalAs(UnmanagedType.LPWStr)] string StoreName, [In, MarshalAs(UnmanagedType.LPWStr)] string SubjectName); + + /// Removes the client certificate from the job. + new void RemoveClientCertificate(); + + /// Retrieves the client certificate from the job. + /// + /// Identifies the location of a system store to use for looking up the certificate. For possible values, see the + /// BG_CERT_STORE_LOCATION enumeration. + /// + /// + /// Null-terminated string that contains the name of the certificate store. To free the string when done, call the CoTaskMemFree function. + /// + /// + /// SHA1 hash that identifies the certificate. To free the blob when done, call the CoTaskMemFree function. + /// + /// + /// Null-terminated string that contains the simple subject name of the certificate. The RDNs in the subject name are in the + /// reverse order from what the certificate displays. Subject name can be empty if the certificate does not contain a subject + /// name. To free the string when done, call the CoTaskMemFree function. + /// + new void GetClientCertificate(out BG_CERT_STORE_LOCATION pStoreLocation, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string pStoreName, out SafeCoTaskMemHandle ppCertHashBlob, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string pSubjectName); + + /// Specifies one or more custom HTTP headers to include in HTTP requests. + /// + /// Null-terminated string that contains the custom headers to append to the HTTP request. Each header must be terminated by a + /// carriage return and line feed (CR/LF) character. The string is limited to 16,384 characters, including the null terminator. + /// To remove the custom headers from the job, set the RequestHeaders parameter to NULL. + /// + new void SetCustomHeaders([In, MarshalAs(UnmanagedType.LPWStr)] string RequestHeaders); + + /// + /// Retrieves the custom headers set by an earlier call to IBackgroundCopyJobHttpOptions::SetCustomHeaders (that is, headers + /// which BITS will be sending to the remote, not headers which BITS receives from the remote). + /// + /// + /// Null-terminated string that contains the custom headers. Each header is terminated by a carriage return and line feed (CR/LF) + /// character. To free the string when finished, call the CoTaskMemFree function. + /// + [return: MarshalAs(UnmanagedType.LPWStr)] + new string GetCustomHeaders(); + + /// + /// Sets flags for HTTP that determine whether the certificate revocation list is checked and certain certificate errors are + /// ignored, and the policy to use when a server redirects the HTTP request. + /// + /// + /// HTTP security flags that indicate which errors to ignore when connecting to the server. You can set one or more of the + /// following flags: + /// + new void SetSecurityFlags([In] BG_HTTP_SECURITY Flags); + + /// + /// Retrieves the flags for HTTP that determine whether the certificate revocation list is checked and certain certificate errors + /// are ignored, and the policy to use when a server redirects the HTTP request. + /// + /// + /// HTTP security flags that indicate which errors to ignore when connecting to the server. One or more of the following flags + /// can be set: + /// + new BG_HTTP_SECURITY GetSecurityFlags(); + + /// Overrides the default HTTP method used for a BITS transfer. + /// + /// Type: LPCWSTR + /// A pointer to a constant null-terminated string of wide characters containing the HTTP method name. + /// + /// + /// + /// BITS allows you, as the developer, to choose an HTTP method other than the default method. This increases BITS' ability to + /// interact with servers that don't adhere to the normal BITS requirements for HTTP servers. Bear the following in mind when + /// you choose a different HTTP method from the default one. + /// + /// + /// + /// BITS automatically changes the job priority to BG_JOB_PRIORITY_FOREGROUND, and prevents that priority from being changed. + /// + /// + /// + /// An error that would ordinarily be resumable (such as loss of connectivity) transitions the job to an ERROR state. You, as + /// the developer, can restart the job by calling IBackgroundCopyJob::Resume, and the job will be restarted from the beginning. + /// See Life Cycle of a BITS Job for more information on BITS job states. + /// + /// + /// + /// BITS doesn’t allow DYNAMIC_CONTENT nor ON_DEMAND_MODE jobs with SetHttpMethod. + /// + /// + /// + /// SetHttpMethod does nothing if the method name that you pass matches the default HTTP method for the transfer type. + /// For example, if you set a download job method to "GET" (the default), then the job priority won't be changed. The HTTP + /// method must be set before the first call to IBackgroundCopyJob::Resume that starts the job. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/bits10_2/nf-bits10_2-ibackgroundcopyjobhttpoptions2-sethttpmethod + // HRESULT SetHttpMethod( [in] LPCWSTR method ); + new void SetHttpMethod([MarshalAs(UnmanagedType.LPWStr)] string method); + + /// + /// Retrieves a wide string containing the HTTP method name for the BITS transfer. By default, download jobs will be "GET", and + /// upload and upload-reply jobs will be "BITS_POST". + /// + /// A string containing the HTTP method name. + // https://docs.microsoft.com/en-us/windows/win32/api/bits10_2/nf-bits10_2-ibackgroundcopyjobhttpoptions2-gethttpmethod + // HRESULT GetHttpMethod( [out] LPWSTR *method ); + [return: MarshalAs(UnmanagedType.LPWStr)] + new string GetHttpMethod(); + + /// + /// Server certificates are sent when an HTTPS connection is opened. Use this method to set a callback to be called to validate + /// those server certificates. + /// + /// + /// Type: IUnknown* + /// + /// A pointer to an object that implements IBackgroundCopyServerCertificateValidationCallback. To remove the current callback + /// interface pointer, set this parameter to nullptr. + /// + /// + /// + /// Use this method when you want to perform your own checks on the server certificate. + /// Call this method only if you implement the IBackgroundCopyServerCertificateValidationCallback interface. + /// + /// The validation interface becomes invalid when your application terminates; BITS does not maintain a record of the validation + /// interface. As a result, your application's initialization process should call SetServerCertificateValidationInterface + /// on those existing jobs for which you want to receive certificate validation requests. + /// + /// + /// If more than one application calls SetServerCertificateValidationInterface to set the notification interface for the + /// job, the last application to call it is the one that will receive notifications. The other applications will not receive notifications. + /// + /// + /// If any certificate errors are found during the OS validation of the certificate, then the connection is aborted, and the + /// custom callback is never called. You can customize the OS validation logic with a call to + /// IBackgroundCopyJobHttpOptions::SetSecurityFlags. For example, you can ignore expected certificate validation errors. + /// + /// + /// If OS validation passes, then the IBackgroundCopyServerCertificateValidationCallback::ValidateServerCertificate method is + /// called before completing the TLS handshake and before the HTTP request is sent. + /// + /// + /// If your validation method declines the certificate, the job will transition to BG_JOB_STATE_TRANSIENT_ERROR with a + /// job error context of BG_ERROR_CONTEXT_SERVER_CERTIFICATE_CALLBACK and the error HRESULT from your callback. If + /// your callback couldn't be called (for example, because BITS needed to validate a server certificate after your program + /// exited), then the job error code will be BG_E_SERVER_CERT_VALIDATION_INTERFACE_REQUIRED. When your application is + /// next run, it can fix this error by setting the validation callback again and resuming the job. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/bits10_3/nf-bits10_3-ibackgroundcopyjobhttpoptions3-setservercertificatevalidationinterface + // HRESULT SetServerCertificateValidationInterface( IUnknown *certValidationCallback ); + void SetServerCertificateValidationInterface(IBackgroundCopyServerCertificateValidationCallback certValidationCallback); + + /// + /// Sets the HTTP custom headers for this job to be write-only. Write-only headers cannot be read by BITS methods such as the + /// IBackgroundCopyJobHttpOptions::GetCustomHeaders method. + /// + /// + /// Use this API when your BITS custom headers must include security information (such as an API token) that you don't want to + /// be readable by other programs running on the same computer. The BITS process, of course, can still read these headers, and + /// send them over the HTTP connection. Once the headers are set to write-only, that cannot be unset. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/bits10_3/nf-bits10_3-ibackgroundcopyjobhttpoptions3-makecustomheaderswriteonly + // HRESULT MakeCustomHeadersWriteOnly(); + void MakeCustomHeadersWriteOnly(); + } + /// /// Creates transfer jobs, retrieves an enumerator object that contains the jobs in the queue, and retrieves individual jobs from the queue. /// @@ -3737,6 +4696,149 @@ namespace Vanara.PInvoke void GetFileRanges(out uint pRangeCount, out SafeCoTaskMemHandle ppRanges); } + /// + /// Server certificates are sent when an HTTPS connection is opened. Use this method to implement a callback to be called to + /// validate those server certificates. This interface extends IUnknown. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/bits10_3/nn-bits10_3-ibackgroundcopyservercertificatevalidationcallback + [PInvokeData("bits10_3.h", MSDNShortId = "NN:bits10_3.IBackgroundCopyServerCertificateValidationCallback")] + [ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("4CEC0D02-DEF7-4158-813A-C32A46945FF7")] + public interface IBackgroundCopyServerCertificateValidationCallback + { + /// + /// A callback method that you implement that will be called so that you can validate the server certificates sent when an HTTPS + /// connection is opened. + /// + /// + /// Type: IBackgroundCopyJob* + /// The job. + /// + /// + /// Type: IBackgroundCopyFile* + /// The file being transferred. + /// + /// + /// Type: DWORD + /// The length in bytes of the certificate data. + /// + /// + /// Type: const BYTE [] + /// An array of bytes containing the certificate data. The number of bytes must match certLength. + /// + /// + /// Type: DWORD + /// The certificate encoding type. + /// + /// + /// Type: DWORD + /// The length in bytes of the certificate store data. + /// + /// + /// Type: const BYTE [] + /// An array of bytes containing the certificate store data. The number of bytes must match certStoreLength. + /// + /// + /// Return S_OK to indicate that the certificate is acceptable. Otherwise, return any HRESULT error code to + /// indicate that the certificate is not acceptable. + /// + /// + /// + /// Certificate validation is performed in two phases. The first phase is the operating system (OS) phase where the OS performs + /// a standard set of validation checks on the certificate. After that, if the OS phase passes the certificate, your callback + /// will be called to perform additional validation. + /// + /// + /// Implement this validation method when you want to perform your own checks on the server certificate. Your own checks are in + /// addition to the normal OS certificate validation checks. + /// + /// + /// If your validation method declines the certificate, the job will transition to BG_JOB_STATE_TRANSIENT_ERROR with a + /// job error context of BG_ERROR_CONTEXT_SERVER_CERTIFICATE_CALLBACK and the error HRESULT from your callback. If + /// your callback couldn't be called (for example, because BITS needed to validate a server certificate after your program + /// exited), then the job error code will be BG_E_SERVER_CERT_VALIDATION_INTERFACE_REQUIRED. When your application is + /// next run, it can fix this error by setting the validation callback again and resuming the job. + /// + /// + /// BITS calls this callback method only if you implement the IBackgroundCopyServerCertificateValidationCallback interface and + /// pass it into IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface. + /// + /// + /// The validation interface becomes invalid when your application terminates; BITS does not maintain a record of the validation + /// interface. As a result, your application's initialization process should call SetServerCertificateValidationInterface on + /// those existing jobs for which you want to receive certificate validation requests. + /// + /// + /// If more than one application calls SetServerCertificateValidationInterface to set the notification interface for the + /// job, the last application to call it is the one that will receive notifications. The other applications will not receive notifications. + /// + /// + /// Here are the general steps to validate a certificate. Be aware that these steps are just an example. The actual validation + /// is under your control. Also, steps 5-7 are largely the same as what the OS does during the OS validation step. + /// + /// + /// + /// Call CertCreateCertificateContext with certEncodingType, certData, and certLength to retrieve a CERT_CONTEXT. + /// + /// + /// Declare and initialize a CRYPT_DATA_BLOB structure (defined in wincrypt.h) with the serialized memory blob passed via certStoreLength and certStoreData. + /// (certStoreData);]]> + /// + /// + /// Obtain a handle to the certificate chain by calling CertOpenStore with CERT_STORE_PROV_SERIALIZED, 0, nullptr, flags, + /// and a pointer to the CRYPT_DATA_BLOB from step 2. + /// + /// + /// Obtain a pointer to a certificate chain context by calling CertGetCertificateChain with nullptr, certContext, nullptr, the handle from step 3, chain parameters, flags, and nullptr. + /// + /// + /// Create the certificate validation policy. + /// + /// + /// + /// Call CertVerifyCertificateChainPolicy with policy type, chain context, policy parameters, and policy status. + /// + /// + /// Convert the Win32 error (policyStatus.dwError) to an HRESULT and return that. + /// + /// + /// + /// A description of the BITS validation caching behaviors follows. BITS maintains a per-job cache of certificates that have + /// passed custom validation. This is to avoid redundant and potentially expensive re-validation over the lifetime of the job. + /// The cache consists of <server endpoint, cert hash> tuples, where endpoint is defined as server name:port. If a job has + /// already allowed a specific certificate from a specific endpoint, then the callback will not be called again. + /// + /// + /// Of course, the certificate will have to pass through the OS validation logic on every connection attempt (you can customize + /// the OS validation logic with a call to IBackgroundCopyJobHttpOptions::SetSecurityFlags), which addresses time-sensitive + /// corner cases such as when the certificate was valid very recently (in terms of seconds), but it has expired now. + /// + /// + /// BITS does not cache certificates that are deemed invalid by the app-provided validation callback. It's important that you're + /// aware of all unsuccessful connection attempts, so that you can detect malicious deployments at the app level. For example, a + /// one-off bad certificate is much less concerning than thousands of bad certificates from the same server. + /// + /// + /// A job's certificate cache is cleared on every call to SetServerCertificateValidationInterface, since it indicates + /// that the app's server certificate validation logic has changed. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/bits10_3/nf-bits10_3-ibackgroundcopyservercertificatevalidationcallback-validateservercertificate + // HRESULT ValidateServerCertificate( IBackgroundCopyJob *job, IBackgroundCopyFile *file, DWORD certLength, const BYTE [] + // certData, DWORD certEncodingType, DWORD certStoreLength, const BYTE [] certStoreData ); + [PreserveSig] + HRESULT ValidateServerCertificate(IBackgroundCopyJob job, IBackgroundCopyFile file, uint certLength, + [In, MarshalAs(UnmanagedType.LPArray)] byte[] certData, uint certEncodingType, uint certStoreLength, + [In, MarshalAs(UnmanagedType.LPArray)] byte[] certStoreData); + } + /// /// /// Use IBitsTokenOptions to associate and manage a pair of security tokens for a Background Intelligent Transfer Service