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
);

Die 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 die folgenden Rückgabewerte sowie andere zurück.

Bemerkungen

In der Regel verwenden Sie diese Methode, um den Serverteil des Remotenamens zu ändern, wenn der Server nicht verfügbar ist, oder um Roamingbenutzern die Verbindung mit dem nächstgelegenen Server zu ermöglichen. Diese Methode ändert alle übereinstimmenden Remotenamen im Auftrag. Verwenden Sie zum Ändern des Remotenamens einer bestimmten Datei die IBackgroundCopyFile2::SetRemoteName-Methode .

Die ReplaceRemotePrefix-Methode führt eine Suche nach Groß-/Kleinschreibung aller Remotenamen im Auftrag durch. Wenn der Anfangstext des Remotenamens der Zeichenfolge in OldPrefix entspricht, ersetzt BITS den Text durch die in NewPrefix gefundene Zeichenfolge. Zum Beispiel zum Ändern von "http://Server/Path/File.ext" auf "http://NewServerName/Path/File.ext", set 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 den Prüfpunkt-Lebenslauf (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.

Sie können diese Methode verwenden, um Protokolle zu ändern. Die resultierende URL ist jedoch möglicherweise nicht wohlgeformt. Beispielsweise kann das Ändern von \Server\Dir\File.ext http://Server\Dir\File.ext nicht aufgelöst werden. Verwenden Sie stattdessen die IBackgroundCopyFile2::SetRemoteName-Methode .

Beachten Sie, dass diese Methode möglicherweise keine URLs findet, die geändert werden sollen, wenn Sie die IBackgroundCopyJobHttpOptions::SetSecurityFlags-Methode aufgerufen und das BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT Flag festgelegt haben. Diese Richtlinie ändert die ursprüngliche URL in die endgültige umgeleitete URL, wenn die URL umgeleitet wird.

Examples

Das folgende Beispiel zeigt, wie Die ReplaceRemotePrefix-Methode aufgerufen wird, um den Servernamen einer URL zu ändern. Im Beispiel wird davon ausgegangen, dass die Variable "IBackgroundCopyJob ", pJob, 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

Siehe auch

IBackgroundCopyFile2::SetRemoteName

IBackgroundCopyJob3