RasDialA-Funktion (ras.h)

Artikel
08/25/2023

Die RasDial-Funktion stellt eine RAS-Verbindung zwischen einem RAS-Client und einem RAS-Server her. Die Verbindungsdaten enthalten Rückruf- und Benutzerauthentifizierungsinformationen.

Syntax

DWORD RasDialA(
  [in]  LPRASDIALEXTENSIONS unnamedParam1,
  [in]  LPCSTR              unnamedParam2,
  [in]  LPRASDIALPARAMSA    unnamedParam3,
  [in]  DWORD               unnamedParam4,
  [in]  LPVOID              unnamedParam5,
  [out] LPHRASCONN          unnamedParam6
);

Parameter

[in] unnamedParam1

Zeiger auf eine RASDIALEXTENSIONS-Struktur , die eine Reihe erweiterter RasDial-Features angibt, die aktiviert werden sollen. Legen Sie diesen Parameter auf NULL fest, wenn diese Features nicht aktiviert werden müssen.

[in] unnamedParam2

Zeiger auf eine NULL-beendete 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] unnamedParam3

Zeiger auf eine RASDIALPARAMS-Struktur , die Aufrufparameter für die RAS-Verbindung angibt. Verwenden Sie die RasGetEntryDialParams-Funktion , um eine Kopie dieser Struktur für einen bestimmten Telefonbucheintrag abzurufen.

Der Aufrufer muss den dwSize-Member der RASDIALPARAMS-Struktur auf sizeof(RASDIALPARAMS) festlegen, um die Version der übergebenen Struktur zu identifizieren.

Wenn das element szPhoneNumber der RASDIALPARAMS-Struktur eine leere Zeichenfolge ist, verwendet RasDial die im Telefonbucheintrag gespeicherte Telefonnummer.

[in] unnamedParam4

Gibt die Art des lpvNotifier-Parameters an . Wenn lpvNotifierNULL ist, wird dwNotifierType ignoriert. Wenn lpvNotifier nicht NULL ist, legen Sie dwNotifierType auf einen der folgenden Werte fest.

Wert	Bedeutung
0	Der lpvNotifier-Parameter verweist auf eine RasDialFunc-Rückruffunktion .
1	Der lpvNotifier-Parameter verweist auf eine RasDialFunc1-Rückruffunktion .
2	Der lpvNotifier-Parameter verweist auf eine RasDialFunc2-Rückruffunktion .

[in] unnamedParam5

Gibt ein Fensterhandle oder eine RasDialFunc-, RasDialFunc1- oder RasDialFunc2-Rückruffunktion an, um RasDial-Ereignisbenachrichtigungen zu empfangen. Der dwNotifierType-Parameter gibt die Art von lpvNotifier an. Weitere Details finden Sie in der vorherigen Beschreibung.

Wenn dieser Parameter nicht NULL ist, sendet RasDial dem Fenster eine Nachricht oder ruft die Rückruffunktion für jedes RasDial-Ereignis auf. Darüber hinaus wird der RasDial-Aufruf asynchron ausgeführt: RasDial gibt sofort zurück, bevor die Verbindung hergestellt wird, und kommuniziert seinen Fortschritt über das Fenster oder die Rückruffunktion.

Wenn lpvNotifierNULL ist, wird der RasDial-Aufruf synchron ausgeführt: RasDial wird erst zurückgegeben, wenn der Verbindungsversuch erfolgreich abgeschlossen oder fehlgeschlagen ist.

Wenn lpvNotifier nicht NULL ist, können nach dem ersten Aufruf von RasDial jederzeit Benachrichtigungen an das Fenster oder die Rückruffunktion erfolgen. Benachrichtigungen enden, wenn eines der folgenden Ereignisse auftritt:

Die Verbindung wird hergestellt. Anders ausgedrückt: Der RAS-Verbindungsstatus ist RASCS_Connected.
Bei der Verbindung tritt ein Fehler auf. Mit anderen Worten, dwError ist nichtzero.
RasHangUp wird für die Verbindung aufgerufen.

Die Rückrufbenachrichtigungen werden im Kontext eines Threads ausgeführt, der während des ersten Aufrufs von RasDial erfasst wurde.

[out] unnamedParam6

