LocalDBGetInstanceInfo 関数

指定した SQL Server Express LocalDB インスタンスの情報を返します。たとえば、存在するかどうか、使用する LocalDB バージョン、実行中かどうかなどです。

この情報は、LocalDBInstanceInfo という名前の struct で返されます。これには次の定義があります。

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;

ヘッダー ファイル: sqlncli.h

構文

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

パラメーター

• wszInstanceName
  [入力] インスタンス名。

• pInstanceInfo
  [出力] LocalDB インスタンスについての情報を格納するバッファー。

• dwInstanceInfoSize
  [入力] InstanceInfo バッファーのサイズを保持します。

戻り値

• S_OK
  関数が正常に実行されました。

• LOCALDB_ERROR_NOT_INSTALLED
  SQL Server Express LocalDB は、コンピューターにインストールされていません。

• LOCALDB_ERROR_INVALID_PARAMETER
  指定した 1 つまたは複数の入力パラメーターが無効です。

• LOCALDB_ERROR_INVALID_INSTANCE_NAME
  指定したインスタンス名は無効です。

• LOCALDB_ERROR_UNKNOWN_INSTANCE
  インスタンスは存在しません。

• LOCALDB_ERROR_INSTANCE_FOLDER_PATH_TOO_LONG
  インスタンスを格納するパスの長さが MAX_PATH を超過しています。

• LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_FOLDER
  インスタンス フォルダーにアクセスできません。

• LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_REGISTRY
  インスタンス レジストリにアクセスできません。

• LOCALDB_ERROR_INSTANCE_CONFIGURATION_CORRUPT
  インスタンス構成が破損しています。

• LOCALDB_ERROR_INTERNAL_ERROR
  予期しないエラーが発生しました。 詳細をイベント ログで確認してください。

詳細

struct サイズ引数 (lpInstanceInfoSize) を導入した理論的根拠は、API がさまざまなバージョンの LocalDBInstanceInfo struct を返せるようにすることで、上位互換性と下位互換性を効率的に有効化するためです。

struct サイズ引数 (lpInstanceInfoSize) が、既知のバージョンの LocalDBInstanceInfo struct のサイズに一致する場合、そのバージョンの struct が返されます。 それ以外の場合、LOCALDB_ERROR_INVALID_PARAMETER が返されます。

LocalDBGetInstanceInfo API の一般的な使用例は、次のようになります。

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

LocalDB API を使用するコード例については、「SQL Server Express LocalDB リファレンス」を参照してください。

関連項目

概念

SQL Server Express LocalDB ヘッダーとバージョン情報