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
[輸入]驅動程式描述（通常是相關聯的 DBMS 名稱）呈現給使用者，而不是實體驅動程式名稱。 lpszDriver 自變數必須包含描述驅動程式之關鍵詞/值組的兩倍結束清單。 如需關鍵詞/值組的詳細資訊，請參閱 驅動程式規格子機碼。 如需多倍 Null 終止字串的詳細資訊，請參閱 ConfigDSN 函式。

lpszPathIn
[輸入]安裝目標目錄的完整路徑，或 Null 指標。 如果 lpszPathIn 是 Null 指標，驅動程式將會安裝在系統目錄中。

lpszPathOut
[輸出]應該安裝驅動程式的目標目錄路徑。 如果驅動程式先前尚未安裝， lpszPathOut 應該與 lpszPathIn 相同。 如果先前已安裝驅動程式， lpszPathOut 是先前安裝的路徑。

cbPathOutMax
[輸入]lpszPathOut 的長度。

pcpathOut
[輸出]可用在 lpszPathOut 中傳回的位元組總數（不包括 Null 終止字元）。 如果可用的位元組數目大於或等於 cbPathOutMax，lpszPathOut 中的輸出路徑會截斷為 cbPathOutMax 減去 null 終止字元。 對pcspcPathOut 自變數可以是 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 Drivers] 區段。 然後，它會建立標題為驅動程式描述的區段，並新增驅動程式 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。 這將會傳回在pcerpathOut 緩衝區中可用的位元組總數。 接著，可以使用 fRequest ODBC_INSTALL_COMPLETE 呼叫 SQLInstallDriverEx，並將 cbPathOutMax 自變數設定為ODBC_INSTALL_COMPLETE緩衝區中的值，加上 null 終止字元。

如果您選擇不使用 SQLInstallDriverEx 的兩階段模型，則必須將 cbPathOutMax 設定為定義目標目錄路徑的記憶體大小，將值_MAX_PATH，如 Stdlib.h 中所定義，以避免截斷。

當 fRequest ODBC_INSTALL_COMPLETE時，SQLInstallDriverEx 不允許 lpszPathOut 成為 NULL（或 cbPathOutMax 為 0）。 如果 fRequest 是ODBC_INSTALL_COMPLETE，當可用的位元元組數目大於或等於 cbPathOutMax 時，就會傳回 FALSE，併產生截斷的結果。

呼叫 SQLInstallDriverEx 並複製驅動程式檔案的應用程式安裝程式之後（如有必要），驅動程式安裝程式 DLL 必須呼叫 SQLConfigDriver 來設定驅動程式的組態。

相關函數

如需下列資訊	請參閱
安裝驅動程式管理員	SQLInstallDriverManager