IBackgroundCopyJob2 ::SetCredentials, méthode (bits1_5.h)

Spécifie les informations d’identification à utiliser pour une demande d’authentification utilisateur de serveur proxy ou de 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 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.

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 pour Reprendre.

Vous devez appeler cette méthode pour chaque paire cible et schéma que vous souhaitez fournir. Par exemple, si vous souhaitez spécifier des informations d’identification proxy pour l’authentification De base et Digest, vous appelez cette méthode une fois pour spécifier les informations d’identification de base et une seconde 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 de schéma, les informations d’identification existantes sont remplacées par les nouvelles informations d’identification. Les informations d’identification persistent pour 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 ne pouvez fournir que ces informations d’identification. Sinon, fournissez des informations d’identification pour tous les schémas.

Le travail entre dans 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 de 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 de 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 des informations d’identification implicites (les informations d’identification de l’utilisateur connectés), 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 utilise également les informations d’identification implicites pour l’authentification du serveur, sauf si vous spécifiez des informations d’identification de serveur explicites.

Examples

L’exemple suivant montre comment appeler la méthode SetCredentials pour spécifier des informations d’identification de base pour une demande d’authentification utilisateur de 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));
}

Spécifications

Voir aussi

Authentification

BG_AUTH_CREDENTIALS

IBackgroundCopyJob2 ::RemoveCredentials