Establecer y recuperar las propiedades de un trabajo

El propietario del trabajo o un usuario con privilegios de administrador pueden establecer y recuperar las propiedades del trabajo en cualquier momento. Para obtener una lista completa de las propiedades que puede establecer y recuperar, consulte las interfaces IBackgroundCopyJob, IBackgroundCopyJob2, IBackgroundCopyJob3 e IBackgroundCopyJob4 .

Los archivos también contienen propiedades. Para obtener información sobre cómo recuperar un archivo y sus propiedades de un trabajo, vea Enumerar archivos en un trabajo.

Para transferir archivos, no es necesario cambiar los valores predeterminados de las propiedades del trabajo: BITS usa valores predeterminados que son adecuados para la aplicación típica.

Establecimiento de las propiedades de un trabajo

En el ejemplo siguiente se muestra cómo establecer las propiedades que es más probable que cambie la aplicación: prioridad, interfaz de notificación, marcas de notificación y nombre de archivo de respuesta. En el ejemplo se supone que el puntero de la interfaz IBackgroundCopyJob , pJob, es válido.

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();

De forma predeterminada, BITS descarga contenido del servidor de origen. Para descargar contenido de un mismo nivel, tanto el equipo como el trabajo deben habilitar el almacenamiento en caché del mismo nivel. Para habilitar el almacenamiento en caché del mismo nivel en el equipo, establezca la configuración de directiva de grupo EnablePeerCaching. También puede llamar al método IBitsPeerCacheAdministration::SetConfigurationFlags para habilitar el almacenamiento en caché del mismo nivel en el equipo; sin embargo, la directiva invalida la configuración de preferencias, si se establece. Para habilitar el almacenamiento en caché del mismo nivel para el trabajo, debe llamar al método IBackgroundCopyJob4::SetPeerCachingFlags .

Para especificar encabezados personalizados, un certificado de cliente para la autenticación de cliente y opciones HTTP, como la directiva de redirección, la comprobación de CRL y la especificación de los errores de certificado que se van a omitir, use la interfaz IBackgroundCopyJobHttpOptions . Para obtener la interfaz IBackgroundCopyJobHttpOptions , consulte cualquiera de las interfaces IBackgroundCopyJob .

Recuperar las propiedades de un trabajo

En el ejemplo siguiente se muestra cómo recuperar los valores de propiedad de nombre para mostrar, propietario, progreso y estado de un trabajo. En el ejemplo se supone que el puntero de la interfaz IBackgroundCopyJob , pJob, es válido.

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.
}