Fungsi RasSetCredentialsA (ras.h)

Artikel
03/15/2023

Fungsi RasSetCredentials mengatur kredensial pengguna yang terkait dengan entri buku telepon RAS tertentu.

Sintaks

DWORD RasSetCredentialsA(
  [in] LPCSTR            unnamedParam1,
  [in] LPCSTR            unnamedParam2,
  [in] LPRASCREDENTIALSA unnamedParam3,
  [in] BOOL              unnamedParam4
);

Parameter

[in] unnamedParam1

Penunjuk ke string yang dihentikan null yang menentukan jalur lengkap dan nama file file buku telepon (PBK). Jika parameter ini NULL, fungsi menggunakan file buku telepon default saat ini. File buku telepon default adalah file yang dipilih oleh pengguna di lembar properti Preferensi Pengguna dari kotak dialog Jaringan Dial-Up .

[in] unnamedParam2

Penunjuk ke string yang dihentikan null yang menentukan nama entri buku telepon.

[in] unnamedParam3

Penunjuk ke struktur RASCREDENTIALS yang menentukan kredensial pengguna yang akan diatur untuk entri buku telepon yang ditentukan. Sebelum memanggil RasSetCredentials, atur anggota dwSize struktur ke sizeof(RASCREDENTIALS) dan atur anggota dwMask untuk menunjukkan informasi kredensial yang akan ditetapkan.

[in] unnamedParam4

Nilai yang menentukan apakah RasSetCredentials menghapus kredensial yang ada dengan mengaturnya ke string kosong, "". Jika bendera ini TRUE, anggota dwMask dari struktur RASCREDENTIALS menunjukkan kredensial mana yang diatur fungsi ke string kosong. Jika bendera ini FALSE, fungsi mengatur kredensial yang ditunjukkan sesuai dengan konten anggota RASCREDENTIALS yang sesuai.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan berikut atau nilai dari Kode Kesalahan Perutean dan Akses Jarak Jauh atau WinError.h.

Nilai	Makna
ERROR_CANNOT_OPEN_PHONEBOOK	Buku telepon yang ditentukan tidak dapat ditemukan.
ERROR_INVALID_PARAMETER	Parameter lpCredentials adalah NULL, atau entri yang ditentukan tidak ada dalam buku telepon.
ERROR_ACCESS_DENIED	Salah satu kondisi berikut terjadi: Aplikasi panggilan mencoba mengatur kredensial default untuk koneksi per pengguna. Kredensial default hanya dapat diatur untuk koneksi semua pengguna. Pengguna tidak memiliki hak istimewa yang benar untuk mengatur kunci atau kredensial yang dibagikan sebelumnya untuk semua pengguna jika terjadi konekoid semua pengguna. Hanya administrator yang dapat menyelesaikan tugas-tugas ini.

Keterangan

Fungsi RasSetCredentials mengatur kredensial pengguna yang terkait dengan entri buku telepon RAS tertentu. Kredensial yang disimpan dengan entri buku telepon adalah kredensial pengguna terakhir yang berhasil terhubung dengan menggunakan entri buku telepon yang ditentukan, atau kredensial yang kemudian ditentukan dalam panggilan ke fungsi RasSetCredentials atau RasSetEntryDialParams untuk entri buku telepon.

Fungsi RasSetCredentials adalah cara yang disukai untuk menyimpan kredensial dengan aman dengan entri buku telepon. RasSetCredentials menggantikan fungsi RasSetEntryDialParams , yang mungkin tidak didukung dalam rilis sistem operasi Windows di masa mendatang.

Handel kata sandi adalah "****************** " (16 tanda bintang). Jika Anda memanggil RasGetCredentials dan menerima 16 *s kembali di bidang kata sandi, Anda memiliki kata sandi yang disimpan dan, karena alasan keamanan, itu tidak akan diberikan kembali kepada Anda dalam teks biasa. Jika anggota szPassword dari struktur RASCREDENTIALS berisi handel kata sandi (16 *s) yang dikembalikan oleh RasGetCredentials atau RasGetEntryDialParams, panggilan berikutnya ke RasSetCredentials tidak akan mengubah kata sandi yang disimpan.

Untuk mengatur kredensial default untuk koneksi semua pengguna, atur bendera RASCM_DefaultCreds di anggota dwMask dari struktur RASCREDENTIALS yang ditunjukkan oleh parameter lpCredentials . Jika Anda mencoba mengatur kredensial default untuk koneksi per pengguna, RasSetCredentials mengembalikan ERROR_ACCESS_DENIED.

Saat mengatur kredensial untuk koneksi semua pengguna, jika aplikasi panggilan menentukan nilai non-NULL untuk parameter buku telepon, lpszPhonebook, file buku telepon harus terletak di direktori buku telepon di bawah jalur data aplikasi semua pengguna. Untuk mendapatkan lokasi yang benar untuk file buku telepon, pertama-tama panggil SHGetFolderPath dengan nilai CSIDLCSIDL_COMMON_APPDATA. SHGetFolderPath mengembalikan jalur data aplikasi semua pengguna. Tambahkan string berikut ke jalur ini:

Microsoft\Network\Connections\Pbk

Jalur gabungan adalah lokasi yang benar untuk file buku telepon.

Catatan Menentukan nilai non-NULL untuk parameter lpszPhonebook mungkin tidak didukung di versi sistem operasi Windows yang lebih baru.

Untuk mengatur kunci yang telah dibagikan sebelumnya, gunakan bendera RASCM_PreSharedKey di RASCREDENTIALS. bidang dwMask .

Catatan

Header ras.h mendefinisikan RasSetCredentials sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	ras.h
Pustaka	Rasapi32.lib
DLL	Rasapi32.dll