BITS DOWNLOADS Sample
Summary
This sample
demonstrates the use of new BITS APIs to download files.
Program flow
- DOWNLOADS.cpp
begins by determining that the correct number of arguments has been used
on the command line. If not, a usage summary is output and the program
ends.
- The
next step is to initialize COM. Note that the security level is then set
to RPC_C_IMP_LEVEL_IMPERSONATE. This is the lowest security level that
will work for our purposes.
- If
all of that goes correctly, we then instanciate
an instance of IBackgroundCopyManager. In
effect, this puts us in communication with the BITS processes that may be
running in the test machine. If any of these fail, a suitable message is
output, and the job ends.
- We
use the IBackgroundCopyManager to create a new
BITS job. In doing so, we pass it the name we wish to use for the job, and
an enumeration telling the manager that it is a download job. When it
returns, assuming a good completion code, it will pass back a new Globaly Uniquie Identifier (GUID), and a pointer to another COM object that is an IBackgroundCopyJob.
- In
the downloads.h file, we described a class named
CNotifyInterface. CNotifyInterface
inherits from IBackgroundCopyCallback2. We use this newly instanciated object by telling the IBackgroundCopyJob
to set it as our Notify Interface. This Notify Interface will be called
when certain events occur.
- Next
the remote and local file names are added.
- Once
files have been added to the job, the job is “Resumed”. This command tells
the job to begin its work.
- Downloads.cpp
is now almost done. This main thread falls into a dispatch loop, looking
for a WM_QUIT message, and dispatching any other messages it finds.
Key Concepts
- Basic
connection with BITS job manager and submission of BITS jobs
- Adding
a file to the job
- Registration
of a job callback for special handling of errors and job states
- Submission
of download job
- Processing
notifications on completion.
- Use
of BITS IBackgroundCopyManager
- Use
of BITS IBackgroundCopyJob(n)
Build/Configuration instructions
- Run
"VCBuild Downloads" in the directory
where the sources are. Or, use Visual Studio to build the job. Optionally,
the binaries are provided.
- Execute
DOWNLOADS.exe.
Basic Usage
- Select
a file on a remote computer that your test machine has access to.
- Select
a location and name for the downloaded file to occupy on the test machine.
- Enter
the command DOWNLOADS.exe <RemoteName>
<LocalName>
- When
the download completes or fails, you will be notified.
System configuration
- To
be able to compile the samples, the Windows Vista SDK must be installed.
- The
sample code requires BITS version 1.0 or later. BITS 3.0 is available as
part of Windows Vista, or Windows codename Server 2008.