Función RasDialA (ras.h)

Artículo
03/15/2023

La función RasDial establece una conexión RAS entre un cliente RAS y un servidor RAS. Los datos de conexión incluyen información de devolución de llamada y autenticación de usuario.

Sintaxis

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

Parámetros

[in] unnamedParam1

Puntero a una estructura RASDIALEXTENSIONS que especifica un conjunto de características extendidas rasDial que se van a habilitar. Establezca este parámetro en NULL si no es necesario habilitar estas características.

[in] unnamedParam2

Puntero a una cadena terminada en null que especifica la ruta de acceso completa y el nombre de archivo de un archivo de libreta telefónica (PBK). Si este parámetro es NULL, la función usa el archivo de libreta telefónica predeterminado actual. El archivo de libreta telefónica predeterminado es el seleccionado por el usuario en la hoja de propiedades Preferencias de usuario del cuadro de diálogo Redes de acceso telefónico .

[in] unnamedParam3

Puntero a una estructura RASDIALPARAMS que especifica los parámetros de llamada para la conexión RAS. Use la función RasGetEntryDialParams para recuperar una copia de esta estructura para una entrada de libreta de teléfono determinada.

El llamador debe establecer el miembro dwSize de la estructura RASDIALPARAMS en sizeof(RASDIALPARAMS) para identificar la versión de la estructura que se pasa.

Si el miembro szPhoneNumber de la estructura RASDIALPARAMS es una cadena vacía, RasDial usa el número de teléfono almacenado en la entrada de la libreta de teléfonos.

[in] unnamedParam4

Especifica la naturaleza del parámetro lpvNotifier . Si lpvNotifier es NULL, dwNotifierType se omite. Si lpvNotifier no es NULL, establezca dwNotifierType en uno de los valores siguientes.

Valor	Significado
0	El parámetro lpvNotifier apunta a una función de devolución de llamada RasDialFunc .
1	El parámetro lpvNotifier apunta a una función de devolución de llamada RasDialFunc1 .
2	El parámetro lpvNotifier apunta a una función de devolución de llamada RasDialFunc2 .

[in] unnamedParam5

Especifica un identificador de ventana o una función de devolución de llamada RasDialFunc, RasDialFunc1 o RasDialFunc2 para recibir notificaciones de eventos RasDial . El parámetro dwNotifierType especifica la naturaleza de lpvNotifier. Consulte su descripción anterior para obtener más detalles.

Si este parámetro no es NULL, RasDial envía un mensaje a la ventana o llama a la función de devolución de llamada para cada evento RasDial . Además, la llamada RasDial funciona de forma asincrónica: RasDial devuelve inmediatamente, antes de establecer la conexión y comunica su progreso a través de la ventana o la función de devolución de llamada.

Si lpvNotifier es NULL, la llamada RasDial funciona sincrónicamente: RasDial no devuelve hasta que el intento de conexión se haya completado correctamente o fallado.

Si lpvNotifier no es NULL, las notificaciones a la ventana o la función de devolución de llamada pueden producirse en cualquier momento después de la llamada inicial a RasDial. Las notificaciones finalizan cuando se produce uno de los siguientes eventos:

Se establece la conexión. En otras palabras, el estado de conexión ras es RASCS_Connected.
Se produce un error en la conexión. En otras palabras, dwError es distinto de cero.
Se llama a RasHangUp en la conexión.

Las notificaciones de devolución de llamada se realizan en el contexto de un subproceso capturado durante la llamada inicial a RasDial.

[out] unnamedParam6

Puntero a una variable de tipo HRASCONN. Establezca la variable HRASCONN en NULL antes de llamar a RasDial. Si RasDial se realiza correctamente, almacena un identificador de la conexión RAS en *lphRasConn.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto se ERROR_SUCCESS y se devuelve un identificador a la conexión RAS en la variable a la que apunta lphRasConn.

Si se produce un error en la función, el valor devuelto procede de Los códigos de error de enrutamiento y acceso remoto o Winerror.h.

Comentarios

RasGetConnectStatus puede detectar errores que se producen después de la devolución inmediata. Los datos están disponibles hasta que una aplicación llama a RasHangUp para bloquear la conexión.

Una aplicación debe llamar finalmente a RasHangUp siempre que se almacene un identificador de conexión que no sea NULL en *lphRasConn. Esto se aplica incluso si RasDial devuelve un valor distinto de cero (error).

Una aplicación puede llamar de forma segura a RasHangUp desde una función de devolución de llamada del notificador RasDial . Sin embargo, si esto se hace, el bloqueo no se produce hasta que se devuelve la rutina.

Si la estructura a la que apunta lpRasDialExtensions habilita RDEOPT_PausedStates, la función RasDial se pausa cada vez que entra en un estado en el que el bit de RASCS_PAUSED se establece en uno. Para reiniciar RasDial desde este estado en pausa, llame a RasDial de nuevo, pasando el identificador de conexión devuelto desde la llamada RasDial original en *lphRasConn. El mismo notificador usado en la llamada RasDial original debe usarse al reiniciar desde un estado en pausa.

El parámetro lpvNotifier es un identificador de una ventana para recibir mensajes de notificación de progreso. En un mensaje de notificación de progreso, wParam es el equivalente del parámetro rasconnstate de RasDialFunc y RasDialFunc1, y lParam es el equivalente del parámetro dwError de RasDialFunc y RasDialFunc1.

El mensaje de notificación de progreso usa un código de mensaje registrado por el sistema. Puede obtener el valor de este código de mensaje de la siguiente manera:

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

RAS admite conexiones a las que se hace referencia. Si la entrada que se marca ya está conectada, RasDial devuelve SUCCESS y se hace referencia a la conexión. Para desconectar la conexión, cada RasDial de la conexión debe coincidir con un RasHangUp.

Dado que algunas entradas de la libreta de teléfono requieren el Protocolo de autenticación extensible (EAP) para la autenticación, el autor de la llamada debe llamar a RasGetEapUserIdentity antes de llamar a RasDial. Si RasGetEapUserIdentity devuelve ERROR_INVALID_FUNCTION_FOR_ENTRY, la entrada de la libreta de teléfonos no requiere EAP. Sin embargo, si RasGetEapUserIdentity devuelve NO_ERROR, el autor de la llamada debe copiar la información de identidad de EAP de RasGetEapUserIdentity en el miembro RasEapInfo de RASDIALEXTENSIONS y el miembro szUserName de RASDIALPARAMS. Consulte RasGetEapUserIdentity para obtener más información. Si la entrada de la libreta telefónica requiere EAP, el miembro dwfOptions de la estructura RASENTRY para la entrada contiene la marca RASEO_RequireEAP .

Para especificar que RasDial debe especificar un estado de RASCS_CallbackSetByCaller, establezca lpRasDialParams-szCallbackNumber> en "*" en la llamada inicial a RasDial. Cuando se llama al controlador de notificaciones con este estado, establezca el número de devolución de llamada en un número proporcionado por el usuario.

Nota:

El encabezado ras.h define RasDial como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	ras.h
Library	Rasapi32.lib
Archivo DLL	Rasapi32.dll