Функция SQLInstallDriverEx
Соответствия
Представлена версия: ODBC 3.0
Сводка
SQLInstallDriverEx добавляет сведения о драйвере в запись Odbcinst.ini в системной информации и увеличивает число потребления драйвера на 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 | Error | Description |
|---|---|---|
| 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 |
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по