Método IBackgroundCopyJob2::SetCredentials (bits1_5.h)
Especifica las credenciales que se usarán para una solicitud de autenticación de usuario de servidor remoto o proxy.
Sintaxis
HRESULT SetCredentials(
[in] BG_AUTH_CREDENTIALS *credentials
);
Parámetros
[in] credentials
Identifica el destino (proxy o servidor), el esquema de autenticación y las credenciales del usuario que se van a usar para la autenticación de usuario. Para obtener más información, consulte la estructura BG_AUTH_CREDENTIALS .
Valor devuelto
Este método devuelve los siguientes valores devueltos, así como otros.
| Código devuelto | Descripción |
|---|---|
|
Correcto |
|
Valor de enumeración de destino no reconocido. |
|
Valor de enumeración de esquema no reconocido. |
|
El nombre de usuario es demasiado largo. Para obtener el límite, consulte la estructura BG_BASIC_CREDENTIALS . |
|
La contraseña es demasiado larga. Para obtener el límite, consulte la estructura BG_BASIC_CREDENTIALS . |
|
Los miembros UserName y Password de la estructura BG_BASIC_CREDENTIALS no pueden ser NULL si se especifica el esquema Basic o Digest. |
Comentarios
BITS proporciona las credenciales a un servidor proxy o servidor en respuesta a una solicitud de autenticación de usuario. Establezca las credenciales antes de la llamada inicial a Resume.
Debe llamar a este método para cada par de esquema y destino que desee proporcionar. Por ejemplo, si desea especificar credenciales de proxy para la autenticación básica y implícita, llamaría a este método una vez para especificar las credenciales básicas y una segunda vez para especificar las credenciales implícitas.
Si el trabajo contiene actualmente credenciales con el mismo par de esquema y destino, las credenciales existentes se reemplazan por las nuevas credenciales. Las credenciales se conservan durante la vida del trabajo. Para quitar las credenciales del trabajo, llame al método IBackgroundCopyJob2::RemoveCredentials .
Si conoce los esquemas que solicitará el proxy o el servidor, solo puede proporcionar esas credenciales. De lo contrario, proporcione credenciales para todos los esquemas.
El trabajo entra en el estado de BG_JOB_STATE_ERROR si no proporciona las credenciales solicitadas por el proxy o el servidor, o el proxy o el servidor no pueden autenticar las credenciales. Compruebe el código de error para determinar si se produjo un error de autenticación en el servidor (BG_E_HTTP_ERROR_401) o proxy (BG_E_HTTP_ERROR_407). Para recuperar el código de error, llame al método IBackgroundCopyJob::GetError para recuperar un puntero de interfaz IBackgroundCopyError . A continuación, llame al método IBackgroundCopyError::GetError para recuperar el código de error. Después de determinar dónde se produjo el error de autenticación (proxy o servidor), especifique las nuevas credenciales que se usarán para el proxy o el servidor y llame al método IBackgroundCopyJob::Resume para reanudar el trabajo. Dado que no se puede determinar qué esquema no se pudo realizar, especifique las credenciales de todos los esquemas antes de llamar al método Resume .
No hay ningún método para recuperar las credenciales que ha establecido.
Debe llamar a este método en el contexto del propietario del trabajo.
Al llamar al método IBackgroundCopyJob::TakeOwnership , se quitan las credenciales del trabajo.
Para especificar credenciales implícitas (las credenciales del usuario que ha iniciado sesión), establezca el esquema en NTLM y el nombre de usuario y la contraseña en NULL. Si especifica credenciales implícitas para un proxy, BITS también usará las credenciales implícitas para la autenticación del servidor a menos que especifique credenciales de servidor explícitas.
Ejemplos
En el ejemplo siguiente se muestra cómo llamar al método SetCredentials para especificar credenciales básicas para una solicitud de autenticación de usuario de servidor. En el ejemplo se usa la función CredUIPromptForCredentials para capturar el nombre de usuario y la contraseña. En el ejemplo se supone que hay un puntero de interfaz IBackgroundCopyJob válido, pJob. En el ejemplo se usa la función SecureZeroMemory para borrar las ubicaciones de memoria asociadas a la información confidencial. La función SecureZeroMemory se define en 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 compatible | Windows Vista |
| Servidor mínimo compatible | Windows Server 2003 |
| Plataforma de destino | Windows |
| Encabezado | bits1_5.h (incluir Bits.h) |
| Library | Bits.lib |
| Archivo DLL | BitsPrx2.dll |
| Redistribuible | BITS 1.5 en Windows XP |