IBackgroundCopyJob3::ReplaceRemotePrefix-Methode (bits2_0.h)
Ersetzt den Anfangstext aller Remotenamen im Downloadauftrag durch die angegebene Zeichenfolge.
Syntax
HRESULT ReplaceRemotePrefix(
[in] LPCWSTR OldPrefix,
[in] LPCWSTR NewPrefix
);
Parameter
[in] OldPrefix
Null-beendete Zeichenfolge, die den Text identifiziert, der im Remotenamen ersetzt werden soll. Der Text muss am Anfang des Remotenamens beginnen.
[in] NewPrefix
Null-beendete Zeichenfolge, die den Ersetzungstext enthält.
Rückgabewert
Diese Methode gibt neben anderen auch die folgenden Rückgabewerte zurück.
| Rückgabecode | Beschreibung |
|---|---|
|
Erfolg |
|
Keine Übereinstimmungen gefunden. |
|
Durch anwenden von NewPrefix wird eine ungültige URL erstellt, oder die neue URL ist zu lang (die URL darf nicht mehr als 2.200 Zeichen lang sein).
Sie können diesen Rückgabecode auch erhalten, wenn OldPrefix oder NewPrefix eine leere Zeichenfolge ist. |
|
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 werden. |
Hinweise
In der Regel verwenden Sie diese Methode, um den Serverteil des Remotenamens zu ändern, wenn der Server nicht verfügbar ist, oder um Roamingbenutzern eine Verbindung mit dem nächstgelegenen Server zu ermöglichen. Diese Methode ändert alle übereinstimmenden Remotenamen im Auftrag. Um den Remotenamen einer bestimmten Datei zu ändern, verwenden Sie die IBackgroundCopyFile2::SetRemoteName-Methode .
Die ReplaceRemotePrefix-Methode führt eine Suche nach Groß-/Kleinschreibung bei allen Remotenamen im Auftrag durch. Wenn der Anfangstext des Remotenamens mit der Zeichenfolge in OldPrefix übereinstimmt, ersetzt BITS den Text durch die in NewPrefix gefundene Zeichenfolge. So ändern Sie z. B. "http://Server/Path/File.ext" auf "http://NewServerName/Path/File.ext", legen Sie OldPrefix auf "http://Server" und NewPrefix auf "http://NewServerName". Beachten Sie, dass BITS keine Gebietsschemakonvertierungen in der Suche ausführt.
Wenn sich der Zeitstempel oder die Dateigröße des neuen Remotenamens vom vorherigen Remotenamen unterscheidet oder der neue Server keine Prüfpunkt-Fortsetzung unterstützt (für HTTP-Remotenamen), wird der Download von BITS neu gestartet. Andernfalls wird die Übertragung von derselben Position auf dem neuen Server fortgesetzt. BITS startet bereits übertragene Dateien nicht neu.
Sie können diese Methode verwenden, um Protokolle zu ändern. Die resultierende URL ist jedoch möglicherweise nicht gut formatiert. Beispielsweise kann der Wechsel von \Server\Dir\File.ext in http://Server\Dir\File.ext möglicherweise nicht aufgelöst werden. Erwägen Sie stattdessen die IBackgroundCopyFile2::SetRemoteName-Methode .
Beachten Sie, dass diese Methode möglicherweise keine ZU ändernden URLs findet, wenn Sie die IBackgroundCopyJobHttpOptions::SetSecurityFlags-Methode aufgerufen und das BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT-Flag festlegen. Diese Richtlinie ändert die ursprüngliche URL in die endgültige, umgeleitete URL, wenn die URL umgeleitet wird.
Beispiele
Das folgende Beispiel zeigt, wie Sie die ReplaceRemotePrefix-Methode aufrufen, um den Servernamen einer URL zu ändern. Im Beispiel wird davon ausgegangen, dass die IBackgroundCopyJob-VariablepJob gültig ist und der Auftrag mindestens eine Datei enthält.
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.
}
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 |