Función InitiateSystemShutdownExA (winreg.h)
Inicia un apagado y un reinicio opcional del equipo especificado y, opcionalmente, registra el motivo del apagado.
Sintaxis
BOOL InitiateSystemShutdownExA(
[in, optional] LPSTR lpMachineName,
[in, optional] LPSTR lpMessage,
[in] DWORD dwTimeout,
[in] BOOL bForceAppsClosed,
[in] BOOL bRebootAfterShutdown,
[in] DWORD dwReason
);
Parámetros
[in, optional] lpMachineName
Nombre de red del equipo que se va a apagar. Si lpMachineName es NULL o una cadena vacía, la función apaga el equipo local.
[in, optional] lpMessage
Mensaje que se va a mostrar en el cuadro de diálogo de apagado. Este parámetro puede ser NULL si no se requiere ningún mensaje.
Windows Server 2003 y Windows XP: Esta cadena también se almacena como comentario en la entrada del registro de eventos.
Windows Server 2003 y Windows XP con SP1: La cadena está limitada a 3072 TCHAR.
[in] dwTimeout
Tiempo durante el que se debe mostrar el cuadro de diálogo de apagado, en segundos. Mientras se muestra este cuadro de diálogo, la función AbortSystemShutdown puede detener el apagado.
Si dwTimeout no es cero, InitiateSystemShutdownEx muestra un cuadro de diálogo en el equipo especificado. El cuadro de diálogo muestra el nombre del usuario que llamó a la función, muestra el mensaje especificado por el parámetro lpMessage y solicita al usuario que cierre sesión. El cuadro de diálogo suena cuando se crea y permanece encima de otras ventanas del sistema. El cuadro de diálogo se puede mover pero no cerrar. Un temporizador cuenta el tiempo restante antes del apagado.
Si dwTimeout es cero, el equipo se apaga sin mostrar el cuadro de diálogo y AbortSystemShutdown no puede detener el apagado.
Windows Server 2003 y Windows XP con SP1: El valor de tiempo de espera se limita a MAX_SHUTDOWN_TIMEOUT segundos.
Windows Server 2003 y Windows XP con SP1: Si el equipo que se va a apagar es un servidor de Terminal Services, el sistema muestra un cuadro de diálogo a todos los usuarios locales y remotos que les advierten de que se ha iniciado el apagado. El cuadro de diálogo incluye quién solicitó el apagado, el mensaje de presentación (consulte lpMessage) y cuánto tiempo hay hasta que se apague el servidor.
[in] bForceAppsClosed
Si este parámetro es TRUE, las aplicaciones con cambios no guardados se cerrarán forzosamente. Si este parámetro es FALSE, el sistema muestra un cuadro de diálogo que indica al usuario que cierre las aplicaciones.
[in] bRebootAfterShutdown
Si este parámetro es TRUE, el equipo se reiniciará inmediatamente después de apagarse. Si este parámetro es FALSE, el sistema vacía todas las memorias caché en el disco y apaga el sistema de forma segura.
[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 configure 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.
Windows XP: La información de estado del sistema no se guarda durante un apagado del sistema no planeado. El texto anterior no se aplica.
Valor devuelto
Si la función se realiza correctamente, el valor devuelto es distinto de cero.
Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.
Comentarios
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 SE_SHUTDOWN_NAME en el equipo en el que han iniciado sesión y los administradores pueden habilitar el privilegio SE_REMOTE_SHUTDOWN_NAME en equipos remotos. Para más información, consulte 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 ningún usuario ha iniciado sesión.
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 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 los parámetros se realizó correctamente y que el sistema aceptó la solicitud de apagado.
Cuando se llama a esta función, el autor de la llamada debe especificar si las aplicaciones con cambios no guardados deben cerrarse forzosamente. Si el autor de la llamada decide no forzar que estas aplicaciones se cierren y una aplicación con cambios no guardados se ejecute en la sesión de consola, el apagado permanecerá en curso hasta que el usuario haya iniciado sesión en la sesión de consola anule el apagado, guarde los cambios, cierre la aplicación o obligue a que la aplicación se cierre. Durante este período, es posible que el usuario de la consola no anule el apagado, excepto por el usuario de la consola, y es posible que no se inicie otro apagado.
Tenga en cuenta que llamar a esta función con el valor del parámetro bForceAppsClosed establecido en TRUE evita esta situación. Recuerde que esto puede dar lugar a la pérdida de datos.
Windows Server 2003 y Windows XP: Si el equipo está bloqueado y el parámetro bForceAppsClosed es FALSE, el último código de error es ERROR_MACHINE_LOCKED. Si el sistema no está listo para controlar la solicitud, se ERROR_NOT_READY el último código de error. La aplicación debe esperar un breve tiempo y volver a intentar la llamada. Por ejemplo, el sistema puede no leerse para iniciar un apagado y devolver ERROR_NOT_READY, si la solicitud de apagado llega al mismo tiempo que un usuario intenta iniciar sesión en el sistema. En este caso, la aplicación debe esperar un breve tiempo y volver a intentar la llamada.
Nota
El encabezado winreg.h define InitiateSystemShutdownEx 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows XP [aplicaciones de escritorio | aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | winreg.h (incluya Windows.h) |
| Library | Advapi32.lib |
| Archivo DLL | Advapi32.dll |