EN
Deze inhoud is niet beschikbaar in uw taal, maar wel in het Engels.

IBackgroundCopyJob3::ReplaceRemotePrefix method

Replaces the beginning text of all remote names in the download job with the specified string.

Syntax


HRESULT ReplaceRemotePrefix(
  [in] LPCWSTR OldPrefix,
  [in] LPCWSTR NewPrefix
);

Parameters

OldPrefix [in]

Null-terminated string that identifies the text to replace in the remote name. The text must start at the beginning of the remote name.

NewPrefix [in]

Null-terminated string that contains the replacement text.

Return value

This method returns the following return values, as well as others.

Return codeDescription
S_OK

Success

S_FALSE

No matches found.

E_INVALIDARG

Applying NewPrefix creates an invalid URL or the new URL is too long (the URL cannot exceed 2,200 characters).

You can also receive this return code if the OldPrefix or NewPrefix is an empty string.

E_NOTIMPL

You cannot call this method for upload or upload-reply jobs; call this method only for download jobs.

BG_E_INVALID_STATE

The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.

 

Remarks

Typically, you use this method to change the server portion of the remote name when the server is unavailable or to let roaming users connect to the closest server. This method changes all matching remote names in the job. To change the remote name of a specific file, use the IBackgroundCopyFile2::SetRemoteName method.

The ReplaceRemotePrefix method performs a case-sensitive search of all the remote names in the job. If the beginning text of the remote name matches the string in OldPrefix, BITS replaces the text with the string found in NewPrefix. For example, to change "http://Server/Path/File.ext" to "http://NewServerName/Path/File.ext", set OldPrefix to "http://Server" and NewPrefix to "http://NewServerName". Note that BITS does not perform locale conversions in the search.

If the time stamp or file size of the new remote name is different from the previous remote name or the new server does not support checkpoint resume (for HTTP remote names), BITS restarts the download. Otherwise, the transfer resumes from the same position on the new server. BITS does not restart already transferred files.

You can use this method to change protocols. However, the resulting URL may not be well formed. For example, changing from \\Server\Dir\File.ext to http://Server\Dir\File.ext may not resolve. Consider using the IBackgroundCopyFile2::SetRemoteName method instead.

Note that this method may not find URLs to change if you called the IBackgroundCopyJobHttpOptions::SetSecurityFlags method and set the BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT flag. This policy changes the original URL to the final, redirected URL if the URL is redirected.

Examples

The following example shows how to call the ReplaceRemotePrefix method to change the server name of a URL. The example assumes the IBackgroundCopyJob variable, pJob, is valid and the job contains one or more files.


     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.
     }

Requirements

Minimum supported client

Windows Vista, Windows XP with SP2

Minimum supported server

Windows Server 2008, Windows Server 2003 with SP1

Version

KB842773 on Windows Server 2003, and Windows XP

Header

Bits2_0.h (include Bits.h)

IDL

Bits2_0.idl

Library

Bits.lib

DLL

BitsPrx3.dll

IID

IID_IBackgroundCopyJob3 is defined as 443C8934-90FF-48ED-BCDE-26F5C7450042

See also

IBackgroundCopyFile2::SetRemoteName
IBackgroundCopyJob3

 

 

Weergeven: