clip_image001

clip_image002

Background Intelligent Transfer Service

Microsoft Corporation

Published: August 2002

Abstract

Background Intelligent Transfer Service (BITS) asynchronously transfers files in the foreground or background, throttles the transfers to preserve the responsiveness of other network applications, and automatically resumes file transfers after network disconnects and machine restarts.

Applications use the BITS application program interface (API) to create transfer jobs and to monitor the progress of jobs in the transfer queue. The BITS API is included in the Microsoft® Platform Software Development Kit (SDK).

This document is intended for IT professionals who are interested in using BITS from within their software.

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

The example companies, organizations, products, people and events depicted herein are fictitious. No association with any real company, organization, product, person or event is intended or should be inferred.

© 2002 Microsoft Corporation. All rights reserved.

Microsoft, Windows, Windows Logo and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.


Contents

Introduction. 1

Why BITS?. 2

Lifecycle of a BITS Job. 3

Users and Network Connections. 6

Service Accounts and BITS. 7

Throttling Transfers in the Background. 8

Job Status. 9

File Availability. 10

BITS Server 11

Comparing BITS to Other Internet Data Transfer Technologies. 12

File Transfer Technologies Provided by the Windows Operating System.. 12

Tools and Samples. 13

BitsAdmin Tool 13

BITS_IE Sample. 13

Frequently Asked Questions. 14

Summary. 17

Related Links. 18

Introduction

BITS is a file transfer service that transfers files between a client and a server. Unlike other protocols that transfer files in the foreground, BITS transfers files in the background (default). Background transfers use only idle network bandwidth in an effort to preserve the user’s interactive experience with other network applications, such as Internet Explorer. BITS does this by examining the network traffic, and using only the idle portion of the network bandwidth. BITS throttles its use of the bandwidth as the user increases or decreases their use of the bandwidth.

BITS performs the transfers asynchronously, which means your application does not need to be running for BITS to perform the transfer. After your application creates the transfer job, the user can close the application and BITS continues to transfer the files. BITS transfers the files as long as there is a network connection and the user who created the job is logged on the computer. Service accounts, such as LocalSystem, are considered always logged on, so transfer jobs created by a service always run.

BITS suspends transfers if the user logs off or the network connection is lost. When the user logs on and a network connection exists, BITS resumes the transfer from where it left off previously. The same is true for system reboots.

BITS version 1.0 is included with the Microsoft® Windows® XP operating system and supports only downloads. BITS version 1.5 is included with Microsoft Windows Server 2003 and supports both downloads and uploads. Version 1.5 will be available as a redistributable for Windows 2000 and Windows XP following the Microsoft Windows Server 2003 release. Uploads require Internet Information Services (IIS) server, versions 5.0 or 6.0, with the BITS server extension installed.

BITS supports HTTP and HTTPS downloads and uploads and requires an HTTP 1.1 compliant server. For downloads, the HTTP server's Head method must return the file size and its Get method must support the Content-Range and Content-Length headers. To transfer dynamic content, the ASP, ISAPI, or CGI script must support the Content-Range and Content-Length headers. Otherwise, you can transfer only static content.

The Platform SDK includes the BITS API which you use to create and manage file transfer jobs.

Why BITS?

The following five points illustrate the value provided by BITS:

1. Transfers data in the background. BITS can transfer files in the foreground or background. Foreground transfers compete with other applications that require network bandwidth. By default, BITS transfers files in the background in an effort to preserve the user's experience with other network applications. BITS throttles the background transfers based on the available network bandwidth. As the use of network bandwidth by other applications increases, BITS use decreases. As the use of network bandwidth by other applications decreases, BITS use increases.

2. Transfers are restartable. To transfer files, BITS requires a network connection and the user who created the job to be logged onto the computer. If the network connection is lost or the user logs off, BITS suspends the job. BITS automatically resumes the job from where it left off previously when the network connection is restored and the owner of the job is logged on. Also, BITS automatically restarts file transfers after reboots (as long as a network connection exists and the user is logged on).

