IBackgroundCopyJob3::AddFileWithRanges 메서드(bits2_0.h)

  • 아티클

다운로드 작업에 파일을 추가하고 다운로드할 파일의 범위를 지정합니다.

구문

HRESULT AddFileWithRanges(
  [in] LPCWSTR          RemoteUrl,
  [in] LPCWSTR          LocalName,
  [in] DWORD            RangeCount,
  [in] BG_FILE_RANGE [] Ranges
);

매개 변수

[in] RemoteUrl

서버의 파일 이름을 포함하는 Null로 끝나는 문자열입니다. 원격 이름을 지정하는 방법에 대한 자세한 내용은 BG_FILE_INFO 구조체의 RemoteName 멤버 및 주의 섹션을 참조하세요.

BITS 3.0부터 범위에서 SMB 프로토콜이 지원되지 않습니다.

BITS 2.5 및 2.0: BITS는 범위에 대한 SMB 프로토콜을 지원합니다.

[in] LocalName

클라이언트의 파일 이름을 포함하는 Null로 끝나는 문자열입니다. 로컬 이름을 지정하는 방법에 대한 자세한 내용은 BG_FILE_INFO 구조체의 LocalName 멤버 및 설명 섹션을 참조하세요.

[in] RangeCount

범위의 요소 수입니다.

[in] Ranges

다운로드할 범위를 지정하는 하나 이상의 BG_FILE_RANGE 구조체 배열입니다. 중복되거나 겹치는 범위를 지정하지 마세요.

반환 값

이 메서드는 다음 반환 값뿐만 아니라 다른 값을 반환합니다.

반환 코드 설명
S_OK
 Success
E_INVALIDARG
 다음 이유 중 하나로 이 오류가 발생할 수 있습니다.
  • RangeCount 매개 변수는 0입니다. 하나 이상의 범위를 지정해야 합니다.
  • 로컬 또는 원격 파일 이름이 잘못되었습니다.
  • 원격 파일 이름은 지원되지 않는 프로토콜을 사용합니다.
  • 로컬 파일 이름은 상대 경로를 사용하여 지정되었습니다.
E_NOTIMPL
 업로드 또는 업로드-회신 작업에 대해 이 메서드를 호출할 수 없습니다. 만 다운로드 작업에 대해이 메서드를 호출합니다.
E_ACCESSDENIED
 사용자에게 클라이언트의 지정된 디렉터리에 쓸 수 있는 권한이 없습니다.
BG_E_INVALID_RANGE
 범위 중 하나가 잘못되었습니다. 예를 들어 InitialOffset은 BG_LENGTH_TO_EOF.
BG_E_OVERLAPPING_RANGES
 중복되거나 겹치는 범위는 지정할 수 없습니다.
참고 범위는 길이가 아닌 값의 오프셋을 기준으로 정렬됩니다. 오프셋이 같지만 역순인 범위를 입력하면 이 오류가 반환됩니다. 예를 들어 100.5 및 100.0을 해당 순서로 입력하면 작업에 파일을 추가할 수 없습니다.
 
BG_E_TOO_MANY_RANGES_IN_FILE
 MaxRangesPerFile 그룹 정책 설정은 파일에 대해 지정할 수 있는 범위 수를 결정합니다. 이러한 범위를 추가하면 MaxRangesPerFile 제한이 초과됩니다.
BG_E_INVALID_STATE
 작업의 상태는 BG_JOB_STATE_CANCELLED 또는 BG_JOB_STATE_ACKNOWLEDGED 수 없습니다.

설명

범위는 지정된 순서대로 LocalName 파일에 기록됩니다. 예를 들어 Ranges 가 원격 파일의 바이트 100-199, 900-999 및 400-499를 식별하는 경우 로컬 파일의 길이는 300바이트입니다. 로컬 파일의 바이트 0-99에는 원격 파일의 바이트 100-199가 포함되고, 로컬 파일의 바이트 100-199에는 원격 파일의 바이트 900-999가 포함되며, 로컬 파일의 바이트 200-299에는 원격 파일의 바이트 400-499가 포함됩니다.

