MsiGetPropertyA, fonction (msiquery.h)

Article
02/29/2024

La fonction MsiGetProperty obtient la valeur d’une propriété de programme d’installation.

Syntaxe

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

Paramètres

[in] hInstall

Gérez l’installation fournie à une action personnalisée DLL ou obtenue via MsiOpenPackage, MsiOpenPackageEx ou MsiOpenProduct.

[in] szName

Chaîne terminée par null qui spécifie le nom de la propriété.

[out] szValueBuf

Pointeur vers la mémoire tampon qui reçoit la chaîne null terminée contenant la valeur de la propriété . N’essayez pas de déterminer la taille de la mémoire tampon en transmettant une valeur null (valeur=0) pour szValueBuf. Vous pouvez obtenir la taille de la mémoire tampon en transmettant une chaîne vide (par exemple « »). La fonction retourne ensuite ERROR_MORE_DATA et pchValueBuf contient la taille de mémoire tampon requise dans les TCHAR, sans inclure le caractère null de fin. Au retour de ERROR_SUCCESS, pcchValueBuf contient le nombre de TCHAR écrits dans la mémoire tampon, sans inclure le caractère null de fin.

[in, out] pcchValueBuf

Pointeur vers la variable qui spécifie la taille, en TCHAR, de la mémoire tampon pointée par la variable szValueBuf. Lorsque la fonction retourne ERROR_SUCCESS, cette variable contient la taille des données copiées dans szValueBuf, sans inclure le caractère null de fin. Si szValueBuf n’est pas assez grand, la fonction retourne ERROR_MORE_DATA et stocke la taille requise, sans inclure le caractère null de fin, dans la variable pointée par pchValueBuf.

Valeur retournée

Cette fonction retourne UINT.

Remarques

Si la valeur de la propriété récupérée par la fonction MsiGetProperty n’est pas définie, elle équivaut à une valeur de longueur 0. Il ne s’agit pas d’une erreur.

Si ERROR_MORE_DATA est retourné, le paramètre qui est un pointeur donne la taille de la mémoire tampon requise pour contenir la chaîne. Si ERROR_SUCCESS est retourné, il indique le nombre de caractères écrits dans la mémoire tampon de chaîne. Par conséquent, vous pouvez obtenir la taille de la mémoire tampon en transmettant une chaîne vide (par exemple « ») pour le paramètre qui spécifie la mémoire tampon. N’essayez pas de déterminer la taille de la mémoire tampon en transmettant une valeur Null (valeur=0).

L’exemple suivant montre comment une action personnalisée DLL peut accéder à la valeur d’une propriété en déterminant dynamiquement la taille de la mémoire tampon de valeur.

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

Notes

L’en-tête msiquery.h définit MsiGetProperty comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Installer 5.0 sur Windows Server 2012, Windows 8, Windows Server 2008 R2 ou Windows 7. Windows Installer 4.0 ou Windows Installer 4.5 sur Windows Server 2008 ou Windows Vista. Windows Installer sur Windows Server 2003 ou Windows XP
Plateforme cible	Windows
En-tête	msiquery.h
Bibliothèque	Msi.lib
DLL	Msi.dll

Voir aussi

Fonctions d’accès à l’état du programme d’installation

Passage de la valeur Null en tant qu’argument des fonctions Windows Installer

Partager via