Partager via


MsiEnumProductsExA, fonction (msi.h)

La fonction MsiEnumProductsEx énumère une ou toutes les instances de produits actuellement publiés ou installés dans les contextes spécifiés. Cette fonction remplace MsiEnumProducts.

Syntaxe

UINT MsiEnumProductsExA(
  [in, optional]      LPCSTR            szProductCode,
  [in]                LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwIndex,
  [out, optional]     CHAR [39]         szInstalledProductCode,
  [out, optional]     MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional]     LPSTR             szSid,
  [in, out, optional] LPDWORD           pcchSid
);

Paramètres

[in, optional] szProductCode

ProductCode GUID du produit à énumérer. Seules les instances de produits dans l’étendue du contexte spécifié par les paramètres szUserSid et dwContext sont énumérées. Ce paramètre peut être défini sur NULL pour énumérer tous les produits dans le contexte spécifié.

[in] szUserSid

Chaîne terminée par null qui spécifie un identificateur de sécurité (SID) qui restreint le contexte d’énumération. La chaîne SID spéciale s-1-1-0 (Tout le monde) spécifie l’énumération entre tous les utilisateurs du système. Une valeur SID autre que s-1-1-0 est considérée comme un SID utilisateur et limite l’énumération à l’utilisateur actuel ou à tout utilisateur du système. Ce paramètre peut être défini sur NULL pour limiter l’étendue de l’énumération à l’utilisateur actuel.

Type SID Signification
NULL
Spécifie l’utilisateur actuellement connecté.
SID de l’utilisateur
Spécifie l’énumération d’un utilisateur particulier dans le système. Un exemple de SID utilisateur est « S-1-3-64-2415071341-1358098788-3127455600-2561 ».
s-1-1-0
Spécifie l’énumération pour tous les utilisateurs du système.
 
Note La chaîne SID spéciale s-1-5-18 (Système) ne peut pas être utilisée pour énumérer les produits ou les correctifs installés en tant que machine. Lorsque dwContext est défini sur MSIINSTALLCONTEXT_MACHINE uniquement, szUserSid doit avoir la valeur NULL.
 

[in] dwContext

Limite l’énumération à un contexte. Ce paramètre peut être une ou une combinaison des valeurs indiquées dans le tableau suivant.

Context Signification
MSIINSTALLCONTEXT_USERMANAGED
Énumération étendue à toutes les installations gérées par utilisateur pour les utilisateurs spécifiés par szUserSid. Un SID non valide ne retourne aucun élément.
MSIINSTALLCONTEXT_USERUNMANAGED
Énumération étendue à toutes les installations non managées par utilisateur pour les utilisateurs spécifiés par szUserSid. Un SID non valide ne retourne aucun élément.
MSIINSTALLCONTEXT_MACHINE
Énumération étendue à toutes les installations par ordinateur. Lorsque dwInstallContext a la valeur MSIINSTALLCONTEXT_MACHINE uniquement, le paramètre szUserSID doit avoir la valeur NULL.

[in] dwIndex

Spécifie l’index du produit à récupérer. Ce paramètre doit être égal à zéro pour le premier appel à la fonction MsiEnumProductsEx , puis incrémenté pour les appels suivants. L’index doit être incrémenté uniquement si l’appel précédent a retourné ERROR_SUCCESS. Étant donné que les produits ne sont pas commandés, tout nouveau produit a un index arbitraire. Cela signifie que la fonction peut retourner des produits dans n’importe quel ordre.

[out, optional] szInstalledProductCode

Chaîne null de TCHAR qui donne le GUID ProductCode du produit instance énuméré. Ce paramètre peut être NULL.

[out, optional] pdwInstalledContext

Retourne le contexte du produit instance énuméré. La valeur de sortie peut être MSIINSTALLCONTEXT_USERMANAGED, MSIINSTALLCONTEXT_USERUNMANAGED ou MSIINSTALLCONTEXT_MACHINE. Ce paramètre peut être NULL.

[out, optional] szSid

Mémoire tampon de sortie qui reçoit le SID de chaîne du compte sous lequel ce produit instance existe. Cette mémoire tampon retourne une chaîne vide pour un instance installé dans un contexte par machine.