Zeiger auf eine Variable vom Typ HRASCONN. Legen Sie die HRASCONN-Variable auf NULL fest, bevor Sie RasDial aufrufen. Wenn RasDial erfolgreich ist, speichert es ein Handle für die RAS-Verbindung in *lphRasConn.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS und ein Handle für die RAS-Verbindung in der Variablen zurückgegeben, auf die von lphRasConn verwiesen wird.

Wenn die Funktion fehlschlägt, stammt der Rückgabewert von Routing- und RAS-Fehlercodes oder Winerror.h.

Hinweise

Fehler, die nach der sofortigen Rückgabe auftreten, können von RasGetConnectStatus erkannt werden. Daten sind so lange verfügbar, bis eine Anwendung RasHangUp aufruft , um die Verbindung aufzugeben.

Eine Anwendung muss Schließlich RasHangUp aufrufen, wenn ein Nicht-NULL-Verbindungshandle in *lphRasConn gespeichert wird. Dies gilt auch dann, wenn RasDial einen Nonzero-Wert (Error) zurückgibt.

Eine Anwendung kann RasHangUp über eine RasDial-Notifier-Rückruffunktion sicher aufrufen. Wenn dies geschieht, tritt der Aufhänger jedoch erst auf, wenn die Routine zurückkehrt.

Wenn die Struktur, auf die von lpRasDialExtensions verwiesen wird, RDEOPT_PausedStates aktiviert, wird die RasDial-Funktion immer dann angehalten, wenn sie in einen Zustand wechselt, in dem das RASCS_PAUSED Bit auf eins festgelegt ist. Um RasDial aus einem solchen angehaltenen Zustand neu zu starten, rufen Sie RasDial erneut auf, und übergeben Sie das Verbindungshandle, das vom ursprünglichen RasDial-Aufruf in *lphRasConn zurückgegeben wurde. Der gleiche Notifier, der im ursprünglichen RasDial-Aufruf verwendet wurde, muss beim Neustart aus einem angehaltenen Zustand verwendet werden.

Der lpvNotifier-Parameter ist ein Handle für ein Fenster zum Empfangen von Statusbenachrichtigungen. In einer Statusbenachrichtigungsmeldung entspricht wParam dem rasconnstate-Parameter von RasDialFunc und RasDialFunc1, und lParam entspricht dem dwError-Parameter von RasDialFunc und RasDialFunc1.

Die Statusbenachrichtigungsmeldung verwendet einen systemregistrierten Nachrichtencode. Sie können den Wert dieses Nachrichtencodes wie folgt abrufen:

UINT unMsg = RegisterWindowMessageA( RASDIALEVENT );
if (unMsg == 0)
    unMsg = WM_RASDIALEVENT;

RAS unterstützt Verbindungen, auf die verwiesen wird. Wenn der zu wählende Eintrag bereits verbunden ist, gibt RasDialSUCCESS zurück, und auf die Verbindung wird verwiesen. Um die Verbindung zu trennen, sollte jede RasDial für die Verbindung mit einem RasHangUp abgeglichen werden.

Da für einige Telefonbucheinträge das Extensible Authentication Protocol (EAP) für die Authentifizierung erforderlich ist, sollte der Anrufer RasGetEapUserIdentity vor dem Aufrufen von RasDial aufrufen. Wenn RasGetEapUserIdentityERROR_INVALID_FUNCTION_FOR_ENTRY zurückgibt, ist für den Telefonbucheintrag kein EAP erforderlich. Wenn RasGetEapUserIdentity jedoch NO_ERROR zurückgibt, sollte der Aufrufer die EAP-Identitätsinformationen aus RasGetEapUserIdentity in das RasEapInfo-Member von RASDIALEXTENSIONS und das szUserName-Member von RASDIALPARAMS kopieren. Weitere Informationen finden Sie unter RasGetEapUserIdentity . Wenn für den Telefonbucheintrag EAP erforderlich ist, enthält das dwfOptions-Element der RASENTRY-Struktur für den Eintrag das flag RASEO_RequireEAP .

Wenn Sie angeben möchten, dass RasDial in einen RASCS_CallbackSetByCaller Zustand eintreten soll, legen Sie lpRasDialParams-szCallbackNumber> für den ersten Aufruf von RasDial auf "*" fest. Wenn der Benachrichtigungshandler mit diesem Zustand aufgerufen wird, legen Sie die Rückrufnummer auf eine vom Benutzer angegebene Zahl fest.

Hinweis

Der ras.h-Header definiert RasDial 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 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