Función InitiateSystemShutdownW (winreg.h)
Inicia un apagado y un reinicio opcional del equipo especificado.
Para registrar un motivo del apagado en el registro de eventos, llame a la función
Sintaxis
BOOL InitiateSystemShutdownW(
[in, optional] LPWSTR lpMachineName,
[in, optional] LPWSTR lpMessage,
[in] DWORD dwTimeout,
[in] BOOL bForceAppsClosed,
[in] BOOL bRebootAfterShutdown
);
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
El período de 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 de
Si dwTimeout no es cero, InitiateSystemShutdown 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 pite 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 de un apagado forzado.
Si dwTimeout es cero, el equipo se apaga sin mostrar el cuadro de diálogo y el apagado no se puede detener AbortSystemShutdown.
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 (vea 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 deben cerrarse forzadamente. Tenga en cuenta que esto puede provocar la pérdida de datos.
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 de forma segura el sistema.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es distinto de cero.
Si se produce un error en la función, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.
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. Se puede devolver el error ERROR_NOT_READY 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.
Cuando se llama a esta función, el autor de la llamada debe especificar si las aplicaciones con cambios no guardados deben cerrarse forzadamente. Si el autor de la llamada decide no forzar el cierre de estas aplicaciones y una aplicación con cambios no guardados se ejecuta 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 anula el apagado, guarda los cambios, cierra la aplicación o obliga a la aplicación a cerrarse. 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, el último código de error es ERROR_NOT_READY. 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.
Ejemplos
Para obtener un ejemplo, vea Mostrar el cuadro de diálogo Apagar.
Nota
El encabezado winreg.h define InitiateSystemShutdown 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 XP [aplicaciones de escritorio | Aplicaciones para UWP] |
| servidor mínimo admitido | Windows Server 2003 [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
funciones de apagado del sistema de