IBackgroundCopyFile2：：SetRemoteName 方法（bits2_0.h）

在下載作業中將遠端名稱改成新的網址。

語法

HRESULT SetRemoteName(
  [in] LPCWSTR Val
);

參數

[in] Val

包含伺服器檔案名稱的空終止字串。 關於指定遠端名稱的資訊，請參閱 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