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.
| Código de retorno | Descrição |
|---|---|
|
Êxito |
|
Valor de enumeração de destino não reconhecido. |
|
Valor de enumeração de esquema não reconhecido. |
|
O nome de usuário é muito longo. Para obter o limite, consulte a estrutura BG_BASIC_CREDENTIALS . |
|
A senha é muito longa. Para obter o limite, consulte a estrutura BG_BASIC_CREDENTIALS . |
|
Os membros UserName e Password da estrutura BG_BASIC_CREDENTIALS não poderão ser NULL se você especificar o esquema Básico ou Digest. |
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
| Cliente mínimo com suporte | Windows Vista |
| Servidor mínimo com suporte | Windows Server 2003 |
| Plataforma de Destino | Windows |
| Cabeçalho | bits1_5.h (inclua Bits.h) |
| Biblioteca | Bits.lib |
| DLL | BitsPrx2.dll |
| Redistribuível | BITS 1.5 no Windows XP |