Сообщений 1    Оценка 115        Оценить

Введение в Remote Access Service

Автор: Новиков Михаил

Опубликовано: 11.01.2004
Исправлено: 17.06.2009
Версия текста: 1.0

Исходные тексты

Вступление

В последнее время в Интернете появляется большое количество программ, целью которых является упрощение процесса дозвона до провайдера, так называемых «звонилок». Такие приложения используют для работы возможность удаленного соединения, предоставляемую Windows. В значительной части случаев соединение происходит по телефонной линии через модем. Все перечисленное является частными примерами, иллюстрирующими некоторые аспекты применения Remote Access Service (RAS).

Основные положения

Remote Access Service предоставяет пользователю услуги удаленного доступа к сети, с использованием удаленного соединения. Для разработчиков программного обеспечения существует специальный набор функций RAS API, позволяющий непосредственно из приложения производить манипуляции с соединениями, такие как:

• Создание, удаление, копирование, переименование в телефонной книге (phone-book)
• Изменения значительного набора настроек
• Осуществление подключения
• Получение исчерпывающей информации о ходе подключения

Так же предусмотрена возможность управления и наблюдения за соединениями, которые в данное время используются пользователем.

Программист сам в праве решать, будут ли использованы стандартные диалоговые окна RAS или все настройки и вывод информации будет происходить через интерфейс программы.

Работа RAS в операционных системах семейства WinNT и Win9x имеет отдельные нюансы. Существенным отличием во втором случае является отсутсвие RAS server administration и ряда функций, которые порой бывают незаменимы.

Описание функций

Перечисление

Функция, которая перечисляет все соединения или как их еще называют «точки входа», которые находятся в телефонной книге, носит название RasEnumEntries (Обычно пользователь просматривает эти соединения через папку «Удаленный доступ к сети»):

DWORD RasEnumEntries(
  LPCTSTR reserved,
  LPTCSTR lpszPhonebook,
  LPRASENTRYNAME lprasentryname,
  LPDWORD lpcb,
  LPDWORD lpcEntries
);

Первый параметр в этой функции, как видно из названия, зарезервирован для дальнейшего использования и должен быть установлен в NULL. Второй параметр – это указатель на строку, в которой должен содержаться полный путь к файлу телефонной книги с расширением .PBK. Если же передать NULL, то функция будет использовать текущую телефонную книгу. Остальные три аргумента связаны со структурой RASENTRYNAME:

typedef struct _RASENTRYNAME { 
  DWORD  dwSize; 
  TCHAR  szEntryName[RAS_MaxEntryName + 1]; 
#if (WINVER >= 0x500)
  DWORD dwFlags;
  TCHAR  szPhonebookPath[MAX_PATH + 1];
#endif
} RASENTRYNAME;

Поле dwSize, означающее размер структуры, должно быть заполнено перед вызвом функции. В поле szEntryName после вызова будет находиться имя «точки входа». Далее с помощью макросов сделано ограничение, что следущие поля в версиях Windows NT, Windows Me/9x не поддерживаются. Однако, следует их разобрать: dwFlags – указывает что найденная «точка входа» находится в системной телефонной книге и в профиле AllUsers, если принимает значение REN_AllUsers, или в профиле текущего пользователя, если равна REN_User; в szPhonebookPath просто передается полные путь с именем телефонной книги.

Итак, третий параметр функции RasEnumEntries является указателем на только что разобранную структуру RASENTRYNAME. В четвертый аргумент нужно передать количество байт буфера lprasentryname. Наконец lpcEntries будет содержать после вызова функции количество найденных «точек входа».

Иногда возникает необходимость получить список соединений, которые в настоящий момент используются. Решение этой проблемы заключается в функции RasEnumConnections:

DWORD RasEnumConnections(
  LPRASCONN lprasconn,
  LPDWORD lpcb,
  LPDWORD lpcConnections
);

Очевидно, что первым параметром ее является указатель на структуру RASCONN, содержащей иформацию о подключении:

typedef struct _RASCONN {
  DWORD     dwSize;
  HRASCONN  hrasconn;
  TCHAR     szEntryName[RAS_MaxEntryName + 1];
#if (WINVER >= 0x400)
  TCHAR    szDeviceType[ RAS_MaxDeviceType + 1 ];
  TCHAR    szDeviceName[ RAS_MaxDeviceName + 1 ];								   
#endif
#if (WINVER >= 0x401)
   TCHAR    szPhonebook [ MAX_PATH ];
   DWORD    dwSubEntry;
#endif
#if (WINVER >= 0x500)
   GUID     guidEntry;
#endif
#if (WINVER >= 0x501)
   DWORD     dwSessionId;
   DWORD     dwFlags;
   LUID      luid;													
#endif
} RASCONN ;

