Функция SQLInstallDriverEx

Соответствие
Представлена версия: ODBC 3.0

Сводка
SQLInstallDriverEx добавляет сведения о драйвере в запись Odbcinst.ini в системной информации и увеличивает значение параметра UsageCount на 1. Однако если версия драйвера уже существует, но значение UsageCount для драйвера не существует, новое значение UsageCount имеет значение 2.

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

К функциям SQLInstallDriverEx также можно получить доступ с помощью ODBCCONF.EXE.

Синтаксис

  
BOOL SQLInstallDriverEx(  
     LPCSTR    lpszDriver,  
     LPCSTR    lpszPathIn,  
     LPSTR     lpszPathOut,  
     WORD      cbPathOutMax,  
     WORD *    pcbPathOut,  
     WORD      fRequest,  
     LPDWORD   lpdwUsageCount);  

Аргументы

lpszDriver
[Входные данные] Описание драйвера (обычно имя связанной СУБД), представленное пользователям вместо имени физического драйвера. Аргумент lpszDriver должен содержать вдвойне завершенный список пар "ключевое слово-значение", описывающих драйвер. Дополнительные сведения о парах "ключевое слово-значение" см. в подразделах спецификации драйвера. Дополнительные сведения о двукратной строке, завершаемой значением NULL, см. в разделе "Функция ConfigDSN".

lpszPathIn
[Входные данные] Полный путь к целевому каталогу установки или указателю NULL. Если lpszPathIn является указателем null, драйверы будут установлены в системном каталоге.

lpszPathOut
[Выходные данные] Путь к целевому каталогу, в котором должен быть установлен драйвер. Если драйвер еще не установлен, lpszPathOut должен совпадать с lpszPathIn. Если драйвер был установлен ранее, lpszPathOut — путь к предыдущей установке.

cbPathOutMax
[Входные данные] Длина lpszPathOut.

pcbPathOut
[Выходные данные] Общее количество байтов (за исключением символа завершения null), доступное для возврата в lpszPathOut. Если число байтов, доступное для возврата, больше или равно cbPathOutMax, выходной путь в lpszPathOut усечен до cbPathOutMax минус символ завершения null. Аргумент pcbPathOut может быть указателем null.

fRequest
[Входные данные] Тип запроса. Аргумент fRequest должен содержать одно из следующих значений:

ODBC_INSTALL_INQUIRY. Запрос о том, где можно установить драйвер.

ODBC_INSTALL_COMPLETE. Выполните запрос на установку.

lpdwUsageCount
[Выходные данные] Количество использования драйвера после вызова этой функции.

Приложения не должны задавать количество использования. ODBC будет поддерживать это число.

Возвраты

Функция возвращает значение TRUE, если оно выполнено успешно, значение FALSE, если оно завершается ошибкой.

Диагностика

Когда SQLInstallDriverEx возвращает ЗНАЧЕНИЕ FALSE, связанное значение *pfErrorCode можно получить путем вызова SQLInstallerError. В следующей таблице перечислены значения *pfErrorCode , которые можно возвращать SQLInstallerError и объясняет каждый из них в контексте этой функции.

*pfErrorCode	Ошибка	Описание
ODBC_ERROR_GENERAL_ERR	Общая ошибка установщика	Произошла ошибка, для которой не было определенной ошибки установщика.
ODBC_ERROR_INVALID_BUFF_LEN	Недопустимая длина буфера	Аргумент lpszPathOut был недостаточно большим, чтобы содержать выходной путь. Буфер содержит усеченный путь. Аргумент cbPathOutMax был 0, и fRequest был ODBC_INSTALL_COMPLETE.
ODBC_ERROR_INVALID_REQUEST_TYPE	Недопустимый тип запроса	Аргумент fRequest не был одним из следующих: ODBC_INSTALL_INQUIRY ODBC_INSTALL_COMPLETE
ODBC_ERROR_INVALID_KEYWORD_VALUE	Недопустимые пары "ключевое слово-значение"	Аргумент lpszDriver содержал синтаксическую ошибку.
ODBC_ERROR_INVALID_PATH	Недопустимый путь установки	Аргумент lpszPathIn содержал недопустимый путь.
ODBC_ERROR_LOAD_LIBRARY_FAILED	Не удалось загрузить библиотеку установки драйвера или переводчика	Не удалось загрузить библиотеку установки драйвера.
ODBC_ERROR_INVALID_PARAM_SEQUENCE	Недопустимая последовательность параметров	Аргумент lpszDriver не содержал список пар "ключевое слово-значение".
ODBC_ERROR_USAGE_UPDATE_FAILED	Не удалось увеличить или открепить количество использования компонентов	Установщик не смог увеличить число использования драйвера.

Комментарии

