Función RasDialA (ras.h)

Artículo
11/20/2024

La función RasDial establece una conexión RAS entre un cliente RAS y un servidor RAS. Los datos de conexión incluyen la devolución de llamada y la información de 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 de RASDIALEXTENSIONS que especifica un conjunto de RasDial características extendidas 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 de teléfonos (PBK). Si este parámetro es NULL, la función usa el archivo de libreta de teléfono predeterminado actual. El archivo de libreta de teléfonos predeterminado es el seleccionado por el usuario en la hoja de propiedades preferencias de usuario de del cuadro de diálogo Redes de acceso telefónico.

[in] unnamedParam3

Puntero a una estructura de RASDIALPARAMS que especifica 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 autor de la llamada debe establecer el miembro RASDIALPARAMS de la estructura dwSize en sizeof(RASDIALPARAMS) para identificar la versión de la estructura que se pasa.

Si el szPhoneNumber miembro del RASDIALPARAMS estructura 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 , se omite dwNotifierType. 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 de 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 un RasDialFunc, RasDialFunc1, o RasDialFunc2 función de devolución de llamada 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 de RasDial de . Además, la llamada de RasDial funciona de forma asincrónica: rasDial devuelve inmediatamente, antes de establecer la conexión y comunica su progreso a través de la función de devolución de llamada o ventana.

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

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 terminan 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 al 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 Códigos de error de enrutamiento y acceso remoto o Winerror.h.

Observaciones

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

Una aplicación debe llamar eventualmente a RasHangUp cada vez que se almacena un identificador de conexión noNULL 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 de RasDial. Sin embargo, si esto se hace, el bloqueo no se produce hasta que la rutina vuelve.

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 de nuevo a RasDial, pasando el identificador de conexión devuelto desde la llamada original RasDial en *lphRasConn. Se debe usar el mismo notificador usado en el original llamada rasDial 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 de 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 de la conexión debe coincidir con una RasHangUp.

Dado que algunas entradas de libreta de teléfonos requieren 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 RASDIALEXTENSIONSy el miembro szUserName de RASDIALPARAMS. Consulte rasGetEapUserIdentity para obtener más información. Si la entrada de la libreta de teléfonos requiere EAP, el dwfOptions miembro del RASENTRY estructura 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 Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	ras.h
biblioteca de	Rasapi32.lib
DLL de	Rasapi32.dll