Первой поле dwSize должно содержать размер стуктуры в байтах, и заполняется оно перед вызовом функции, обычно конструкцией типа sizeof(RASCONN). Поле hrasconn содержит хэндл соединения, который в дальнейшем можно будет использовать в других функциях RAS API. Третьим полем является просто имя «точки входа», с помощью которой установилось подключение. Далее, как видно, с помощью макросов идет определенное ограничение на использование полей в зависимости от версии Windows. Напомню значение WINVER, и соответствующие им версии ОС:

• WINVER < 0x400 - WinNT версий 3.5 и 3.51
• WINVER >= 0x400 - Win9x/ME, WinNT версии 4
• WINVER = 0x500 - Win2000
• WINVER = 0x501 - WinXP

Следующие поля szDeviceType и szDeviceName содержат тип и имя устройства, через которое происходит подключение. В поле szPhoneBook передается полный путь и имя телефонной книги. Двойное слово dwSubEntry определяет, какой номер по счету занимает найденное соединение, если подключение состоит из нескольких соединений (multilink). Поле guidEntry является глобальным уникальным индентификатором (GUID) «точки входа». Поле dwSessionId содержит индентификатор сессии пользователя, установившего соединение. Двойное слово dwFlags может принимать нулевое значение или следующие значения:

• RASCF_AllUsers – означает, что соединение является доступным для всех пользователей.
• RASCF_GlobalCreds – означает, что права на использование соединения предоставляются по умолчанию.

Последний член luid – это локальный уникальный индентификатор сессии, в которой связь была установлена связь.

Вернемся к рассматриваемой функции RasEnumConnections, в которой используется разобранная структура RASCONN. Вторым ее аргументом является указатель на двойное слово, в котором должен содержаться размер в байтах буфера lprasconn. Третий параметр lpcConnections после вызова функции будет содержать количесво найденных подключений.

Для того чтобы узнать все устройства установленные на компьютере, через которые возможно совершить подключение используется функция RasEnumDevice:

DWORD RasEnumDevices(
  LPRASDEVINFO lpRasDevInfo,
  LPDWORD lpcb,
  LPDWORD lpcDevices
);

Первым же параметром этой функции является указатель на структуру RASDEVINFO:

typedef struct tagRASDEVINFO {  
DWORD dwSize;  
TCHAR szDeviceType[RAS_MaxDeviceType + 1];  
TCHAR szDeviceName[RAS_MaxDeviceName + 1];
} RASDEVINFO;

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

#define RASDT_Modem                     TEXT("modem")
#define RASDT_Isdn                      TEXT("isdn")
#define RASDT_X25                       TEXT("x25")
#define RASDT_Vpn                       TEXT("vpn")
#define RASDT_Pad                       TEXT("pad")
#define RASDT_Generic                   TEXT("GENERIC")
#define RASDT_Serial        		    TEXT("SERIAL")
#define RASDT_FrameRelay                TEXT("FRAMERELAY")
#define RASDT_Atm                       TEXT("ATM")
#define RASDT_Sonet                     TEXT("SONET")
#define RASDT_SW56                      TEXT("SW56")
#define RASDT_Irda                      TEXT("IRDA")
#define RASDT_Parallel                  TEXT("PARALLEL")
#if (WINVER >= 0x501)
#define RASDT_PPPoE                     TEXT("PPPoE")
#endif

Поле szDeviceName просто содержит название устройства.

Второй аргумент функции RasEnumDevice должен содержать размер буфера lpRasDevInfo. В третьий параметр функция передает число найденных устройств.

Редактирование

Далее будет рассказано о нескольких функциях, которые вызывают стандартные диалоговые окна RAS для различных манипуляций над действиями, так и функции, через которые программа может производить действия без участия пользователя. Первое действие, которое следует разобрать, - это создание соединений. Для этой цели служит функция RasCreatePhonebookEntry:

DWORD RasCreatePhonebookEntry(
  HWND hwnd,
  LPCTSTR lpszPhonebook
);

Из первого параметра становится ясно, что будет вызван диалог создания соединения, для которого необходимо знать HWND окна родителя. Вторым параметром является полный путь к телефонной книге, здесь можно передать NULL, и тогда соединение будет создано в текущей телефонной книге.

Для обратного действия – удаления, существует функция RasDeleteEntry:

DWORD RasDeleteEntry(
  LPCTSTR lpszPhonebook,
  LPCTSTR lpszEntry
);

Чтобы удалить «точку входа» нужно передать путь к телефонной книге lpszPhonebook и имя соединения lpszEntry.

Переименование соединения осуществляется с помощью функции RasRenameEntry:

DWORD RasRenameEntry(
  LPCTSTR lpszPhonebook,
  LPCTSTR lpszOldEntry,
  LPCTSTR lpszNewEntry
);

Как и в предыдущих функциях в параметр lpszPhonebook нужно передать путь к телефонной книге. Параметры lpszOldEntry и lpszNewEntry являются старым, текущим именем «точки входа» и желаемым новым именем соответственно. Существует ряд ограничений наложенных на названия соединений:

• Не могут использоваться символы «|»,«<»,«>»,«?»,«*»,«:»,«\»,«/», а также пробелы.
• Длина не должна превышать макрос RAS_MaxEntryName, определенный в Ras.h:

#if (WINVER >= 0x400)
#define RAS_MaxEntryName      256
#else
#define RAS_MaxEntryName      20
#endif

Чтобы автоматически проверить содержится ли в новом имени ошибка удобно использовать функцию RasValidateEntryName:

DWORD RasValidateEntryName(
  LPCTSTR lpszPhonebook,
  LPCTSTR lpszEntry
);

Первым аргументом передается путь к телефонной книге, в которой будет производиться проверка на возможность переименования. Вторым параметром нужно указать строку, содержащую новое имя соединения. Если имя допустимо функция возвращает значение ERROR_SUCCESS, но если возникли ошибки, будет возвращено одно из значений:

• ERROR_ALREADY_EXISTS – соединение с таким именем уже существует
• ERROR_INVALID_NAME – в имени не соблюдаются описанные выше правила

Редактирование непосредственно соединения может осуществляься пользователем при помощи стандартного диалога, вызов которого можно осуществить функцией RasEditPhonebookEntry:

DWORD RasEditPhonebookEntry(
  HWND hwnd,
  LPCTSTR lpszPhonebook,
  LPCTSTR lpszEntryName
);

Первым параметром нужно передать HWND окна, который будет родительским по отношению к диалогу. Вторым параметром должен передаваться путь к телефонной книге, и третьим имя редактируемого соединения.

Отметим, что разобранные нами функции RasCreatePhonebookEntry и RasEditPhonebookEntry работают благодаря вызову универсальной функции вызова стандартных диалогов RasEntryDlg. Главным их отличием является то, что последняя функция поддерживается только опрерационными системами версий WinNT/2000/XP, а две первые практически всеми версиями Windows. Функция также позволяет вызвать несколько дополнительных диалогов. Рассмотрим RasEntryDlg:

BOOL RasEntryDlg(
  LPTSTR lpszPhonebook,
  LPTSTR lpszEntry,
  LPRASENTRYDLG lpInfo
);

В перыве два парметра lpszPhonebook и lpszEntry передается путь к телефонной книге и имя «точки входа». Особого внимания следует уделить третьиму аргументу lpInfo, являющемуся указателем на стуктуру RASENTRYDLG:

typedef struct tagRASENTRYDLG {  
IN  DWORD dwSize;  
IN  HWND hwndOwner; 
IN  DWORD dwFlags; 
IN  LONG xDlg;  
IN  LONG yDlg;  
OUT TCHAR szEntry[RAS_MaxEntryName + 1];  
OUT DWORD dwError;  
IN  ULONG_PTR reserved;  
IN  ULONG_PRT reserved2;
} RASENTRYDLG;

Первый поле dwSize должно содержать размер структуры в байтах и обязано быть заполнено до вызова функции. Второй член структуры должен содержать HWND окна – родителя вызываемого диалога. Следующим полем является двойное слово dwFlags, значение битов которого, позволяют указать, какой именно диалог требуется вызвать:

Поле szEntry после вызова функции будет содержать имя созданного соединения или отредактированного, взависимости какой диалог был вызван. Если в процессе работы функции возникла, по каким – либо причинам, ошибка, то код этой ошибки будет содержать двойное слово dwError. Остальные два поля структуры зарезервированы для дальнейшего использования.

Изменение настроек

В предыдущей части статьи мы рассмотрели случаи, когда редактирование соединений и их параметров осуществляется стандартными диалогами, с непосредственным участием пользователя. Сейчас предстоит ознакомиться с функциями, предоставляющими программе создавать и изменять соединения, без применения диалогов и если потребуется без участия пользователя.

Для этих целей существет структура RASENTRY, которая описывает все возможные настройки и свойства соединения. Ее используют две функции, о них речь пойдет позднее. Итак, рассмотрим многочисленные поля RASENTRY:

