Função LocalDBGetInstanceInfo

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 nomeado LocalDBInstanceInfoque tem a seguinte definição.

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: sqlncli.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] Mantém tamanho do buffer InstanceInfo.

Retorna

• 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 razão por trás da introdução do argumento de tamanho struct (lpInstanceInfoSize) é permitir que a API retorne versões diferentes do LocalDBInstanceInfo struct, habilitando compatibilidade com versões anteriores e posteriores.

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

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

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

Para obter uma amostra do código que usa a API LocalDB, consulte Referência de LocalDB do SQL Server Express.

Consulte também

Conceitos

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