Função MsiGetPropertyA (msiquery.h)

A função MsiGetProperty obtém o valor de uma propriedade do instalador.

Sintaxe

UINT MsiGetPropertyA(
  [in]      MSIHANDLE hInstall,
  [in]      LPCSTR    szName,
  [out]     LPSTR     szValueBuf,
  [in, out] LPDWORD   pcchValueBuf
);

Parâmetros

[in] hInstall

Manipule para a instalação fornecida a uma ação personalizada de DLL ou obtida por meio de MsiOpenPackage, MsiOpenPackageEx ou MsiOpenProduct.

[in] szName

Uma cadeia de caracteres terminada em nulo que especifica o nome da propriedade.

[out] szValueBuf

Ponteiro para o buffer que recebe a cadeia de caracteres terminada em nulo que contém o valor da propriedade . Não tente determinar o tamanho do buffer passando um nulo (value=0) para szValueBuf. Você pode obter o tamanho do buffer passando uma cadeia de caracteres vazia (por exemplo, ""). Em seguida, a função retornará ERROR_MORE_DATA e pchValueBuf conterá o tamanho do buffer necessário em TCHARs, sem incluir o caractere nulo de terminação. No retorno de ERROR_SUCCESS, pcchValueBuf contém o número de TCHARs gravados no buffer, sem incluir o caractere nulo de terminação.

[in, out] pcchValueBuf

Ponteiro para a variável que especifica o tamanho, em TCHARs, do buffer apontado pela variável szValueBuf. Quando a função retorna ERROR_SUCCESS, essa variável contém o tamanho dos dados copiados para szValueBuf, sem incluir o caractere nulo de terminação. Se szValueBuf não for grande o suficiente, a função retornará ERROR_MORE_DATA e armazenará o tamanho necessário, sem incluir o caractere nulo de terminação, na variável apontada por pchValueBuf.

Retornar valor

Essa função retorna UINT.

Comentários

Se o valor da propriedade recuperada pela função MsiGetProperty não estiver definido, ele será equivalente a um valor de 0 comprimento. Não é um erro.

Se ERROR_MORE_DATA for retornado, o parâmetro que é um ponteiro fornecerá o tamanho do buffer necessário para manter a cadeia de caracteres. Se ERROR_SUCCESS for retornado, ele fornecerá o número de caracteres gravados no buffer de cadeia de caracteres. Portanto, você pode obter o tamanho do buffer passando uma cadeia de caracteres vazia (por exemplo, "") para o parâmetro que especifica o buffer. Não tente determinar o tamanho do buffer passando um Null (value=0).

O exemplo a seguir mostra como uma ação personalizada de DLL pode acessar o valor de uma propriedade determinando dinamicamente o tamanho do buffer de valor.

UINT __stdcall MyCustomAction(MSIHANDLE hInstall)
{
    TCHAR* szValueBuf = NULL;
    DWORD cchValueBuf = 0;
    UINT uiStat =  MsiGetProperty(hInstall, TEXT("MyProperty"), TEXT(""), &cchValueBuf);
    //cchValueBuf now contains the size of the property's string, without null termination
    if (ERROR_MORE_DATA == uiStat)
    {
        ++cchValueBuf; // add 1 for null termination
        szValueBuf = new TCHAR[cchValueBuf];
        if (szValueBuf)
        {
            uiStat = MsiGetProperty(hInstall, TEXT("MyProperty"), szValueBuf, &cchValueBuf);
        }
    }
    if (ERROR_SUCCESS != uiStat)
    {
        if (szValueBuf != NULL) 
           delete[] szValueBuf;
        return ERROR_INSTALL_FAILURE;
    }

    // custom action uses MyProperty
    // ...

    delete[] szValueBuf;

    return ERROR_SUCCESS;
}

Observação

O cabeçalho msiquery.h define MsiGetProperty como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Installer 5.0 no Windows Server 2012, no Windows 8, no Windows Server 2008 R2 ou no Windows 7. Windows Installer 4.0 ou Windows Installer 4.5 no Windows Server 2008 ou no Windows Vista. Windows Installer no Windows Server 2003 ou no Windows XP
Plataforma de Destino	Windows
Cabeçalho	msiquery.h
Biblioteca	Msi.lib
DLL	Msi.dll

Confira também

Funções de acesso ao estado do instalador

Passando Null como o argumento das funções do Windows Installer