typedef struct tagRASENTRY {
  DWORD      dwSize;
  DWORD      dwfOptions;
  // Настройки телефонного номера
  DWORD      dwCountryID;
  DWORD      dwCountryCode;
  TCHAR      szAreaCode[ RAS_MaxAreaCode + 1 ];
  TCHAR      szLocalPhoneNumber[ RAS_MaxPhoneNumber + 1 ];
  DWORD      dwAlternateOffset;
  //
  // PPP(Протокол Point-to-point)/Ip
  //
  RASIPADDR  ipaddr;
  RASIPADDR  ipaddrDns;
  RASIPADDR  ipaddrDnsAlt;
  RASIPADDR  ipaddrWins;
  RASIPADDR  ipaddrWinsAlt;
  // Протокол
  DWORD      dwFrameSize;
  DWORD      dwfNetProtocols;
  DWORD      dwFramingProtocol;
  // Сценарии
  TCHAR      szScript[ MAX_PATH ];
  // Автодозвон
  TCHAR      szAutodialDll[ MAX_PATH ];
  TCHAR      szAutodialFunc[ MAX_PATH ];
  // Устройство
  TCHAR      szDeviceType[ RAS_MaxDeviceType + 1 ];
  TCHAR      szDeviceName[ RAS_MaxDeviceName + 1 ];
  // X.25
  TCHAR      szX25PadType[ RAS_MaxPadType + 1 ];
  TCHAR      szX25Address[ RAS_MaxX25Address + 1 ];
  TCHAR      szX25Facilities[ RAS_MaxFacilities + 1 ];
  TCHAR      szX25UserData[ RAS_MaxUserData + 1 ];
  DWORD      dwChannels;
  // Зарезервировано
  DWORD      dwReserved1;
  DWORD      dwReserved2;
#if (WINVER >= 0x401)
  // Подключение из многих соединений
  DWORD      dwSubEntries;
  DWORD      dwDialMode;
  DWORD      dwDialExtraPercent;
  DWORD      dwDialExtraSampleSeconds;
  DWORD      dwHangUpExtraPercent;
  DWORD      dwHangUpExtraSampleSeconds;
  // Время простоя до разъединения
  DWORD      dwIdleDisconnectSeconds;
#endif
#if (WINVER >= 0x500)
  DWORD      dwType;
  DWORD      dwEncryptionType;
  DWORD      dwCustomAuthKey;
  GUID       guidId;
   
  TCHAR      szCustomDialDll[MAX_PATH]; 
  DWORD      dwVpnStrategy; 
#endif
#if (WINVER >= 0x501)
  DWORD      dwfOptions2;
  DWORD      dwfOptions3;
  TCHAR      szDnsSuffix[RAS_MaxDnsSuffix];
  DWORD      dwTcpWindowSize;
  TCHAR      szPrerequisitePbk[MAX_PATH];
  TCHAR      szPrerequisiteEntry[RAS_MaxEntryName + 1];
  DWORD      dwRedialCount;
  DWORD      dwRedialPause;
#endif
} RASENTRY;

Первым полем dwSize является размер стуктуры в байтах, заполняется конструкцией sizeof(RASENTRY) до использования функции. Значения бит второго поля dwfOptions характеризуют главные и самые необходимые настройки соединения, аналогичные тем, что можно изменить в стандартных диалоговых окнах. Вы можете установить одно или несколько флагов из следующей таблицы:

Далее, поле dwCountryID должно содержать индентификационный номер страны. Поля dwCountryCode и dwAreaCode должны содержать код страны и код города соответственно, которые в дальнейшем будут использоваться для дозвона. Причем только что рассмотренные три члена структуры игнорируются, если в поле dwfOptions не установлен флаг RASEO_UseCountryAndAreaCodes. Следующее за ними поле szLocalPhoneNumber, представляет собой строку, в которой находится телефонный номер без кода города и страны. Идущая следом часть структуры содержит пять полей, которые отвечают за настройки IP и Point-to-Point Protocol (PPP). Все поля предстваляют из себя одну и ту же структуру RASIPADDR, описанную следующим образом:

#define RASIPADDR struct RASIPADDR
RASIPADDR
{
    BYTE a;
    BYTE b;
    BYTE c;
    BYTE d;
};

Итак, поле ipaddr определяет IP адрес при активном соединении и игнорируется, если в dwfOptions не установлен флаг RASEO_SpecificIpAddr. Поля ipaddrDns и ipaddrDnsAlt определяют IP адреса DNS серверов в порядке использования. Аналогично, поля ipaddrWins и ipaddrWinsAlt определяют IP адреса WINS серверов. Последний четыре поля игнорируются, если в dwsOptions не установлен флаг RASEO_SpecificNameServers.

Три поля dwFrameSize, dwfNetProtocols и dwFramingProtocol определяют свойства используемых соединением протоколов. Первый параметр dwFrameSize содержит размер «кадра», принимающий значение 1006 или 1500 (необходимо заполнить, только если тип подключаемого удаленного сервера SLIP). Значения бит двойного слова dwfNetProtocols указывают, на то будет или нет использоваться протокол:

Поле dwFramingProtocol определяет протокол сервера удаленного доступа и может принимать одно из следующих значений:

Следующее поле szScript, является строкой, в которой должен содержаться путь к файлу сценария (*.scp).

Два поля szAutodialDll и szAutodialFunc отвечают за работу автодозвона, однако, в последних версиях Win2000/XP и Windows Server 2003 больше эти поля игнорируются. Итак, строка szAutodialDll должна содержать путь и имя Dll библиотеки, содержащую функцию автодозвона. Если эту строку оставить пустой, то будут использоваться стандартные средства. Поле szAutodialFunc в свою очередь должно содержать имя экспортируемой из Dll функции автодозвона RASADFunc, причем Dll должна содержать как ANSI версию, так и UNICODE версию функции.

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

