Función InitiateShutdownA (winreg.h)

Artículo
11/20/2024

Inicia un apagado y reinicio del equipo especificado y reinicia las aplicaciones que se han registrado para el reinicio.

Sintaxis

DWORD InitiateShutdownA(
  [in, optional] LPSTR lpMachineName,
  [in, optional] LPSTR lpMessage,
  [in]           DWORD dwGracePeriod,
  [in]           DWORD dwShutdownFlags,
  [in]           DWORD dwReason
);

Parámetros

[in, optional] lpMachineName

Nombre del equipo que se va a apagar. Si el valor de este parámetro es NULL, se apaga el equipo local.

[in, optional] lpMessage

Mensaje que se va a mostrar en el cuadro de diálogo de apagado interactivo.

[in] dwGracePeriod

Número de segundos que se deben esperar antes de apagar el equipo. Si el valor de este parámetro es cero, el equipo se apaga inmediatamente. Este valor se limita a MAX_SHUTDOWN_TIMEOUT.

Si el valor de este parámetro es mayor que cero y el dwShutdownFlags parámetro especifica la marca SHUTDOWN_GRACE_OVERRIDE, la función produce un error y devuelve el código de error ERROR_BAD_ARGUMENTS.

[in] dwShutdownFlags

Una o varias marcas de bits que especifican opciones para el apagado. Se definen los siguientes valores.

Valor	Significado
SHUTDOWN_FORCE_OTHERS 0x00000001 (0x1)	Todas las sesiones se cierran con fuerza. Si esta marca no está establecida y los usuarios que no sean el usuario actual inician sesión en el equipo especificado por el parámetro lpMachineName, esta función produce un error con un valor devuelto de ERROR_SHUTDOWN_USERS_LOGGED_ON.
SHUTDOWN_FORCE_SELF 0x00000002 (0x2)	Especifica que la sesión de origen se cierra con fuerza. Si no se establece esta marca, la sesión de origen se apaga de forma interactiva, por lo que no se garantiza un apagado aunque la función se devuelva correctamente.
SHUTDOWN_GRACE_OVERRIDE 0x00000020 (0x20)	Invalida el período de gracia para que el equipo se apague inmediatamente.
SHUTDOWN_HYBRID 0x00000200 (0x200)	A partir de InitiateShutdown que se ejecuta en Windows 8, debes incluir la marca SHUTDOWN_HYBRID con una o varias de las marcas de esta tabla para especificar opciones para el apagado. A partir de Windows 8, InitiateShutdown iniciar siempre un apagado completo del sistema si la marca SHUTDOWN_HYBRID está ausente.
SHUTDOWN_INSTALL_UPDATES 0x00000040 (0x40)	El equipo instala las actualizaciones antes de iniciar el apagado.
SHUTDOWN_NOREBOOT 0x00000010 (0x10)	El equipo está apagado, pero no está apagado o reiniciado.
SHUTDOWN_POWEROFF 0x00000008 (0x8)	El equipo está apagado y apagado.
SHUTDOWN_RESTART 0x00000004 (0x4)	El equipo se apaga y reinicia.
SHUTDOWN_RESTARTAPPS 0x00000080 (0x80)	El sistema se reinicia con la función ExitWindowsEx con la marca EWX_RESTARTAPPS. Esto reinicia las aplicaciones que se han registrado para reiniciarse mediante la función RegisterApplicationRestart.

[in] dwReason

Motivo para iniciar el apagado. Este parámetro debe ser uno de los códigos de motivo de apagado del sistema . Si este parámetro es cero, el valor predeterminado es un apagado indefinido que se registra como "No se encuentra ningún título por este motivo". De forma predeterminada, también es un apagado no planeado. Dependiendo de cómo se configura el sistema, un apagado no planeado desencadena la creación de un archivo que contiene la información de estado del sistema, que puede retrasar el apagado. Por lo tanto, no use cero para este parámetro.

Valor devuelto

Si la función se ejecuta correctamente, devuelve ERROR_SUCCESS.

Si se produce un error en la función, devuelve uno de los siguientes códigos de error.

Código devuelto	Descripción
ERROR_ACCESS_DENIED	El autor de la llamada no tiene el privilegio necesario (SE_SHUTDOWN_PRIVILEGE o SE_REMOTE_SHUTDOWN_PRIVILEGE) para realizar esta operación.
ERROR_BAD_NETPATH	El equipo especificado no existe o no es accesible.
ERROR_INVALID_COMPUTERNAME	El nombre de equipo especificado no es un nombre de equipo válido.
ERROR_INVALID_FUNCTION	El equipo especificado no admite una interfaz de apagado.
ERROR_INVALID_PARAMETER	Se pasó un conjunto no válido de parámetros. Esto incluye las siguientes combinaciones. El parámetro lpMachineName especifica un equipo remoto y el parámetro dwShutdownFlags no especifica SHUTDOWN_FORCE_SELF. El valor del dwGracePeriod es mayor que cero y el parámetro dwShutdownFlags no especifica SHUTDOWN_FORCE_SELF. El valor del dwGracePeriod de es mayor que cero y el parámetro dwShutdownFlags especifica SHUTDOWN_GRACE_OVERRIDE.
ERROR_SHUTDOWN_IN_PROGRESS	Ya se ha iniciado un apagado en el equipo especificado.
ERROR_SHUTDOWN_IS_SCHEDULED	Se ha programado un apagado para el equipo especificado, pero no se ha iniciado. Para que esta función se realice correctamente, se debe establecer la marca SHUTDOWN_GRACE_OVERRIDE.
ERROR_SHUTDOWN_USERS_LOGGED_ON	Uno o varios usuarios que no sean el usuario actual han iniciado sesión en el equipo especificado y no se estableció la marca SHUTDOWN_FORCE_OTHERS.

Observaciones

Para apagar el equipo local, el subproceso que llama debe tener el privilegio SE_SHUTDOWN_NAME. Para apagar un equipo remoto, el subproceso que llama debe tener el privilegio SE_REMOTE_SHUTDOWN_NAME en el equipo remoto. De forma predeterminada, los usuarios pueden habilitar el privilegio de SE_SHUTDOWN_NAME en el equipo en el que han iniciado sesión y los administradores pueden habilitar el privilegio de SE_REMOTE_SHUTDOWN_NAME en equipos remotos. Para obtener más información, vea En ejecución con privilegios especiales.

Entre los motivos comunes del error se incluyen un nombre de equipo no válido o inaccesible o privilegios insuficientes. El error ERROR_SHUTDOWN_IN_PROGRESS se devuelve si un apagado ya está en curso en el equipo especificado. El error ERROR_NOT_READY se puede devolver si el cambio rápido de usuario está habilitado, pero no se ha iniciado sesión ningún usuario.

Un valor devuelto distinto de cero no significa que el logoff fue o se realizará correctamente. El apagado es un proceso asincrónico y puede producirse mucho tiempo después de que se haya devuelto la llamada API, o no en absoluto. Incluso si el valor de tiempo de espera es cero, las aplicaciones, los servicios o incluso el sistema pueden anular el apagado. El valor devuelto distinto de cero indica que la validación de los derechos y parámetros se realizó correctamente y que el sistema aceptó la solicitud de apagado.

Nota

El encabezado winreg.h define InitiateShutdown 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 Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2008 [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	winreg.h (incluya Windows.h)
biblioteca de	Advapi32.lib
DLL de	Advapi32.dll

Consulte también

apagar

Compartir a través de