IBackgroundCopyFile2：：SetRemoteName 方法 （bits2_0.h）

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

Syntax

HRESULT SetRemoteName(
  [in] LPCWSTR Val
);

参数

[in] Val

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

返回值

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

注解

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

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

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

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

例子

以下示例演示如何调用 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.

要求

另请参阅

IBackgroundCopyFile2

IBackgroundCopyJob3：：ReplaceRemotePrefix