共用方式為

IBackgroundCopyFile2：：SetRemoteName 方法 (bits2_0.h)

  • 發行項

將遠端名稱變更為下載作業中的新 URL。

語法

HRESULT SetRemoteName(
  [in] LPCWSTR Val
);

參數

[in] Val

Null 終止的字串，其中包含伺服器上的檔名。 如需指定遠端名稱的資訊，請參閱 BG_FILE_INFO 結構的 RemoteName 成員和備註一節。

傳回值

這個方法會傳回下列傳回值，以及其他傳回值。

傳回碼 Description
S_OK
 Success
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 上的 SP2、KB842773 和 Windows XP
最低支援的伺服器 Windows Server 2008、Windows Server 2003 SP1
目標平台 Windows
標頭 bits2_0.h (包含 Bits.h)
程式庫 Bits.lib
Dll BitsPrx3.dll

另請參閱

IBackgroundCopyFile2

IBackgroundCopyJob3：：ReplaceRemotePrefix