Background Intelligent Transfer Service

Overview of the Background Intelligent Transfer Service technology.

To develop Background Intelligent Transfer Service, you need these headers:

For programming guidance for this technology, see:

Enumerations

Title Description
BG_AUTH_SCHEME Defines constants that specify the authentication scheme to use when a proxy or server requests user authentication.
BG_AUTH_TARGET Defines constants that specify whether the credentials are used for proxy or server user authentication requests.
BG_CERT_STORE_LOCATION Defines constants that specify the location of the certificate store.
BG_ERROR_CONTEXT Defines constants that specify the context in which the error occurred.
BG_JOB_PRIORITY Defines constants that specify the priority level of a job.
BG_JOB_PROXY_USAGE Defines constants that specify which proxy to use for file transfers. You can define different proxy settings for each job.
BG_JOB_STATE Defines constants that specify the different states of a job.
BG_JOB_TYPE Defines constants that specify the type of transfer job, such as download.
BITS_FILE_PROPERTY_ID Defines constants that specify ID values corresponding to background copy file properties.
BITS_JOB_PROPERTY_ID Defines constants that specify the ID of the property for the BITS job.
BITS_JOB_TRANSFER_POLICY Defines constants that specify ID values corresponding to BITS properties.
GROUPPROP The GROUPPROP enumeration defines the constant values for retrieving and setting group property values.

Functions

