Функция RasDialA (ras.h)

Статья
08/25/2023

Функция RasDial устанавливает соединение RAS между клиентом RAS и сервером RAS. Данные подключения включают сведения о обратном вызове и проверке подлинности пользователя.

Синтаксис

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

Параметры

[in] unnamedParam1

Указатель на структуру RASDIALEXTENSIONS , которая указывает набор расширенных функций RasDial для включения. Присвойте этому параметру значение NULL , если нет необходимости включать эти функции.

[in] unnamedParam2

Указатель на строку, завершающуюся значением NULL, которая указывает полный путь и имя файла телефонной книги (PBK). Если этот параметр имеет значение NULL, функция использует текущий файл телефонной книги по умолчанию. Файл телефонной книги по умолчанию — это файл, выбранный пользователем на странице свойств Пользовательские настройки диалогового окна Сеть удаленного доступа.

[in] unnamedParam3

Указатель на структуру RASDIALPARAMS , которая задает вызывающие параметры для подключения RAS. Используйте функцию RasGetEntryDialParams , чтобы получить копию этой структуры для определенной записи телефонной книги.

Вызывающий объект должен задать для члена dwSize структуры RASDIALPARAMS значение sizeof(RASDIALPARAMS), чтобы определить версию передаваемой структуры.

Если элемент szPhoneNumber структуры RASDIALPARAMS является пустой строкой, RasDial использует номер телефона, хранящийся в записи телефонной книги.

[in] unnamedParam4

Указывает характер параметра lpvNotifier . Если lpvNotifier имеет значение NULL, dwNotifierType игнорируется. Если значение lpvNotifier не равно NULL, задайте параметру dwNotifierType одно из следующих значений.

Значение	Значение
0	Параметр lpvNotifier указывает на функцию обратного вызова RasDialFunc .
1	Параметр lpvNotifier указывает на функцию обратного вызова RasDialFunc1 .
2	Параметр lpvNotifier указывает на функцию обратного вызова RasDialFunc2 .

[in] unnamedParam5

Указывает дескриптор окна или функцию обратного вызова RasDialFunc, RasDialFunc1 или RasDialFunc2 для получения уведомлений о событиях RasDial . Параметр dwNotifierType указывает природу lpvNotifier. Дополнительные сведения см. в описании выше.

Если этот параметр не равен NULL, RasDial отправляет в окно сообщение или вызывает функцию обратного вызова для каждого события RasDial . Кроме того, вызов RasDial работает асинхронно: RasDial возвращается немедленно, до установления соединения, и сообщает о ходе выполнения через окно или функцию обратного вызова.

Если lpvNotifier имеет значение NULL, вызов RasDial работает синхронно: RasDial не возвращается, пока попытка подключения не завершится успешно или не завершится сбоем.

Если значение lpvNotifier не равно NULL, уведомления в окно или функцию обратного вызова могут происходить в любое время после первоначального вызова RasDial. Уведомления заканчиваются, когда происходит одно из следующих событий:

Подключение установлено. Другими словами, состояние подключения RAS RASCS_Connected.
Сбой подключения. Другими словами, значение dwError не равно нулю.
Для подключения вызывается RasHangUp.

Уведомления о обратном вызове создаются в контексте потока, записанного во время первоначального вызова RasDial.

[out] unnamedParam6

Указатель на переменную типа HRASCONN. Перед вызовом RasDial задайте для переменной HRASCONNзначение NULL. Если RasDial завершается успешно, он сохраняет дескриптор подключения RAS в *lphRasConn.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение ERROR_SUCCESS и дескриптор соединения RAS возвращается в переменной, на которую указывает lphRasConn.

Если функция завершается сбоем, возвращается значение из кода ошибок маршрутизации и удаленного доступа или Winerror.h.

Ошибки, возникающие после немедленного возврата, могут быть обнаружены с помощью RasGetConnectStatus. Данные будут доступны до тех пор, пока приложение не вызовет RasHangUp , чтобы зависнуть подключение.

Приложение должно в конечном итоге вызывать RasHangUp всякий раз, когда дескриптор соединения, отличный от NULL , сохраняется в *lphRasConn. Это применимо, даже если RasDial возвращает ненулевое значение (ошибка).

Приложение может безопасно вызывать RasHangUp из функции обратного вызова уведомитель RasDial . Однако если это сделать, зависание не происходит до тех пор, пока не будет возвращена подпрограмма.

Если структура, на которую указывает lpRasDialExtensions , включает RDEOPT_PausedStates, функция RasDial приостанавливается всякий раз, когда она переходит в состояние, в котором RASCS_PAUSED бит имеет значение 1. Чтобы перезапустить RasDial из такого приостановленного состояния, вызовите RasDial еще раз, передав дескриптор подключения, возвращенный из исходного вызова RasDial в *lphRasConn. При перезапуске из приостановленного состояния необходимо использовать тот же уведомитель, который использовался в исходном вызове RasDial .

Параметр lpvNotifier — это дескриптор окна для получения сообщений о ходе выполнения. В сообщении уведомления о ходе выполнения wParam является эквивалентом параметра rasconnstateRasDialFunc и RasDialFunc1, а lParam является эквивалентом параметра dwErrorRasDialFunc и RasDialFunc1.

В сообщении о ходе выполнения используется код зарегистрированного в системе сообщения. Значение этого кода сообщения можно получить следующим образом:

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

RAS поддерживает соединения, на которые указывает ссылка. Если набираемая запись уже подключена, RasDial возвращает значение SUCCESS и ссылка на соединение. Чтобы отключить подключение, каждый RasDial в соединении должен соответствовать RasHangUp.

Поскольку для некоторых записей телефонной книги требуется протокол EAP для проверки подлинности, вызывающий объект должен вызвать RasGetEapUserIdentity перед вызовом RasDial. Если RasGetEapUserIdentity возвращает ERROR_INVALID_FUNCTION_FOR_ENTRY, запись телефонной книги не требует EAP. Однако если RasGetEapUserIdentity возвращает NO_ERROR, вызывающий объект должен скопировать сведения об удостоверениях EAP из RasGetEapUserIdentity в элемент RasEapInfoRASDIALEXTENSIONS, а элемент szUserName объекта RASDIALPARAMS. Дополнительные сведения см. в разделе RasGetEapUserIdentity . Если для записи телефонной книги требуется EAP, элемент dwfOptions структуры RASENTRY для записи содержит флаг RASEO_RequireEAP .

Чтобы указать, что RasDial должен входить в состояние RASCS_CallbackSetByCaller, установите для параметра lpRasDialParams-szCallbackNumber> значение "*" при первоначальном вызове RasDial. При вызове обработчика уведомлений с таким состоянием задайте для номера обратного вызова номер, указанный пользователем.

Примечание

Заголовок ras.h определяет RasDial как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	ras.h
Библиотека	Rasapi32.lib
DLL	Rasapi32.dll