다음 표에서는 작업을 다시 시작하면 발생할 수 있는 가능한 오류 코드를 식별합니다. 이러한 오류는 작업을 BG_JOB_STATE_ERROR 상태로 설정합니다.

오류 코드 Description
BG_E_INVALID_SERVER_RESPONSE BITS는 중복되거나 겹치는 범위를 통합하는 서버를 지원하지 않습니다.
BG_E_INVALID_RANGE 범위 중 하나는 원격 파일의 경계 밖에 있습니다.
BG_E_INSUFFICIENT_RANGE_SUPPORT 서버는 범위를 지원하지 않습니다.
 

BITS는 전송하는 파일의 버전(콘텐츠가 아닌 파일 크기 및 날짜 기준)이 일관되도록 보장합니다. 그러나 파일 집합이 일관될 것이라고 보장하지는 않습니다. 예를 들어 BITS가 서버에서 파일을 업데이트할 때 작업에서 두 번째 파일 중 두 번째 파일을 다운로드하는 중이면 BITS는 두 번째 파일의 다운로드를 다시 시작합니다. 그러나 첫 번째 파일은 다시 다운로드되지 않습니다.

기본적으로 사용자는 파일에 대해 최대 500개의 범위를 추가할 수 있습니다. 이 제한은 관리자 또는 서비스 계정에는 적용되지 않습니다. 기본값을 변경하려면 MaxRangesPerFile 그룹 정책을 설정합니다.

Windows Vista 이전: 사용자가 작업에 추가할 수 있는 파일 수에는 제한이 없습니다.

Windows BranchCache 사용 파일 전송의 성능을 향상시키려면 범위 길이를 400바이트 이상으로 설정하는 것이 좋습니다.

예제

다음 예제에서는 AddFileWithRanges 메서드를 호출하여 다운로드할 파일의 범위를 지정하는 방법을 보여 줍니다. 이 예제에서는 IBackgroundCopyJob 변수 pJob이 유효하다고 가정합니다.

    IBackgroundCopyJob *pJob;
    IBackgroundCopyJob3 *pJob3 = NULL;
    DWORD dwRangeCount = 3;                  //Number of elements in Ranges.
    BG_FILE_RANGE Ranges[] = {24, 17,        //Array of ranges to download (offset and length).
                              111, BG_LENGTH_TO_EOF,
                              83, 7
                             };

    //Need to query the IBackgroundCopyJob interface for an IBackgroundCopyJob3
    //interface pointer. The IBackgroundCopyJob3 interface contains the AddFileWithRanges method.
    hr = pJob->QueryInterface(__uuidof( IBackgroundCopyJob3 ), (void**)&pJob3;);
    if (S_OK == hr)
    {
         pJob->Release(); //No longer need the IBackgoundCopyJob interface pointer.

         //Add a file to the job and specify the ranges from the file to download.
         hr = pJob3->AddFileWithRanges(L"<REMOTENAMEGOESHERE>", L"<LOCALNAMEGOESHERE>",
                                       dwRangeCount, Ranges);
         if (FAILED(hr))
         {
              //Handle error.
              //Returns E_NOTIMPL if not a download job.
              //Returns E_INVALIDARG if dwRangeCount is zero or the remote or local name is invalid.
              //Returns BG_E_INVALID_RANGE if one of the ranges is invalid.
              //Returns BG_E_OVERLAPPING_RANGES if you specify overlapping or duplicate ranges.
         }

          pJob3->Release(); //Release the interface if you are done with it.
     }
    else
    {
         //Handle error. QueryInterface will return E_NOINTERFACE if the version of BITS
         //running on the computer is less than BITS 2.0.
    }

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows Vista, Windows XP SP2, windows Server 2003의 KB842773 및 Windows XP
지원되는 최소 서버 Windows Server 2008, Windows Server 2003 with SP1
대상 플랫폼 Windows
헤더 bits2_0.h(Bits.h 포함)
라이브러리 Bits.lib
DLL BitsPrx3.dll

추가 정보

BG_FILE_RANGE

IBackgroundCopyFile2::GetFileRanges

IBackgroundCopyJob3

IBackgroundCopyJob::AddFile