Аргумент lpszDriver — это список атрибутов в виде пар "ключевое слово-значение". Каждая пара завершается с байтом NULL, и весь список завершается с байтом NULL. (То есть два байта null помечают конец списка.) Формат этого списка выглядит следующим образом:

driver-desc\ 0Driver=driver-DLL-filename\0[Setup-DLL-filename=\0]

[driver-attr-keyword1 value1\=0][driver-attr-keyword2 value2=\0]...\0

где \0 является байтом NULL и driver-attr-keywordn является любым ключевым словом атрибута драйвера. Ключевые слова должны отображаться в указанном порядке. Например, предположим, что драйвер для отформатированных текстовых файлов имеет отдельные библиотеки DLL и настраивает библиотеки DLL и может использовать файлы с расширениями .txt и .csv. Аргумент lpszDriver для этого драйвера может быть следующим:

Text\0Driver=TEXT.DLL\0Setup=TXTSETUP.DLL\0FileUsage=1\0  
FileExtns=*.txt,*.csv\0\0  

Предположим, что драйвер для SQL Server не имеет отдельной библиотеки DLL установки и не имеет ключевых слов атрибутов драйвера. Аргумент lpszDriver для этого драйвера может быть следующим:

SQL Server\0Driver=SQLSRVR.DLL\0\0  

После того как SQLInstallDriverEx извлекает сведения о драйвере из аргумента lpszDriver , он добавляет описание драйвера в раздел [Драйверы ODBC] записи Odbcinst.ini в системной информации. Затем он создает раздел с описанием драйвера и добавляет полные пути библиотеки DLL драйвера и библиотеки DLL установки. Наконец, он возвращает путь к целевому каталогу установки, но не копирует файлы драйверов в него. Вызывающая программа должна фактически скопировать файлы драйверов в целевой каталог.

SQLInstallDriverEx увеличивает число использования компонентов для установленного драйвера на 1. Если версия драйвера уже существует, но число использования компонентов для драйвера не существует, то для нового значения количества использования компонентов задано значение 2.

Программа установки приложений отвечает за физическое копирование файла драйвера и поддержание количества использования файлов. Если файл драйвера еще не установлен, программа установки приложения должна скопировать файл в путь lpszPathIn и создать число использования файлов. Если файл был установлен ранее, программа установки просто увеличивает количество использования файлов и возвращает путь к предыдущей установке в аргументе lpszPathOut .

Примечание.

Дополнительные сведения о счетчиках использования компонентов и количествах использования файлов см. в разделе "Подсчет использования".

Если более ранняя версия файла драйвера была установлена приложением, драйвер должен быть удален и переустановлен таким образом, чтобы число использования компонентов драйвера было допустимым. SqlConfigDriver (с fRequest ODBC_REMOVE_DRIVER) следует сначала вызвать, а затем вызвать SQLRemoveDriver , чтобы отсортировать количество использования компонентов. Затем необходимо вызвать SQLInstallDriverEx , чтобы переустановить драйвер, добавив количество использования компонентов. Программа установки приложения должна заменить старый файл новым файлом. Число использования файлов останется прежним, и любое другое приложение, которое использовал старый файл версии, теперь будет использовать более новую версию.

Примечание.

Если драйвер был установлен ранее и вызывается SQLInstallDriverEx для установки драйвера в другом каталоге, функция вернет TRUE, но lpszPathOut будет включать каталог, в котором драйвер уже установлен. Он не будет включать каталог, введенный в аргумент lpszDriver .

Длина пути в lpszPathOut в SQLInstallDriverEx позволяет выполнять двухэтапную установку, чтобы приложение может определить, какой cbPathOutMax должен быть путем вызова SQLInstallDriverEx с fRequestst of ODBC_INSTALL_INQUIRY режиме. При этом будет возвращено общее количество байтов, доступных в буфере pcbPathOut . Затем SQLInstallDriverEx можно вызвать с помощью fRequest ODBC_INSTALL_COMPLETE и аргумента cbPathOutMax , заданного значением в буфере pcbPathOut, а также символом завершения null.

Если вы решили не использовать двухфазную модель для SQLInstallDriverEx, необходимо задать cbPathOutMax, которая определяет размер хранилища для пути к целевому каталогу, значение _MAX_PATH, как определено в Stdlib.h, чтобы предотвратить усечение.

Если fRequest ODBC_INSTALL_COMPLETE, SQLInstallDriverEx не разрешает значение NULL ( или cbPathOutMax равно 0). Если fRequest ODBC_INSTALL_COMPLETE, значение FALSE возвращается, если число байтов, доступное для возврата, больше или равно cbPathOutMax, с результатом усечения.

После вызова SQLInstallDriverEx программа установки приложения скопировал файл драйвера (при необходимости), библиотека DLL установки драйвера должна вызвать SQLConfigDriver , чтобы задать конфигурацию драйвера.

Связанные функции

Сведения	Смотрите
Установка диспетчера драйверов	SQLInstallDriverManager