BITS HTTPHEADER Sample
Summary
This sample
demonstrates using the BITS APIs that allow you to modify HTTP headers. HTTP
headers are in the HTTP 1.1 protocol to allow HTTP servers and HTTP clients to
communicate their intentions. For example a request header can be passed by a
client to a server that gives the server additional information about the
request. The HTTP 1.1 specification (http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
provides some examples of the usage of headers.
Should a
client pass a request header like:
Accept: audio/*;
q=0.2, audio/basic
This should
be interpreted by the server as "I prefer audio/basic, but send me any
audio type if it is the best available after an 80% mark-down in quality."
The Accept
request-header field can be used to specify certain media types which are
acceptable for the response. Accept headers can be used to indicate that the
request is specifically limited to a small set of desired types, as in the case
of a request for an in-line image.
BITS
has
the ability to allow API callers to specify their own custom headers that are
passed to the HTTP server as part of the HTTP protocol.
Program flow
In this
sample, the request property “Accept-Encoding: gzip,
deflate” is used. When passed to the server, it tells the server that the
client will accept responses compressed in gzip
format. HTTPHEADER.cpp builds on the concepts established in the DOWNLOADS.cpp
example, it is recommended that you review DOWNLOADS.cpp prior to reviewing
this sample – it will aid understanding of the program flow. The key difference
between the two samples is the use of the SetCustomHeaders method in the IBackgroundCopyJobHttpOptions interface.
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
- Adding
a header to the HTTP request made by BITS.
- Submission
of a job
- Processing
notifications on completion.
- Use
of BITS IBackgroundCopyManager
- Use
of BITS IBackgroundCopyJob(n)
- Use
of BITS IBackgroundCopyJobHttpOptions
Build/Configuration instructions
- Run
"VCBuild HTTPHEADER" in the directory
where the sources are. Or, use Visual Studio to build the job. Optionally,
the binaries are provided.
- Execute
HTTPHEADERS.exe.
Basic Usage
- Select
a file on a HTTP server 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 HTTPHEADER.exe <RemoteName>
<LocalName>
- When
the HTTPHEADER completes or fails, you will be notified.
Notes:
- It
is suggested that a loosely spaced .txt file is used for the download.
- In
order for a compressed file to be returned in IIS, the file must have an
extension that is eligible for compression, and compression must be
enabled (default setting).
- Ensure
that the IIS setting for the minimum size of response to compress is
smaller than the size of the text file.
- When
a request is made for a compressed file, IIS checks to see if the file is
in the temporary compression directory. If not, it sends the uncompressed
version to the requestor, and starts a background task to compress the
response and place it into the temporary compression directory. This means
that the 1st request will always be uncompressed.
System configuration
- To
be able to compile the samples, the Windows Vista SDK must be installed.
- The
sample code requires BITS version 2.5 or later. BITS 3.0 is available as
part of Windows Vista, or Windows codename Server 2008.