IBackgroundCopyFile2::SetRemoteName-Methode (bits2_0.h)
Ändert den Remotenamen in einer neuen URL in einem Downloadauftrag.
Syntax
HRESULT SetRemoteName(
[in] LPCWSTR Val
);
Parameter
[in] Val
Null-beendete Zeichenfolge, die den Namen der Datei auf dem Server enthält. Informationen zum Angeben des Remotenamens finden Sie im Abschnitt RemoteName-Member und Hinweise der BG_FILE_INFO-Struktur .
Rückgabewert
Diese Methode gibt die folgenden Rückgabewerte sowie andere rückgabewerte zurück.
| Rückgabecode | Beschreibung |
|---|---|
|
Erfolg |
|
Der neue Remotename ist eine ungültige URL, oder die neue URL ist zu lang (die URL darf 2.200 Zeichen nicht überschreiten). |
|
Sie können diese Methode nicht für Upload- oder Upload-Antwortaufträge aufrufen. Rufen Sie diese Methode nur für Downloadaufträge auf. |
|
Der Status des Auftrags kann nicht BG_JOB_STATE_CANCELLED oder BG_JOB_STATE_ACKNOWLEDGED sein. |
Hinweise
In der Regel rufen Sie diese Methode auf, wenn Sie das Protokoll ändern möchten, das zum Übertragen der Datei verwendet wird (z. B. von SMB zu HTTP) oder wenn Sie den Dateinamen oder Pfad ändern möchten.
Diese Methode serialisiert sich nicht, wenn sie zurückgibt. Um die Änderung zu serialisieren, setzen Sie den Auftrag an , rufen Sie diese Methode auf (wenn Sie mehrere Dateien im Auftrag ändern, verwenden Sie eine Schleife), und setzen Sie den Auftrag fort. Durch Aufrufen der IBackgroundCopyJob::Resume-Methode wird die Änderung serialisiert.
Wenn sich der Zeitstempel oder die Dateigröße des neuen Remotenamens vom vorherigen Remotenamen unterscheidet oder der neue Server die Prüfpunkt-Fortsetzung (für HTTP-Remotenamen) nicht unterstützt, startet BITS den Download neu. Andernfalls wird die Übertragung von derselben Position auf dem neuen Server fortgesetzt. BITS startet bereits übertragene Dateien nicht neu.
Wenn der Remotename einen SMB-Pfad (Server Message Block) identifiziert, sind in der folgenden Tabelle mögliche Fehlercodes aufgeführt, die auftreten können, nachdem Sie den Auftrag fortgesetzt haben. Diese Fehler versetzen den Auftrag in den BG_JOB_STATE_ERROR Zustand.
| Fehlercode | BESCHREIBUNG |
|---|---|
HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND) |
Das Verzeichnis wurde nicht gefunden. |
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) |
Die Datei wurde nicht gefunden. |
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED) |
Der Benutzer hat keinen Zugriff auf die in Val angegebene Datei. |
Beispiele
Das folgende Beispiel zeigt, wie Sie die SetRemoteName-Methode aufrufen, um den Remotenamen einer Datei zu ändern. Im Beispiel wird davon ausgegangen, dass die IBackgroundCopyJob-Variable pJob gültig ist und der Auftrag mindestens eine Datei enthält.
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.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista, Windows XP mit SP2, KB842773 unter Windows Server 2003 und Windows XP |
| Unterstützte Mindestversion (Server) | Windows Server 2008, Windows Server 2003 mit SP1 |
| Zielplattform | Windows |
| Kopfzeile | bits2_0.h (Bits.h einschließen) |
| Bibliothek | Bits.lib |
| DLL | BitsPrx3.dll |