Función MsiEnumClientsExA (msi.h)

Artículo
11/20/2024

La función msiEnumClientsEx enumera las aplicaciones instaladas que usan un componente especificado. La función recupera un código de producto para una aplicación cada vez que se llama a ella.

Windows Installer 4.5 o versiones anteriores: no se admite . Esta función está disponible a partir de Windows Installer 5.0.

Sintaxis

UINT MsiEnumClientsExA(
  [in]                LPCSTR            szComponent,
  [in, optional]      LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwProductIndex,
  [out, optional]     CHAR [39]         szProductBuf,
  [out, optional]     MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional]     LPSTR             szSid,
  [in, out, optional] LPDWORD           pcchSid
);

Parámetros

[in] szComponent

GUID de código de componente que identifica el componente. La función enumera las aplicaciones que usan este componente.

[in, optional] szUserSid

Valor de cadena terminada en null que contiene un identificador de seguridad (SID). La enumeración de aplicaciones se extiende a los usuarios identificados por este SID. La cadena de SID especial s-1-1-0 (Todos) enumera todas las aplicaciones para todos los usuarios del sistema. Un valor de SID distinto de s-1-1-0 especifica un SID de usuario para un usuario determinado y enumera las instancias de las aplicaciones instaladas por el usuario especificado.

Tipo de SID	Significado
NULL	Especifica el usuario que ha iniciado sesión actualmente.
siD de usuario de	Especifica una enumeración para un usuario determinado. Un ejemplo de SID de usuario es "S-1-3-64-2415071341-1358098788-3127455600-2561".
s-1-1-0	Especifica una enumeración para todos los usuarios del sistema.

Nota La cadena de SID especial s-1-5-18 (Sistema) no se puede usar para enumerar las aplicaciones que existen en el contexto de instalación por máquina. Si se establece el valor de SID en s-1-5-18, se devuelve ERROR_INVALID_PARAMETER. Cuando dwContext solo se establece en MSIINSTALLCONTEXT_MACHINE, el valor de szUserSid debe ser NULL.

[in] dwContext

Marca que extiende la enumeración a instancias de aplicaciones instaladas en el contexto de instalación especificado. La enumeración solo incluye instancias de aplicaciones instaladas por los usuarios identificados por szUserSid.

Puede ser una combinación de los siguientes valores.

Contexto	Significado
MSIINSTALLCONTEXT_USERMANAGED 1	Incluya las aplicaciones instaladas en el contexto de instalación administrado por usuario.
MSIINSTALLCONTEXT_USERUNMANAGED 2	Incluya las aplicaciones instaladas en el contexto de instalación por usuario y no administrado.
MSIINSTALLCONTEXT_MACHINE 4	Incluya las aplicaciones instaladas en el contexto de instalación por máquina. Cuando dwInstallContext solo se establece en MSIINSTALLCONTEXT_MACHINE, el valor del parámetro szUserSID debe ser NULL.

[in] dwProductIndex

Especifica el índice de la aplicación que se va a recuperar. El valor de este parámetro debe ser cero (0) en la primera llamada a la función. Para cada llamada posterior, el índice debe incrementarse en 1. El índice solo debe incrementarse si la llamada anterior a la función devuelve ERROR_SUCCESS.

[out, optional] szProductBuf

Valor de cadena que recibe el código de producto de la aplicación. La longitud del búfer en esta ubicación debe ser lo suficientemente grande como para contener un valor de cadena terminada en NULL que contenga el código del producto. Los primeros 38 caracteres TCHAR reciben el GUID del componente y el carácter 39 recibe un carácter NULL de terminación.

[out, optional] pdwInstalledContext

Marca que proporciona el contexto de instalación de la aplicación.

Puede ser una combinación de los siguientes valores.

Contexto	Significado
MSIINSTALLCONTEXT_USERMANAGED 1	La aplicación se instala en el contexto de instalación administrado por usuario.
MSIINSTALLCONTEXT_USERUNMANAGED 2	La aplicación se instala en el contexto de instalación por usuario y no administrado.
MSIINSTALLCONTEXT_MACHINE 4	La aplicación se encuentra en el contexto de instalación por máquina.

[out, optional] szSid

Recibe el identificador de seguridad (SID) que identifica al usuario que instaló la aplicación. La ubicación recibe un valor de cadena vacío si esta instancia de la aplicación existe en un contexto de instalación por máquina.

La longitud del búfer debe ser lo suficientemente grande como para contener un valor de cadena terminada en NULL que contenga el SID. Si el búfer es demasiado pequeño, la función devuelve ERROR_MORE_DATA y la ubicación a la que apunta pcchSid recibe el número de TCHAR en el SID, no incluido el carácter NULL de terminación.

Si szSid se establece en NULL y pcchSid es un puntero válido a una ubicación en memoria, la función devuelve ERROR_SUCCESS y la ubicación recibe el número de TCHAR en el SID, no incluido el carácter nulo de terminación. A continuación, se puede llamar a la función de nuevo para recuperar el valor, con el búfer de szSid tamaño lo suficientemente grande como para contener *pcchSid + 1 caracteres.

Tipo de SID	Significado
Cadena vacía	La aplicación se instala en un contexto de instalación por máquina.
siD de usuario de	SID para el usuario que instaló el producto.

[in, out, optional] pcchSid

Puntero a una ubicación en la memoria que contiene una variable que especifica el número de TCHAR en el SID, no incluido el carácter nulo de terminación. Cuando la función devuelve, esta variable se establece en el tamaño del SID solicitado si la función puede copiar correctamente el SID y terminar el carácter NULL en la ubicación del búfer a la que apunta szSid. El tamaño se devuelve como el número de TCHAR en el valor solicitado, no incluido el carácter nulo de terminación.

Este parámetro se puede establecer en null solo si szSid también es NULL; de lo contrario, la función devuelve ERROR_INVALID_PARAMETER. Si szSid y pcchSid se establecen en NULL, la función devuelve ERROR_SUCCESS si el SID existe, sin recuperar el valor del SID.

Valor devuelto

La función MsiEnumClientsEx devuelve uno de los valores siguientes.

Código devuelto	Descripción
ERROR_ACCESS_DENIED	Los privilegios de administrador son necesarios para enumerar los componentes de las aplicaciones instaladas por los usuarios distintos del usuario actual.
ERROR_BAD_CONFIGURATION	Los datos de configuración están dañados.
ERROR_INVALID_PARAMETER	Se pasa un parámetro no válido a la función .
ERROR_NO_MORE_ITEMS	No hay más aplicaciones para enumerar.
ERROR_SUCCESS	La función se realizó correctamente.
ERROR_MORE_DATA	El búfer proporcionado era demasiado pequeño para contener todo el valor.
ERROR_FUNCTION_FAILED	Error en la función.

Observaciones

Nota

El encabezado msi.h define MsiEnumClientsEx como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows Installer 5.0 en Windows Server 2012, Windows 8, Windows Server 2008 R2 o Windows 7. Consulte Windows Installer Run-Time Requirements (Requisitos de Windows Installer) para obtener información sobre el Service Pack mínimo de Windows que requiere una versión de Windows Installer.
de la plataforma de destino de	Windows
encabezado de	msi.h
biblioteca de	Msi.lib
DLL de	Msi.dll

Compartir a través de