Title Description
AddFile Adds a single file to the job.
AddFiles Use the AddFiles method to add one or more files to download to the job.
AddFileSet Adds multiple files to a job.
AddFileWithRanges Adds a file to a download job and specifies the ranges of the file you want to download.
Cancel Deletes the job from the transfer queue and removes related temporary files from the client (downloads) and server (uploads).
CancelGroup Use the CancelGroup method to remove the group from the queue. Files completely downloaded before calling this method are available to the client. You can cancel a group at anytime; however, the group cannot be recovered once it is canceled.
ClearHelperToken Discards the helper token, and does not change the usage flags.
ClearPeers Removes all peers from the list of peers that can serve content.
ClearRecords Removes all the records and files from the cache.
Clone Creates another IEnumBackgroundCopyFiles enumerator that contains the same enumeration state as the current one.
Clone Creates another IEnumBackgroundCopyJobs enumerator that contains the same enumeration state as the current one.
Clone Creates another IEnumBitsPeerCacheRecords enumerator that contains the same enumeration state as the current one.
Clone Creates another IEnumBitsPeers enumerator that contains the same enumeration state as the current one.
Clone Use the Clone method to create another IEnumBackgroundCopyGroups enumerator that contains the same enumeration state as the current one.
Clone Use the Clone method to create another IEnumBackgroundCopyJobs1 enumerator that contains the same enumeration state as the current one.
Complete Ends the job and saves the transferred files on the client.
CreateGroup Use the CreateGroup method to create a new group and add it to the download queue.
CreateJob Creates a job.
CreateJob Use the CreateJob method to add a new job to the group. A group can contain only one job.
DeleteRecord Deletes a record and file from the cache. This method uses the record's identifier to identify the record to delete.
DeleteUrl Deletes all cache records and the file from the cache for the given URL.
DisableBITSUploads Use the DisableBITSUploads method to disable BITS upload on the virtual directory to which the ADSI object points. This method sets the BITSUploadEnabled IIS extension property.
DiscoverPeers Generates a list of peers that can serve content.
EnableBITSUploads Use the EnableBITSUploads method to enable BITS upload on the virtual directory to which the ADSI object points. This method sets the BITSUploadEnabled IIS extension property.
EnumFiles Retrieves an IEnumBackgroundCopyFiles interface pointer that you use to enumerate the files in a job.
EnumGroups Use the EnumGroups method to retrieve a list of groups that the current user owns. If the current user has Administrator privileges, the method returns all groups in the queue.
EnumJobs Retrieves an interface pointer to an enumerator object that you use to enumerate the jobs in the transfer queue. The order of the jobs in the enumerator is arbitrary.
EnumJobs Use the EnumJobs method to retrieve a list of jobs in the group. The list contains only one job.
EnumPeers Gets an IEnumBitsPeers interface pointer that you use to enumerate the peers that can serve content. The enumeration is a snapshot of the records in the cache.
EnumRecords Gets an IEnumBitsPeerCacheRecords interface pointer that you use to enumerate the records in the cache. The enumeration is a snapshot of the records in the cache.
FileRangesTransferred BITS calls your implementation of the FileRangesTransferred method when one or more file ranges have been downloaded. File ranges are added to the job using the IBackgroundCopyFile6::RequestFileRanges method.
FileTransferred BITS calls your implementation of the FileTransferred method when BITS successfully finishes transferring a file.
get_GroupID Use the get_GroupID method to retrieve the group's identifier.
get_JobID Use the get_JobID method to retrieve the job's identifier.
get_Size Use the get_Size method to retrieve the size of all files in the group to download.
GetCleanupTask Use the GetCleanupTask method to retrieve an interface pointer to the cleanup task associated with the virtual directory.
GetCleanupTaskName Use the GetCleanupTaskName method to retrieve the name of the cleanup task associated with the virtual directory.
GetClientCertificate Retrieves the client certificate from the job.
GetConfigurationFlags Gets the configuration flags that determine if the computer serves content to peers and can download content from peers.
GetCount Retrieves a count of the number of files in the enumeration.
GetCount Retrieves a count of the number of jobs in the enumeration.
GetCount Retrieves a count of the number of cache records in the enumeration.
GetCount Retrieves a count of the number of peers in the enumeration.
GetCount Use the GetCount method to retrieve a count of the number of groups in the enumeration.
GetCount Use the GetCount method to retrieve a count of the number of jobs in the enumeration.
GetCustomHeaders 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).
GetDescription Retrieves the description of the job.
GetDisplayName Retrieves the display name for the job. Typically, you use the display name to identify the job in a user interface.
GetError Retrieves the error code and identify the context in which the error occurred.
GetError Retrieves the error interface after an error occurs.
GetErrorContextDescription Retrieves the description of the context in which the error occurred.
GetErrorCount Retrieves the number of times BITS tried to transfer the job and an error occurred.
GetErrorDescription Retrieves the error text associated with the error.
GetErrorDescription Retrieves a description for the specified error code.
GetFile Retrieves an interface pointer to the file object associated with the error.
GetFile Use the GetFile method to retrieve the remote and local file names for the given file in the job.
GetFileACLFlags Retrieves the flags that identify the owner and ACL information to maintain when transferring a file using SMB.
GetFileCount Use the GetFileCount method to retrieve the number of files in the job.
GetFileModificationTime Gets the date and time that the file was last modified on the server.
GetFileRanges Gets the ranges of the file that are in the cache.
GetFileRanges Retrieves the ranges that you want to download from the remote file.
GetFileSize Gets the size of the file.
GetFilledFileRanges Returns the set of file ranges that have been downloaded.
GetGroup Use the GetGroup method to retrieve a group from the download queue.
GetHelperTokenFlags Returns the usage flags for a token that is associated with a BITS transfer job.
GetHelperTokenSid Returns the SID of the helper token if one is set.
GetHttpMethod 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".
GetId Retrieves the identifier used to identify the job in the queue.
GetId Gets the identifier that uniquely identifies the record in the cache.
GetJob Retrieves a specified job from the transfer queue. Typically, your application persists the job identifier, so you can later retrieve the job from the queue.
GetJob Use the GetJob method to retrieve a job from the group.
GetLastAccessTime Gets the date and time that the file was last accessed.
GetLocalName Retrieves the local name of the file.
GetMaximumCacheSize Gets the maximum size of the cache.
GetMaximumContentAge Gets the age by when files are removed from the cache.
GetMaximumDownloadTime Retrieves the maximum time that BITS will spend transferring the files in the job.
GetMinimumRetryDelay Retrieves the minimum length of time that the service waits after encountering a transient error condition before trying to transfer the file.
GetNoProgressTimeout 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.
GetNotifyCmdLine Retrieves the program to execute when the job enters the error or transferred state.
GetNotifyFlags Retrieves the event notification flags for the job.
GetNotifyInterface Retrieves the interface pointer to your implementation of the IBackgroundCopyCallback interface.
GetObject Use the GetObject method to retrieve a pointer to the IBITSExtensionSetup interface. This method performs the same binding that the ADsGetObject ADSI function performs.
GetOriginUrl Gets the origin URL of the cached file.
GetOwner Retrieves the identity of the job's owner.
GetOwnerElevationState Gets a value that determines if the token of the owner was elevated at the time they created or took ownership of the job.
GetOwnerIntegrityLevel Gets the integrity level of the token of the owner that created or took ownership of the job.
GetPeerCachingFlags 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.
GetPeerDownloadStats Specifies statistics about the amount of data downloaded from peers and origin servers.
GetPeerName Gets the server principal name that uniquely identifies the peer.
GetPriority Retrieves the priority level for the job. The priority level determines when the job is processed relative to other jobs in the transfer queue.
GetProgress Retrieves information on the progress of the file transfer.
GetProgress Retrieves job-related progress information, such as the number of bytes and files transferred.
GetProgress Use the GetProgress method to retrieve the progress of the download.
GetProgress Use the GetProgress method to retrieve the job's progress.
GetProp Use the GetProp method to retrieve a property value from the group.
GetProperty Gets a generic property of a BITS file transfer.
GetProperty A generic method for getting BITS job properties.
GetProtocol Retrieves the protocol used to transfer the file. The remote file name identifies the protocol to use to transfer the file.
GetProxySettings Retrieves the proxy information that the job uses to transfer the files.
GetRecord Gets a record from the cache.
GetRemoteName Retrieves the remote name of the file.
GetReplyData 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.
GetReplyFileName 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.
GetReplyProgress Retrieves progress information related to the transfer of the reply data from an upload-reply job.
GetSecurityFlags 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.
GetState Retrieves the state of the job.
GetStatus Use the GetStatus method to retrieve the state of the group.
GetStatus Use the GetStatus method to retrieve the state of the job.
GetTemporaryName Gets the full path of the temporary file that contains the content of the download.
GetTimes Retrieves job-related time stamps, such as the time that the job was created or last modified.
GetType Retrieves the type of transfer being performed, such as a file download or upload.
GetValidationState Gets the current validation state of this file.
IsAuthenticated Determines whether the peer is authenticated.
IsAvailable Determines whether the peer is available (online) to serve content.
IsDownloadedFromPeer Gets a value that determines if any part of the file was downloaded from a peer.
IsFileValidated Determines whether the file has been validated.
JobError BITS calls your implementation of the JobError method when the state of the job changes to BG_JOB_STATE_ERROR.
JobModification BITS calls your implementation of the JobModification method when the job has been modified.
JobTransferred BITS calls your implementation of the JobTransferred method when all of the files in the job have been successfully transferred.
MakeCustomHeadersWriteOnly Sets the HTTP custom headers for this job to be write-only.
Next Retrieves a specified number of items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements.
Next Retrieves a specified number of items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements.
Next Retrieves a specified number of items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements.
Next Retrieves a specified number of items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements.
Next Use the Next method to retrieve the specified number of items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements.
Next Use the Next method to retrieve the specified number of items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements.
OnStatus Implement the OnStatus method to receive notification when the group is complete or an error occurs.
RemoveClientCertificate Removes the client certificate from the job.
RemoveCredentials 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.
ReplaceRemotePrefix Replaces the beginning text of all remote names in the download job with the specified string.
RequestFileRanges Adds a new set of file ranges to be prioritized for download.
Reset Resets the enumeration sequence to the beginning.
Reset Resets the enumeration sequence to the beginning.
Reset Resets the enumeration sequence to the beginning.
Reset Resets the enumeration sequence to the beginning.
Reset Use the Reset method to reset the enumeration sequence to the beginning.
Reset Use the Reset method to reset the enumeration sequence to the beginning.
Resume Activates a new job or restarts a job that has been suspended.
ResumeGroup Use the ResumeGroup method to start a group that has been suspended in the download queue.
SetClientCertificateByID Specifies the identifier of the client certificate to use for client authentication in an HTTPS (SSL) request.
SetClientCertificateByName Specifies the subject name of the client certificate to use for client authentication in an HTTPS (SSL) request.
SetConfigurationFlags Sets the configuration flags that determine if the computer can serve content to peers and can download content from peers.
SetCredentials Specifies the credentials to use for a proxy or remote server user authentication request.
SetCustomHeaders Specifies one or more custom HTTP headers to include in HTTP requests.
SetDescription Provides a description of the job.
SetDisplayName Specifies a display name for the job. Typically, you use the display name to identify the job in a user interface.
SetFileACLFlags Specifies the owner and ACL information to maintain when using SMB to download or upload a file.
SetHelperToken Sets the helper token to impersonate the token of the COM client.
SetHelperTokenFlags Sets the usage flags for a token that is associated with a BITS transfer job.
SetHttpMethod Overrides the default HTTP method used for a BITS transfer.
SetMaximumCacheSize Specifies the maximum size of the cache.
SetMaximumContentAge Specifies when files are removed from the cache based on age.
SetMaximumDownloadTime Sets the maximum time that BITS will spend transferring the files in the job.
SetMinimumRetryDelay Sets the minimum length of time that BITS waits after encountering a transient error condition before trying to transfer the file.
SetNoProgressTimeout 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.
SetNotifyCmdLine 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.
SetNotifyFlags Specifies the type of event notification you want to receive, such as job transferred events.
SetNotifyInterface Identifies your implementation of the IBackgroundCopyCallback interface to BITS. Use the IBackgroundCopyCallback interface to receive notification of job-related events.
SetPeerCachingFlags 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.
SetPriority Specifies the priority level of your job. The priority level determines when your job is processed relative to other jobs in the transfer queue.
SetProp Use the SetProp method to set the property value for a group property.
SetProperty Sets a generic property of a BITS file transfer.
SetProperty A generic method for setting BITS job properties.
SetProxySettings Specifies which proxy to use to transfer files.
SetRemoteName Changes the remote name to a new URL in a download job.
SetReplyFileName 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.
SetSecurityFlags 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.
SetServerCertificateValidationInterface 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.
SetValidationState Sets the validation state of this file.
Skip Skips the next specified number of elements in the enumeration sequence. If there are fewer elements left in the sequence than the requested number of elements to skip, it skips past the last element in the sequence.
Skip Skips the next specified number of elements in the enumeration sequence. If there are fewer elements left in the sequence than the requested number of elements to skip, it skips past the last element in the sequence.
Skip Skips the next specified number of elements in the enumeration sequence. If there are fewer elements left in the sequence than the requested number of elements to skip, it skips past the last element in the sequence.
Skip Skips the next specified number of elements in the enumeration sequence. If there are fewer elements left in the sequence than the requested number of elements to skip, it skips past the last element in the sequence.
Skip Use the Skip method to skip the next specified number of elements in the enumeration sequence. If there are fewer elements left in the sequence than the requested number of elements to skip, it skips past the last element in the sequence.
Skip Use the Skip method to skip the next specified number of elements in the enumeration sequence. If there are fewer elements left in the sequence than the requested number of elements to skip, it skips past the last element in the sequence.
Suspend Suspends a job. New jobs, jobs that are in error, and jobs that have finished transferring files are automatically suspended.
SuspendGroup Use the SuspendGroup method to pause a group in the download queue. New groups, groups that are in error, or groups that have finished downloading are automatically suspended.
SwitchToForeground Use the SwitchToForeground method to download the group in the foreground instead of the background.
TakeOwnership Changes ownership of the job to the current user.
UpdateDownloadPosition Specifies a position to prioritize downloading missing data from.
ValidateServerCertificate 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.

