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 状態になります。
| エラー コード | 説明 |
|---|---|
HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND) |
ディレクトリが見つかりませんでした。 |
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) |
ファイルが見つかりませんでした。 |
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED) |
ユーザーは 、Val で指定されたファイルにアクセスできません。 |
例
次の例は 、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))
{
//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 SP1 |
| 対象プラットフォーム | Windows |
| ヘッダー | bits2_0.h (Bits.h を含む) |
| Library | Bits.lib |
| [DLL] | BitsPrx3.dll |