SQLInstallDriverEx 函数

一致性
引入的版本：ODBC 3.0

总结
SQLInstallDriverEx 将有关驱动程序的信息添加到系统信息中的Odbcinst.ini条目，并将驱动程序的 UsageCount 递增 1。 但是，如果驱动程序的版本已存在，但 驱动程序的 UsageCount 值不存在，则新的 UsageCount 值设置为 2。

此函数实际上不会复制任何文件。 调用程序负责正确将驱动程序的文件复制到目标目录。

也可以使用 ODBCCONF.EXE访问 SQLInstallDriverEx 的功能。

语法

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

参数

lpszDriver
[输入]驱动程序说明（通常是关联的 DBMS 的名称）提供给用户，而不是物理驱动程序名称。 lpszDriver 参数必须包含描述驱动程序的关键字值对的以 null 结尾的双倍列表。 有关关键字值对的详细信息，请参阅 驱动程序规范子项。 有关以 null 结尾的双倍字符串的详细信息，请参阅 ConfigDSN 函数。

lpszPathIn
[输入]安装的目标目录的完整路径，或 null 指针。 如果 lpszPathIn 是空指针，驱动程序将安装在系统目录中。

lpszPathOut
[输出]应安装驱动程序的目标目录的路径。 如果之前尚未安装驱动程序， lpszPathOut 应与 lpszPathIn 相同。 如果之前安装了驱动程序， 则 lpszPathOut 是上一安装的路径。

cbPathOutMax
[输入]lpszPathOut 的长度。

javaPathOut
[输出]可用于在 lpszPathOut 中返回的字节总数（不包括 null 终止字符）。 如果可用于返回的字节数大于或等于 cbPathOutMax，则 lpszPathOut 中的输出路径将被截断为 cbPathOutMax 减去 null 终止字符。 jsonPathOut 参数可以是 null 指针。

fRequest
[输入]请求的类型。 fRequest 参数必须包含以下值之一：

ODBC_INSTALL_INQUIRY：询问可以安装驱动程序的位置。

ODBC_INSTALL_COMPLETE：完成安装请求。

lpdwUsageCount
[输出]调用此函数后驱动程序的使用计数。

应用程序不应设置使用情况计数。 ODBC 将维护该计数。

返回

如果函数成功，则返回 TRUE;如果失败，则返回 FALSE。

诊断

当 SQLInstallDriverEx 返回 FALSE 时，可以通过调用 SQLInstallerError 来获取关联的 *pfErrorCode 值。 下表列出了 SQLInstallerError 可返回的 *pfErrorCode 值，并解释此函数上下文中的每个值。

*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 setup-DLL-filename=\0]

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

其中 \0 是 null 字节，driver-attr-keywordn 是任何驱动程序属性关键字。 关键字必须按指定顺序显示。 例如，假设格式化文本文件的驱动程序具有单独的驱动程序和设置 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 参数检索有关驱动程序的信息后，它会将驱动程序说明添加到系统信息中Odbcinst.ini项的 [ODBC 驱动程序] 部分。 然后，它会创建一个标题为驱动程序说明的部分，并添加驱动程序 DLL 和安装 DLL 的完整路径。 最后，它将返回安装的目标目录的路径，但不会将驱动程序文件复制到其中。 调用程序实际上必须将驱动程序文件复制到目标目录。

SQLInstallDriverEx 将已安装驱动程序的组件使用量计数递增 1。 如果驱动程序的版本已存在，但驱动程序的组件使用情况计数不存在，则新组件使用情况计数值设置为 2。

应用程序安装程序负责以物理方式复制驱动程序文件并维护文件使用情况计数。 如果以前尚未安装驱动程序文件，应用程序安装程序必须在 lpszPathIn 路径中复制该文件，并创建文件使用情况计数。 如果文件以前已安装，安装程序只会递增文件使用情况计数，并在 lpszPathOut 参数中返回先前安装的路径。

注意

有关组件使用情况计数和文件使用情况计数的详细信息，请参阅 使用情况计数。

如果应用程序以前安装了旧版驱动程序文件，则应卸载驱动程序，然后重新安装驱动程序，以便驱动程序组件使用情况计数有效。 应先调用 SQLConfigDriver （具有 fRequest ODBC_REMOVE_DRIVER），然后 调用 SQLRemoveDriver 以减少组件使用计数。 然后应调用 SQLInstallDriverEx 来重新安装驱动程序，从而增加组件使用情况计数。 应用程序安装程序必须将旧文件替换为新文件。 文件使用计数将保持不变，使用旧版本文件的任何其他应用程序现在都将使用较新版本。

注意

如果之前安装了驱动程序，并且 调用 SQLInstallDriverEx 以在不同的目录中安装驱动程序，该函数将返回 TRUE，但 lpszPathOut 将包含已安装驱动程序的目录。 它不包括在 lpszDriver 参数中输入的目录。

SQLInstallDriverEx 中 lpszPathOut 中路径的长度允许进行两阶段安装过程，因此应用程序可以通过使用 fRequest ODBC_INSTALL_INQUIRY 模式调用 SQLInstallDriverEx 来确定什么是 cbPathOutMax。 这将返回在PathOut 缓冲区中可用的字节总数。 然后，可以使用 fRequest of ODBC_INSTALL_COMPLETE 和 cbPathOutMax 参数设置为ODBC_INSTALL_COMPLETE的值调用 SQLInstallDriverEx，以及 null 终止字符。

如果选择不使用 SQLInstallDriverEx 的双阶段模型，则必须将 cbPathOutMax（它定义目标目录路径的存储大小）设置为 stdlib.h 中定义的值_MAX_PATH，以防止截断。

当 fRequest ODBC_INSTALL_COMPLETE时，SQLInstallDriverEx 不允许 lpszPathOut 为 NULL（或 cbPathOutMax 为 0）。 如果 fRequest 是ODBC_INSTALL_COMPLETE，则当可用可返回的字节数大于或等于 cbPathOutMax 时返回 FALSE，并产生截断的结果。

调用 SQLInstallDriverEx 并且应用程序安装程序复制驱动程序文件（如有必要），驱动程序设置 DLL 必须调用 SQLConfigDriver 来设置驱动程序的配置。

相关函数

有关以下内容的信息	请参阅
安装驱动程序管理器	SQLInstallDriverManager