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

아티클
03/14/2023

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

구문

HRESULT AddFileSet(
  [in] ULONG        cFileCount,
  [in] BG_FILE_INFO *pFileSet
);

매개 변수

[in] cFileCount

paFileSet의 요소 수입니다.

[in] pFileSet

전송할 파일의 로컬 및 원격 파일 이름을 식별하는 BG_FILE_INFO 구조체의 배열입니다.

업로드 작업은 단일 파일로 제한됩니다. 배열에 둘 이상의 요소가 포함되어 있거나 작업에 이미 파일이 포함되어 있으면 메서드는 BG_E_TOO_MANY_FILES 반환합니다.

반환 값

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

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

설명

작업에 여러 파일을 추가할 때 루프에서 IBackgroundCopyJob::AddFile 메서드를 호출하는 것보다 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 사용 시 모범 사례를 참조하세요.

예제

다음 예제에서는 다운로드 작업에 여러 파일을 추가하는 방법을 보여줍니다. 이 예제에서는 IBackgroundCopyJob 인터페이스 포인터가 유효하다고 가정합니다.

HRESULT hr;
IBackgroundCopyJob* pJob;
BG_FILE_INFO* paFiles = NULL;
int idx = 0;
int nCount = 0;  //Number of files to add to the job.
LPWSTR pszLocalName = NULL;
LPWSTR pszRemoteName = NULL;

//Set nCount to the number of files to transfer.

//Allocate a block of memory to contain the array of BG_FILE_INFO structures.
//The BG_FILE_INFO structure contains the local and remote names of the 
//file being transferred.
paFiles = (BG_FILE_INFO*) malloc(sizeof(BG_FILE_INFO) * nCount);
if (NULL == paFiles)
{
  //Handle error
}
else
{
  //Add local and remote file name pairs to the memory block. 
  for (idx=0; idx<nCount; idx++)
  {
    //Set pszLocalName to point to an LPWSTR that contains the local name or
    //allocate memory for pszLocalName and copy the local name to pszLocalName.
    (paFiles+idx)->LocalName = pszLocalName;

    //Set pszRemoteName to point to an LPWSTR that contains the remote name or
    //allocate memory for pszRemoteName and copy the remote name to pszRemoteName.
    (paFiles+idx)->RemoteName = pszRemoteName;
  }

  //Add the files to the job.
  hr = pJob->AddFileSet(nCount, paFiles);
  if (SUCCEEDED(hr))
  {
     //Do Something.
  }

  //Free the memory block for the array of BG_FILE_INFO structures. If you allocated
  //memory for the local and remote file names, loop through the array and free the
  //memory for the file names before you free paFiles.
  free(paFiles);
}

요구 사항

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