Fungsi RasGetCredentialsA (ras.h)
Fungsi RasGetCredentials mengambil kredensial pengguna yang terkait dengan entri buku telepon RAS tertentu.
Sintaks
DWORD RasGetCredentialsA(
[in] LPCSTR unnamedParam1,
[in] LPCSTR unnamedParam2,
[in, out] LPRASCREDENTIALSA unnamedParam3
);
Parameter
[in] unnamedParam1
Penunjuk ke string yang dihentikan null yang menentukan jalur lengkap dan nama file dari file buku telepon (PBK). Jika parameter ini ADALAH 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, out] unnamedParam3
Penunjuk ke struktur RASCREDENTIALS yang, pada output, menerima kredensial pengguna yang terkait dengan entri buku telepon yang ditentukan.
Pada input, atur anggota dwSize struktur ke sizeof (RASCREDENTIALS), dan atur anggota dwMask untuk menunjukkan informasi kredensial yang akan diambil. Saat fungsi kembali, dwMask menunjukkan anggota yang berhasil diambil.
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 |
|---|---|
|
Buku telepon yang ditentukan tidak dapat ditemukan. |
|
Entri yang ditentukan tidak ada di buku telepon. |
|
Parameter lpCredentials adalah NULL. |
|
Anggota dwSize dari struktur RASCREDENTIALS adalah nilai yang tidak dikenali. |
Keterangan
Fungsi RasGetCredentials mengambil kredensial pengguna terakhir untuk terhubung menggunakan entri buku telepon yang ditentukan, atau kredensial yang kemudian ditentukan dalam panggilan ke fungsi RasSetCredentials untuk entri buku telepon.
Fungsi ini adalah cara yang disukai untuk mengambil kredensial yang terkait dengan entri buku telepon RAS dengan aman. RasGetCredentials menggantikan fungsi RasGetEntryDialParams , yang mungkin tidak didukung dalam rilis Windows di masa mendatang.
RasGetCredentials tidak mengembalikan kata sandi yang sebenarnya. Sebagai gantinya, anggota szPassword dari struktur RASCREDENTIALS berisi handel ke kata sandi yang disimpan. Ganti handel ini untuk kata sandi yang disimpan dalam panggilan berikutnya ke RasSetCredentials dan RasDial. Ketika disajikan dengan handel ini, RasDial mengambil dan menggunakan kata sandi yang disimpan. Nilai handel ini dapat berubah dalam versi sistem operasi yang akan datang; jangan kembangkan kode yang bergantung pada konten atau format nilai ini.
Anggota dwMaskRASCREDENTIALS berisi bendera RASCM_Password jika sistem telah menyimpan kata sandi untuk entri yang ditentukan. Jika sistem tidak memiliki kata sandi yang disimpan untuk entri ini, dwMask tidak berisi RASCM_Password.
Windows 2000/NT: Fitur ini tidak didukung.
Jika dwMask struktur RASCREDENTIALS berisi bendera RASCM_DefaultCreds, kredensial yang dikembalikan adalah kredensial default untuk koneksi semua pengguna.
Untuk mengambil kunci yang dibagikan sebelumnya, gunakan bendera RASCM_PreSharedKey di bidang RASCREDENTIALS.dwMask.
Windows 2000/NT: Fitur ini tidak didukung.
Kode sampel berikut membuat entri buku telepon "RasEntryName", mengatur kredensialnya menggunakan RasSetCredentials, lalu mengambil kredensial tersebut menggunakan RasGetCredentials.
#include <windows.h>
#include "ras.h"
#include <stdio.h>
#include <tchar.h>
#include "strsafe.h"
#define PHONE_NUMBER_LENGTH 7
#define DEVICE_NAME_LENGTH 5
#define DEVICE_TYPE_LENGTH 5
#define DOMAIN_NAME_LENGTH 9
#define USER_NAME_LENGTH 11
DWORD __cdecl wmain(){
DWORD dwRet = ERROR_SUCCESS;
LPTSTR lpszEntry = L"RasEntryName";
LPTSTR lpszPhoneNumber = L"5555555";
LPTSTR lpszDeviceName = L"Modem";
LPTSTR lpszDeviceType = RASDT_Modem;
LPTSTR lpszDomainName = L"RASDomain";
LPTSTR lpszUserName = L"RASUserName";
/***********************************************************************************************/
// Create a new phone book entry
/***********************************************************************************************/
// Allocate heap memory for the RASENTRY structure
LPRASENTRY lpentry = (LPRASENTRY)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASENTRY));
if (lpentry == NULL){
wprintf(L"HeapAlloc failed!\n");
return 0;
}
// The RASENTRY->dwSize member has to be initialized or the RRAS RasValidateEntryName() and
// RasSetEntryProperties APIs will fail below.
lpentry->dwSize = sizeof(RASENTRY);
lpentry->dwFramingProtocol = RASFP_Ppp;
lpentry->dwfOptions = 0;
lpentry->dwType = RASFP_Ppp;
dwRet |= StringCchCopyN(lpentry->szLocalPhoneNumber, RAS_MaxPhoneNumber, lpszPhoneNumber, PHONE_NUMBER_LENGTH);
dwRet |= StringCchCopyN(lpentry->szDeviceName, RAS_MaxDeviceName, lpszDeviceName, DEVICE_NAME_LENGTH);
dwRet |= StringCchCopyN(lpentry->szDeviceType, RAS_MaxDeviceType, lpszDeviceType, DEVICE_TYPE_LENGTH);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RASENTRY structure initialization failed!\n");
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
// Validate the new entry's name
dwRet = RasValidateEntryName(NULL, lpszEntry);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RasValidateEntryName failed: Error = %d\n", dwRet);
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
// Create and set the new entry's properties
dwRet = RasSetEntryProperties(NULL, lpszEntry, lpentry, lpentry->dwSize, NULL, 0);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RasSetEntryProperties failed: Error = %d\n", dwRet);
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
/******************************************************************************************/
// Set and get the new entry's credentials
/******************************************************************************************/
// Allocate heap memory for the RASCREDENTIALS structure
LPRASCREDENTIALS lpCred = (LPRASCREDENTIALS) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASCREDENTIALS));
if (lpCred == NULL){
wprintf(L"HeapAlloc failed!\n");
return 0;
}
// The RASCREDENTIALS->dwsize member must be initialized or the RRAS RasSetCredentials() and
// RasGetCredentials() APIs will fail below
lpCred->dwSize = sizeof(RASCREDENTIALS);
// The entry's credentials must first be set with RasSetCredentials() before they can be
// retrieved with RasGetCredentials(). The values below are used to set the new entry's credentials.
dwRet |= StringCchCopyN(lpCred->szDomain, DNLEN, lpszDomainName, DOMAIN_NAME_LENGTH);
dwRet |= StringCchCopyN(lpCred->szUserName, UNLEN, lpszUserName, USER_NAME_LENGTH);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RASCREDENTIALS structure initialization failed!\n");
HeapFree(GetProcessHeap(), 0, lpCred);
return 0;
}
// The username, password, and Domain credentials are valid
lpCred->dwMask = RASCM_UserName | RASCM_Password | RASCM_Domain;
// Set the newly created entry's credentials
dwRet = RasSetCredentials(NULL, lpszEntry, lpCred, FALSE);
// The same RASCREDENTIALS structure is used to 'set' and 'get' the credentials. Therefore, zero out
// its values. (this proves RasGetCredentials works below!)
dwRet |= StringCchCopyN(lpCred->szDomain, DNLEN, L"", 0);
dwRet |= StringCchCopyN(lpCred->szUserName, UNLEN, L"", 0);
dwRet |= StringCchCopyN(lpCred->szPassword, UNLEN, L"", 0);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RASCREDENTIALS structure reset failed!\n");
HeapFree(GetProcessHeap(), 0, lpCred);
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
// Grab the newly created entry's credentials
dwRet = RasGetCredentials(NULL, lpszEntry, lpCred);
if(dwRet == ERROR_SUCCESS){
wprintf(L"The following credentials were retrieved for the entry: %s\n\tUser name: %s\n\tPassword: %s\n\tDomain: %s\n", lpszEntry, lpCred->szUserName, lpCred->szPassword, lpCred->szDomain);
}else{
wprintf(L"RasValidateEntryName failed: Error = %d\n", dwRet);
}
// Clean up: delete the new entry
dwRet = RasDeleteEntry(NULL, lpszEntry);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RasDeleteEntry failed: Error = %d\n", dwRet);
}
HeapFree(GetProcessHeap(), 0, lpentry);
HeapFree(GetProcessHeap(), 0, lpCred);
return 0;
}
Catatan
Header ras.h mendefinisikan RasGetCredentials 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 |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk