Método IBackgroundCopyJob2::SetCredentials (bits1_5.h)

Especifica as credenciais a serem usadas para uma solicitação de autenticação de usuário de servidor remoto ou proxy.

Sintaxe

HRESULT SetCredentials(
  [in] BG_AUTH_CREDENTIALS *credentials
);

Parâmetros

[in] credentials

Identifica o destino (proxy ou servidor), o esquema de autenticação e as credenciais do usuário a serem usadas para autenticação do usuário. Para obter detalhes, consulte a estrutura de BG_AUTH_CREDENTIALS .

Valor retornado

Esse método retorna os seguintes valores retornados, bem como outros.

Comentários

O BITS fornece as credenciais para um proxy ou servidor em resposta a uma solicitação de autenticação de usuário. Defina as credenciais antes da chamada inicial como Retomar.

Você deve chamar esse método para cada par de destino e esquema que deseja fornecer. Por exemplo, se você quiser especificar credenciais de proxy para autenticação Básica e Digest, chame esse método uma vez para especificar as credenciais Básicas e uma segunda vez para especificar as credenciais digest.

Se o trabalho contiver credenciais com o mesmo par de destino e esquema, as credenciais existentes serão substituídas pelas novas credenciais. As credenciais persistem durante a vida útil do trabalho. Para remover as credenciais do trabalho, chame o método IBackgroundCopyJob2::RemoveCredentials .

Se você souber os esquemas que o proxy ou o servidor solicitará, poderá fornecer apenas essas credenciais. Caso contrário, forneça credenciais para todos os esquemas.

O trabalho entrará no estado BG_JOB_STATE_ERROR se você não fornecer as credenciais solicitadas pelo proxy ou servidor ou o proxy ou servidor não puder autenticar as credenciais. Verifique o código de erro para determinar se a autenticação falhou no servidor (BG_E_HTTP_ERROR_401) ou proxy (BG_E_HTTP_ERROR_407). Para recuperar o código de erro, chame o método IBackgroundCopyJob::GetError para recuperar um ponteiro de interface IBackgroundCopyError . Em seguida, chame o método IBackgroundCopyError::GetError para recuperar o código de erro. Depois de determinar onde a autenticação falhou (proxy ou servidor), especifique novas credenciais a serem usadas para o proxy ou servidor e chame o método IBackgroundCopyJob::Resume para retomar o trabalho. Como não é possível determinar qual esquema falhou, especifique as credenciais para todos os esquemas antes de chamar o método Resume .

Não há nenhum método para recuperar as credenciais que você definiu.

Você deve chamar esse método no contexto do proprietário do trabalho.

Chamar o método IBackgroundCopyJob::TakeOwnership remove as credenciais do trabalho.

Para especificar credenciais implícitas (as credenciais do usuário conectado), defina o esquema como NTLM e o nome de usuário e a senha como NULL. Se você especificar credenciais implícitas para um proxy, o BITS também usará as credenciais implícitas para autenticação de servidor, a menos que você especifique credenciais explícitas do servidor.

Exemplos

O exemplo a seguir mostra como chamar o método SetCredentials para especificar credenciais básicas para uma solicitação de autenticação de usuário do servidor. O exemplo usa a função CredUIPromptForCredentials para capturar o nome de usuário e a senha. O exemplo pressupõe um ponteiro de interface IBackgroundCopyJob válido, pJob. O exemplo usa a função SecureZeroMemory para limpar os locais de memória associados às informações confidenciais. A função SecureZeroMemory é definida em WinBase.h.

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

CREDUI_INFO cuiinfo;
WCHAR szUserName[MAX_STR_LENGTH];  
WCHAR szPassword[MAX_STR_LENGTH];
DWORD rc;
IBackgroundCopyJob* pJob;
IBackgroundCopyJob2* pJob2 = NULL;
BG_AUTH_CREDENTIALS ac;

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, 
    NULL, CREDUI_FLAGS_DO_NOT_PERSIST | CREDUI_FLAGS_GENERIC_CREDENTIALS);

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

Requisitos

Confira também

Autenticação

BG_AUTH_CREDENTIALS

IBackgroundCopyJob2::RemoveCredentials