RasSetCredentialsA-Funktion (ras.h)

Artikel
08/25/2023

Die RasSetCredentials-Funktion legt die Benutzeranmeldeinformationen fest, die einem angegebenen RAS-Telefonbucheintrag zugeordnet sind.

Syntax

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

Parameter

[in] unnamedParam1

Ein Zeiger auf eine NULL-Zeichenfolge, die den vollständigen Pfad und Dateinamen einer TELEFONBUCHdatei (PBK) angibt. Wenn dieser Parameter NULL ist, verwendet die Funktion die aktuelle Standard-Telefonbuchdatei. Die Standard-Telefonbuchdatei wird vom Benutzer im Eigenschaftenblatt Benutzereinstellungen des DialogfeldsDFÜ-Netzwerk ausgewählt.

[in] unnamedParam2

Ein Zeiger auf eine NULL-Zeichenfolge, die den Namen eines Telefonbucheintrags angibt.

[in] unnamedParam3

Ein Zeiger auf eine RASCREDENTIALS-Struktur , die die Benutzeranmeldeinformationen angibt, die für den angegebenen Telefonbucheintrag festgelegt werden sollen. Legen Sie vor dem Aufrufen von RasSetCredentials das dwSize-Element der Struktur auf sizeof(RASCREDENTIALS) fest, und legen Sie den dwMask-Member so fest, dass die festzulegenden Anmeldeinformationen angegeben werden sollen.

[in] unnamedParam4

Ein Wert, der angibt, ob RasSetCredentials vorhandene Anmeldeinformationen löscht, indem sie auf die leere Zeichenfolge "" festgelegt werden. Wenn dieses Flag TRUE ist, gibt das dwMask-Element der RASCREDENTIALS-Struktur an, welche Anmeldeinformationen die Funktion auf die leere Zeichenfolge festlegt. Wenn dieses Flag FALSE ist, legt die Funktion die angegebenen Anmeldeinformationen entsprechend dem Inhalt der entsprechenden RASCREDENTIALS-Member fest.

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
ERROR_CANNOT_OPEN_PHONEBOOK	Das angegebene Telefonbuch wurde nicht gefunden.
ERROR_INVALID_PARAMETER	Der lpCredentials-Parameter war NULL, oder der angegebene Eintrag ist nicht im Telefonbuch vorhanden.
ERROR_ACCESS_DENIED	Eine der folgenden Bedingungen ist aufgetreten: Die aufrufende Anwendung hat versucht, Standardanmeldeinformationen für eine Benutzerverbindung festzulegen. Standardanmeldeinformationen können nur für eine All-User-Verbindung festgelegt werden. Der Benutzer verfügt nicht über die richtigen Berechtigungen, um vorab freigegebene Schlüssel oder Anmeldeinformationen für alle Benutzer festzulegen, wenn alle Benutzerverbindungsoide vorhanden sind. Nur Administratoren können diese Aufgaben ausführen.

Hinweise

Die RasSetCredentials-Funktion legt die Benutzeranmeldeinformationen fest, die einem angegebenen RAS-Telefonbucheintrag zugeordnet sind. Die mit einem Telefonbucheintrag gespeicherten Anmeldeinformationen sind die Anmeldeinformationen des letzten Benutzers, der eine erfolgreiche Verbindung mithilfe des angegebenen Telefonbucheintrags herstellen konnte, oder die Anmeldeinformationen, die später in einem Anruf der RasSetCredentials - oder RasSetEntryDialParams-Funktion für den Telefonbucheintrag angegeben wurden.

Die RasSetCredentials-Funktion ist die bevorzugte Methode zum sicheren Speichern von Anmeldeinformationen mit einem Telefonbucheintrag. RasSetCredentials ersetzt die RasSetEntryDialParams-Funktion , die in zukünftigen Versionen des Windows-Betriebssystems möglicherweise nicht unterstützt wird.

Ein Kennworthandle ist "****************" (16 Sternchen). Wenn Sie RasGetCredentials aufrufen und 16 *s zurück im Kennwortfeld erhalten, verfügen Sie über ein gespeichertes Kennwort, das aus Sicherheitsgründen nicht im Nur-Text-Format zurückgerufen wird. Wenn das szPassword-Element der RASCREDENTIALS-Struktur das Kennworthandle (16 *s) enthält, das von RasGetCredentials oder RasGetEntryDialParams zurückgegeben wird, ändert der nächste Aufruf von RasSetCredentials das gespeicherte Kennwort nicht.

Um die Standardanmeldeinformationen für eine All-User-Verbindung festzulegen, legen Sie das RASCM_DefaultCreds-Flag im dwMask-Element der RASCREDENTIALS-Struktur fest, auf die der lpCredentials-Parameter verweist. Wenn Sie versuchen, Standardanmeldeinformationen für eine Benutzerverbindung festzulegen, gibt RasSetCredentialsERROR_ACCESS_DENIED zurück.

Wenn die aufrufende Anwendung beim Festlegen von Anmeldeinformationen für eine Verbindung mit allen Benutzern einen Wert ungleich NULL für den Telefonbuchparameter lpszPhonebook angibt, muss sich die Telefonbuchdatei im Telefonbuchverzeichnis unter dem Anwendungsdatenpfad für alle Benutzer befinden. Um den richtigen Speicherort für die Telefonbuchdatei zu erhalten, rufen Sie zuerst SHGetFolderPath mit dem CSIDL-WertCSIDL_COMMON_APPDATA auf. SHGetFolderPath gibt den Anwendungsdatenpfad für alle Benutzer zurück. Fügen Sie die folgende Zeichenfolge an diesen Pfad an:

Microsoft\Network\Connections\Pbk

Der kombinierte Pfad ist der richtige Speicherort für die Telefonbuchdatei.

Hinweis Das Angeben eines Nicht-NULL-Werts für den lpszPhonebook-Parameter wird in späteren Versionen des Windows-Betriebssystems möglicherweise nicht unterstützt.

Verwenden Sie zum Festlegen eines vorab freigegebenen Schlüssels das Flag RASCM_PreSharedKey in RASCREDENTIALS. dwMask-Feld .

Hinweis

Der ras.h-Header definiert RasSetCredentials als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code 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