将文件添加到作业

作业包含要传输的一个或多个文件。 使用以下方法之一将文件添加到作业:

IBackgroundCopyJob::AddFile

将单个文件添加到作业。

IBackgroundCopyJob::AddFileSet

将一个或多个文件添加到作业。 如果要添加多个文件,则调用此方法比在循环中调用 AddFile 方法更有效。

IBackgroundCopyJob3::AddFileWithRanges

将单个文件添加到作业。 如果要从文件下载数据范围,请使用此方法。 只能将此方法用于下载作业。

将文件添加到作业时,请指定远程名称和文件的本地名称。 有关本地和远程文件名格式的详细信息,请参阅 BG_FILE_INFO 结构。

上传作业只能包含一个文件。 如果尝试将多个文件添加到上传作业,IBackgroundCopyJob::AddFileSet 方法将返回BG_E_TOO_MANY_FILES IBackgroundCopyJob::AddFileSet 方法。 如果需要上传多个文件,请考虑使用 CAB 或 ZIP 文件。

对于下载作业,BITS 将用户可以添加到作业的文件数限制为 200 个文件,将文件的范围数限制为 500 个范围。 这些限制不适用于管理员或服务。 若要更改这些默认限制,请参阅 组策略

作业的所有者或具有管理员权限的用户可以在调用 IBackgroundCopyJob::Complete 方法或 IBackgroundCopyJob::Cancel 方法之前随时将文件添加到作业。

如果在将文件添加到作业后需要更改文件的远程名称,可以调用 IBackgroundCopyJob3::ReplaceRemotePrefix 方法或 IBackgroundCopyFile2::SetRemoteName 方法。 使用 ReplaceRemotePrefix 方法可以更改服务器不可用时远程名称的服务器部分,或者让漫游用户连接到最近的服务器。 使用 SetRemoteName 方法更改用于传输文件的协议,或更改文件名或路径。

BITS 在目标目录中创建一个临时文件,并使用临时文件进行文件传输。 若要获取临时文件名,请调用 IBackgroundCopyFile3::GetTemporaryName 方法。 调用 Complete 方法时,BITS 会将临时文件名更改为目标文件名。 当 BITS 创建 临时文件时,BITS 不会指定安全描述符, (该文件从目标目录继承 ACL 信息) 。 如果传输的数据很敏感,应用程序应在目标目录中指定适当的 ACL,以防止未经授权的访问。

若要使用传输的文件维护所有者和 ACL 信息,请调用 IBackgroundCopyJob3::SetFileACLFlags 方法。

作业的所有者 (创建作业的用户或 拥有作业所有权 的管理员) 必须有权访问服务器上的文件以及客户端。 例如,若要下载文件,用户必须在服务器上具有读取权限,并向客户端上的本地目录写入权限。

以下示例演示如何将单个文件添加到作业。 该示例假定 IBackgroundCopyJob 接口指针 pJob 有效。

HRESULT hr;
IBackgroundCopyJob* pJob;

//Replace parameters with variables that contain valid paths.
hr = pJob->AddFile(L"https://ServerName/Path/File.Ext", L"d:\\Path\\File.Ext");
if (SUCCEEDED(hr))
{
  //Do something.
}

以下示例演示如何将多个文件添加到作业。 该示例假定 IBackgroundCopyJob 接口指针 pJob 有效,本地名称和远程名称来自用户界面中的列表。

HRESULT hr;
IBackgroundCopyJob* pJob;
BG_FILE_INFO* paFiles = NULL;
ULONG idx = 0;
ULONG nCount = 0;            //Set to the number of files to add to the job.
LPWSTR pszLocalName = NULL;  //Comes from the list in the user interface.
LPWSTR pszRemoteName = NULL; //Comes from the list in the user interface.

//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);
}