IBackgroundCopyJob3::ReplaceRemotePrefix 메서드(bits2_0.h)

  • 아티클

다운로드 작업의 모든 원격 이름의 시작 텍스트를 지정된 문자열로 바꿉니다.

구문

HRESULT ReplaceRemotePrefix(
  [in] LPCWSTR OldPrefix,
  [in] LPCWSTR NewPrefix
);

매개 변수

[in] OldPrefix

원격 이름에서 바꿀 텍스트를 식별하는 Null로 끝나는 문자열입니다. 텍스트는 원격 이름의 시작 부분에서 시작해야 합니다.

[in] NewPrefix

대체 텍스트를 포함하는 Null로 끝나는 문자열입니다.

반환 값

이 메서드는 다음 반환 값뿐만 아니라 다른 값을 반환합니다.

반환 코드 설명
S_OK
 Success
S_FALSE
 일치하는 항목을 찾을 수 없습니다.
E_INVALIDARG
 NewPrefix를 적용하면 잘못된 URL이 생성되거나 새 URL이 너무 깁니다(URL은 2,200자를 초과할 수 없음).

OldPrefix 또는 NewPrefix가 빈 문자열인 경우에도 이 반환 코드를 받을 수 있습니다.
E_NOTIMPL
 업로드 또는 업로드-회신 작업에 대해 이 메서드를 호출할 수 없습니다. 다운로드 작업에 대해서만 이 메서드를 호출합니다.
BG_E_INVALID_STATE
 작업의 상태는 BG_JOB_STATE_CANCELLED 또는 BG_JOB_STATE_ACKNOWLEDGED 수 없습니다.

설명

일반적으로 이 메서드를 사용하여 서버를 사용할 수 없을 때 원격 이름의 서버 부분을 변경하거나 로밍 사용자가 가장 가까운 서버에 연결할 수 있도록 합니다. 이 메서드는 작업의 일치하는 모든 원격 이름을 변경합니다. 특정 파일의 원격 이름을 변경하려면 IBackgroundCopyFile2::SetRemoteName 메서드를 사용합니다.

ReplaceRemotePrefix 메서드는 작업의 모든 원격 이름에 대해 대/소문자를 구분하는 검색을 수행합니다. 원격 이름의 시작 텍스트가 OldPrefix의 문자열과 일치하는 경우 BITS는 텍스트를 NewPrefix에 있는 문자열로 바꿉니다. 예를 들어 를 변경하려면 "http://Server/Path/File.ext" "http://NewServerName/Path/File.ext"로, OldPrefix 를 "http://Server" 및 NewPrefix 를 "http://NewServerName"로 설정합니다. BITS는 검색에서 로캘 변환을 수행하지 않습니다.

새 원격 이름의 타임스탬프로 또는 파일 크기가 이전 원격 이름과 다르거나 새 서버가 검사점 다시 시작을 지원하지 않는 경우(HTTP 원격 이름의 경우) BITS가 다운로드를 다시 시작합니다. 그렇지 않으면 새 서버의 동일한 위치에서 전송이 다시 시작됩니다. BITS는 이미 전송된 파일을 다시 시작하지 않습니다.

이 메서드를 사용하여 프로토콜을 변경할 수 있습니다. 그러나 결과 URL이 잘 구성되지 않을 수 있습니다. 예를 들어 \Server\Dir\File.ext에서 로 변경하면 http://Server\Dir\File.ext resolve 않을 수 있습니다. 대신 IBackgroundCopyFile2::SetRemoteName 메서드를 사용하는 것이 좋습니다.

이 메서드는 IBackgroundCopyJobHttpOptions::SetSecurityFlags 메서드를 호출하고 BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT 플래그를 설정하는 경우 변경할 URL을 찾을 수 없습니다. 이 정책은 URL이 리디렉션되는 경우 원래 URL을 최종 리디렉션된 URL로 변경합니다.

예제

다음 예제에서는 ReplaceRemotePrefix 메서드를 호출하여 URL의 서버 이름을 변경하는 방법을 보여줍니다. 이 예제에서는 IBackgroundCopyJob 변수 pJob이 유효하고 작업에 하나 이상의 파일이 포함되어 있다고 가정합니다.

     IBackgroundCopyJob *pJob;
     IBackgroundCopyJob3 *pJob3 = NULL;

     //Need to query the IBackgroundCopyJob interface for an IBackgroundCopyJob3
     //interface pointer. The IBackgroundCopyJob3 interface contains the ReplaceRemotePrefix method.
     hr = pJob->QueryInterface(__uuidof( IBackgroundCopyJob3 ), (void**)&pJob3;);
     if (S_OK == hr)
     {
          pJob->Release(); //No longer need the IBackgoundCopyJob interface pointer.

          //Identify the old and new remote name text. For example, "http://oldservername" and 
          //"http://newservername". For SMB, specify "\\\\oldservername" and "\\\\newservername".
          hr = pJob3->ReplaceRemotePrefix(L"<OLDSERVERNAMEGOESHERE>", L"<NEWSERVERNAMEGOESHERE>");
          if (S_FALSE == hr)
          {
               wprintf(L"The job does not contain files with a remote name that matches the prefix.\n");
          }
          else if (FAILED(hr))
          {
               //Handle error.
               //Returns E_NOTIMPL if not a download job.
               //Returns E_INVALIDARG if new prefix is empty or the resulting URL is invalid.
          }

          pJob3->Release();
     }
     else
     {
          //Handle error. QueryInterface will return E_NOINTERFACE if the version of BITS
          //running on the computer is less than BITS 2.0.
     }

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows Vista, Windows XP SP2, windows Server 2003의 KB842773 및 Windows XP
지원되는 최소 서버 Windows Server 2008, Windows Server 2003 with SP1
대상 플랫폼 Windows
헤더 bits2_0.h(Bits.h 포함)
라이브러리 Bits.lib
DLL BitsPrx3.dll

추가 정보

IBackgroundCopyFile2::SetRemoteName

IBackgroundCopyJob3