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 code | Description |
|---|---|
| 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, DO replaces the text with the string found in NewPrefix. For example, to change "https://Server/Path/File.ext" to "https://NewServerName/Path/File.ext", set OldPrefix to "https://Server" and NewPrefix to "https://NewServerName". Note that DO 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), DO restarts the download. Otherwise, the transfer resumes from the same position on the new server. DO 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 https://Server\Dir\File.ext may not resolve. Consider using the IBackgroundCopyFile2::SetRemoteName method instead.
Requirements
Minimum supported client |
Windows 10, version 1709 [desktop apps only] |
Minimum supported server |
Windows Server 2016 [desktop apps only] |
Header |
Deliveryoptimization.h |
IDL |
DeliveryOptimization.idl |
Library |
Dosvc.lib |
DLL |
Dosvc.dll |
IID |
IID_IBackgroundCopyJob3 is defined as 443C8934-90FF-48ED-BCDE-26F5C7450042 |