LocalDBGetInstanceInfo-Funktion

Gibt Informationen für die angegebene SQL Server Express LocalDB-Instanz zurück (beispielsweise, ob sie vorhanden ist, die verwendete LocalDB-Version, ob sie ausgeführt wird usw.).

Die Informationen werden in einem struct mit der Bezeichnung LocalDBInstanceInfo und folgender Definition zurückgegeben.

typedef struct _LocalDBInstanceInfo
{
      // Contains the size of the LocalDBInstanceInfo struct
      DWORD  cbLocalDBInstanceInfoSize;

      // Holds the instance name
      TLocalDBInstanceNamewszInstanceName;

      // TRUE if the instance files exist on disk, FALSE otherwise
      BOOL   bExists;

      // TRUE if the instance configuration registry is corrupted, FALSE otherwise
      BOOLbConfigurationCorrupted;

      // TRUE if the instance is running at the moment, FALSE otherwise
      BOOL   bIsRunning;

      // Holds the LocalDB version for the instance in the format: major.minor.build.revision
      DWORD  dwMajor;
      DWORD  dwMinor;
      DWORD  dwBuild;
      DWORD  dwRevision;

      // Holds the date and time when the instance was started for the last time
      FILETIME ftLastStartUTC;

      // Holds the name of the TDS named pipe to connect to the instance
      WCHARwszConnection;

      // TRUE if the instance is shared, FALSE otherwise
      BOOLbIsShared;

      // Holds the shared name for the instance (if the instance is shared)
      TLocalDBInstanceNamewszSharedInstanceName;

      // Holds the SID of the instance owner (if the instance is shared)
      WCHARwszOwnerSID; 

      // TRUE if the instance is Automatic, FALSE otherwise
      BOOLbIsAutomatic;
} LocalDBInstanceInfo;

Headerdatei: sqlncli.h

Syntax

HRESULT LocalDBGetInstanceInfo(
           PCWSTR wszInstanceName,
           PLocalDBInstanceInfo pInstanceInfo,
           DWORD dwInstanceInfoSize 
);

Parameter

• wszInstanceName
  [Eingabe] Der Name der Instanz.

• pInstanceInfo
  [Ausgabe] Der Puffer zum Speichern der Informationen zur LocalDB-Instanz.

• dwInstanceInfoSize
  [Eingabe] Enthält die Größe des InstanceInfo-Puffers.

Rückgabewerte

• S_OK
  Die Funktion wurde erfolgreich ausgeführt.

• LOCALDB_ERROR_NOT_INSTALLED
  SQL Server Express LocalDB ist nicht auf dem Computer installiert.

• LOCALDB_ERROR_INVALID_PARAMETER
  Mindestens ein angegebener Eingabeparameter ist ungültig.

• LOCALDB_ERROR_INVALID_INSTANCE_NAME
  Der angegebene Instanzname ist ungültig.

• LOCALDB_ERROR_UNKNOWN_INSTANCE
  Die Instanz ist nicht vorhanden.

• LOCALDB_ERROR_INSTANCE_FOLDER_PATH_TOO_LONG
  Der Pfad, unter dem die Instanz gespeichert werden soll, ist länger als MAX_PATH.

• LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_FOLDER
  Auf einen Instanzordner kann nicht zugegriffen werden.

• LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_REGISTRY
  Auf eine Instanzregistrierung kann nicht zugegriffen werden.

• LOCALDB_ERROR_INSTANCE_CONFIGURATION_CORRUPT
  Eine Instanzkonfiguration ist beschädigt.

• LOCALDB_ERROR_INTERNAL_ERROR
  Ein unerwarteter Fehler ist aufgetreten. Weitere Informationen finden Sie im Ereignisprotokoll.

Details

Der Grund für die Einführung in des struct-Größenarguments (lpInstanceInfoSize) ist der API zu ermöglichen, verschiedene Versionen von LocalDBInstanceInfo struct zurückzugeben und Aufwärts- und Abwärtskompatibilität effektiv zu unterstützen.

Falls das struct-Größenargument (lpInstanceInfoSize) mit der Größe einer bekannten Version von LocalDBInstanceInfo struct übereinstimmt, wird diese Version von struct zurückgegeben. Andernfalls wird LOCALDB_ERROR_INVALID_PARAMETER zurückgegeben.

Beispiele für die Verwendung der LocalDBGetInstanceInfo-API sehen meist wie folgt aus:

LocalDBInstanceInfo ii;
LocalDBInstanceInfo(L”Test”, &ii, sizeof(LocalDBInstanceInfo));

Ein Codebeispiel, in dem die LocalDB-API verwendet wird, finden Sie unter SQL Server Express LocalDB-Verweis.

Siehe auch

Konzepte

SQL Server Express LocalDB-Header und Versionsinformationen