Interfaces

Title Description
IBackgroundCopyCallback Implement the IBackgroundCopyCallback interface to receive notification that a job is complete, has been modified, or is in error. Clients use this interface instead of polling for the status of the job.
IBackgroundCopyCallback1 Implement the IBackgroundCopyCallback1 interface to receive notification when events occur.
IBackgroundCopyCallback2 Implement this interface to receive notification that a file has completed downloading.
IBackgroundCopyCallback3 Clients implement the IBackgroundCopyCallback3 interface to receive notification that ranges of a file have completed downloading.
IBackgroundCopyError Use the IBackgroundCopyError interface to determine the cause of an error and if the transfer process can proceed.
IBackgroundCopyFile IBackgroundCopyFile contains information about a file that is part of a job. For example, you can use IBackgroundCopyFile methods to retrieve the local and remote names of the file and transfer progress information.
IBackgroundCopyFile2 Use the IBackgroundCopyFile2 interface to specify a new remote name for the file and retrieve the list of ranges to download.
IBackgroundCopyFile3 Use this interface to retrieve the name of the temporary file that contains the downloaded content and to validate the file so that peers can request its content.
IBackgroundCopyFile4 Use this interface to retrieve download statistics for peers and origin servers.
IBackgroundCopyFile5 Use this interface to get or set generic properties of BITS file transfers.
IBackgroundCopyFile6 Use this interface to request file ranges for On Demand download jobs.
IBackgroundCopyGroup Use the IBackgroundCopyGroup interface to manage a group. A group contains download jobs. For example, add a job to the group, set the properties of the group, and start and stop the group in the download queue.
IBackgroundCopyJob Use the IBackgroundCopyJob interface to add files to the job, set the priority level of the job, determine the state of the job, and to start and stop the job.
IBackgroundCopyJob1 Use the IBackgroundCopyJob1 interface to add files to the job and retrieve the job's status.
IBackgroundCopyJob2 Retrieve reply data from an upload-reply job, determine the progress of the reply data transfer to the client, request command line execution, and provide credentials for proxy and remote server authentication requests.
IBackgroundCopyJob3 Use the IBackgroundCopyJob3 interface to download ranges of a file and change the prefix of a remote file name.
IBackgroundCopyJob4 Use this interface to enable peer caching, restrict download time, and inspect user token characteristics.
IBackgroundCopyJob5 Use this interface to query or set several optional behaviors of a job.
IBackgroundCopyJobHttpOptions Use this interface to specify client certificates for certificate-based client authentication and custom headers for HTTP requests.
IBackgroundCopyJobHttpOptions2 Use this interface to retrieve and/or to override the HTTP method used for a BITS transfer.
IBackgroundCopyJobHttpOptions3 Use this interface to set HTTP customer headers to write-only, or to set a server certificate validation callback method that you've implemented.
IBackgroundCopyManager Creates transfer jobs, retrieves an enumerator object that contains the jobs in the queue, and retrieves individual jobs from the queue.
IBackgroundCopyQMgr Use the IBackgroundCopyQMgr interface to create a new group, retrieve an existing group, or enumerate all groups in the queue. A group contains a download job.
IBackgroundCopyServerCertificateValidationCallback 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.
IBITSExtensionSetup Use the IBITSExtensionSetup interface to enable or disable BITS uploads to a virtual directory.
IBITSExtensionSetupFactory Use the IBITSExtensionSetupFactory interface to get a pointer to the IBITSExtensionSetup interface.
IBitsPeer Use IBitsPeer to get information about a peer in the neighborhood.
IBitsPeerCacheAdministration Use IBitsPeerCacheAdministration to manage the pool of peers from which you can download content.
IBitsPeerCacheRecord Use IBitsPeerCacheRecord to get information about a file in the cache.
IBitsTokenOptions Use IBitsTokenOptions to associate and manage a pair of security tokens for a Background Intelligent Transfer Service (BITS) transfer job.
IEnumBackgroundCopyFiles Use the IEnumBackgroundCopyFiles interface to enumerate the files that a job contains. To get an IEnumBackgroundCopyFiles interface pointer, call the IBackgroundCopyJob::EnumFiles method.
IEnumBackgroundCopyGroups Use the IEnumBackgroundCopyGroups interface to enumerate the list of groups in the download queue. To get an IEnumBackgroundCopyGroups interface pointer, call the IBackgroundCopyQMgr::EnumGroups method.
IEnumBackgroundCopyJobs Use the IEnumBackgroundCopyJobs interface to enumerate the list of jobs in the transfer queue. To get an IEnumBackgroundCopyJobs interface pointer, call the IBackgroundCopyManager::EnumJobs method.
IEnumBackgroundCopyJobs1 Use the IEnumBackgroundCopyJobs1 interface to enumerate the list of jobs in a group. To get an IEnumBackgroundCopyJobs1 interface pointer, call the IBackgroundCopyGroup::EnumJobs method.
IEnumBitsPeerCacheRecords Use IEnumBitsPeerCacheRecords to enumerate the records of the cache.
IEnumBitsPeers Use IEnumBitsPeers to enumerate the list of peers that BITS has discovered.

