IBackgroundCopyJob3::ReplaceRemotePrefix 메서드(bits2_0.h)
다운로드 작업의 모든 원격 이름의 시작 텍스트를 지정된 문자열로 바꿉니다.
구문
HRESULT ReplaceRemotePrefix(
[in] LPCWSTR OldPrefix,
[in] LPCWSTR NewPrefix
);
매개 변수
[in] OldPrefix
원격 이름에서 바꿀 텍스트를 식별하는 Null로 끝나는 문자열입니다. 텍스트는 원격 이름의 시작 부분에서 시작해야 합니다.
[in] NewPrefix
대체 텍스트를 포함하는 Null로 끝나는 문자열입니다.
반환 값
이 메서드는 다음 반환 값뿐만 아니라 다른 값을 반환합니다.
| 반환 코드 | 설명 |
|---|---|
|
Success |
|
일치하는 항목을 찾을 수 없습니다. |
|
NewPrefix를 적용하면 잘못된 URL이 생성되거나 새 URL이 너무 깁니다(URL은 2,200자를 초과할 수 없음).
OldPrefix 또는 NewPrefix가 빈 문자열인 경우에도 이 반환 코드를 받을 수 있습니다. |
|
업로드 또는 업로드-회신 작업에 대해 이 메서드를 호출할 수 없습니다. 다운로드 작업에 대해서만 이 메서드를 호출합니다. |
|
작업의 상태는 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 |