3. Manageability. The BITS API provides interfaces and methods that you use to manage the transfer job. Use the methods to start and stop the transfer job, specify the priority of the job relative to other jobs in the transfer queue, check the progress of the job, and specify for which events you want to receive notification. In addition, you can use the API to enumerate all jobs in the transfer queue, specify which proxy to use for the job, specify credentials for user authentication by a proxy or server, and specify a program to execute based on an event.

4. Security. BITS processes the transfer job using the security context of the job's owner. You can also use the BITS API to specify credentials to use for a proxy or server user authentication request. BITS supports Basic, NTLM, Negotiate, Digest, and Passport authentication. ITS supports HTTP and HTTPS protocols. Use HTTPS if the privacy and integrity of the job is a concern.

5. Prioritized transfers. Applications use the job's priority to specify when the job is processed relative to other jobs in the transfer queue. Jobs with a higher priority are processed before jobs with a lower priority. BITS uses round-robin scheduling to process jobs at the same priority level to prevent a large job from blocking the others. By default, job transfers use the Normal background priority level. Applications can also specify the High and Low background priority levels. The highest priority level is Foreground. BITS does not throttle foreground transfers, so they compete with other applications for network bandwidth

Lifecycle of a BITS Job

The lifecycle of a BITS job begins when you create a job. A job is a container that contains one or more files to transfer. A job also has properties that specify how BITS transfers the files and interacts with your application. For example, you can specify the priority of the job, whether the job is an upload or download job, and for which events you want to receive notification.

After you create the job, you add one or more files (upload jobs can contain only one file) to the job and change any of the property values as appropriate for your application. When you add a file to the job, you specify both the local (client) and remote (server) name of the file. The remote file name must use the HTTP or HTTPS protocol. Figure 1 below shows the steps to perform to create a job.

clip_image003

Figure 1. Creating a BITS job

BITS automatically suspends the job when you create it. You must resume the job to activate it in the transfer queue. You can suspend or resume a job at any time. Resuming the job moves the job from the suspend state to the queued state. The job stays in the queued state until the scheduler determines it is its turn to transfer files. The job moves to the connecting state while BITS connects to the remote server specified in the remote file name. If BITS connects to the remote server, the job moves to the transferring state where it stays until its time slice ends, the transfer is complete, an error occurs, or the application suspends the job.

If the job is large and there are many jobs in the queue, the job may be preempted by another job (moves back to the queued state). The job moves between the queued, connecting, and transferring states until BITS transfers all files in the job. At that point, the job moves to the transferred state. The files are not available to the client until the application calls the IBackgroundCopyJob::Complete method to transfer ownership of the files from BITS to the application. Upload jobs also are set to the transferred state when the file is successfully received by the server. Upload-reply jobs are set to the transferred state after the file is successfully sent to the server and the reply from the server application is successfully transferred to the client.

If an error occurs, the job moves to either the fatal or transient error state. Fatal errors are errors that BITS cannot recover from or which require intervention to fix. If the application is able to fix the error, the application resumes the job and BITS moves the job to the queued state. Transient errors are errors that may resolve themselves. BITS retries jobs in the transient error state until the transfer is successful or the job times out. The job times out when no progress is made within an application specified period. If the job times out, BITS moves the job to fatal error state.

Figure 2 below shows the different states of a job.

clip_image002

Figure 2. The different states of a BITS job

Users and Network Connections

BITS only transfers files when the job's owner is logged on and a network connection (LAN or modem) is established. BITS processes the transfer job using the security context of the job's owner. The user who created the job is considered the owner of the job; only the owner can modify the job. However, a user with administrator privileges can modify any job and take ownership of another user's job.

BITS suspends a job when the owner logs off or if the network connection is lost, and resumes the job when the owner logs back on and a network connection is established.

For BITS to detect that a user is logged on, the user must use one of the following interactive logon options:

· Log on through the Welcome screen.

· Log on to a Terminal Services client. BITS only supports terminal service logon in Windows XP; BITS does not support terminal service logon in Windows 2000.

· Use fast user switching.

Service Accounts and BITS

You can use BITS to transfer files from a service. The service must run as the LocalSystem, LocalService, or NetworkService system account. Jobs created by the system account are owned by that account. Because system accounts are always logged on, BITS transfers the files as long as the computer is running and there is a network connection. If a service running under a system account impersonates the user before calling BITS, BITS responds as it would for any user account (the user must be logged on). For more details on using a service with BITS, see the Platform SDK.