В полях szDeviceType и szDeviceName должны быть записаны тип и имя используемого соединением устройства. Возможные варианты значения поля szDeviceType были приведены выше при разборе структуры RASDEVINFO.

Далее часть структуры, состоящая из четырех полей szX25PadType, szX25Address, szX25Facilities и szX25UserData отвечает за настройку соединения по протоколу X.25. Строка szX25PadType должна содержать службу доступа к сети, в szX25Address должен содержаться адрес для соединения. В поле szX25Facilities записывается дополнительные услуги, которые потребуются от хоста. Строка szX25UserData отвечает за передачу дополнительную информацию о пользователе. Все четыре поля не поддерживаются версиями Win9x/ME.

Идущие следом три члена структуры dwChannels, dwReserved1 и dwReserved2 зарезервированы и должны быть установлены в NULL.

Двойное слово wIdleDisconnectSeconds определяет количество секунд простоя машины, после которых происходит разъединение. Так же это поле может принимать одно из следующих значений:

В поле dwType должен содержаться один из типов «точки входа», представленных ниже:

Следующее поле dwEncryptionType используется только в Win2000/XP, и отвечает за то, какой тип шифрования данных (Microsoft Point to Point Encryption) будет использоваться при подключении, на пароли это не распространяется. В таблице приведены возможные варианты значений:

Двойное слово dwCustomAuthKey содержит опозновательный ключ метода, использующего Extensible Authentication Protocol (EAP). А в поле guidId записан глобальный идентификатор соединения, причем доступный только для чтения. Далее идет строка szCustomDialDll, в которой должен находится полный путь и имя DLL библиотеки, содержащей функции дозвона. Причем библиотека должна экспортировать Unicode версии функций RasCustomDial, RasCustomHangup, RasCustomEntryDlg, и RasCustomDialDlg. Описание и объяснения работы этих функций выходят за пределы этой статьи.

Поле dwVpnStrategy объясняет, каким образом будет происходить VPN соединение. Поле может принимать значения:

Последние описанные поля стуктуры поддерживаются только в Win2000/XP. Далее же поля, как видно из объявления структуры, используются только в WinXP и Windows Server 2003. Первый член структуры из этой группы – это двойное слово dwfOptions2, биты которого определяют дополнительные настройки соединения:

Следующий параметр dwfOptions3 зарезервирован для дальнейшего использования. Далее следует строка szDnsSuffix, которая должна содержать DNS суффиксы для данного соединения, в зависимости от версии структуры может использоваться Unicode. Строки szPrerequisitePbk и szPrerequisiteEntry востребованы только в для VPN соединения, и содержат полный путь и имя телефонной книги и «точки вход» соответсвенно.

Значение содержащиеся в поле dwRedialCount определяет, сколько будет повторяться автоматический набор номера, если первый дозвон не удался. Поле же dwRedialPause содержит количество секунд, через которые будет повторяться дозвон, при автоматическом наборе.

Теперь, наконец, пришло время рассказать о функциях, которые используют рассмотренную выше структуру RASENTRY, их как говорилась выше две: RasSetEntryProperties и RasGetEntryProperties. Разберем более подробно первую из них, задача которой состоит в том, чтобы программно создавать соединение или изменять настройки уже созданного соединения:

DWORD RasSetEntryProperties(
  LPCTSTR lpszPhonebook,
  LPCTSTR lpszEntry,
  LPRASENTRY lpRasEntry,
  DWORD dwEntryInfoSize,
  LPBYTE lpbDeviceInfo,
  DWORD dwDeviceInfoSize
);

Первые параметры этой функции нам уже знакомы, это строки lpszPhonebook и lpszEntry которые должны содержать полный путь к телефооной книге и имя «точки входа». В lpszPhonenook, если используется текущая телефонная книга, следует передать NULL. Как в прочем и в Win9x/ME этот параметр должен быть всегда равен NULL. Однако аргумент lpszEntry, здесь можно воспринимать двояко, ведь функция может не только изменять, но и создвать соединения. То есть если указанное в lpszEntry имя «точки входа» будет соответствовать уже существующему соединению, то будут просто изменены параметры данного соединения, но если такого соединения в телефонной книге нет, будет создано новое с именем указанным в lpszEntry. Причем перед вызовом функции необходимо проверить правильность имени соединения функцией RasValidateEntryName, описанной выше. Следующий аргумент lpRasEntry - это указатель на структуру RASENTRY, в случае с изменением настроек здесь просто должны содержаться настройки для замены, а вот в случае с созданием соединения, кроме каких то дополнительных настроек обязательно должны быть заполнены следующие поля структуры:

• szPLocalPhoneNumber
• szDeviceName
• szDeviceType
• dwFramingProtocol
• dwfOptions
• dwType (только в Win2000/XP и далее)

