Metode IBackgroundCopyJob2::SetCredentials (bits1_5.h)

  • Artikel

Menentukan kredensial yang akan digunakan untuk permintaan autentikasi pengguna proksi atau server jarak jauh.

Sintaks

HRESULT SetCredentials(
  [in] BG_AUTH_CREDENTIALS *credentials
);

Parameter

[in] credentials

Mengidentifikasi target (proksi atau server), skema autentikasi, dan kredensial pengguna yang akan digunakan untuk autentikasi pengguna. Untuk detailnya, lihat struktur BG_AUTH_CREDENTIALS .

Nilai kembali

Metode ini mengembalikan nilai pengembalian berikut, serta nilai lainnya.

Menampilkan kode Deskripsi
S_OK
 Berhasil
BG_E_INVALID_AUTH_TARGET
 Nilai enumerasi target yang tidak dikenal.
BG_E_INVALID_AUTH_SCHEME
 Nilai enumerasi skema yang tidak dikenal.
BG_E_USERNAME_TOO_LARGE
 Nama pengguna terlalu panjang. Untuk batasnya, lihat struktur BG_BASIC_CREDENTIALS .
BG_E_PASSWORD_TOO_LARGE
 Kata sandi terlalu panjang. Untuk batasnya, lihat struktur BG_BASIC_CREDENTIALS .
E_INVALIDARG
 Anggota Nama Pengguna dan Kata Sandi dari struktur BG_BASIC_CREDENTIALS tidak boleh NULL jika Anda menentukan skema Dasar atau Hash.

Keterangan

BITS menyediakan kredensial ke proksi atau server sebagai respons terhadap permintaan autentikasi pengguna. Atur kredensial sebelum panggilan awal ke Lanjutkan.

Anda harus memanggil metode ini untuk setiap target dan pasangan skema yang ingin Anda sediakan. Misalnya, jika Anda ingin menentukan kredensial proksi untuk autentikasi Dasar dan Hash, Anda akan memanggil metode ini sekali untuk menentukan kredensial Dasar dan kedua kalinya untuk menentukan kredensial Hash.

Jika pekerjaan saat ini berisi kredensial dengan target dan pasangan skema yang sama, kredensial yang ada diganti dengan kredensial baru. Kredensial bertahan untuk kehidupan pekerjaan. Untuk menghapus kredensial dari pekerjaan, panggil metode IBackgroundCopyJob2::RemoveCredentials .

Jika Anda mengetahui skema yang akan diminta proksi atau server, Anda hanya dapat memberikan kredensial tersebut. Jika tidak, berikan kredensial untuk semua skema.

Pekerjaan memasuki status BG_JOB_STATE_ERROR jika Anda tidak memberikan kredensial yang diminta oleh proksi atau server, atau proksi atau server tidak dapat mengautentikasi kredensial. Periksa kode kesalahan untuk menentukan apakah autentikasi gagal di server (BG_E_HTTP_ERROR_401) atau proksi (BG_E_HTTP_ERROR_407). Untuk mengambil kode kesalahan, panggil metode IBackgroundCopyJob::GetError untuk mengambil penunjuk antarmuka IBackgroundCopyError . Kemudian, panggil metode IBackgroundCopyError::GetError untuk mengambil kode kesalahan. Setelah Anda menentukan di mana autentikasi gagal (proksi atau server), tentukan kredensial baru yang akan digunakan untuk proksi atau server dan panggil metode IBackgroundCopyJob::Resume untuk melanjutkan pekerjaan. Karena Anda tidak dapat menentukan skema mana yang gagal, tentukan kredensial untuk semua skema sebelum memanggil metode Resume .

Tidak ada metode untuk mengambil kredensial yang telah Anda tetapkan.

Anda harus memanggil metode ini dalam konteks pemilik pekerjaan.

Memanggil metode IBackgroundCopyJob::TakeOwnership menghapus kredensial dari pekerjaan.

Untuk menentukan kredensial implisit (kredensial pengguna yang masuk), atur skema ke NTLM dan nama pengguna dan kata sandi ke NULL. Jika Anda menentukan kredensial implisit untuk proksi, BITS juga akan menggunakan kredensial implisit untuk autentikasi server kecuali Anda menentukan kredensial server eksplisit.

Catatan BITS mengabaikan kredensial untuk nama jarak jauh yang menentukan jalur SMB.
 
Catatan BITS tidak mengautentikasi server atau mengenkripsi saluran. Gunakan HTTPS jika ini adalah masalah untuk aplikasi Anda.
 

Contoh

Contoh berikut menunjukkan cara memanggil metode SetCredentials untuk menentukan kredensial Dasar untuk permintaan autentikasi pengguna server. Contohnya menggunakan fungsi CredUIPromptForCredentials untuk menangkap nama pengguna dan kata sandi. Contoh mengasumsikan penunjuk antarmuka IBackgroundCopyJob yang valid, pJob. Contohnya menggunakan fungsi SecureZeroMemory untuk menghapus lokasi memori yang terkait dengan informasi sensitif. Fungsi SecureZeroMemory didefinisikan dalam 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));
}

Persyaratan

   
Klien minimum yang didukung Windows Vista
Server minimum yang didukung Windows Server 2003
Target Platform Windows
Header bits1_5.h (termasuk Bits.h)
Pustaka Bits.lib
DLL BitsPrx2.dll
Redistribusi BITS 1.5 di Windows XP

Lihat juga

Autentikasi

BG_AUTH_CREDENTIALS

IBackgroundCopyJob2::RemoveCredentials