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

 
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

 
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

 
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

 
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.