В случае если какое-нибудь поле не будет заполнено, функция возвратит ошибку ERROR_INVALID_PARAMETER. Далее в параметр dwEntryInfoSize функции нужно передать размер в байтах буфера lpRasEntry. Буфер lpbDeviceInfo должен содержать свойства устройства, которое использует соединение. Для получения этих данных нужно использовать уже TAPI функцию lineGetDevConfig, подробный разбор которой не входит в цели статьи. В параметр dwDeviceInfoSize нужно передать размер в байтах буфера lpbDeviceInfo. Последние два аргумента lpbDeviceInfo и dwDeviceInfoSize не используются в WinNT/2000/XP и должны быть установлены в NULL.

Вторая функция RasGetEntryProperties позволяет программно получить настройки существующего соединения, функция объявлена следующим образом:

DWORD RasGetEntryProperties(
  LPCTSTR lpszPhonebook,
  LPCTSTR lpszEntry,
  LPRASENTRY lpRasEntry,
  LPDWORD lpdwEntryInfoSize,
  LPBYTE lpbDeviceInfo,
  LPDWORD lpdwDeviceInfoSize
);

Как видно из описания аргументы этой функции схожи с аргументами RasSetEntryProperties, рассмотренной выше. Главным отличием является смысловая нагрузка каждого параметра. Итак, первый в аргумент lpszPhonebook нужно передать строку, содержащую путь и имя фалйа телефонной книге. Для работы с телефонной книгой по умолчанию нужно передать NULL. Также этот параметр не используется в Win9x/ME и в этом случае тоже передается NULL. Второй аргумент lpszEntry должен содержать строку с именем соединения, настройки которого следует получить. Причем если в lpszEntry передать NULL, то функция запишет настройки соединения по умолчанию. После вызова функции в lpRasEntry будут содержаться свойства «точки входа», но перед вызовом функции необходимо заполнить поле dwSize. В параметр lpdwEntryInfoSize нужно передать размер буфера lpRasEntry в байтах. В lpbDeviceInfo будет записана информация об устройстве. Как и в предыдущем случае для подробной информации нужно обратиться к документации по TAPI. В lpdwDeviceInfoSize после вызова функции запишется размер в байтах буфера lpbDeviceInfo. Два последних параметра не используются в WinNT/2000/XP и должны быть установлены в NULL.

Подключение и разрыв

После того как соединения полностью настроено возникает проблема создать собственно само подключение, то есть начать дозвон, используя информацию, находящуюся в свойствах «точки входа». Решением этой проблемы служат функции RasDial и RasDialDlg. Главным образом эти функции отличаются тем, что RasDial позволяет осуществить дозвон с возможностью более гибкого руководства процессом подключения, а RasDialDlg просто вызвает стандартное диалоговое окно дозвона. Так же нужно отметить, что RasDial более универсальна и доступна практически во всех версиях Windows, а вот RasDialDlg поддерживается только WinNT/2000/XP.

Разберем более подробно функцию RasDial:

DWORD RasDial(
  LPRASDIALEXTENSIONS lpRasDialExtensions,
  LPCTSTR lpszPhonebook,
  LPRASDIALPARAMS lpRasDialParams,
  DWORD dwNotifierType,
  LPVOID lpvNotifier,
  LPHRASCONN lphRasConn
);

Первым же параметром является указатель нас структуру RASDIALEXTENSIONS, поля которой содержат дополнительную информацию о подключении. Этот параметр может быть установлен в NULL, тогда при дозвоне будут использоваться настройки по умолчанию. Даная структура описана так:

typedef struct tagRASDIALEXTENSIONS { 
  DWORD     dwSize;
  DWORD     dwfOptions;
  HWND      hwndParent;
  ULONG_PTR reserved;
#if (WINVER >= 0x500)
  ULONG_PTR reserved1;
  RASEAPINFO RasEapInfo;
#endif
} RASDIALEXTENSIONS;

Если же все-таки было решено использовать эту структуру, то перед вызовом функции необходимо заполнить поле dwSize, определяющее размер структуры в байтах. Значения бит двойного слова dwfOptions отвечают за дополнительные настройки, в таблице приведены возможные флаги:

По умолчанию ни один из флагов флаги не установлены. Далее идет необязательное поле hwndParent обычно равное NULL, которое должно содержать хендл родительского окна, использующего «security» DLL. Этот параметр используется, только в том случае, если эта самая DLL определена. Поля reserved и reserved1 зарезерированы для дальнейшего использования. Поле RasEapInfo является переменной структуры RASEAPINFO, содержащую дополнительную информацию о протоколе EAP. Подробный разбор этой структуры не входит в цели статьи. Сама структура RASDIALEXTENSIONS определена только для WinNT/2000/XP, так что если программа будет работать под Win9x/ME в параметр lpRasDialExtensions функции RasDial необходимо передать NULL.