Throttling Transfers in the Background

BITS uses idle network bandwidth to transfer files. BITS increases or decreases the rate (throttles) at which it transfers files based on the amount of idle network bandwidth available. If another network application begins to consume more bandwidth, BITS decreases its transfer rate to preserve the user's interactive experience. Note that if the link appears to be full, BITS still transfers data, so that BITS jobs make progress.

Job Status

Each job contains state and progress information that you can use to monitor the status of the job. The state tells you whether the job is queued, transferring, or in error. The job progress information tells you the job's progress in terms of files or bytes transferred. You can also retrieve progress information for each file.

By default, applications must poll BITS to determine the status of a job. Applications can poll BITS based on user events or create a timer to poll for status at given intervals. As an alternative to polling, applications can register to receive notification (a com callback) when an event occurs. The three events applications can register for are:

· JobTransferred: All files in the job have been transferred. The job is in the transferred state.

· JobError: An error occurred. The job is in the error state.

· JobModification: The job has been modified. BITS considers the job modified if you change a property, the state changes (except for error and transferred), or data has been transferred.

As an alternative to receiving notification, applications can register to have BITS execute a program as a result of a JobTransferred or JobError events. BITS does not support command line activation for the JobModification event.

For more details on registering to receive event notification, see the BITS documentation on Determining the Status of a Job in the Platform SDK.

File Availability

BITS downloads to temporary files, which are not available to the client. If the application cancels the job, BITS deletes the files from the client. To make the files available to the client, the application must call the IBackgroundCopyJob::Complete method to acknowledge the transfer.

Typically, applications call the Complete method in response to the JobTransferred event or when the state of the job is transferred. If the application calls the Complete method before the job's state is transferred (referred to as a partial-complete), only those files that have already transferred successfully are made available to the client. For example, if a download job contains files A, B and C, and A and B were successfully transferred but C was only partially transferred before Complete was called, then only A and B are made available to the client and C is deleted.

For uploads, the upload file is available on the server as soon as the last fragment is received by the BITS server. The reply portion of an upload-reply job follows the rules for downloads.

BITS Server

To upload files to a server or server farm using BITS, the server(s) must have the BITS server software and Internet Information Services (IIS) installed. The BITS server software is included with Windows Server 2003 and will be available as a redistributable for Windows 2000 following the Windows Server 2003 release. BITS requires IIS 5.0 on Windows 2000 Server and IIS 6.0 on Windows Server 2003; BITS does not support IIS 5.1 on Windows XP.

BITS server extends IIS to support throttled, restartable uploads. To use the upload feature, create an IIS virtual directory on the server where you want clients to upload files. You should create a virtual directory for each type of client you wish to support. For example, mobile clients or clients over slow links may need a larger session timeout than LAN clients, or you may need to restrict the amount of data that certain clients can upload.

BITS adds properties to the IIS metabase for the virtual directory you create and uses these properties to determine how to upload the files.

To use BITS for uploads, you must configure the BITS IIS extension properties and enable the directory for uploads. You can use the BITS API or the property page for the virtual directories to configure the BITS IIS extension. For details, see the BITS documentation on Setting Up the Server for Uploads in the Platform SDK.

Note that BITS will not upload files to a virtual directory that has scripting and execute permissions enabled. If you upload a file to a virtual directory that has these permissions enabled, the job fails. Also, BITS does not require the virtual directory to be write-enabled, so it is recommended that you turn off write access to the virtual directory.

The default property values let you upload a file to the server. The file is written to the URL as specified in the remote file name of the job. To upload the file to a server application and receive a reply, enable notifications and specify the URL of the server application (typically an ISAPI) to notify. The BITS server sends the upload file to a server application. The BITS server uses HTTP request and response headers to communicate with the server application.

BITS can send data to the server application by reference (sends the name of the file that contains the data) or by value (sends the data in the body of the request or response). Server applications that send the same reply to many clients, may want to use by reference, so there is only one copy of the reply on the server. For example, in a software update application, the client would upload its configuration to the server application. The server application determines which package the client needs and sends the URL of the package to BITS. Then, BITS downloads the package as the reply.

