Función SetAdditionalForegroundBoostProcesses (Winuser.h)

SetAdditionalForegroundBoostProcesses es una API de asistencia de rendimiento para ayudar a las aplicaciones con un modelo de aplicación de varios procesos donde varios procesos contribuyen a una experiencia en primer plano, ya sea como datos o representación. Entre los ejemplos se incluyen exploradores (con el administrador del explorador o marco, pestañas, complementos, etc. hospedados en diferentes procesos) e IDE (que generan procesos para la compilación y otras tareas).

Las aplicaciones pueden usar esta API para proporcionar un aumento de prioridad en primer plano a los procesos de trabajo que ayudan a admitir la aplicación principal. Estas aplicaciones pueden tener un aumento de prioridad uniforme aplicado a todos sus procesos constituyentes cuando la ventana de nivel superior de la aplicación está en primer plano.

Sintaxis

BOOL SetAdditionalForegroundBoostProcesses(
  HWND   topLevelWindow,
  DWORD  processHandleCount,
  HANDLE *processHandleArray
);

Parámetros

topLevelWindow

Identificador de la ventana de nivel superior (HWND) de la aplicación.

processHandleCount

Número de identificadores de proceso en processHandleArray. Esta función se puede llamar en una sola vez con un máximo de 32 identificadores. Establezca este parámetro en 0 junto con la configuración processHandleArray enNULL para borrar una configuración de aumento anterior.

processHandleArray

Un grupo de identificadores de proceso que se van a aumentar o desactivar en primer plano. Establezca este parámetro en NULL junto con el establecimiento de processHandleCount en 0 para borrar una configuración de aumento anterior.

Valor devuelto

Devuelve TRUE si la llamada se realiza correctamente al aumentar la aplicación; en caso contrario, FALSE. SetAdditionalForegroundBoostProcesses establece el último código de error, por lo que la aplicación puede llamar a GetLastError() para obtener información extendida si se produjo un error en la llamada (por ejemplo, ERROR_INVALID_PARAMETER, ERROR_NOT_ENOUGH_MEMORY o ERROR_ACCESS_DENIED).

Comentarios

Esta función toma un grupo de identificadores de proceso que se potencian o desenlazan en primer plano cuando el HWND de nivel superior pasado se mueve al primer plano o al fondo respectivamente. Cada vez que el HWND de nivel superior pasado se convierte en la ventana de primer plano, también se aplicará una mejora en primer plano a los procesos pasados en la matriz de identificadores. Se produce un desajuste similar cuando el HWND de nivel superior se mueve al fondo.

El HWND de nivel superior pasado a esta función debe ser propiedad del proceso de llamada. El proceso de llamada debe tener el derecho de acceso PROCESS_SET_INFORMATION en los identificadores del proceso en processHandleArray ; es decir, debe tener control total de todas las ventanas del proceso. Si algún componente externo inserta una ventana que toma primer plano, o si aparece un cuadro de diálogo, perderá el aumento.

Si tiene dos ventanas de nivel superior, debe llamar a esta función para cada una.

Si el HWND de nivel superior pasado ya está en primer plano cuando se llama a SetAdditionalForegroundBoostProcesses , se aumentan inmediatamente todos los procesos de processHandleArray .

Un proceso cuyo identificador se encuentra en processHandleArray obtendrá un aumento en primer plano solo cuando el HWND de nivel superior se convierta en la ventana de primer plano.

La mejora de primer plano adicional solo se aplica cuando:

1. Cambia la ventana de primer plano o
2. Si se llama a esta función mientras la ventana está en primer plano y la nueva lista tiene el identificador de proceso, o la lista no incluye el identificador de proceso mientras se incluyó anteriormente.

Cuando el proceso que posee el HWND de nivel superior sale o finaliza, la relación de aumento adicional se descompone y los procesos secundarios no reciben ninguna mejora en primer plano adicional.

El HWND de nivel superior del proceso principal seguirá manteniendo referencias a procesos secundarios hasta que el HWND de nivel superior del proceso principal borre su estado de aumento agrupado o se destruya el HWND.

Ejemplo

En este escenario sencillo, la aplicación configura su configuración de aumento del proceso en primer plano cuando se crea la ventana de nivel superior. Cuando se controla WM_CREATE, se llama a la función con identificadores en lParam y el recuento de identificadores en wParam. Estos procesos obtendrán prioridad en primer plano o en segundo plano a medida que m_AppWindow se mueve y sale de la ventana de primer plano. Si el m_AppWindow es la ventana de primer plano cuando se llama a la función, los procesos también obtendrán un aumento inmediato de prioridad en primer plano.

case WM_CREATE:   

    // 
    // Configure the passed in worker processes (handles) in lParam, to get foreground priority boost when m_AppWindow moves in and 
    // out of the foreground. 
    //  

    HANDLE *pMyHandles = retinterpret_cast<HANDLE*>(lParam); 
    DWORD cHandles = reinterpret_cast<DWORD>(wParam);  

    If (!SetAdditionalForegroundBoostProcesses(m_AppWindow, cHandles, pMyHandles)) 
    { 
        printf(“SetAdditionalForegroundBoostProcesses() setup failed with error code : %d\n”, GetLastError()); 
    } 

    break;

Requisitos

Consulte también

SetForegroundWindow