Partilhar via

LocalDBGetInstanceInfo function

Applies to:SQL Server

Retorna informações para a instância do SQL Server Express LocalDB especificada, como se ela existe, a versão do LocalDB que usa, se está em execução e assim por diante.

As informações são retornadas em um struct nome LocalDBInstanceInfo, que 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;

Header file:msoledbsql.h

Syntax

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

Arguments

wszInstanceName

[Entrada] O nome da instância.

pInstanceInfo

[Realização] O buffer para armazenar as informações sobre a instância LocalDB.

dwInstanceInfoSize

[Input] Holds the size of the InstanceInfo buffer.

Returns

S_OK: A função foi bem-sucedida.

Error Description
LOCALDB_ERROR_NOT_INSTALLED O SQL Server Express LocalDB 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 da instância especificado é inválido.
LOCALDB_ERROR_UNKNOWN_INSTANCE A instância não existe.
LOCALDB_ERROR_INSTANCE_FOLDER_PATH_TOO_LONG O caminho onde a instância deve ser armazenada é maior que MAX_PATH.
LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_FOLDER Uma pasta de instância não pode ser acessada.
LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_REGISTRY Um registro de instância não pode ser acessado.
LOCALDB_ERROR_INSTANCE_CONFIGURATION_CORRUPT Uma configuração de instância está corrompida.
LOCALDB_ERROR_INTERNAL_ERROR Ocorreu um erro inesperado. Consulte o log de eventos para obter detalhes.

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. Caso contrário, LOCALDB_ERROR_INVALID_PARAMETER é retornado.

Um exemplo típico de uso da LocalDBGetInstanceInfo API tem esta aparência:

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

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

Related content

  • Last updated on