Comment obtenir le dernier ensemble d’en-têtes HTTP reçus pour chaque fichier dans un travail de téléchargement BITS
Cet exemple montre comment utiliser la méthode GetProperty de la nouvelle interface IBackgroundCopyJob5 pour obtenir les derniers en-têtes HTTP définis reçus pour chaque fichier dans un travail de téléchargement BITS (Background Intelligent Transfer Service). Les informations contenues dans l’en-tête HTTP peuvent être utilisées, par exemple, pour déterminer le type de fichier ou le moment où elles ont été modifiées pour la dernière fois sur le serveur. Avant Windows 8 et Windows Server 2012, BITS ne permettait pas à l’application de récupérer et d’inspecter les en-têtes de réponse HTTP d’un téléchargement terminé. Cet exemple montre comment utiliser l’API BITS pour créer un travail BITS avec plusieurs URL à télécharger, répertorier les URL d’un travail et récupérer les en-têtes de réponse HTTP pour chaque URL.
Bon à savoir
Technologies
Prérequis
- Microsoft Visual Studio
Instructions
Étape 1 : Inclure les fichiers d’en-tête BITS requis
Insérez les directives d’en-tête suivantes en haut du fichier source.
#include <bits.h>
Étape 2 : Initialiser COM et instancier une interface d’objet Gestionnaire de copie en arrière-plan BITS
Avant d’instancier l’interface IBackgroundCopyManager (utilisée pour créer un travail BITS), vous devez initialiser COM et définir le modèle de thread com souhaité.
// Initialize COM and specify the appropriate COM threading model for your application.
IBackgroundCopyManager* pManager;
HRESULT hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);
if (SUCCEEDED(hr))
{
hr = CoCreateInstance(__uuidof(BackgroundCopyManager),
NULL,
CLSCTX_LOCAL_SERVER,
__uuidof(IBackgroundCopyManager),
(void**) &pManager);
}
Étape 3 : Créer le travail BITS
Seul l’utilisateur qui crée le travail ou un utilisateur disposant de privilèges d’administrateur peut ajouter des fichiers au travail et modifier les propriétés du travail.
GUID guidJob;
IBackgroundCopyJob* pBackgroundCopyJob;
hr = pManager->CreateJob(L"TransferPolicy",
BG_JOB_TYPE_DOWNLOAD,
&guidJob,
(IBackgroundCopyJob **)&pBackgroundCopyJob);
Étape 4 : Ajouter les fichiers au travail BITS
L’exemple suivant télécharge des documents accessibles au public à partir du Centre de téléchargement Microsoft. Vous devrez modifier ces valeurs pour votre environnement spécifique.
// Array that contains multiple DOWNLOAD_FILE data structures that represent the
// files that will be added to the download job.
DOWNLOAD_FILE FileList[] =
{
{
L"https://download.microsoft.com/download/0/2/8/02809141-3329-4412-8AC4-AA41B406055C/WinRT81-HttpClient-BT-Socket-Poster.pdf",
L"c:\\temp\\data\\WinRT81-HttpClient-BT-Socket-Poster.pdf"
},
{
L"https://download.microsoft.com/download/6/6/2/662DD05E-BAD7-46EF-9431-135F9BAE6332/9781509302963_Microsoft%20Azure%20Essentials%20Fundamentals%20of%20Azure%202nd%20ed%20pdf.pdf",
L"c:\\temp\\data\\Fundamentals of Azure.pdf"
},
{
L"https://aka.ms/WinServ16/StndPDF",
L"c:\\temp\\data\\IntroducingWindowsServer2016.pdf"
}
};
...
// Add the files to the job.
for (int i=0; i < ARRAY_LENGTH(FileList); ++i)
{
hr = Job->AddFile(FileList[i].RemoteFile,
FileList[i].LocalFile);
...
}
Étape 5 : Démarrer le travail BITS
Après avoir configuré le travail BITS, appelez la fonction Resume de l’interface IBackgroundCopyJob pour démarrer ou poursuivre le téléchargement.
// Start the BITS job.
hr = pBackgroundJob->Resume();
Étape 6 : Surveiller et afficher la progression du travail BITS
La MonitorJobProgress fonction d’assistance prend un objet IBackgroundCopyJob comme seul paramètre et interroge le travail pour un status toutes les 500 millisecondes. Cette fonction ne retourne pas tant que le travail n’est pas terminé ou annulé.
HRESULT MonitorJobProgress(__in IBackgroundCopyJob* Job)
{
HRESULT hr;
LPWSTR JobName;
BG_JOB_STATE State;
int PreviousState = -1;
bool Exit = false;
int ProgressCounter = 0;
hr = Job->GetDisplayName(&JobName);
printf("Progress report for download job '%ws'.\n", JobName);
CoTaskMemFree(JobName);
// Display the download progress.
while (!Exit)
{
hr = Job->GetState(&State);
if (State != PreviousState)
{
switch(State)
{
case BG_JOB_STATE_QUEUED:
printf("Job is in the queue and waiting to run.\n");
break;
case BG_JOB_STATE_CONNECTING:
printf("BITS is trying to connect to the remote server.\n");
break;
case BG_JOB_STATE_TRANSFERRING:
printf("BITS has started downloading data.\n");
DisplayProgress( Job );
break;
case BG_JOB_STATE_ERROR:
wprintf(L"ERROR: BITS has encountered a non-recoverable error.\n");
DisplayError(Job);
wprintf(L" Exiting job.\n");
Exit = true;
break;
case BG_JOB_STATE_TRANSIENT_ERROR:
wprintf(L"ERROR: BITS has encountered a recoverable error.\n");
DisplayError(Job);
wprintf(L" Continuing to retry.\n");
break;
case BG_JOB_STATE_TRANSFERRED:
DisplayProgress(Job);
printf("The job has been successfully completed.\n");
printf("Finalizing local files.\n");
Job->Complete();
break;
case BG_JOB_STATE_ACKNOWLEDGED:
printf("Finalization complete.\n");
Exit = true;
break;
case BG_JOB_STATE_CANCELLED:
printf("WARNING: The job has been cancelled.\n");
Exit = true;
break;
default:
printf("WARNING: Unknown BITS state %d.\n", State);
Exit = true;
}
PreviousState = State;
}
else if (State == BG_JOB_STATE_TRANSFERRING)
{
// Display job progress every 2 seconds.
if (++ProgressCounter % TWO_SECOND_LOOP == 0)
{
DisplayProgress( Job );
}
}
Sleep(HALF_SECOND_AS_MILLISECONDS);
}
printf("\n");
return hr;
}
// Display the current progress of the job in terms of the amount of data
// and number of files transferred.
VOID DisplayProgress(__in IBackgroundCopyJob *Job)
{
HRESULT hr;
BG_JOB_PROGRESS Progress;
hr = Job->GetProgress(&Progress);
if (SUCCEEDED(hr))
{
printf("%llu of %llu bytes transferred (%lu of %lu files).\n",
Progress.BytesTransferred, Progress.BytesTotal,
Progress.FilesTransferred, Progress.FilesTotal);
}
}
Étape 7 : Afficher les en-têtes de fichier téléchargés
La DisplayFileHeaders fonction d’assistance énumère les travaux définis pour un objet IBackgroundCopyJob .
// For each file in the job, obtain and display the HTTP header received server.
HRESULT DisplayFileHeaders(__in IBackgroundCopyJob *Job)
{
HRESULT hr;
IEnumBackgroundCopyFiles *FileEnumerator;
hr = Job->EnumFiles(&FileEnumerator);
if (SUCCEEDED(hr))
{
ULONG Count;
hr = FileEnumerator->GetCount(&Count);
if (SUCCEEDED(hr))
{
for (ULONG i=0; i < Count; ++i)
{
IBackgroundCopyFile *TempFile;
hr = FileEnumerator->Next(1, &TempFile, NULL);
if (SUCCEEDED(hr))
{
IBackgroundCopyFile5 *File;
hr = TempFile->QueryInterface(__uuidof( IBackgroundCopyFile5 ), (void **) &File);
if (SUCCEEDED(hr))
{
LPWSTR RemoteFileName;
hr = File->GetRemoteName(&RemoteFileName);
if (SUCCEEDED(hr))
{
printf("HTTP headers for remote file '%ws'\n", RemoteFileName );
CoTaskMemFree( RemoteFileName );
RemoteFileName = NULL;
}
BITS_FILE_PROPERTY_VALUE Value;
hr = File->GetProperty(BITS_FILE_PROPERTY_ID_HTTP_RESPONSE_HEADERS, &Value);
if (SUCCEEDED(hr) && Value.String)
{
printf("Headers: %ws\n", Headers );
CoTaskMemFree(Value.String);
Value.String = NULL;
}
File->Release();
File = NULL;
}
TempFile->Release();
TempFile = NULL;
}
}
}
FileEnumerator->Release();
FileEnumerator = NULL;
}
return S_OK;
}
Exemple
L’exemple de code suivant est une application console entièrement opérationnelle qui montre comment utiliser l’API BITS pour créer un travail BITS avec plusieurs URL à télécharger, répertorier les URL d’un travail et récupérer les en-têtes de réponse HTTP pour chaque URL.
//*********************************************************
//
// Copyright (c) Microsoft. All rights reserved.
// This code is licensed under the Microsoft Public License.
// THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY
// IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR
// PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.
//
//*********************************************************
#define WIN32_LEAN_AND_MEAN // Exclude rarely-used stuff from Windows headers
#include <windows.h>
#include <bits.h>
#include <stdio.h> // needed for wprintf
#include <strsafe.h>
#define ARRAY_LENGTH(x) (sizeof(x) / sizeof( *(x) ))
// Definition of constants.
static const unsigned int HALF_SECOND_AS_MILLISECONDS = 500;
static const unsigned int TWO_SECOND_LOOP = 2000 / HALF_SECOND_AS_MILLISECONDS;
// Simple data structure that contains the remote and local names for a file.
typedef struct
{
LPCWSTR RemoteFile;
LPCWSTR LocalFile;
} DOWNLOAD_FILE;
// Array that contains sample DOWNLOAD_FILE data structures that represent the files
// that will be added to the download job.
DOWNLOAD_FILE FileList[] =
{
{
L"https://download.microsoft.com/download/0/2/8/02809141-3329-4412-8AC4-AA41B406055C/WinRT81-HttpClient-BT-Socket-Poster.pdf",
L"c:\\temp\\data\\WinRT81-HttpClient-BT-Socket-Poster.pdf"
},
{
L"https://download.microsoft.com/download/6/6/2/662DD05E-BAD7-46EF-9431-135F9BAE6332/9781509302963_Microsoft%20Azure%20Essentials%20Fundamentals%20of%20Azure%202nd%20ed%20pdf.pdf",
L"c:\\temp\\data\\Fundamentals of Azure.pdf"
},
{
L"https://aka.ms/WinServ16/StndPDF",
L"c:\\temp\\data\\IntroducingWindowsServer2016.pdf"
}
};
// Forward declaration of functions.
HRESULT GetBackgroundCopyManager(__out IBackgroundCopyManager **Manager);
HRESULT CreateDownloadJob(__in LPCWSTR Name, __in IBackgroundCopyManager *Manager, __out IBackgroundCopyJob **Job);
HRESULT MonitorJobProgress(__in IBackgroundCopyJob *Job);
HRESULT DisplayFileHeaders(__in IBackgroundCopyJob *Job);
VOID DisplayProgress(__in IBackgroundCopyJob *Job);
VOID DisplayHeaders(__in LPWSTR Headers);
VOID DisplayError(__in IBackgroundCopyJob *Job);
// Main program entry point.
int wmain(int argc, wchar_t* argv[])
{
HRESULT hr;
IBackgroundCopyManager *Manager;
// Get the BITS Background Copy Manager.
hr = GetBackgroundCopyManager(&Manager);
if (SUCCEEDED(hr))
{
IBackgroundCopyJob *Job;
// Create a new download job.
hr = CreateDownloadJob(L"MyJob", Manager, &Job);
if (SUCCEEDED(hr))
{
// Add files to the job.
for (int i = 0; i < ARRAY_LENGTH(FileList); ++i)
{
hr = Job->AddFile(FileList[i].RemoteFile, FileList[i].LocalFile);
if (FAILED(hr))
{
wprintf(L"Error: Unable to add remote file '%ws' to the download job (error %08X).\n",
FileList[i].RemoteFile,
hr);
}
else
{
wprintf(L"Downloading remote file '%ws' to local file '%ws'\n",
FileList[i].RemoteFile, FileList[i].LocalFile);
}
}
// Start the job and display its progress.
hr = Job->Resume();
if (FAILED(hr))
{
wprintf(L"ERROR: Unable to start the BITS download job (error code %08X).\n", hr);
}
else
{
MonitorJobProgress(Job);
}
// Release the BITS IBackgroundCopyJob interface.
Job->Release();
Job = NULL;
}
// Release the IBackgroundCopyManager interface.
Manager->Release();
Manager = NULL;
}
return 0;
}
/**
* Gets a pointer to the BITS Background Copy Manager.
*
* If successful, this function returns a success code and sets the
* referenced IBackgroundCopyFileManager interface pointer to a
* reference counted instance of the Background Copy Manager interface.
*/
HRESULT GetBackgroundCopyManager(__out IBackgroundCopyManager **Manager)
{
HRESULT hr;
//Specify the appropriate COM threading model for your application.
hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);
if (SUCCEEDED(hr))
{
hr = CoCreateInstance(__uuidof(BackgroundCopyManager),
NULL,
CLSCTX_LOCAL_SERVER,
__uuidof(IBackgroundCopyManager),
(void**)Manager);
}
else
{
wprintf(L"ERROR: Unable to initialize COM (error code %08X).\n", hr);
}
return hr;
}
/**
* Creates a new download job with the specified name.
*/
HRESULT CreateDownloadJob(__in LPCWSTR Name, __in IBackgroundCopyManager *Manager, __out IBackgroundCopyJob **Job)
{
GUID guid;
return Manager->CreateJob(Name, BG_JOB_TYPE_DOWNLOAD, &guid, Job);
}
/**
* Monitors and displays the progress of the download job.
*
* A new status message is output whenever the job's status changes or,
* when transferring data, every 2 seconds displays how much data
* has been transferred.
*/
HRESULT MonitorJobProgress(__in IBackgroundCopyJob *Job)
{
HRESULT hr;
LPWSTR JobName;
BG_JOB_STATE State;
int PreviousState = -1;
bool Exit = false;
int ProgressCounter = 0;
hr = Job->GetDisplayName(&JobName);
wprintf(L"Progress report for download job '%ws'.\n", JobName);
CoTaskMemFree(JobName);
// Display the download progress.
while (!Exit)
{
hr = Job->GetState(&State);
if (State != PreviousState)
{
switch (State)
{
case BG_JOB_STATE_QUEUED:
wprintf(L"Job is in the queue and waiting to run.\n");
break;
case BG_JOB_STATE_CONNECTING:
wprintf(L"BITS is trying to connect to the remote server.\n");
break;
case BG_JOB_STATE_TRANSFERRING:
wprintf(L"BITS has started downloading data.\n");
DisplayProgress(Job);
break;
case BG_JOB_STATE_ERROR:
wprintf(L"ERROR: BITS has encountered a non-recoverable error.\n");
DisplayError(Job);
wprintf(L" Exiting job.\n");
Exit = true;
break;
case BG_JOB_STATE_TRANSIENT_ERROR:
wprintf(L"ERROR: BITS has encountered a recoverable error.\n");
DisplayError(Job);
wprintf(L" Continuing to retry.\n");
break;
case BG_JOB_STATE_TRANSFERRED:
DisplayProgress(Job);
wprintf(L"The job has been successfully completed.\n");
wprintf(L"Finalizing local files.\n");
Job->Complete();
break;
case BG_JOB_STATE_ACKNOWLEDGED:
wprintf(L"Finalization complete.\n");
Exit = true;
break;
case BG_JOB_STATE_CANCELLED:
wprintf(L"WARNING: The job has been cancelled.\n");
Exit = true;
break;
default:
wprintf(L"WARNING: Unknown BITS state %d.\n", State);
Exit = true;
}
PreviousState = State;
}
else if (State == BG_JOB_STATE_TRANSFERRING)
{
// Display job progress every 2 seconds.
if (++ProgressCounter % TWO_SECOND_LOOP == 0)
{
DisplayProgress(Job);
}
}
Sleep(HALF_SECOND_AS_MILLISECONDS);
}
wprintf(L"\n");
if (SUCCEEDED(hr))
{
hr = DisplayFileHeaders(Job);
}
return hr;
}
/**
* For each file in the job, obtains the (final) HTTP headers received from the
* remote server that hosts the files and then displays the HTTP headers.
*/
HRESULT DisplayFileHeaders(__in IBackgroundCopyJob *Job)
{
HRESULT hr;
IEnumBackgroundCopyFiles *FileEnumerator;
wprintf(L"Individual file information.\n");
hr = Job->EnumFiles(&FileEnumerator);
if (FAILED(hr))
{
wprintf(L"WARNING: Unable to obtain an IEnumBackgroundCopyFiles interface.\n");
wprintf(L" No further information can be provided about the files in the job.\n");
}
else
{
ULONG Count;
hr = FileEnumerator->GetCount(&Count);
if (FAILED(hr))
{
wprintf(L"WARNING: Unable to obtain a count of the number of files in the job.\n");
wprintf(L" No further information can be provided about the files in the job.\n");
}
else
{
for (ULONG i = 0; i < Count; ++i)
{
IBackgroundCopyFile *TempFile;
hr = FileEnumerator->Next(1, &TempFile, NULL);
if (FAILED(hr))
{
wprintf(L"WARNING: Unable to obtain an IBackgroundCopyFile interface for the next file in the job.\n");
wprintf(L" No further information can be provided about this file.\n");
}
else
{
IBackgroundCopyFile5 *File;
hr = TempFile->QueryInterface(__uuidof(IBackgroundCopyFile5), (void **)&File);
if (FAILED(hr))
{
wprintf(L"WARNING: Unable to obtain an IBackgroundCopyFile5 interface for the file.\n");
wprintf(L" No further information can be provided about this file.\n");
}
else
{
LPWSTR RemoteFileName;
hr = File->GetRemoteName(&RemoteFileName);
if (FAILED(hr))
{
wprintf(L"WARNING: Unable to obtain the remote file name for this file.\n");
}
else
{
wprintf(L"HTTP headers for remote file '%ws'\n", RemoteFileName);
CoTaskMemFree(RemoteFileName);
RemoteFileName = NULL;
}
BITS_FILE_PROPERTY_VALUE Value;
hr = File->GetProperty(BITS_FILE_PROPERTY_ID_HTTP_RESPONSE_HEADERS, &Value);
if (FAILED(hr))
{
wprintf(L"WARNING: Unable to obtain the HTTP headers for this file.\n");
}
else
{
if (Value.String)
{
DisplayHeaders(Value.String);
CoTaskMemFree(Value.String);
Value.String = NULL;
}
}
File->Release();
File = NULL;
}
TempFile->Release();
TempFile = NULL;
}
}
}
FileEnumerator->Release();
FileEnumerator = NULL;
}
return S_OK;
}
/**
* Displays the current progress of the job in terms of the amount of data
* and number of files transferred.
*/
VOID DisplayProgress(__in IBackgroundCopyJob *Job)
{
HRESULT hr;
BG_JOB_PROGRESS Progress;
hr = Job->GetProgress(&Progress);
if (SUCCEEDED(hr))
{
wprintf(L"%llu of %llu bytes transferred (%lu of %lu files).\n",
Progress.BytesTransferred, Progress.BytesTotal,
Progress.FilesTransferred, Progress.FilesTotal);
}
else
{
wprintf(L"ERROR: Unable to get job progress (error code %08X).\n", hr);
}
}
/**
* Parses the provided string that contains HTTP headers,
* splits them apart and displays them to the user.
*/
VOID DisplayHeaders(__in LPWSTR Headers)
{
wprintf(L"Headers: %ws\n", Headers);
}
VOID DisplayError(__in IBackgroundCopyJob *Job)
{
HRESULT hr;
IBackgroundCopyError *Error;
LPWSTR ErrorDescription;
hr = Job->GetError(&Error);
if (FAILED(hr))
{
wprintf(L"WARNING: Unable to get job error information (code %08X)\n", hr);
}
else
{
BG_ERROR_CONTEXT ErrorContext;
HRESULT ErrorResult;
hr = Error->GetError(&ErrorContext, &ErrorResult);
if (FAILED(hr))
{
wprintf(L"WARNING: Unable to get job error code information (code %08X)\n", hr);
}
else
{
hr = Error->GetErrorDescription(LANGIDFROMLCID(GetThreadLocale()), &ErrorDescription);
if (FAILED(hr))
{
wprintf(L"WARNING: Unable to get job error description (code %08X) for %08X\n", hr, ErrorResult);
}
else
{
wprintf(L" Error details: code %08X %ws\n", ErrorResult, ErrorDescription);
CoTaskMemFree(ErrorDescription);
}
}
Error->Release();
}
}