RasGetCredentialsA-Funktion (ras.h)
Die RasGetCredentials-Funktion ruft die Benutzeranmeldeinformationen ab, die einem angegebenen RAS-Telefonbucheintrag zugeordnet sind.
Syntax
DWORD RasGetCredentialsA(
[in] LPCSTR unnamedParam1,
[in] LPCSTR unnamedParam2,
[in, out] LPRASCREDENTIALSA unnamedParam3
);
Parameter
[in] unnamedParam1
Zeiger auf eine NULL-endende Zeichenfolge, die den vollständigen Pfad und Dateinamen einer Telefonbuchdatei (PBK) angibt. Wenn dieser Parameter NULL ist, verwendet die Funktion die aktuelle Standardtelefonbuchdatei. Die Standardmäßige Telefonbuchdatei wird vom Benutzer im Eigenschaftenblatt Benutzereinstellungen des DialogfeldsDFÜ-Netzwerk ausgewählt.
[in] unnamedParam2
Zeiger auf eine NULL-endende Zeichenfolge, die den Namen eines Telefonbucheintrags angibt.
[in, out] unnamedParam3
Zeiger auf die RASCREDENTIALS-Struktur , die bei der Ausgabe die Benutzeranmeldeinformationen empfängt, die dem angegebenen Telefonbucheintrag zugeordnet sind.
Legen Sie bei der Eingabe den dwSize-Member der Struktur auf sizeof(RASCREDENTIALS) fest, und legen Sie das dwMask-Element fest, um die abzurufenden Anmeldeinformationen anzugeben. Wenn die Funktion zurückgegeben wird, gibt dwMask die Member an, die erfolgreich abgerufen wurden.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.
Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes oder ein Wert aus Routing- und RAS-Fehlercodes oder Winerror.h.
| Wert | Bedeutung |
|---|---|
|
Das angegebene Telefonbuch wurde nicht gefunden. |
|
Der angegebene Eintrag ist im Telefonbuch nicht vorhanden. |
|
Der lpCredentials-Parameter war NULL. |
|
Der dwSize-Member der RASCREDENTIALS-Struktur ist ein unbekannter Wert. |
Hinweise
Die RasGetCredentials-Funktion ruft die Anmeldeinformationen des letzten Benutzers ab, um eine Verbindung mithilfe des angegebenen Telefonbucheintrags herzustellen, oder die Anmeldeinformationen, die später in einem Aufruf der RasSetCredentials-Funktion für den Telefonbucheintrag angegeben wurden.
Diese Funktion ist die bevorzugte Methode zum sicheren Abrufen der Anmeldeinformationen, die einem RAS-Telefonbucheintrag zugeordnet sind. RasGetCredentials ersetzt die RasGetEntryDialParams-Funktion , die in zukünftigen Versionen von Windows möglicherweise nicht unterstützt wird.
RasGetCredentials gibt nicht das tatsächliche Kennwort zurück. Stattdessen enthält das szPassword-Element der RASCREDENTIALS-Struktur ein Handle für das gespeicherte Kennwort. Ersetzen Sie dieses Handle durch das gespeicherte Kennwort in nachfolgenden Aufrufen von RasSetCredentials und RasDial. Wenn dieses Handle angezeigt wird, ruft RasDial das gespeicherte Kennwort ab und verwendet es. Der Wert dieses Handles kann sich in zukünftigen Versionen des Betriebssystems ändern. entwickeln Sie keinen Code, der vom Inhalt oder Format dieses Werts abhängt.
Das dwMask-Element von RASCREDENTIALS enthält das RASCM_Password-Flag, wenn das System ein Kennwort für den angegebenen Eintrag gespeichert hat. Wenn das System kein Kennwort für diesen Eintrag gespeichert hat, enthält dwMask keine RASCM_Password.
Windows 2000/NT: Dieses Feature wird nicht unterstützt.
Wenn die dwMask der RASCREDENTIALS-Struktur das flag RASCM_DefaultCreds enthält, sind die zurückgegebenen Anmeldeinformationen die Standardanmeldeinformationen für eine Benutzerverbindung.
Verwenden Sie zum Abrufen eines vorinstallierten Schlüssels das Flag RASCM_PreSharedKey im Feld RASCREDENTIALS.dwMask.
Windows 2000/NT: Dieses Feature wird nicht unterstützt.
Der folgende Beispielcode erstellt den Telefonbucheintrag "RasEntryName", legt seine Anmeldeinformationen mithilfe von RasSetCredentials fest und ruft diese Anmeldeinformationen dann mithilfe von RasGetCredentials ab.
#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;
}
Hinweis
Der ras.h-Header definiert RasGetCredentials als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | ras.h |
| Bibliothek | Rasapi32.lib |
| DLL | Rasapi32.dll |