Server applications that generate unique replies for each client may want to use by value. For example, a server application that supports the purchase of music files would need to send a signed music file to the client. Because the signed music file is unique to the client, the server application would not want to store it on the server. Sending data by value is also useful for an application that is already written to accept web client data directly.

Comparing BITS to Other Internet Data Transfer Technologies

Depending on your application requirements, you can choose from several APIs to transfer data over your intranet or the internet. At the lowest level, you can use the Sockets API. Sockets provide flexibility but requires extensive programming to support Web protocols and authentication. The WinInet API supports a broad range of platforms, multiple internet protocols, but is not restartable and will not operate in the background. Also, you cannot use WinInet in a service (or ISAPI within Internet Information Server). WinHttp is similar to WinInet, but only supports HTTP. However, it is supported from within a service context. The CopyFiles API (CopyFile(), CopyFileEx()) can be restartable but does not support background transfers. Typically, the CopyFiles API is used within LANs, but you can configure WebDAV publishing in Internet Information Server to use the CopyFiles API across the internet.

The following table summarizes various file transfer technologies that are provided by the Windows operating system.

File Transfer Technologies Provided by the Windows Operating System

 

Minimum Operating System

Protocol Support

Restartable

Background Transfers

Status Notifications

Internet Authentication and Security

Proxy Support

BITS

Windows 2000

HTTP

Y

Y

Y

Y

Y

Sockets

Windows 95

TCP/IP

N

N

N

N(1)

N

WinInet (2)

Windows 95

HTTP,

FTP

N(3)

N

N

Y

Y

WinHttp

Windows 2000

HTTP

N

N

N

Y

Y

CopyFiles API

Windows 95

SMB

Y

N

N

Y(4)(5)

Y(4)

(1) The sockets API supports IPSec, but does not support any of the standard internet authentication protocols.

(2) Cannot use WinInet in a Windows NT service or IIS ISAPI.

(3) WinInet does not support FTP file restarts.

(4) You can use the CopyFiles API for internet file transfer if you configure WebDAV on the server. However, the server must be Windows 2000 Server or later.

(5) You need to configure authentication in the credential manager before use.

Tools and Samples

The following tool and sample are available in BITS:

BitsAdmin Tool

BitsAdmin is a command line tool that exercises most of the BITS client features. You can use BitsAdmin to create, manage, and list jobs in the transfer queue. In addition, you can call BitsAdmin from a script. Use the usage switch (/?) with BitsAdmin to show the BitsAdmin usage statement.

The BitsAdmin tool is located in the \bin folder of the Platform SDK.

BITS_IE Sample

The BITS_IE sample is an Internet Explorer plug-in that demonstrates the use of the BITS API to download files. The sample is included with the Platform SDK. The BITS_IE sample folder contains the source code, scripts to install and uninstall the plug-in, and the readme.htm file with information on how to use the plug-in.

Frequently Asked Questions

The following information addresses frequently asked questions about BITS:

Q. Is there a way to use the priority levels to ensure one job gets done before another job?

A. BITS uses the job's Priority property to determine when the job runs relative to other jobs in the transfer queue. BITS supports four priorities: Foreground, Background High, Background Normal, and Background Low. Foreground is the highest priority and Background Low is the lowest priority. BITS processes the highest priority jobs before processing jobs at the next highest priority level. If a job with a higher priority is added to the queue, the current job is interrupted and the new job with the higher priority is processed. Within a priority level, BITS uses round-robin scheduling with a time quanta of about 5 minutes to ensure that large jobs do not block other jobs at the same priority level.

You can use different priority levels to ensure one job finishes before another, but within a priority level, BITS cannot guarantee that one job will complete before another.

Q. What is the maximum number of concurrent upload and download jobs that BITS supports?

A. BITS does not support concurrent uploads or downloads; BITS transfers one file at a time.

Q. Can BITS provide an estimate for how long it will take to download a file based on the network bandwidth and the file size?

A. To determine an accurate estimate, BITS would need to take into account future bandwidth usage, whether other jobs will be added at the same priority level or higher, how long the computer will be connected to the network, and how long the user will remain logged on. BITS cannot provide an estimate because there is no way to predict future activity. Although you can't provide a progress bar based on time, you can use the progress properties to provide a progress bar based on the number of files or the number of bytes downloaded.

