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.

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

Weitere Informationen

IBackgroundCopyFile2::SetRemoteName

IBackgroundCopyJob3