IBackgroundCopyFile2：：SetRemoteName 方法 (bits2_0.h)

  • 项目

将远程名称更改为下载作业中的新 URL。

语法

HRESULT SetRemoteName(
  [in] LPCWSTR Val
);

参数

[in] Val

包含服务器上文件名称的以 Null 结尾的字符串。 有关指定远程名称的信息，请参阅BG_FILE_INFO结构的 RemoteName 成员和备注部分。

返回值

此方法返回以下返回值以及其他返回值。

返回代码 说明
S_OK
 成功
E_INVALIDARG
 新远程名称是无效的 URL 或新 URL 太长， (URL) 不能超过 2,200 个字符。
E_NOTIMPL
 不能为上传或上传-回复作业调用此方法;仅对下载作业调用此方法。
BG_E_INVALID_STATE
 作业的状态不能 BG_JOB_STATE_CANCELLED 或 BG_JOB_STATE_ACKNOWLEDGED。

注解

通常，如果要更改用于将文件 (传输的协议（例如，从 SMB 传输到 HTTP) ，或者要更改文件名或路径），则调用此方法。

此方法在返回时不序列化。 若要序列化更改， 请挂起 作业，如果更改作业中的多个文件， (调用此方法，请使用循环) ，然后 恢复 作业。 调用 IBackgroundCopyJob：：Resume 方法将序列化更改。

如果新远程名称的时间戳或文件大小与以前的远程名称不同，或者新服务器不支持 http 远程名称) 检查点恢复 (，则 BITS 将重启下载。 否则，传输将从新服务器上的同一位置恢复。 BITS 不会重启已传输的文件。

如果远程名称标识了 SMB) 路径 (服务器消息块，则下表标识了恢复作业后可能发生的错误代码。 这些错误会将作业置于 BG_JOB_STATE_ERROR 状态。

错误代码 说明
HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND) 找不到目录。
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) 找不到该文件。
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED) 用户无权访问 Val 中指定的文件。
 

示例

以下示例演示如何调用 SetRemoteName 方法来更改文件的远程名称。 该示例假定 IBackgroundCopyJob 变量 pJob 有效，并且作业包含一个或多个文件。

     IBackgroundCopyJob *pJob;
     IEnumBackgroundCopyFiles* pFiles = NULL;
     IBackgroundCopyFile* pFile = NULL;
     IBackgroundCopyFile2* pFile2 = NULL;
     WCHAR* pRemoteFileName = NULL;
     ULONG cFileCount = 0;

     hr = pJob->Suspend();
     hr = pJob->EnumFiles(&pFiles);
     if (SUCCEEDED(hr))
     {
          //Get the count of files in the job. 
          hr = pFiles->GetCount(&cFileCount);

          //Enumerate the files in the job.
          for (ULONG idx=0; idx<cFileCount; idx++)
          {
               hr = pFiles->Next(1, &pFile, NULL);
               if (S_OK == hr)
               {
                    //Get the local name of the file.
                    hr = pFile->GetRemoteName(&pRemoteFileName);
                    if (SUCCEEDED(hr))
                    {
                         //Determine if you want to replace the remote name of this file.
                         if (<CONDITIONGOESHERE>)
                         {
                              //Need to query the IBackgroundCopyFile interface for an IBackgroundCopyFile2
                              //interface pointer. The IBackgroundCopyFile2 interface contains the SetRemoteName method.
                              hr = pFile->QueryInterface(__uuidof(IBackgroundCopyFile2), (void**)&pFile2);
                              if (S_OK == hr)
                              {
                                   hr = pFile2->SetRemoteName(L"<NEWURLGOESHERE>");
                                   if (FAILED(hr))
                                   {
                                        //Handle error. 
                                        //Returns E_NOTIMPL if not a download job.
                                        //Returns E_INVALIDARG if invalid URL.
                                   }
                              }
                              else
                              {
                                   //handle error. QueryInterface will return E_NOINTERFACE if the version of BITS
                                   //running on the computer is less than BITS 2.0.
                              }
                         }
                         CoTaskMemFree(pRemoteFileName); 
                    }    
                    pFile->Release(); 
                    pFile = NULL;
               }
               else
               {
                    //Handle error
                    break;
               }
          }

          pFiles->Release();
          pFiles = NULL;
     }

     hr = pJob->Resume(); //Force the job to serialize.

要求

要求 值
最低受支持的客户端 Windows Vista、Windows XP（在 Windows Server 2003 和 Windows XP 上使用 SP2、KB842773）
最低受支持的服务器 Windows Server 2008、Windows Server 2003 SP1
目标平台 Windows
标头 bits2_0.h (包括 Bits.h)
Library Bits.lib
DLL BitsPrx3.dll

另请参阅

IBackgroundCopyFile2

IBackgroundCopyJob3：：ReplaceRemotePrefix