Funzione RasDialA (ras.h)

Articolo
03/15/2023

La funzione RasDial stabilisce una connessione RAS tra un client RAS e un server RAS. I dati di connessione includono informazioni di callback e autenticazione utente.

Sintassi

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

Parametri

[in] unnamedParam1

Puntatore a una struttura RASDIALEXTENSIONS che specifica un set di funzionalità estese RasDial da abilitare. Impostare questo parametro su NULL se non è necessario abilitare queste funzionalità.

[in] unnamedParam2

Puntatore a una stringa con terminazione Null che specifica il percorso completo e il nome file di un file di rubrica telefonica (PBK). Se questo parametro è NULL, la funzione usa il file di rubrica predefinito corrente. Il file predefinito della rubrica telefonica è quello selezionato dall'utente nella finestra delle proprietà Preferenze utente della finestra di dialogo Rete remota.

[in] unnamedParam3

Puntatore a una struttura RASDIALPARAMS che specifica i parametri chiamanti per la connessione RAS. Usare la funzione RasGetEntryDialParams per recuperare una copia di questa struttura per una determinata voce della rubrica telefonica.

Il chiamante deve impostare il membro dwSize della struttura RASDIALPARAMS su sizeof(RASDIALPARAMS) per identificare la versione della struttura passata.

Se il membro szPhoneNumber della struttura RASDIALPARAMS è una stringa vuota, RasDial usa il numero di telefono archiviato nella voce della rubrica telefonica.

[in] unnamedParam4

Specifica la natura del parametro lpvNotifier . Se lpvNotifier è NULL, dwNotifierType viene ignorato. Se lpvNotifier non è NULL, impostare dwNotifierType su uno dei valori seguenti.

Valore	Significato
0	Il parametro lpvNotifier punta a una funzione di callback RasDialFunc .
1	Il parametro lpvNotifier punta a una funzione di callback RasDialFunc1 .
2	Il parametro lpvNotifier punta a una funzione di callback RasDialFunc2 .

[in] unnamedParam5

Specifica un handle di finestra o una funzione di callback RasDialFunc, RasDialFunc1 o RasDialFunc2 per ricevere le notifiche degli eventi RasDial . Il parametro dwNotifierType specifica la natura di lpvNotifier. Per altri dettagli, vedere la descrizione precedente.

Se questo parametro non è NULL, RasDial invia alla finestra un messaggio o chiama la funzione di callback per ogni evento RasDial . Inoltre, la chiamata RasDial opera in modo asincrono: RasDial restituisce immediatamente, prima che la connessione venga stabilita e comunichi lo stato di avanzamento tramite la finestra o la funzione di callback.

Se lpvNotifier è NULL, la chiamata RasDial opera in modo sincrono: RasDial non restituisce finché il tentativo di connessione non è stato completato correttamente o non è riuscito.

Se lpvNotifier non è NULL, le notifiche alla finestra o alla funzione di callback possono verificarsi in qualsiasi momento dopo la chiamata iniziale a RasDial. Le notifiche terminano quando si verifica uno degli eventi seguenti:

Viene stabilita la connessione. In altre parole, lo stato della connessione RAS è RASCS_Connected.
La connessione non riesce. In altre parole, dwError è diverso da zero.
RasHangUp viene chiamato sulla connessione.

Le notifiche di callback vengono effettuate nel contesto di un thread acquisito durante la chiamata iniziale a RasDial.

[out] unnamedParam6

Puntatore a una variabile di tipo HRASCONN. Impostare la variabile HRASCONN su NULL prima di chiamare RasDial. Se RasDial ha esito positivo, archivia un handle per la connessione RAS in *lphRasConn.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene ERROR_SUCCESS e nella variabile a cui punta lphRasConn viene restituito un handle per la connessione RAS.

Se la funzione ha esito negativo, il valore restituito proviene da Routing e Remote Access Error Codes o Winerror.h.

Commenti

Gli errori che si verificano dopo la restituzione immediata possono essere rilevati da RasGetConnectStatus. I dati sono disponibili fino a quando un'applicazione chiama RasHangUp per appendere la connessione.

Un'applicazione deve infine chiamare RasHangUp ogni volta che un handle di connessione non NULL viene archiviato in *lphRasConn. Questo vale anche se RasDial restituisce un valore diverso da zero (errore).

Un'applicazione può chiamare in modo sicuro RasHangUp da una funzione di callback del notifier RasDial . Se questa operazione viene eseguita, tuttavia, il blocco non si verifica fino a quando la routine non viene restituita.

Se la struttura a cui punta lpRasDialExtensions abilita RDEOPT_PausedStates, la funzione RasDial viene sospesa ogni volta che entra in uno stato in cui il bit RASCS_PAUSED è impostato su uno. Per riavviare RasDial da uno stato di sospensione di questo tipo, chiamare di nuovo RasDial , passando l'handle di connessione restituito dalla chiamata RasDial originale in *lphRasConn. Lo stesso notifier usato nella chiamata RasDial originale deve essere usato durante il riavvio da uno stato sospeso.

Il parametro lpvNotifier è un handle per una finestra per ricevere messaggi di notifica di stato. In un messaggio di notifica di stato , wParam è l'equivalente del parametro rasconnstate di RasDialFunc e RasDialFunc1 e lParam è l'equivalente del parametro dwError di RasDialFunc e RasDialFunc1.

Il messaggio di notifica di stato usa un codice di messaggio registrato dal sistema. È possibile ottenere il valore di questo codice del messaggio come indicato di seguito:

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

RAS supporta le connessioni a cui si fa riferimento. Se la voce da comporre è già connessa, RasDial restituisce SUCCESS e viene fatto riferimento alla connessione. Per disconnettere la connessione, ogni RasDial sulla connessione deve corrispondere a un RasHangUp.

Poiché alcune voci della rubrica richiedono Extensible Authentication Protocol (EAP) per l'autenticazione, il chiamante deve chiamare RasGetEapUserIdentity prima di chiamare RasDial. Se RasGetEapUserIdentity restituisceERROR_INVALID_FUNCTION_FOR_ENTRY, la voce della rubrica telefonica non richiede EAP. Tuttavia, se RasGetEapUserIdentity restituisce NO_ERROR, il chiamante deve copiare le informazioni sull'identità EAP da RasGetEapUserIdentity nel membro RasEapInfo di RASDIALEXTENSIONS e il membro szUserName di RASDIALPARAMS. Per altre informazioni, vedere RasGetEapUserIdentity . Se la voce della rubrica telefonica richiede EAP, il membro dwfOptions della struttura RASENTRY per la voce contiene il flag RASEO_RequireEAP .

Per specificare che RasDial deve immettere uno stato RASCS_CallbackSetByCaller, impostare lpRasDialParams-szCallbackNumber> su "*" nella chiamata iniziale a RasDial. Quando il gestore di notifica viene chiamato con questo stato, impostare il numero di callback su un numero fornito dall'utente.

Nota

L'intestazione ras.h definisce RasDial come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ras.h
Libreria	Rasapi32.lib
DLL	Rasapi32.dll