IBackgroundCopyFile2::SetRemoteName メソッド (bits2_0.h)

  • [アーティクル]

リモート名をダウンロード ジョブの新しい URL に変更します。

構文

HRESULT SetRemoteName(
  [in] LPCWSTR Val
);

パラメーター

[in] Val

サーバー上のファイルの名前を含む Null で終わる文字列。 リモート名の指定については、BG_FILE_INFO構造体の RemoteName メンバーと解説に関するセクションを参照してください。

戻り値

このメソッドは、他の戻り値と同様に、次の戻り値を返します。

リターン コード 説明
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 が有効であり、ジョブに 1 つ以上のファイルが含まれていることを前提としています。

     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 SP2、Windows Server 2003 のKB842773、Windows XP
サポートされている最小のサーバー Windows Server 2008、Windows Server 2003 SP1
対象プラットフォーム Windows
ヘッダー bits2_0.h (Bits.h を含む)
Library Bits.lib
[DLL] BitsPrx3.dll

こちらもご覧ください

IBackgroundCopyFile2

IBackgroundCopyJob3::ReplaceRemotePrefix