ConfigDriver-Funktion

Artikel
05/23/2023

Konformität
Version eingeführt: ODBC 2.5

Zusammenfassung
ConfigDriver ermöglicht es einem Setupprogramm, Installations- und Deinstallationsfunktionen auszuführen, ohne dass das Programm ConfigDSN aufrufen muss. Diese Funktion führt treiberspezifische Funktionen aus, z. B. das Erstellen treiberspezifischer Systeminformationen und die Ausführung von DSN-Konvertierungen während der Installation sowie das Bereinigen von Änderungen an Systeminformationen während der Deinstallation. Diese Funktion wird von der Setup-DLL des Treibers oder einer separaten Setup-DLL verfügbar gemacht.

Syntax

  
BOOL ConfigDriver(  
      HWND    hwndParent,  
      WORD    fRequest,  
      LPCSTR  lpszDriver,  
      LPCSTR  lpszArgs,  
      LPSTR   lpszMsg,  
      WORD    cbMsgMax,  
      WORD *  pcbMsgOut);

Argumente

hwndParent
[Eingabe] Übergeordnetes Fensterhandle. Die Funktion zeigt keine Dialogfelder an, wenn das Handle NULL ist.

fRequest
[Eingabe] Anforderungstyp. Das Argument fRequest muss einen der folgenden Werte enthalten:

ODBC_INSTALL_DRIVER: Installieren Sie einen neuen Treiber.

ODBC_REMOVE_DRIVER: Entfernen Sie einen Treiber.

Diese Option kann auch treiberspezifisch sein. In diesem Fall muss das fRequest-Argument für die erste Option mit ODBC_CONFIG_DRIVER_MAX+1 beginnen. Das fRequest-Argument für jede zusätzliche Option muss auch mit einem Wert beginnen, der größer als ODBC_CONFIG_DRIVER_MAX+1 ist.

lpszDriver
[Eingabe] Der Name des Treibers, der im Odbcinst.ini Schlüssel der Systeminformationen registriert ist.

lpszArgs
[Eingabe] Eine NULL-beendete Zeichenfolge, die Argumente für eine treiberspezifische fRequest enthält.

lpszMsg
[Ausgabe] Eine NULL-beendete Zeichenfolge, die eine Ausgabemeldung vom Treibersetup enthält.

cbMsgMax
[Eingabe] Länge von lpszMsg.

pcbMsgOut
[Ausgabe] Gesamtanzahl der Bytes, die in lpszMsg zurückgegeben werden können.

Wenn die Anzahl der zurückzugebenden Bytes größer oder gleich cbMsgMax ist, wird die Ausgabenachricht in lpszMsg in cbMsgMax abgeschnitten, abzüglich des NULL-Terminzeichens. Das pcbMsgOut-Argument kann ein NULL-Zeiger sein.

Gibt zurück

Die Funktion gibt TRUE zurück, wenn sie erfolgreich ist, FALSE, wenn sie fehlschlägt.

Diagnose

Wenn ConfigDriver FALSE zurückgibt, wird ein zugeordneter *pfErrorCode-Wert durch einen Aufruf von SQLPostInstallerError an den Installerfehlerpuffer gesendet und kann durch Aufrufen von SQLInstallerError abgerufen werden. In der folgenden Tabelle sind die *pfErrorCode-Werte aufgeführt, die von SQLInstallerError zurückgegeben werden können, und die einzelnen Werte im Kontext dieser Funktion werden erläutert.

*pfErrorCode	Fehler	BESCHREIBUNG
ODBC_ERROR_INVALID_HWND	Ungültiges Fensterhandle	Das Argument hwndParent war ungültig.
ODBC_ERROR_INVALID_REQUEST_TYPE	Ungültiger Anforderungstyp	Das fRequest-Argument war nicht eines der folgenden: ODBC_INSTALL_DRIVER ODBC_REMOVE_DRIVER Die treiberspezifische Option war kleiner oder gleich ODBC_CONFIG_DRIVER_MAX.
ODBC_ERROR_INVALID_NAME	Ungültiger Treiber- oder Übersetzername	Das argument lpszDriver war ungültig. Es konnte nicht in der Registrierung gefunden werden.
ODBC_ERROR_REQUEST_FAILED	Fehler bei der Anforderung	Der vom Argument fRequest angeforderte Vorgang konnte nicht ausgeführt werden.
ODBC_ERROR_DRIVER_SPECIFIC	Treiber- oder Übersetzer-spezifischer Fehler	Ein treiberspezifischer Fehler, für den kein definierter ODBC-Installerfehler vorliegt. Das SzError-Argument in einem Aufruf der SQLPostInstallerError-Funktion sollte die treiberspezifische Fehlermeldung enthalten.

Kommentare

Driver-Specific Optionen

Eine Anwendung kann treiberspezifische Features anfordern, die vom Treiber mit dem Argument fRequest verfügbar gemacht werden. Die fRequest für die erste Option ist ODBC_CONFIG_DRIVER_MAX plus 1, und zusätzliche Optionen werden von diesem Wert um 1 erhöht. Alle argumente, die vom Treiber für diese Funktion benötigt werden, sollten in einer null-beendeten Zeichenfolge angegeben werden, die im argument lpszArgs übergeben wird. Treiber, die diese Funktionalität bereitstellen, sollten eine Tabelle mit treiberspezifischen Optionen beibehalten. Die Optionen sollten vollständig in der Treiberdokumentation dokumentiert werden. Anwendungsautoren, die treiberspezifische Optionen verwenden, sollten sich bewusst sein, dass die Anwendung dadurch weniger interoperabel wird.

Meldungen

Eine Treibersetuproutine kann eine SMS als null-beendete Zeichenfolge im lpszMsg-Puffer an eine Anwendung senden. Die Nachricht wird von der ConfigDriver-Funktion in cbMsgMax abgeschnitten, abzüglich des Null-Terminierungszeichens, wenn sie größer oder gleich cbMsgMax-Zeichen ist.

Freigeben über