Cette mémoire tampon doit être suffisamment grande pour contenir le SID. Si la mémoire tampon est trop petite, la fonction retourne ERROR_MORE_DATA et définit *pcchSid sur le nombre de TCHAR dans le SID, sans inclure le caractère NULL de fin.

Si szSid a la valeur NULL et que pcchSid est défini sur un pointeur valide, la fonction retourne ERROR_SUCCESS et définit *pcchSid sur le nombre de TCHAR dans la valeur, sans inclure la valeur NULL de fin. La fonction peut ensuite être appelée à nouveau pour récupérer la valeur, avec la mémoire tampon szSid suffisamment grande pour contenir *pcchSid + 1 caractères.

Si szSid et pcchSid sont tous deux définis sur NULL, la fonction retourne ERROR_SUCCESS si la valeur existe, sans récupérer la valeur.

[in, out, optional] pcchSid

Lors de l’appel de la fonction, ce paramètre doit être un pointeur vers une variable qui spécifie le nombre de TCHAR dans la mémoire tampon szSid . Lorsque la fonction retourne, ce paramètre est défini sur la taille de la valeur demandée, que la fonction copie ou non la valeur dans la mémoire tampon spécifiée. La taille est retournée sous la forme du nombre de TCHAR dans la valeur demandée, sans inclure le caractère null de fin.

Ce paramètre ne peut être défini sur NULL que si szSid a également la valeur NULL, sinon la fonction retourne ERROR_INVALID_PARAMETER.

Valeur retournée

La fonction MsiEnumProductsEx retourne l’une des valeurs suivantes.

Code de retour Description
ERROR_ACCESS_DENIED
Si l’étendue inclut des utilisateurs autres que l’utilisateur actuel, vous avez besoin de privilèges d’administrateur.
ERROR_BAD_CONFIGURATION
Les données de configuration sont endommagées.
ERROR_INVALID_PARAMETER
Un paramètre non valide a été transmis à la fonction.
ERROR_NO_MORE_ITEMS
Il n’y a plus de produits à énumérer.
ERROR_SUCCESS
Un produit est énuméré.
ERROR_MORE_DATA
Le paramètre szSid est trop petit pour obtenir le SID utilisateur.
ERROR_UNKNOWN_PRODUCT
Le produit n’est pas installé sur l’ordinateur dans le contexte spécifié.
ERROR_FUNCTION_FAILED
Défaillance interne inattendue.

Remarques

Pour énumérer des produits, une application doit initialement appeler la fonction MsiEnumProductsEx avec le paramètre iIndex défini sur zéro. L’application doit ensuite incrémenter le paramètre iProductIndex et appeler MsiEnumProductsEx jusqu’à ce qu’elle retourne ERROR_NO_MORE_ITEMS et qu’il n’y ait plus de produits à énumérer.

Lorsque vous effectuez plusieurs appels à MsiEnumProductsEx pour énumérer tous les produits, chaque appel doit être effectué à partir du même thread.

Un utilisateur doit disposer de privilèges d’administrateur pour énumérer les produits dans tous les comptes d’utilisateur ou un compte d’utilisateur autre que le compte d’utilisateur actuel. L’énumération ignore les produits qui sont publiés uniquement (tels que les produits non installés) dans le contexte non managé par utilisateur lors de l’énumération entre tous les utilisateurs ou un utilisateur autre que l’utilisateur actuel.

Utilisez MsiGetProductInfoEx pour obtenir l’état ou d’autres informations sur chaque produit instance énumérés par MsiEnumProductsEx.

Notes

L’en-tête msi.h définit MsiEnumProductsEx comme 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 3.0 ou version ultérieure sur Windows Server 2003 ou Windows XP. Pour plus d’informations sur le Service Pack Windows requis par une version de Windows Installer, consultez Configuration requise pour le runtime Windows.
Plateforme cible Windows
En-tête msi.h
Bibliothèque Msi.lib
DLL Msi.dll

Voir aussi

MsiEnumProducts

Non pris en charge par Windows Installer 2.0 et antérieur

ProductCode

Suppression des correctifs