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 구조체 배열입니다. 중복되거나 겹치는 범위를 지정하지 마세요.
반환 값
이 메서드는 다음 반환 값뿐만 아니라 다른 값을 반환합니다.
| 반환 코드 | 설명 |
|---|---|
|
Success |
|
다음 이유 중 하나로 이 오류가 발생할 수 있습니다.
|
|
업로드 또는 업로드-회신 작업에 대해 이 메서드를 호출할 수 없습니다. 만 다운로드 작업에 대해이 메서드를 호출합니다. |
|
사용자에게 클라이언트의 지정된 디렉터리에 쓸 수 있는 권한이 없습니다. |
|
범위 중 하나가 잘못되었습니다. 예를 들어 InitialOffset은 BG_LENGTH_TO_EOF. |
|
중복되거나 겹치는 범위는 지정할 수 없습니다.
참고 범위는 길이가 아닌 값의 오프셋을 기준으로 정렬됩니다. 오프셋이 같지만 역순인 범위를 입력하면 이 오류가 반환됩니다. 예를 들어 100.5 및 100.0을 해당 순서로 입력하면 작업에 파일을 추가할 수 없습니다.
|
|
MaxRangesPerFile 그룹 정책 설정은 파일에 대해 지정할 수 있는 범위 수를 결정합니다. 이러한 범위를 추가하면 MaxRangesPerFile 제한이 초과됩니다. |
|
작업의 상태는 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 |