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

Article
03/14/2023

Spécifie les informations d’identification à utiliser pour une demande d’authentification utilisateur proxy ou serveur distant.

Syntaxe

HRESULT SetCredentials(
  [in] BG_AUTH_CREDENTIALS *credentials
);

Paramètres

[in] credentials

Identifie la cible (proxy ou serveur), le schéma d’authentification et les informations d’identification de l’utilisateur à utiliser pour l’authentification de l’utilisateur. Pour plus d’informations, consultez la structure BG_AUTH_CREDENTIALS .

Valeur retournée

Cette méthode retourne les valeurs de retour suivantes, ainsi que d’autres.

Code de retour	Description
S_OK	Succès
BG_E_INVALID_AUTH_TARGET	Valeur d’énumération cible non reconnue.
BG_E_INVALID_AUTH_SCHEME	Valeur d’énumération de schéma non reconnue.
BG_E_USERNAME_TOO_LARGE	Le nom d’utilisateur est trop long. Pour connaître la limite, consultez la structure BG_BASIC_CREDENTIALS .
BG_E_PASSWORD_TOO_LARGE	Le mot de passe est trop long. Pour connaître la limite, consultez la structure BG_BASIC_CREDENTIALS .
E_INVALIDARG	Les membres UserName et Password de la structure BG_BASIC_CREDENTIALS ne peuvent pas être NULL si vous spécifiez le schéma De base ou Digest.

Remarques

BITS fournit les informations d’identification à un proxy ou un serveur en réponse à une demande d’authentification utilisateur. Définissez les informations d’identification avant l’appel initial sur Reprendre.

Vous devez appeler cette méthode pour chaque paire cible/schéma que vous souhaitez fournir. Par exemple, si vous souhaitez spécifier des informations d’identification de proxy pour l’authentification De base et Digest, vous devez appeler cette méthode une fois pour spécifier les informations d’identification de base et une deuxième fois pour spécifier les informations d’identification Digest.

Si le travail contient actuellement des informations d’identification avec la même paire cible et schéma, les informations d’identification existantes sont remplacées par les nouvelles informations d’identification. Les informations d’identification sont conservées pendant toute la durée du travail. Pour supprimer les informations d’identification du travail, appelez la méthode IBackgroundCopyJob2::RemoveCredentials .

Si vous connaissez les schémas demandés par le proxy ou le serveur, vous pouvez fournir uniquement ces informations d’identification. Sinon, fournissez des informations d’identification pour tous les schémas.

Le travail passe à l’état BG_JOB_STATE_ERROR si vous ne fournissez pas les informations d’identification demandées par le proxy ou le serveur, ou si le proxy ou le serveur ne peut pas authentifier les informations d’identification. Vérifiez le code d’erreur pour déterminer si l’authentification a échoué sur le serveur (BG_E_HTTP_ERROR_401) ou le proxy (BG_E_HTTP_ERROR_407). Pour récupérer le code d’erreur, appelez la méthode IBackgroundCopyJob::GetError pour récupérer un pointeur d’interface IBackgroundCopyError . Ensuite, appelez la méthode IBackgroundCopyError::GetError pour récupérer le code d’erreur. Après avoir déterminé où l’authentification a échoué (proxy ou serveur), spécifiez les nouvelles informations d’identification à utiliser pour le proxy ou le serveur et appelez la méthode IBackgroundCopyJob::Resume pour reprendre le travail. Étant donné que vous ne pouvez pas déterminer quel schéma a échoué, spécifiez les informations d’identification pour tous les schémas avant d’appeler la méthode Resume .

Il n’existe aucune méthode pour récupérer les informations d’identification que vous avez définies.

Vous devez appeler cette méthode dans le contexte du propriétaire du travail.

L’appel de la méthode IBackgroundCopyJob::TakeOwnership supprime les informations d’identification du travail.

Pour spécifier les informations d’identification implicites (les informations d’identification de l’utilisateur connecté), définissez le schéma sur NTLM et le nom d’utilisateur et le mot de passe sur NULL. Si vous spécifiez des informations d’identification implicites pour un proxy, BITS utilisera également les informations d’identification implicites pour l’authentification du serveur, sauf si vous spécifiez des informations d’identification de serveur explicites.

Note BITS ignore les informations d’identification des noms distants qui spécifient un chemin D’accès SMB.

Note BITS n’authentifie pas le serveur ni ne chiffre le canal. Utilisez HTTPS s’il s’agit d’un problème pour votre application.

Exemples

L’exemple suivant montre comment appeler la méthode SetCredentials pour spécifier des informations d’identification de base pour une demande d’authentification d’utilisateur serveur. L’exemple utilise la fonction CredUIPromptForCredentials pour capturer le nom d’utilisateur et le mot de passe. L’exemple suppose un pointeur d’interface IBackgroundCopyJob valide, pJob. L’exemple utilise la fonction SecureZeroMemory pour effacer les emplacements de mémoire associés aux informations sensibles. La fonction SecureZeroMemory est définie dans 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));
}

Configuration requise


Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2003
Plateforme cible	Windows
En-tête	bits1_5.h (include Bits.h)
Bibliothèque	Bits.lib
DLL	BitsPrx2.dll
Composant redistribuable	BITS 1.5 sur Windows XP

Voir aussi

Authentification

BG_AUTH_CREDENTIALS

IBackgroundCopyJob2::RemoveCredentials

Partager via