Compartir a través de


Función MsiEnumClientsExA (msi.h)

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.

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 terminado 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
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 (System) no se puede usar para enumerar las aplicaciones que existen en el contexto de instalación por máquina. Si se establece el valor del SID en s-1-5-18, se devuelve ERROR_INVALID_PARAMETER. Cuando dwContext se establece en solo 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 incluye solo instancias de aplicaciones instaladas por los usuarios identificados por szUserSid.

Puede ser una combinación de los valores siguientes.

Context Significado
MSIINSTALLCONTEXT_USERMANAGED
1
Incluya las aplicaciones instaladas en el contexto de instalación administrada 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 se establece en solo 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 se debe incrementar 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 valores siguientes.

Context 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 la 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 szSid 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
SID para el usuario que instaló el producto.

[in, out, optional] pcchSid

Puntero a una ubicación en 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 se devuelve la función, esta variable se establece en el tamaño del SID solicitado, independientemente de si la función puede copiar correctamente el SID y terminar el carácter NULO 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, sin incluir el carácter nulo de terminación.

Este parámetro solo se puede establecer en NULL 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 ha realizado 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.

Comentarios

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 Convenciones para prototipos de función.

Requisitos

   
Cliente mínimo compatible Windows Installer 5.0 en Windows Server 2012, Windows 8, Windows Server 2008 R2 o Windows 7. Consulte Windows Installer para obtener información sobre el Service Pack mínimo de Windows que requiere una versión de Windows Installer.
Plataforma de destino Windows
Encabezado msi.h
Library Msi.lib
Archivo DLL Msi.dll