Structures

Title Description
BG_AUTH_CREDENTIALS Identifies the target (proxy or server), authentication scheme, and the user's credentials to use for user authentication requests. The structure is passed to the IBackgroundCopyJob2::SetCredentials method.
BG_AUTH_CREDENTIALS_UNION Identifies the credentials to use for the authentication scheme specified in the BG_AUTH_CREDENTIALS structure.
BG_BASIC_CREDENTIALS The BG_BASIC_CREDENTIALS structure identifies the user name and password to authenticate.
BG_FILE_INFO Provides the local and remote names of the file to transfer.
BG_FILE_PROGRESS Provides file-related progress information, such as the number of bytes transferred.
BG_FILE_RANGE Identifies a range of bytes to download from a file.
BG_JOB_PROGRESS Provides job-related progress information, such as the number of bytes and files transferred.
BG_JOB_REPLY_PROGRESS Provides progress information related to the reply portion of an upload-reply job.
BG_JOB_TIMES Provides job-related time stamps.
BITS_FILE_PROPERTY_VALUE Provides the property value of a BITS file.
BITS_JOB_PROPERTY_VALUE Provides the property value of the BITS job based on the value of the BITS_JOB_PROPERTY_ID enumeration.
FILESETINFO The FILESETINFO structure identifies the remote and local names of the file to download.