작업의 속성 설정 및 검색

작업 소유자 또는 관리자 권한이 있는 사용자는 언제든지 작업의 속성을 설정하고 검색할 수 있습니다. 설정하고 검색할 수 있는 속성의 전체 목록은 IBackgroundCopyJob, IBackgroundCopyJob2, IBackgroundCopyJob3 및 IBackgroundCopyJob4 인터페이스를 참조하세요.

파일에는 속성도 포함됩니다. 작업에서 파일 및 해당 속성을 검색하는 방법에 대한 자세한 내용은 작업 에서 파일 열거를 참조하세요.

파일을 전송하려면 작업 속성의 기본값을 변경할 필요가 없습니다. BITS는 일반적인 애플리케이션에 적합한 기본값을 사용합니다.

작업의 속성 설정

다음 예제에서는 애플리케이션이 변경될 가능성이 가장 높은 속성을 설정하는 방법을 보여줍니다. 우선 순위, 인터페이스 알림, 플래그 알림 및 회신 파일 이름입니다. 이 예제에서는 IBackgroundCopyJob 인터페이스 포인터 pJob이 유효하다고 가정합니다.

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

기본적으로 BITS는 원본 서버에서 콘텐츠를 다운로드합니다. 피어에서 콘텐츠를 다운로드하려면 컴퓨터와 작업 모두에서 피어 캐싱을 사용하도록 설정해야 합니다. 컴퓨터에서 피어 캐싱을 사용하도록 설정하려면 EnablePeerCaching 그룹 정책 설정을 지정합니다. IBitsPeerCacheAdministration::SetConfigurationFlags 메서드를 호출하여 컴퓨터에서 피어 캐싱을 사용하도록 설정할 수도 있습니다. 그러나 기본 설정은 설정된 경우 정책에 의해 재정의됩니다. 작업에 피어 캐싱을 사용하도록 설정하려면 IBackgroundCopyJob4::SetPeerCachingFlags 메서드를 호출해야 합니다.

사용자 지정 헤더, 클라이언트 인증을 위한 클라이언트 인증서 및 리디렉션 정책, CRL 검사 및 무시할 인증서 오류 지정과 같은 HTTP 옵션을 지정하려면 IBackgroundCopyJobHttpOptions 인터페이스를 사용합니다. IBackgroundCopyJobHttpOptions 인터페이스를 얻으려면 IBackgroundCopyJob 인터페이스를 쿼리합니다.

작업의 속성 검색

다음 예제에서는 작업의 표시 이름, 소유자, 진행률 및 상태 속성 값을 검색하는 방법을 보여줍니다. 이 예제에서는 IBackgroundCopyJob 인터페이스 포인터 pJob이 유효하다고 가정합니다.

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