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.
[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.
[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 |
|---|---|
|
Si l’étendue inclut des utilisateurs autres que l’utilisateur actuel, vous avez besoin de privilèges d’administrateur. |
|
Les données de configuration sont endommagées. |
|
Un paramètre non valide a été transmis à la fonction. |
|
Il n’y a plus de produits à énumérer. |
|
Un produit est énuméré. |
|
Le paramètre szSid est trop petit pour obtenir le SID utilisateur. |
|
Le produit n’est pas installé sur l’ordinateur dans le contexte spécifié. |
|
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 |