Définition et récupération des propriétés d’un travail

Le propriétaire du travail ou un utilisateur disposant de privilèges d’administrateur peut définir et récupérer les propriétés du travail à tout moment. Pour obtenir la liste complète des propriétés que vous pouvez définir et récupérer, consultez les interfaces IBackgroundCopyJob, IBackgroundCopyJob2, IBackgroundCopyJob3 et IBackgroundCopyJob4 .

Les fichiers contiennent également des propriétés. Pour plus d’informations sur la récupération d’un fichier et de ses propriétés à partir d’un travail, consultez Énumération de fichiers dans un travail.

Pour transférer des fichiers, vous n’avez pas besoin de modifier les valeurs par défaut des propriétés du travail : BITS utilise des valeurs par défaut appropriées pour l’application standard.

Définition des propriétés d’un travail

L’exemple suivant montre comment définir les propriétés que votre application est susceptible de modifier : priorité, interface de notification, indicateurs de notification et nom du fichier de réponse. L’exemple suppose que le pointeur d’interface IBackgroundCopyJob , pJob, est valide.

HRESULT hr;
IBackgroundCopyJob* pJob;
IBackgroundCopyJob4* pJob4 = NULL;
CNotifyInterface *pNotify = new CNotifyInterface();

hr = pJob->QueryInterface(__uuidof(IBackgroundCopyJob4), (void**)&pJob4);
pJob->Release();

//The default priority level for a job is BG_JOB_PRIORITY_NORMAL. 
hr = pJob4->SetPriority(BG_JOB_PRIORITY_HIGH);
if (FAILED(hr))
{
  //Handle error
}

//By default, an application must poll BITS for the status of a job.
//To specify an IBackgroundCopyCallback interface pointer that receives event 
//notification based on the value of the notify flags property, set the notify 
//interface property. For details on the CNotifyInterface example class, see the 
//IBackgroundCopyCallback interface in the reference section.
hr = pJob4->SetNotifyInterface(pNotify);
if (SUCCEEDED(hr))
{
  hr = pJob4->SetNotifyFlags(BG_NOTIFY_JOB_TRANSFERRED | 
                            BG_NOTIFY_JOB_ERROR);
}
pNotify->Release();
if (FAILED(hr))
{
  //Handle error - failed to setup notification callbacks
}

//Only set the reply file name if the job's type is BG_JOB_TYPE_UPLOAD_REPLY.
//If you do not set the file name before calling the IBackgroundCopyJob::Resume 
//method, BITS generates a file name for you; the directory is the same as that
//specified for the local file name (the file being uploaded). To retrieve the 
//file name, call the IBackgroundCopyJob2::GetReplyFileName method.
hr = pJob4->SetReplyFileName(L"<REPLYPATHGOESHERE>");
if (FAILED(hr))
{
  //Handle error
}
pJob4->Release();

Par défaut, BITS télécharge le contenu à partir du serveur d’origine. Pour télécharger du contenu à partir d’un homologue, l’ordinateur et le travail doivent activer la mise en cache d’homologue. Pour activer la mise en cache d’homologue sur l’ordinateur, définissez le paramètre de stratégie de groupe EnablePeerCaching. Vous pouvez également appeler la méthode IBitsPeerCacheAdministration::SetConfigurationFlags pour activer la mise en cache d’homologue sur l’ordinateur ; toutefois, le paramètre de préférence est remplacé par la stratégie, s’il est défini. Pour activer la mise en cache d’homologue pour le travail, vous devez appeler la méthode IBackgroundCopyJob4::SetPeerCachingFlags .

Pour spécifier des en-têtes personnalisés, un certificat client pour l’authentification client et des options HTTP telles que la stratégie de redirection, la vérification de la liste de révocation de certificats et la spécification des erreurs de certificat à ignorer, utilisez l’interface IBackgroundCopyJobHttpOptions . Pour obtenir l’interface IBackgroundCopyJobHttpOptions , interrogez l’une des interfaces IBackgroundCopyJob .

Récupération des propriétés d’un travail

