Интегрированная среда моделирования РДО / DRIVERS / INST.DLL / README

________________________________________________________________________

Описание библиотеки для работы с драйвером электронных ключей
________________________________________________________________________

Инструменты для работы с драйверами из приложения пользователя находятся
в библиотеке INSTDRV.DLL. В приложения, использующие данную DLL, необходимо
включать файлы INSTDRVS.H и INSTDRVF.H.

В данном каталоге содержатся следующие файлы:

INSTDRV.DLL - Библиотека функций для работы с драйвером
INSTDRVF.H - Файл-заголовок с описанием функций
INSTDRVS.H - Файл-заголовок с описанием структуры и кодов возврата
README.TXT - Этот файл
Файлы для примера:
MK_DEMO.BAT - Командный файл для трансляции
INSTDEMO.MAK - MAKE-файл для трансляции
INSTDEMO.IDE - Проектный файл ( создан на Borland C++ 5.02 )
INSTDRV.C - Исходный текст ( основной модуль )
DIALOG.C - Исходный текст ( дополнительный модуль )
INSTDRV.H - Файл-заголовок
INSTSTR.H - Файл-заголовок с описанием констант для строчных ресурсов
INSTDRV.RC - Ресурсы
INSTDRV.LIB - Библиотека импорта для INSTDRV.DLL (Borland)
INSTDMS.LIB - Библиотека импорта для INSTDRV.DLL (Microsoft)
INSTDRV.ICO - Иконка програмы

Пример использования библиотеки - полностью фукциональная утилита для
работы с драйвером. Странслировав этот пример Вы получите поставляемую
с нашими драйверами утилиту установки. Единственное отличие между ними
будет заключаться в том, что в примере используется внешняя DLL, а в
утилите установки все функции включены в ЕХЕ-файл.


ВНИМАНИЕ! Для работы примера (как и для утилиты) необходимо, чтобы в
текущем каталоге находились файлы драйвера.

______________________________________________________________________________
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Описание библиотеки INSTDRV.DLL
______________________________________________________________________________
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

//////////////////////////////////////////////////////
ЭКСПОРТИРУЕМЫЕ ФУНКЦИИ *
Описание находится в файле INSTDRVF.H
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

* Все функции предназначены для работы как в Windows 95/98,
так и в Windows NT/2000
______________________________
int WINAPI GD_ReInstallDriver ( void );

Input -
Return - Код ошибки

Устанавливает свежую версию драйвера. Если драйвер уже находился в системе,
то происходит переустановка.
Существовавшая ранее конфигурация сохраняется.

____________________________
int WINAPI GD_InstallDriver ( void );

Input -
Return - Код ошибки

Устанавливает драйвер в систему.
Если драйвер уже установлен, то возвращается ge_DRIVER_ALREADY_INSTALLED

___________________________
int WINAPI GD_RemoveDriver ( BOOL bSaveConfig );

Input - Признак: сохранять ли конфигурацию
Return - Код ошибки

Удаляет драйвер из системы.

При bSaveConfig == TRUE конфигурация драйвера не удаляется из системного
реестра. В этом случае при последущей установке драйвера будет использована
уже существующая конфигурация.

При bSaveConfig == FALSE конфигурация стирается.

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

__________________________
int WINAPI GD_CheckDriver ( PGD_DRIVER_INFO pDI, DWORD dwSize );

Input - Указатель на буфер для информации о драйвере
Размер буфера
Return - Код ошибки

Если код ошибки равен ge_NO_ERROR, то в буфер помещается структура с
полной информацией о текущем состоянии драйвера.

Описание полей структуры GD_DRIVER_INFO см. ниже.

________________________________
int WINAPI GD_ConfigSetDefaults ( void );

Input -
Output - Код ошибки

Устанавливает конфигурацию драйвера по умолчанию.
Значения по умолчанию берутся из файла INSTDRV.INI

Для активизации изменений в конфигурации драйвера необходим
вызов процедуры GD_ReconfigureDriver()

_____________________________
int WINAPI GD_ConfigPortsUse ( BYTE PortsMask );

