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 상태로 설정합니다.

오류 코드 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

추가 정보

IBackgroundCopyFile2

IBackgroundCopyJob3::ReplaceRemotePrefix