IBackgroundCopyFile2::SetRemoteName 메서드(bits2_0.h)
원격 이름을 다운로드 작업의 새 URL로 변경합니다.
구문
HRESULT SetRemoteName(
[in] LPCWSTR Val
);
매개 변수
[in] Val
서버의 파일 이름을 포함하는 Null로 끝나는 문자열입니다. 원격 이름을 지정하는 방법에 대한 자세한 내용은 BG_FILE_INFO 구조체의 RemoteName 멤버 및 주의 섹션을 참조하세요.
반환 값
이 메서드는 다음 반환 값뿐만 아니라 다른 값을 반환합니다.
| 반환 코드 | 설명 |
|---|---|
|
Success |
|
새 원격 이름이 잘못된 URL이거나 새 URL이 너무 깁니다(URL은 2,200자를 초과할 수 없음). |
|
업로드 또는 업로드-회신 작업에 대해 이 메서드를 호출할 수 없습니다. 만 다운로드 작업에 대해이 메서드를 호출합니다. |
|
작업의 상태는 BG_JOB_STATE_CANCELLED 또는 BG_JOB_STATE_ACKNOWLEDGED 수 없습니다. |
설명
일반적으로 파일을 전송하는 데 사용되는 프로토콜(예: SMB에서 HTTP로)을 변경하거나 파일 이름 또는 경로를 변경하려는 경우 이 메서드를 호출합니다.
이 메서드는 반환할 때 직렬화되지 않습니다. 변경 사항을 직렬화하려면 작업을 일시 중단하고 이 메서드를 호출하고(작업에서 여러 파일을 변경하는 경우 루프를 사용) 작업을 다시 시작 합니다. IBackgroundCopyJob::Resume 메서드를 호출하면 변경 내용이 직렬화됩니다.
새 원격 이름의 타임스탬프로 또는 파일 크기가 이전 원격 이름과 다르거나 새 서버가 검사점 다시 시작을 지원하지 않는 경우(HTTP 원격 이름의 경우) BITS가 다운로드를 다시 시작합니다. 그렇지 않으면 새 서버의 동일한 위치에서 전송이 다시 시작됩니다. BITS는 이미 전송된 파일을 다시 시작하지 않습니다.
원격 이름이 SMB(서버 메시지 블록) 경로를 식별하는 경우 다음 표에서는 작업을 다시 시작하면 발생할 수 있는 가능한 오류 코드를 식별합니다. 이러한 오류는 작업을 BG_JOB_STATE_ERROR 상태로 설정합니다.
| 오류 코드 | Description |
|---|---|
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 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 |