Input - Маска используемых портов
Output - Код ошибки

Устанавливает порты, в которых будет производиться поиск электронного ключа
Маска задается как сумма gd_USE_PORT_LPT#

Для активизации изменений в конфигурации драйвера необходим
вызов процедуры GD_ReconfigureDriver()

______________________________
int WINAPI GD_ConfigPortAlloc ( BYTE Port, DWORD Method );

Input - Номер порта
Маска способа захвата
Output - Код ошибки

Устанавливает комбинацию способов захвата для указаного порта
Номер порта задается константой gd_PORT_LPT#

Способ захвата задается как сумма необходимых констант gd_METHOD_#######

Для активизации изменений в конфигурации драйвера необходим
вызов процедуры GD_ReconfigureDriver()

____________________________
int WINAPI GD_ConfigTimeOut ( DWORD TimeOut );

Input - Время ожидания в милисекундах (1/1000 секунды)
Output - Код ошибки

Устанавливает общее время, которое драйвер пытатся захватить порт
По истечению этого времени драйвер возвращает ошибку PORT_BUSY
Значение должно быть от 1 до 600000 (от 0.001 до 600 секунд)

Для активизации изменений в конфигурации драйвера необходим
вызов процедуры GD_ReconfigureDriver()

_________________________
int WINAPI GD_ConfigIrql ( BYTE Port, BYTE Irql );

Input - Номер порта,
Значение IRQL
Output - Код ошибки

Устанавливает значение IRQL при использовании для данного
порта соответствующего способа захвата gd_METHOD_IRQL
Номер порта задается константой gd_PORT_LPT#
Значение IRQL должно находиться в пределах от 0 до 26

Для активизации изменений в конфигурации драйвера необходим
вызов процедуры GD_ReconfigureDriver()

* Только для Windows NT/2000
(в Windows 95/98 тоже работает, но ни на что не влияет)
________________________________
int WINAPI GD_ReconfigureDriver ( void );

Input -
Output - Код ошибки

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

______________________________
void WINAPI GD_SetMessageMode ( BOOL bShowMessages, BOOL bShowFullDescriptions );

Input - Признак: выводить сообщения?
Признак: выводить подробные сообщения?
Output -

!!! Эта функция только для совместимости в предыдущими версиями
!!! Используйте GD_SetInstdrvConfig()

Устанавливает режим вывода сообщений для всех функций
bShowMessages
true Выводить сообщения об основных ошибках
и результатах операций
false На экран вообще ничего не выводится

bShowFullDescriptions
true Выводить сообщения обо всех ошибках
и о результате всех операций.
Данный режим полезен при отладке

______________________________
void WINAPI GD_SetInstdrvConfig ( DWORD dwFlags );

Input - Флаги

Output -

Устанавливает конфицурацию инсталятора через комбинацию флагов dwFlags
см. константы gic_######### в файле INSTDRVS.H

______________________________
void WINAPI GD_PrintLog ( char * szMessage );

Input - Строка сообщения

Output -

При установленом режиме gic_PRINTLOG функции GD_SetInstdrvConfig()
помещает в LOG-файл сообщение.

Файл _INSTRDV.LOG создается в там-же, где находится INSTDRV.DLL.
Если файл по каким-то причинам не может быть там создан ( диск защищен от
записи ), то он создается в каталоге %SYTEMROOT%\SYSTEM для Windows 95/98
и в %SYSTEMROOT%\SYSTEM32\DRIVERS для Windows NT/2000

___________________________
void WINAPI GD_GetVersions ( BOOL* bWinNT, BOOL* bRus, int* CurDrvVer );

Input - Буфер для признака Windows NT/2000
Буфер для признака русского языка
Буфер для версии драйвера
Output -

При загрузке в память DLL определяет версию Windows (NT/2000 или 95/98)
текущую кодовую страницу(язык системы) и версию драйвера,
который поставляется вместе с DLL (а не того, который установлен в системе!)

Все эти данные можно получить с помощь данной процедуры