Q. What happens if two different users download the same file to the same location?

A. BITS downloads the file twice. Each user's copy of the file is written to a different temporary file on the local computer. The temporary file is renamed to the local file name specified in the job when the application calls the IBackgroundCopyJob::Complete method. If User B calls the Complete method first, User B's copy of the file is written to the local file. When User A calls the Complete method. User A's copy overwrites User B's copy. This is only an issue if the contents of the file changes between the time User A successfully downloads the file and the time User B downloads the file.

Q. What happens if two different users upload a file to the same location?

A. By default, BITS does not allow overwrites. The first upload to complete is written to the final destination folder. When the second job finishes the transfer and tries to write the file, BITS returns an error to the client. To allow overwrites, set the BITSAllowOverwrites property to true in the IIS metabase.

Q. Can I access or enumerate other user's jobs in the queue?

A. Only administrators can access or enumerate all jobs in the queue. For details, see the IBackgroundCopyManager::EnumJobs method.

Q. What if a user submits a job and never logs in again?

A. BITS automatically cancels jobs that do not make progress for 90 days. Administrators can set the JobInactivityTimeout Group Policy to specify a different timeout period.

Q. Will BITS ever initiate a network connection?

A. BITS will not initiate a network connection. BITS waits for a network connection before making transfer requests. However, BITS may force a dial-up for home networks that use Microsoft Internet Connection Sharing (ICS) if the ICS machine has the Establish a dial-up connection whenever a computer on my network attempts to access the Internet option set.

Q. Will BITS decrease its network usage in a timely manner?

A. Typically within two seconds.

Q. If the computer contains multiple network interfaces, such as a modem, virtual private network (VPN), and several network interface cards (NIC), which interface does BITS monitor to determine idle bandwidth?

A. BITS calls the IP Helper function, GetBestInterface, to determine the interface that has the best route to the specified IP address.

Q. How can I use BITS in applications where there is no user?

A. You can use BITS to transfer files from a service. For details, see the BITS documentation on Service Account and BITS in the Platform SDK.

Q. How does BITS behave in fast user switching (FUS) scenarios? Are the jobs per user or do they continue after a switch?

A. All jobs are associated with a particular user and may be downloaded as long as that user is logged on. In a FUS scenario, the disconnected users are still considered logged on, so BITS continues to download their jobs.

Q. Where does BITS put partially downloaded files?

A. BITS downloads the file to a temporary file in the destination folder. BITS impersonates the user before writing the file to ensure that file system security and quotas are enforced. When the application calls the IBackgroundCopyJob::Complete method on the job, BITS renames the temporary files to their destination names and the files are available to the client. If there is already a file in the destination with the same name, BITS overwrites the file.

Summary

This document is an introduction to the Background Intelligent Transfer Service. It is intended for IT professionals who are interested in using BITS from within a software application.

BITS transfers files using leftover bandwidth. For example, if you are currently using 60 percent of your bandwidth, BITS will only use the remaining 40 percent. BITS also maintains file transfers when a network disconnection occurs, or a computer needs to be restarted: When the network connection is re-established, BITS will continue where it left off.

Related Links

See the following resources for further information:

· BITS software development kit (SDK) at http://msdn.microsoft.com/

· Technical Overview of Networking and Communications at http://www.microsoft.com/windowsserver2003/techinfo/overview/netcomm.mspx

· Technical Overview of File Services at http://www.microsoft.com/windowsserver2003/techinfo/overview/file.mspx

· Windows XP Network Features and Enhancements at http://www.microsoft.com/windowsxp/pro/techinfo/planning/networking/overview/NetworkingInWindowsXP.doc

· Networking and Communications Services at http://www.microsoft.com/windows2000/technologies/communications/default.asp

· File Services at http://www.microsoft.com/windows2000/technologies/fileandprint/file/default.asp

For the latest information about the Microsoft Windows family, see the Windows Web site at http://www.microsoft.com/windows.

Last edited Sep 14, 2011 at 2:43 PM by dohly, version 1

Comments

No comments yet.