Función LocalDBGetInstanceInfo

Artigo
07/04/2024

Se aplica a: SQL Server

Devuelve información para la instancia de SQL Server Express LocalDB especificada, por ejemplo si existe, la versión de LocalDB que usa, si se está ejecutando, etc.

La información se devuelve en una estructura denominada LocalDBInstanceInfo, que tiene la siguiente definición.

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;

Archivo de encabezado: msoledbsql.h

Sintaxis

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

Parámetros

wszInstanceName
[Input] Nombre de la instancia.

pInstanceInfo
[Output] Búfer para almacenar información sobre la instancia de LocalDB.

dwInstanceInfoSize
[Entrada] Contiene el tamaño del búfer InstanceInfo .

Devoluciones

S_OK
La función se ha realizado correctamente.

LOCALDB_ERROR_NOT_INSTALLED
SQL Server Express LocalDB no está instalado en el equipo.

LOCALDB_ERROR_INVALID_PARAMETER
Uno o más parámetros de entrada especificados no son válidos.

LOCALDB_ERROR_INVALID_INSTANCE_NAME
El nombre de instancia de especificado no es válido.

LOCALDB_ERROR_UNKNOWN_INSTANCE
La instancia no existe.

LOCALDB_ERROR_INSTANCE_FOLDER_PATH_TOO_LONG
La ruta de acceso donde la instancia debe almacenarse es mayor que MAX_PATH.

LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_FOLDER
No se puede tener acceso a una carpeta de la instancia.

LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_REGISTRY
No se puede tener acceso a un registro de la instancia.

LOCALDB_ERROR_INSTANCE_CONFIGURATION_CORRUPT
Una configuración de instancia está dañada.

LOCALDB_ERROR_INTERNAL_ERROR
Se ha producido un error inesperado. Vea el registro de eventos para obtener detalles.

Detalles

La justificación detrás de la introducción del argumento de tamaño de estructura (lpInstanceInfoSize) es permitir que la API devuelva diferentes versiones de localDBInstanceInfostruct, lo que permite de forma eficaz la compatibilidad con versiones anteriores y hacia delante.

Si el argumento de tamaño de estructura (lpInstanceInfoSize) coincide con el tamaño de una versión conocida de LocalDBInstanceInfostruct, se devuelve esa versión del struct. De lo contrario, se devuelve LOCALDB_ERROR_INVALID_PARAMETER.

Un ejemplo típico del uso de la API localDBGetInstanceInfo tiene este aspecto:

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

Para obtener un ejemplo de código que utilice LocalDB API, vea SQL Server Express LocalDB Reference.

Consulte también

Información de encabezado y versión de SQL Server Express LocalDB

Compartir por