IBackgroundCopyFile2

IBackgroundCopyFile2 インターフェイスを使用すると、ファイルに新しいリモート名を指定したり、ダウンロードする範囲の一覧を取得したりできます。

リモートファイルからダウンロードする範囲を取得します。

このメソッドは、次の戻り値のほか、その他の値を返します。

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

このメソッドは、次の戻り値のほか、その他の値を返します。

通常、このメソッドは、ファイルの転送に使用するプロトコルを変更する場合 (たとえば SMB から HTTP へ) や、ファイル名またはパスを変更する場合に呼び出します。

このメソッドは、戻り時にシリアル化を行いません。変更をシリアル化するには、ジョブを中断 (Suspend) し、このメソッドを呼び出して (ジョブ内の複数のファイルを変更する場合はループを使用します)、ジョブを再開 (Resume) します。IBackgroundCopyJob::Resume メソッドを呼び出すと、変更がシリアル化されます。

新しいリモート名のタイムスタンプまたはファイルサイズが以前のリモート名と異なる場合、あるいは新しいサーバーがチェックポイント再開をサポートしていない場合 (HTTP のリモート名の場合)、BITS はダウンロードを最初からやり直します。それ以外の場合、転送は新しいサーバー上の同じ位置から再開されます。BITS は、転送済みのファイルを再転送することはありません。

リモート名がサーバーメッセージブロック (SMB) パスを示している場合、ジョブを再開した後に発生する可能性のあるエラーコードを次の表に示します。これらのエラーが発生すると、ジョブは BG_JOB_STATE_ERROR 状態になります。

例

次の例は、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))
     {
          //ジョブ内のファイル数を取得します。
          hr = pFiles->GetCount(&cFileCount);

          //ジョブ内のファイルを列挙します。
          for (ULONG idx=0; idx<cFileCount; idx++)
          {
               hr = pFiles->Next(1, &pFile, NULL);
               if (S_OK == hr)
               {
                    //ファイルのローカル名を取得します。
                    hr = pFile->GetRemoteName(&pRemoteFileName);
                    if (SUCCEEDED(hr))
                    {
                         //このファイルのリモート名を置き換えるかどうかを判断します。
                         if (<CONDITIONGOESHERE>)
                         {
                              //IBackgroundCopyFile インターフェイスに対して QueryInterface を行い、IBackgroundCopyFile2
                              //インターフェイスポインターを取得する必要があります。SetRemoteName メソッドは IBackgroundCopyFile2 インターフェイスに含まれています。
                              hr = pFile->QueryInterface(__uuidof(IBackgroundCopyFile2), (void**)&pFile2);
                              if (S_OK == hr)
                              {
                                   hr = pFile2->SetRemoteName(L"<NEWURLGOESHERE>");
                                   if (FAILED(hr))
                                   {
                                        //エラー処理。
                                        //ダウンロードジョブでない場合は E_NOTIMPL を返します。
                                        //URL が無効な場合は E_INVALIDARG を返します。
                                   }
                              }
                              else
                              {
                                   //エラー処理。コンピューター上で動作している BITS のバージョンが BITS 2.0 未満の場合、
                                   //QueryInterface は E_NOINTERFACE を返します。
                              }
                         }
                         CoTaskMemFree(pRemoteFileName); 
                    }    
                    pFile->Release(); 
                    pFile = NULL;
               }
               else
               {
                    //エラー処理
                    break;
               }
          }

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

     hr = pJob->Resume(); //ジョブに強制的にシリアル化させます。