IBackgroundCopyJob2::SetCredentials method
Specifies the credentials to use for a proxy or remote server user authentication request.
Syntax
HRESULT SetCredentials(
[in] BG_AUTH_CREDENTIALS *Credentials
);
Parameters
- Credentials [in]
Identifies the target (proxy or server), authentication scheme, and the user's credentials to use for user authentication.
Return value
This method returns the following return values, as well as others.
| Return code | Description |
|---|---|
| S_OK | Success |
| BG_E_INVALID_AUTH_TARGET | Unrecognized target enumeration value. |
| BG_E_INVALID_AUTH_SCHEME | Unrecognized scheme enumeration value. |
| BG_E_USERNAME_TOO_LARGE | The user name is too long. |
| BG_E_PASSWORD_TOO_LARGE | The password is too long. |
| E_INVALIDARG | The UserName and Password members of the BG_BASIC_CREDENTIALS structure cannot be NULL if you specify the Basic or Digest scheme. |
Remarks
DO provides the credentials to a proxy or server in response to a request for user authentication. Set the credentials before the initial call to Resume.
You must call this method for each target and scheme pair that you want to provide. For example, if you want to specify proxy credentials for both Basic and Digest authentication, you would call this method once to specify the Basic credentials and a second time to specify the Digest credentials.
If the job currently contains credentials with the same target and scheme pair, the existing credentials are replaced with the new credentials. The credentials persist for the life of the job. To remove the credentials from the job, call the IBackgroundCopyJob2::RemoveCredentials method.
If you know the schemes the proxy or server will request, you can provide only those credentials. Otherwise, provide credentials for all schemes.
The job enters the BG_JOB_STATE_ERROR state if you do not provide the credentials requested by the proxy or server, or the proxy or server cannot authenticate the credentials. Check the error code to determine if the authentication failed at the server (BG_E_HTTP_ERROR_401) or proxy (BG_E_HTTP_ERROR_407). To retrieve the error code, call the IBackgroundCopyJob::GetError method to retrieve an IBackgroundCopyError interface pointer. Then, call the IBackgroundCopyError::GetError method to retrieve the error code. After you determine where the authentication failed (proxy or server), specify new credentials to use for the proxy or server and call the IBackgroundCopyJob::Resume method to resume the job. Because you cannot determine which scheme failed, specify credentials for all schemes before calling the Resume method.
There is no method to retrieve credentials that you have set.
You must call this method in the context of the job's owner.
Calling the IBackgroundCopyJob::TakeOwnership method removes the credentials from the job.
To specify implicit credentials (the logged on user's credentials), set the scheme to NTLM and the user name and password to NULL. If you specify implicit credentials for a proxy, DO will also use the implicit credentials for server authentication unless you specify explicit server credentials.
Note DO ignores credentials for remote names that specify an SMB path.
Note DO does not authenticate the server or encrypt the channel. Use HTTPS if this is an issue for your application.
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_IBackgroundCopyJob2 is defined as 54B50739-686F-45EB-9DFF-D6A9A0FAA9AF |