Во второй парметр lpszPhonebook нужно передать, как и в большинстве предыдущих случаев, полный путь и имя файл телефонной книги. Если же будет использоваться телефонная книга по умолчанию, то необходимо установить этот параметр в NULL. Следующий параметр lpRasDialParams, это ничто иное, как указатель структуры RASDIALPARAMS, в которой содержутся настройки, связанные только с процессом дозвона:

typedef struct _RASDIALPARAMS { 
  DWORD  dwSize; 
  TCHAR  szEntryName[RAS_MaxEntryName + 1]; 
  TCHAR  szPhoneNumber[RAS_MaxPhoneNumber + 1]; 
  TCHAR  szCallbackNumber[RAS_MaxCallbackNumber + 1]; 
  TCHAR  szUserName[UNLEN + 1]; 
  TCHAR  szPassword[PWLEN + 1]; 
  TCHAR  szDomain[DNLEN + 1] ; 
#if (WINVER >= 0x401)
  DWORD      dwSubEntry;
  ULONG_PTR  dwCallbackId;
#endif
} RASDIALPARAMS;

Итак, первое поле dwSize определяет размер структуры и должно заполняться перед использованием функции RasDial, кострукцией типа sizeof(RASDIALPARAMS). Второе поле szEntryName – это строка, которая должна содержать название «точки входа» с помощью которой и будет происходить подключение к серверу. Причем нуно заметить, что это поле является своеобразным связующим звеном между самим соединением и функцией дозвона, то есть все настройки, и свойства для дозвона будут использоваться из структуры RASENTRY, описывающую соединение, указанное в szEntryName. Третье поле szPhoneNumber, в которое нужно записать телефонный номер для дозвона. Строка szCallbackNumber должна содержать номер телефона, который использует сервер для ответного вызова пользователя, обычно поле не заполняется. Следующие поля szUserName и szPasswords – это ничто иное, как строки, в которых должны содержаться логин и пароль. В строку szDomain нужно записать домен. Заметьте, что далее идут два поля, имеющие ограничения на использования. Первое из этих полей dwSubEntry используется только для многоканальных соединений, то есть для соединений, которые задействывают несколько устройств и состоят из нескольких «подвходов» - subentry. dwSubEntry как раз указывает на индекс начального «подвхода». Если поле dwDialMode в стуктуре RASENTRY содержит RASEDM_DialAll, то dwSubEntry игнорируется, также оно игнорируется, если телефонная книга не имеет никаких «подвходов». Причем в Win2000 и далее дозвон осущесвляется в любом случае, если в dwSubEntry содержится правильный индекс. Но если dwSubEntry содержит нуль и dwDialMode равен RASEDM_DialAll, то используются все «подвходы». Ну и в последнее поле dwCallbackId должно быть записано значение, которое определяет само приложение и передает в функцию RasDialFunc2, о которой будет сказано ниже.

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

void CALLBACK RasDialFunc(
  UINT unMsg,
  RASCONNSTATE rasconnstate,
  DWORD dwError
);

Если же в dwNotifierType записать значение 1, тогда в lpvNotifier передается указатель на функцию RasDialFunc1:

void CALLBACK RasDialFunc1(
  HRASCONN hrasconn,
  UINT unMsg,
  RASCONNSTATE rascs,
  DWORD dwError,
  DWORD dwExtendedError
);

Параметр dwNotifierType также может быть равным и 2, только в этом в lpvNotifier нужно передать указатель на функцию RasDialFunc2, которая не поддерживается в Win9x/ME:

DWORD CALLBACK RasDialFunc2(
  DWORD dwCallbackId,
  DWORD dwSubEntry,
  HRASCONN hrasconn,
  UINT unMsg,
  RASCONNSTATE rascs,
  DWORD dwError,
  DWORD dwExtendedError
);

Как видно из описаний этих функций, каждая из них предоставляет возможность получить информацию о подключении через параметры, причем самым важным аргументом Если dwNotifierType установить равным 0xFFFFFFFF, то в параметр lpvNotifier можно передать хендл окна, причем в этом случае нужно будет зарегестировать сообщение, в параметрах wParam и lParam которого будет содержаться информация о подключении:

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

При получении такого сообщения в параметре wParam будет содержаться одно из значений перечисления RASCONNSTATE, а в lParam будет записан код ошибки.

rasconnstate = (RASCONNSTATE) wParam; 
dwError = (DWORD) lParam;

Сам перечислимый тип RASCONNSTATE содержит более 25 значений и объявлено так:

