Função LocalDBGetInstanceInfo

Artigo
07/04/2024

Aplica-se: SQL Server

Retorna informações sobre a instância de LocalDB do SQL Server Express especificada, como se existe ou não, a versão do LocalDB usada, se está sendo executada ou não, e assim por diante.

As informações são retornadas em um struct chamado LocalDBInstanceInfo, que tem a definição a seguir.

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;

Arquivo de cabeçalho: msoledbsql.h

Sintaxe

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

Parâmetros

wszInstanceName
[Entrada] O nome da instância.

pInstanceInfo
[Saída] O buffer para armazenar as informações sobre a instância de LocalDB.

dwInstanceInfoSize
[Entrada] Contém o tamanho do buffer InstanceInfo .

Devoluções

S_OK
A função foi bem-sucedida.

LOCALDB_ERROR_NOT_INSTALLED
O LocalDB do SQL Server Express não está instalado no computador.

LOCALDB_ERROR_INVALID_PARAMETER
Um ou mais parâmetros de entrada especificados são inválidos.

LOCALDB_ERROR_INVALID_INSTANCE_NAME
O nome de instância especificado é inválido.

LOCALDB_ERROR_UNKNOWN_INSTANCE
A instância não existe.

LOCALDB_ERROR_INSTANCE_FOLDER_PATH_TOO_LONG
O caminho em que a instância deve estar armazenada não é maior que MAX_PATH.

LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_FOLDER
Não é possível acessar uma pasta de instância.

LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_REGISTRY
Não é possível acessar um registro de instância.

LOCALDB_ERROR_INSTANCE_CONFIGURATION_CORRUPT
Uma configuração de instância está corrompida.

LOCALDB_ERROR_INTERNAL_ERROR
Erro inesperado. Consulte o log de eventos para obter detalhes.

Detalhes

A lógica por trás da introdução do argumento struct size (lpInstanceInfoSize) é permitir que a API retorne versões diferentes do LocalDBInstanceInfostruct, habilitando efetivamente a compatibilidade com versões anteriores e posteriores.

Se o argumento de tamanho de struct (lpInstanceInfoSize) corresponder ao tamanho de uma versão conhecida do LocalDBInstanceInfostruct, essa versão do struct será retornada. Caso contrário, LOCALDB_ERROR_INVALID_PARAMETER será retornado.

Um exemplo típico de uso da API LocalDBGetInstanceInfo é semelhante a este:

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

Para obter uma amostra do código que usa a API LocalDB, consulte SQL Server Express LocalDB Reference.

Confira também

Cabeçalho e informações de versão de LocalDB do SQL Server Express

Partilhar via