IBackgroundCopyJob2::SetCredentials method

Specifies the credentials to use for a proxy or remote server user authentication request.


HRESULT SetCredentials(
  BG_AUTH_CREDENTIALS *credentials



Identifies the target (proxy or server), authentication scheme, and the user's credentials to use for user authentication. For details, see the BG_AUTH_CREDENTIALS structure.

Return Value

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

Return code Description
Unrecognized target enumeration value.
Unrecognized scheme enumeration value.
The user name is too long. For the limit, see the BG_BASIC_CREDENTIALS structure.
The password is too long. For the limit, see the BG_BASIC_CREDENTIALS structure.
The UserName and Password members of the BG_BASIC_CREDENTIALS structure cannot be NULL if you specify the Basic or Digest scheme.


BITS 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, BITS will also use the implicit credentials for server authentication unless you specify explicit server credentials.

Note  BITS ignores credentials for remote names that specify an SMB path.
Note  BITS does not authenticate the server or encrypt the channel. Use HTTPS if this is an issue for your application.


The following example shows how to call the SetCredentials method to specify Basic credentials for a server user authentication request. The example uses the CredUIPromptForCredentials function to capture the user name and password. The example assumes a valid IBackgroundCopyJob interface pointer, pJob. The example uses the SecureZeroMemory function to clear the memory locations associated with the sensitive information. The SecureZeroMemory function is defined in WinBase.h.

#define MAX_STR_LENGTH 300+1    // BITS limit for user name and password

CREDUI_INFO cuiinfo;
IBackgroundCopyJob* pJob;
IBackgroundCopyJob2* pJob2 = NULL;

cuiinfo.cbSize = sizeof(CREDUI_INFO);
cuiinfo.hbmBanner = NULL;
cuiinfo.hwndParent = NULL; //Desktop is parent
cuiinfo.pszCaptionText = L"Server Authentication";
cuiinfo.pszMessageText = L"Enter user credentials for Basic authentication.";

//Initialize the UserName and Password fields. This example sets  
//UserName to blank, but you could also set UserName to the owner 
//of the job or the current user. For an example that retrieves the owner's
//name, see the example code for the IBackgroundCopyJob::GetOwner method. 
szUserName[0] = L'\0';
szPassword[0] = L'\0';
rc = CredUIPromptForCredentials(&cuiinfo, NULL, NULL, 0,
    szUserName, MAX_STR_LENGTH,
    szPassword, MAX_STR_LENGTH, 

if (NO_ERROR == rc)
    pJob->QueryInterface(__uuidof(IBackgroundCopyJob2), (void**)&pJob2);
    ac.Target = BG_AUTH_TARGET_SERVER;
    ac.Scheme = BG_AUTH_SCHEME_BASIC;
    ac.Credentials.Basic.UserName = szUserName;
    ac.Credentials.Basic.Password = szPassword;
    hr = pJob2->SetCredentials(&ac);
    if (FAILED(hr))
      //Handle error
    SecureZeroMemory(szUserName, sizeof(szUserName));
    SecureZeroMemory(szPassword, sizeof(szPassword));


Minimum supported client Windows Vista
Minimum supported server Windows Server 2003
Target Platform Windows
Header bits1_5.h (include Bits.h)
Library Bits.lib
DLL BitsPrx2.dll
Redistributable BITS 1.5 on Windows XP

See Also