Если любой из параметров равен NULL, то он игнорируется

________________________________________
char* WINAPI GD_GetLastErrorDescription ( char* szErr, DWORD dwLen );

Input - Буфер для строки
Размер буфера
Output - Указатель на буфер

Если результат последней операции не равен ge_NO_ERROR, то данная
процедура возвращает описание ошибки.
Данное описание выводится на экран в виде сообщения при установленом
режиме gic_FULLINFO функции GD_SetInstdrvConfig()

В буфер копируется либо вся строка,
либо dwLen байт, если строка длинее буфера

После удачного завершения последней операции (код ощибки ge_NO_ERROR )
значение возвращаемой строки не определено.

______________________________________________________________________________
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

//////////////////////////////////////////////////
СТРУКТУРА GD_DRIVER_INFO
Описание находится в файле INSTDRVS.H
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

WORD di_wSize
Размер структуры в байтах

WORD di_wSign
Сигнатура. Равна 0x4447 ('GD')

DWORD di_dwUpdateFlags
Флаги для будущих расширений. Равны 0

WORD di_wVersion
Версия драйвера. Major = HiByte, Minor = LoByte (0x0301 ==> 3.1)

BYTE di_bPort
Маска портов, в которых ищутся электронные ключи

WORD di_awBase[3]
Базовые адреса портов. Base[0] для LPT1, Base[1] для LPT2 и т.д

DWORD di_adwMethod[3]
Методы захвата для каждого порта

BYTE di_abIrql[3]
Значения IRQL для каждого порта
(используются только в Windows NT/2000)

DWORD di_dwTimeout
Значение таймаута для захвата порта

BYTE di_lpBuildTime[16]
Строка, содержащая дату и время компиляции драйвера

DWORD di_adwHKey[3]
Ключи реестра. Для каждого порта содержит ключ к разделу системного
реестра, в котором находится информация о порте. В примере используется
для считывания строчки-описания порта (freindly name)

DWORD di_dwTimeLoop
Методы таймеров и задержек, которые поддерживает драйвер

DWORD di_dwConfigFlags
Конфигурация драйвера. (флаги свойств драйвера)

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


STRUCT di_Flags
Флаги (каждая переменная принимает значения 0 или 1):
fConfigurable Признак того, что драйвер можно конфигурировать в данный момент
Поддерживаемые методы захвата портов:
mSteal Захват LPT ( Windows 95/98 )
mAquire Захват IO диапазона ( Windows 95/98 )
mCrSect Критическая секция ( Windows 95/98 )
mMask Маскирование прерываний ( Windows 95/98 )
mCli Запрет прерываний Cli ( Windows 95/98 )
mAlloc Захват LPT ( Windows NT/2000 )
mIrql Изменение IRQL ( Windows NT/2000 )

Поддерживаемые возможности:

cTimers Конфигурирование способа определения времени (таймер)
и метода формирования задержек
___________________________________________________________________________
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

//////////////////////////////////////////////////
Коды возврата функций
Описание находится в файле INSTDRVS.H
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\


ge_NO_ERROR
Операция успешно завершена

ge_DRIVER_NOT_FOUND
Драйвер не найден

ge_DRIVER_ALREADY_INSTALLED
Драйвер уже установлен

ge_DRIVER_NOT_INSTALLED
Драйвер не установлен

ge_DRIVER_OLD_VERSION
В системе установлена более старая версия драйвера

ge_DRIVER_NEWER_VERSION
В системе установлена более свежая версия драйвера

ge_DRIVER_NOT_REMOVED
Ошибка при удалении: драйвер все еще активен

ge_DRIVER_CONFIG_NOT_SUPPORTED
Драйвер не может быть сконфигурирован.
Ошибка возвращается функциями конфигурирования GD_Config######
Эта ошибка возникает в случаях, если:
- в системе установлен драйвер более старой версии
- установленый драйвер не поддерживает конфигурирование

ge_REBOOT_NEEDED
Для завершения операции необходима перезагрузка системы.

ge_DIOCTL_FAIL
Ошибка обмена с драйвером.

