LocalDBGetInstanceInfo Function

Applies to: SQL Server

Returns information for the specified SQL Server Express LocalDB instance, such as whether it exists, the LocalDB version it uses, whether it is running, and so on.

The information is returned in a struct named LocalDBInstanceInfo, which has the following definition.

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;  
  

Header file: msoledbsql.h

Syntax

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

Parameters

wszInstanceName
[Input] The instance name.

pInstanceInfo
[Output] The buffer to store the information about the LocalDB instance.

dwInstanceInfoSize
[Input] Holds the size of the InstanceInfo buffer.

Returns

S_OK
The function succeeded.

LOCALDB_ERROR_NOT_INSTALLED
SQL Server Express LocalDB is not installed on the computer.

LOCALDB_ERROR_INVALID_PARAMETER
One or more specified input parameters are invalid.

LOCALDB_ERROR_INVALID_INSTANCE_NAME
The specified instance name is invalid.

LOCALDB_ERROR_UNKNOWN_INSTANCE
The instance does not exist.

LOCALDB_ERROR_INSTANCE_FOLDER_PATH_TOO_LONG
The path where the instance should be stored is longer than MAX_PATH.

LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_FOLDER
An instance folder cannot be accessed.

LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_REGISTRY
An instance registry cannot be accessed.

LOCALDB_ERROR_INSTANCE_CONFIGURATION_CORRUPT
An instance configuration is corrupted.

LOCALDB_ERROR_INTERNAL_ERROR
An unexpected error occurred. See the event log for details.

Details

The rationale behind the introduction of the struct size argument (lpInstanceInfoSize) is to enable the API to return different versions of the LocalDBInstanceInfostruct, effectively enabling forward and backward compatibility.

If the struct size argument (lpInstanceInfoSize) matches the size of a known version of the LocalDBInstanceInfostruct, that version of the struct is returned. Otherwise, LOCALDB_ERROR_INVALID_PARAMETER is returned.

A typical example of LocalDBGetInstanceInfo API usage looks like this:

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

For a code sample that uses LocalDB API, see SQL Server Express LocalDB Reference.

See Also

SQL Server Express LocalDB Header and Version Information