L’exemple suivant montre comment récupérer le nom d’affichage, le propriétaire, la progression et les valeurs de propriété d’état d’un travail. L’exemple suppose que le pointeur d’interface IBackgroundCopyJob , pJob, est valide.

HRESULT hr;
IBackgroundCopyJob* pJob;
WCHAR* pszJobName = NULL;
WCHAR* pszOwnerSid = NULL;
BOOL bResult;
DWORD dwNameSize = 0;
DWORD dwDomainSize = 0;
WCHAR* pszName = NULL;
WCHAR* pszDomain = NULL;
WCHAR* pszFullOwnerName = NULL;
PSID pSid = NULL;
SID_NAME_USE eNameUse;
BG_JOB_PROGRESS Progress;
int PercentOfFiles = 0;
BG_JOB_PRIORITY Priority;
BG_JOB_STATE State;
//WCHAR *JobStates[] = { L"Queued", L"Connecting", L"Transferring",
//                       L"Suspended", L"Error", L"Transient Error",
//                       L"Transferred", L"Acknowledged", L"Canceled"
//                     };

//Name of the job to use in the user interface. The name is set when you 
//create the job. You can use the SetDisplayName method to change the name. 
hr = pJob->GetDisplayName(&pszJobName);
if (SUCCEEDED(hr))
{
  //Use the name in a user interface or output.
  CoTaskMemFree(pszJobName);       
}

//The owner property contains the SID of the job's owner. The following code
//shows how to get the domain and user names associated with the SID.
hr = pJob->GetOwner(&pszOwnerSID);
if (SUCCEEDED(hr))
{
  bResult = ConvertStringSidToSid(pszOwnerSid, &pSid);
  CoTaskMemFree(pszOwnerSid);
  if (bResult)
  {
    //Call LookupAccountSid twice. The first call retrieves the buffer size 
    //for name and domain and the second call retrieves the actual name and domain.
    LookupAccountSid(NULL, pSid, NULL, &cbNameSize, 
                               NULL, &cbDomainSize, &eNameUse);
    LastError = GetLastError();
    if (ERROR_INSUFFICIENT_BUFFER == LastError)
    {
      pszName = (WCHAR*)malloc(sizeof(WCHAR) * cbNameSize);
      pszDomain = (WCHAR*)malloc(sizeof(WCHAR) * cbDomainSize);
      if (pszName && pszDomain)
      {
        bResult = LookupAccountSid(NULL, pSid, pszName, &cbNameSize, 
                                   pszDomain, &cbDomainSize, &eNameUse);
        if (bResult)
        {
          pszFullName = (WCHAR*)malloc(sizeof(WCHAR)*(cbDomainSize+1+cbNameSize+1));
          if (pszFullName)
          {
            StringCchPrintf(pszFullName, cbDomainSize+1+cbNameSize+1, L"%s\\%s", pszDomain, pszName);
            //Do something with pszFullName. 
            free(pszFullName);
          }
        }
      }
      if (pszDomain)
        free(pszDomain);
      if(pszName)
        free(pszName);
    }
    else
    {
      //Handle error - most likely ERROR_NONE_MAPPED, could not find the SID.
    }
    LocalFree(pSid);
  }
}

//The state property identifies the current state of the job. For example, the 
//state of the job is BG_JOB_STATE_TRANSFERRING or BG_JOB_STATE_ERROR. 
hr = pJob->GetState(&State);
if (SUCCEEDED(hr))
{
  //Use JobStates[State] to set the text representation of the job's 
  //state in a user interface.
}

//Use the information contained in the BG_JOB_PROGRESS structure to determine the 
//overall progress of the job. The structure contains information on the number of 
//bytes and files transferred. 
hr = pJob->GetProgress(&Progress);
if (SUCCEEDED(hr))
{
  //Determine the progress of the job based on the number of files transferred.
  if (Progress.FilesTotal > 0)
  {
    PercentOfFiles = 100*Progress.FilesTransferred/Progress.FilesTotal
  }
  //For an example that shows determining the progress of the job based on the 
  //number of bytes transferred, see the topic Determing the Progress of a Job.
}