Función InitiateSystemShutdownA (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 InitiateSystemShutdownEx .
Sintaxis
BOOL InitiateSystemShutdownA(
[in, optional] LPSTR lpMachineName,
[in, optional] LPSTR 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
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 AbortSystemShutdown puede detener el apagado.
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 la 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 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. 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 el sistema de forma segura.
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 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 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 no se ha iniciado sesión ningún usuario.
Un valor devuelto distinto de cero no significa que el logoff fuera o se realizara 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 cierre.
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 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 cierre no se anule, 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 hacerlo 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, se ERROR_MACHINE_LOCKED el último código de error. 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.
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 Convenciones para prototipos de función.
Requisitos
| 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 (incluye Windows.h) |
| Library | Advapi32.lib |
| Archivo DLL | Advapi32.dll |