typedef enum _RASCONNSTATE { 
  RASCS_OpenPort = 0, 
  RASCS_PortOpened, 
  RASCS_ConnectDevice, 
  RASCS_DeviceConnected, 
  RASCS_AllDevicesConnected, 
  RASCS_Authenticate, 
  RASCS_AuthNotify, 
  RASCS_AuthRetry, 
  RASCS_AuthCallback, 
  RASCS_AuthChangePassword, 
  RASCS_AuthProject, 
  RASCS_AuthLinkSpeed, 
  RASCS_AuthAck, 
  RASCS_ReAuthenticate, 
  RASCS_Authenticated, 
  RASCS_PrepareForCallback, 
  RASCS_WaitForModemReset, 
  RASCS_WaitForCallback,
  RASCS_Projected, 
#if (WINVER >= 0x400) 
  RASCS_StartAuthentication,    // Windows 95 only 
  RASCS_CallbackComplete,       // Windows 95 only 
  RASCS_LogonNetwork,           // Windows 95 only 
#endif 
  RASCS_SubEntryConnected,
  RASCS_SubEntryDisconnected,
  RASCS_Interactive = RASCS_PAUSED, 
  RASCS_RetryAuthentication, 
  RASCS_CallbackSetByCaller, 
  RASCS_PasswordExpired, 
#if (WINVER >= 0x500)
  RASCS_InvokeEapUI,
#endif
  RASCS_Connected = RASCS_DONE, 
  RASCS_Disconnected 
} RASCONNSTATE ; 

Объяснение каждого значения выходит за рамки этой статьи, причем, если читатель знаком с английским языком ему не составит труда понять назначение самостоятельно.

Наконец переходим к разбору последнего параметра lphRasConn функции RasDial. В этот параметр нужно передать указатель на хендл RAS соединения HRASCONN. То есть в этот параметр будет записан хендл соединения после удачного завершения функции (после установки подключения), причем этот хендл пригодится в последующих действиях над соединением.

Если Вы точно значете, что программа будет работать под WinNT/2k/XP, и хотите просто установить соединение без изменения настроек, то оптимальным вариантом будет использовать функцию RasDialDlg, которая вызвает стандартный диалог соединения. Итак, функция объявлена следующим образом:

BOOL RasDialDlg(
  LPTSTR lpszPhonebook,
  LPTSTR lpszEntry,
  LPTSTR lpszPhoneNumber,
  LPRASDIALDLG lpInfo
);

Первые два параметра lpszPhonebook и lpszEntry – это полный путь к файлу телефонной книге и имя соединения. Параметр lpszPhoneNumber должен содержать строку в котроую необходимо записать телефонный номер для дозвона, если же в этот параметр передать NULL, то номер будет взят из настроек указанного соединения. А вот четвертый параметр lpInfo – это указатель на структуру RASDIALDLG:

typedef struct tagRASDIALDLG {
  IN  DWORD dwSize;
  IN  HWND hwndOwner;
  IN  DWORD dwFlags;
  IN  LONG xDlg;
  IN  LONG yDlg;
  IN  DWORD dwSubEntry;
  OUT DWORD dwError;
  IN  ULONG_PTR reserved;
  IN  ULONG_PTR reserved2;
} RASDIALDLG;

Первое поле dwSize перед вызовом функции должно содержать размер структуры. В поле hwndOwner запишем хендл окна «родителя», заметим, что это поле может быть установлено в NULL. Биты двойного слова dwFlags определяют настройки вызова диалога. Пока существует всего один флаг RASDDFLAG_PositionDlg, при установке которого в поля xDlg и yDlg должны быть записаны координаты левого верхнего угла диалога, которые используются для позиционирования. Поле dwSubEntry используется для многоканальных соединений, то есть оно определяет номер «подвхода», который необходимо набрать. Если же этот параметр равен NULL, то будут задейсвованы все каналы. В поле dwError, после вызова функции, будет храниться результат вызова функции. Два последних поля не используются и зарезервированы.

Естественно, что иногда возникает проблема из программы закрыть какое либо RAS соединение. В этом случае на помощь приходит функция RasHangUp:

DWORD RasHangUp(
  HRASCONN hrasconn
);

Единственным параметром ее является тот самый хендл соединения, который возвращает нам функция RasDial в последнем параметре. Этот хендл так же можно получить при перечислении всех соединений. После удачного завершения работы этой функции (разрыва соединения), этот хендл использовать больше нельзя. При возникновении ошибки фугкция возвращает ее код. Коды ошибок RAS находится в заголовочном файле RasError.h.

Заключение

Остались не разобранными довольно большое количество возможностей, которые предоставляет RAS разработчику. Но все же следует подчеркнуть, что с помощью данного материала читатель сможет написать действенное и функциональное приложение.

Для того, чтобы можно было проверить работоспособность вышеописанных функций, мною написана программа SmartDial, в которой ипользуется только WinAPI и RAS API. В ней реальзованы самые необходимые действия над соединенями: создание, удаление, редактирование и переименование. Так же можно разрывать текущие соединения и изменять логин и пароль, при желании использовать домен при подключении.

Исходные тексты программы прилагаются в архиве к этой статье. Хочу также заметить, что при написании этой статьи были использованы материалы с сайтов http://www.firststeps.ru и, конечно, http://www.msdn.com .

Сообщений 1    Оценка 115        Оценить