IBackgroundCopyJob::AddFile 메서드(bits.h)

아티클
08/22/2023

작업에 단일 파일을 추가합니다.

구문

HRESULT AddFile(
  [in] LPCWSTR RemoteUrl,
  [in] LPCWSTR LocalName
);

매개 변수

[in] RemoteUrl

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

[in] LocalName

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

반환 값

이 메서드는 다음 HRESULT 값과 다른 값을 반환합니다.

반환 코드	설명
S_OK	파일이 작업에 성공적으로 추가되었습니다.
BG_E_TOO_MANY_FILES	업로드 작업에는 하나의 파일만 포함될 수 있습니다. 작업에 다른 파일을 추가할 수 없습니다.
BG_E_TOO_MANY_FILES_IN_JOB	MaxFilesPerJob 그룹 정책 설정은 작업에 포함될 수 있는 파일 수를 결정합니다. 작업에 파일을 추가하면 MaxFilesPerJob 제한이 초과됩니다.
E_INVALIDARG	다음 이유 중 하나로 이 오류가 발생할 수 있습니다. 로컬 또는 원격 파일 이름이 잘못되었습니다. 원격 파일 이름은 지원되지 않는 프로토콜을 사용합니다. 로컬 파일 이름은 상대 경로를 사용하여 지정되었습니다.
E_ACCESSDENIED	사용자에게 클라이언트의 지정된 디렉터리에 쓸 수 있는 권한이 없습니다.

설명

한 번에 둘 이상의 파일을 작업에 추가하려면 IBackgroundCopyJob::AddFileSet 메서드를 호출합니다. 작업에 여러 파일을 추가할 때 AddFileSet 메서드를 호출하는 것이 루프에서 AddFile 메서드를 호출하는 것보다 더 효율적입니다. 자세한 내용은 작업에 파일 추가를 참조하세요.

BITS가 파일에서 데이터 범위를 다운로드하는 작업에 파일을 추가하려면 IBackgroundCopyJob3::AddFileWithRanges 메서드를 호출합니다.

업로드 작업에는 하나의 파일만 포함될 수 있습니다. 두 번째 파일을 추가하면 메서드는 BG_E_TOO_MANY_FILES 반환합니다.

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

서버에서 다운로드되는 파일이 있는 경우 파일의 각 새 버전에 대한 새 URL을 만들어야 합니다. 새 버전의 파일에 동일한 URL을 사용하는 경우 일부 프록시 서버는 파일이 부실한 경우 원래 서버에서 확인하지 않기 때문에 캐시의 부실 데이터를 제공할 수 있습니다.

업로드의 경우 파일이 전송되는 동안 로컬 파일이 변경되면 BITS에서 오류가 발생합니다. 오류 코드가 BG_E_FILE_CHANGED 컨텍스트가 BG_ERROR_CONTEXT_LOCAL_FILE.

BITS는 작업 내에서 파일을 순차적으로 전송합니다. 파일을 전송하는 동안 오류가 발생하면 작업이 오류 상태로 이동하고 오류가 해결될 때까지 작업 내의 파일이 더 이상 처리되지 않습니다.

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

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

확장성 문제는 BITS 사용 시 모범 사례를 참조하세요.

예제

작업에 단일 파일을 추가하는 예제는 작업에 파일 추가를 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP
지원되는 최소 서버	Windows Server 2003
대상 플랫폼	Windows
헤더	bits.h
라이브러리	Bits.lib
DLL	QmgrPrxy.dll