ge_RETURNED_PART_ONLY
Буфер для структуры GD_DRIVER_INFO не достаточного размера.
Скопирована только поместившаяся часть.

ge_SOURCE_FILE_NOT_FOUND
Не найден файл драйвера, предназначеного для установки.
Данный файл должен находится в текущей директории.
В такой ситуации невозможна установка и сравнение версий.

ge_CANNOT_COPY_FILE
Ошибка при копировании файла

ge_CANNOT_DELETE_FILE
Ошибка при удалении файла

ge_CANNOT_CREATE_REGKEY
Невозможно создать ключ реестра

ge_CANNOT_OPEN_REGKEY
Невозможно открыть ключ реестра

ge_CANNOT_SET_REGKEY
Невозможно установить значение в ключе реестра

ge_CANNOT_QUERY_REGKEY
Невозможно считать значение в ключе реестра

ge_CANNOT_REMOVE_REGKEY
Невозможно удалить ключ реестра

ge_CANNOT_OPEN_DEVICE
Невозможно открыть устройство

ge_CANNOT_CREATE_SERVICE
Невозможно создать службу (Windows NT)

ge_CANNOT_OPEN_SERVICE
Невозможно открыть службу (Windows NT)

ge_CANNOT_START_SERVICE
Невозможно запустить службу (Windows NT)

ge_CANNOT_STOP_SERVICE
Невозможно остановить службу (Windows NT)

ge_CANNOT_DELETE_SERVICE
Невозможно удалить службу (Windows NT)

ge_CANNOT_ADD_CONFIG
Невозможно добавить строку в CONFIG.SYS (Windows NT)

ge_INCORRECT_WINDOWS_VERSION
Операционная система не является Windows 95/98 или Windows NT

ge_ACCESS_DENIED
Доступ закрыт. Необходимо обладать правами администратора (Windows NT)

ge_VALUE_OUT_OF_RANGE
Значение параметра выходит за допусттимые пределы

ge_USER_BREAK
Пользователь прервал операцию

ge_PORTS_NOT_USED
Драйвер сконфигурирован так, что ни один порт не используется.
В таком случае электронный ключ не может быть найден!

___________________________________________________________________________
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

//////////////////////////////////////////////////
Примеры использования функций
из библиотеки INSTDRV.DLL
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

Данные примеры необходимо понимать как описание концепции.

Тонкости обработки ошибок и т.п. опущены.

Полные исходные тексты програмы установки
драйверов находятся в файлах в INSTDRV.C и DIALOG.C

1. Самый простой и быстрый вариант:
Переустановка

{
GD_ReInstallDriver();
}

Драйвер устанавливается, конфигурация берется из INSTDRV.INI
Если драйвер уже был установлен, то он обновляется и конфигурация сохраняется

2. Вариант с переконфигурированием
Проверка: стоит ли драйвер или нет?
Если да - переконфигурировать
иначе - переустановить


{
GD_DRIVER_INFO DI; // Структура информации о драйвере
int nRet; // Возвращаемое значение

nRet = GD_CheckDriver(&DI);
if (( nRet == ge_NO_ERROR )&& // Драйвер уже стоит,версии совпадают
( DI.Flags.bConfigurable )) // и поддерживается конфигурирование
{
// Устанавливаем конфигурацию по-умолчанию
GD_ConfigSetDefaults ();

// Далее изменяем некоторые параметры конфигурации по-своему:
// Использовать только LPT1
GD_ConfigPortUse (gd_USE_PORT_LPT1);

// Метод захвата - захват порта + критическая секция
GD_ConfigPortAlloc (gd_PORT_LPT1, gd_METHOD_STEAL + gd_METHOD_CS );

// Передать драйверу созданую конфигурацию
GD_ReconfigureDriver ();
}
else // Драйвера нет или версия не та...
{ // Переустановим его. Конфигурация останется прежней.
nRet = GD_ReInstallDriver();
if ( nRet == ge_REBOOT_NEEDED )
{
// Перезагрузка системы....
..............

}
}
}






end-of-file