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
Zeigen Sie auf eine NULL--terminated-Zeichenfolge, die den vollständigen Pfad und Dateinamen einer PbK-Datei (Phone-Book) angibt. Wenn dieser Parameter NULL-ist, verwendet die Funktion die aktuelle Standarddatei des Telefonbuchs. Die Standardmäßige Telefonbuchdatei ist die vom Benutzer im Eigenschaftenblatt Benutzereinstellungen Eigenschaftenblatt des Dialogfelds DFÜ-Netzwerk ausgewählt.
[in] unnamedParam2
Zeigen Sie auf eine NULL--terminated-Zeichenfolge, die den Namen eines Telefonbucheintrags angibt.
[in, out] unnamedParam3
Zeigen Sie auf die RASCREDENTIALS- Struktur, die bei der Ausgabe die Benutzeranmeldeinformationen empfängt, die dem angegebenen Telefonbucheintrag zugeordnet sind.
Legen Sie bei eingaben das dwSize Member der Struktur auf sizeof(RASCREDENTIALS) fest, und legen Sie den dwMask Member fest, um die abzurufenden Anmeldeinformationen anzugeben. Wenn die Funktion zurückgegeben wird, gibt dwMask die Elemente 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 Remotezugriffsfehlercodes oder Winerror.h.
| Wert | Bedeutung |
|---|---|
|
Das angegebene Telefonbuch kann nicht gefunden werden. |
|
Der angegebene Eintrag ist im Telefonbuch nicht vorhanden. |
|
Der parameter lpCredentials war NULL. |
|
Der dwSize Mitglied der RASCREDENTIALS- Struktur ist ein unbekannter Wert. |
Bemerkungen
Die RasGetCredentials--Funktion ruft die Anmeldeinformationen des letzten Benutzers ab, um eine Verbindung mit dem angegebenen Telefonbucheintrag herzustellen, oder die anmeldeinformationen, die anschließend in einem Aufruf der RasSetCredentials--Funktion für den Eintrag für das Telefonbuch 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 das tatsächliche Kennwort nicht zurück. Stattdessen enthält das szPassword Mitglied der RASCREDENTIALS- Struktur ein Handle für das gespeicherte Kennwort. Ersetzen Sie dieses Handle für 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 Mitglied 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 RASCM_DefaultCreds Flag enthält, sind die zurückgegebenen Anmeldeinformationen die Standardanmeldeinformationen für eine Verbindung mit allen Benutzern.
Verwenden Sie zum Abrufen eines vorab freigegebenen Schlüssels das RASCM_PreSharedKey Flag im Feld RASCREDENTIALS.dwMask.
Windows 2000/NT: Dieses Feature wird nicht unterstützt.
Der folgende Beispielcode erstellt den "RasEntryName"-Telefonbucheintrag, legt seine Anmeldeinformationen mithilfe RasSetCredentials-fest und ruft diese Anmeldeinformationen dann mit 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;
}
Anmerkung
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
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 2000 Professional [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | ras.h |
| Library | Rasapi32.lib |
| DLL- | Rasapi32.dll |
Siehe auch
übersicht über Ras(Remote Access Service)