MsiGetPropertyA-Funktion (msiquery.h)

Artikel
03/13/2024

Die MsiGetProperty-Funktion ruft den Wert für eine Installereigenschaft ab.

Syntax

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

Parameter

[in] hInstall

Behandeln Sie die Installation, die für eine benutzerdefinierte DLL-Aktion bereitgestellt oder über MsiOpenPackage, MsiOpenPackageEx oder MsiOpenProduct abgerufen wird.

[in] szName

Eine NULL-endende Zeichenfolge, die den Namen der Eigenschaft angibt.

[out] szValueBuf

Zeiger auf den Puffer, der die Zeichenfolge mit NULL-Beendigung empfängt, die den Wert der -Eigenschaft enthält. Versuchen Sie nicht, die Größe des Puffers zu bestimmen, indem Sie null (value=0) für szValueBuf übergeben. Sie können die Größe des Puffers abrufen, indem Sie eine leere Zeichenfolge übergeben (z. B. ""). Die Funktion gibt dann ERROR_MORE_DATA zurück, und pchValueBuf enthält die erforderliche Puffergröße in TCHARs, ohne das abschließende NULL-Zeichen. Bei Rückgabe von ERROR_SUCCESS enthält pcchValueBuf die Anzahl der TCHARs, die in den Puffer geschrieben wurden, ohne das abschließende NULL-Zeichen.

[in, out] pcchValueBuf

Zeiger auf die Variable, die in TCHARs die Größe des Puffers angibt, auf den die Variable szValueBuf verweist. Wenn die Funktion ERROR_SUCCESS zurückgibt, enthält diese Variable die Größe der in szValueBuf kopierten Daten, ohne das abschließende NULL-Zeichen. Wenn szValueBuf nicht groß genug ist, gibt die Funktion ERROR_MORE_DATA zurück und speichert die erforderliche Größe (ohne das abschließende NULL-Zeichen) in der Variablen, auf die von pchValueBuf verwiesen wird.

Rückgabewert

Diese Funktion gibt UINT zurück.

Hinweise

Wenn der Wert für die Eigenschaft, die von der MsiGetProperty-Funktion abgerufen wird, nicht definiert ist, entspricht er einem Wert der Länge 0. Es handelt sich nicht um einen Fehler.

Wenn ERROR_MORE_DATA zurückgegeben wird, gibt der Parameter, bei dem es sich um einen Zeiger handelt, die Größe des Puffers an, der zum Halten der Zeichenfolge erforderlich ist. Wenn ERROR_SUCCESS zurückgegeben wird, wird die Anzahl der In den Zeichenfolgenpuffer geschriebenen Zeichen angegeben. Daher können Sie die Größe des Puffers abrufen, indem Sie eine leere Zeichenfolge (z. B. "") für den Parameter übergeben, der den Puffer angibt. Versuchen Sie nicht, die Größe des Puffers zu bestimmen, indem Sie einen Nullwert (wert=0) übergeben.

Das folgende Beispiel zeigt, wie eine benutzerdefinierte DLL-Aktion auf den Wert einer Eigenschaft zugreifen kann, indem die Größe des Wertpuffers dynamisch bestimmt wird.

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;
}

Hinweis

Der msiquery.h-Header definiert MsiGetProperty als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Installer 5.0 unter Windows Server 2012, Windows 8, Windows Server 2008 R2 oder Windows 7. Windows Installer 4.0 oder Windows Installer 4.5 unter Windows Server 2008 oder Windows Vista. Windows Installer unter Windows Server 2003 oder Windows XP
Zielplattform	Windows
Kopfzeile	msiquery.h
Bibliothek	Msi.lib
DLL	Msi.dll

Weitere Informationen

Installerstatuszugriffsfunktionen

Übergeben von NULL als Argument von Windows Installer Functions

Freigeben über