InitiateSystemShutdownA 函式 (winreg.h)
起始指定電腦的關機和選擇性重新開機。
若要在事件記錄檔中記錄關機的原因,請呼叫 InitiateSystemShutdownEx 函 式。
語法
BOOL InitiateSystemShutdownA(
[in, optional] LPSTR lpMachineName,
[in, optional] LPSTR lpMessage,
[in] DWORD dwTimeout,
[in] BOOL bForceAppsClosed,
[in] BOOL bRebootAfterShutdown
);
參數
[in, optional] lpMachineName
要關閉之電腦的網路名稱。 如果 lpMachineName 為 Null 或空字串,則函式會關閉本機電腦。
[in, optional] lpMessage
要顯示在 [關機] 對話方塊中的訊息。 如果不需要任何訊息,這個參數可以是 Null 。
Windows Server 2003 和 Windows XP: 此字串也會儲存為事件記錄專案中的批註。
Windows Server 2003 和 Windows XP SP1: 字串限制為 3072 TCHAR。
[in] dwTimeout
應該以秒為單位顯示關機對話方塊的時間長度。 顯示此對話方塊時, AbortSystemShutdown 函式可以停止關機。
如果 dwTimeout 不是零, 則 InitiateSystemShutdown 會在指定的電腦上顯示對話方塊。 對話方塊會顯示呼叫函式的使用者名稱、顯示 lpMessage 參數所指定的訊息,並提示使用者登出。 建立對話方塊時會發出嗶聲,並保留在系統中的其他視窗之上。 對話方塊可以移動,但無法關閉。 計時器會倒數強制關機之前的剩餘時間。
如果 dwTimeout 為零,則電腦會關閉而不顯示對話方塊,而且 AbortSystemShutdown無法停止關機。
Windows Server 2003 和 Windows XP SP1: 逾時值限制為 MAX_SHUTDOWN_TIMEOUT 秒。
Windows Server 2003 和 Windows XP SP1: 如果要關閉的電腦是終端機服務伺服器,系統會向所有本機和遠端使用者顯示對話方塊,警告他們已起始關機。 對話方塊包含要求關機的人員、顯示訊息 (請參閱 lpMessage) ,以及伺服器關機前有多少時間。
[in] bForceAppsClosed
如果此參數為 TRUE,則會強制關閉具有未儲存變更的應用程式。 請注意,這可能會導致資料遺失。
如果此參數為 FALSE,系統會顯示對話方塊,指示使用者關閉應用程式。
[in] bRebootAfterShutdown
如果此參數為 TRUE,電腦會在關機後立即重新開機。 如果此參數為 FALSE,系統會將所有快取排清到磁片,並安全地關閉系統。
傳回值
如果函式成功,則傳回非零的值。
如果此函式失敗,則傳回值為零。 若要取得擴充的錯誤資訊,請呼叫 GetLastError。
備註
若要關閉本機電腦,呼叫執行緒必須具有 SE_SHUTDOWN_NAME 許可權。 若要關閉遠端電腦,呼叫執行緒必須在遠端電腦上具有 SE_REMOTE_SHUTDOWN_NAME 許可權。 根據預設,使用者可以在登入的電腦上啟用 SE_SHUTDOWN_NAME 許可權,而系統管理員可以在遠端電腦上啟用 SE_REMOTE_SHUTDOWN_NAME 許可權。 如需詳細資訊,請參閱 以特殊許可權執行。
失敗的常見原因包括無效或無法存取的電腦名稱稱或許可權不足。 如果指定的電腦上已經在進行關機,則會傳回錯誤 ERROR_SHUTDOWN_IN_PROGRESS 。 如果已啟用快速使用者切換,但未登入使用者,則可以傳回錯誤 ERROR_NOT_READY 。
非零的傳回值並不表示登出是或將會成功。 關機是非同步進程,而且在 API 呼叫傳回或完全不傳回之後,可能會發生很長的時間。 即使逾時值為零,關閉仍可由應用程式、服務或甚至系統中止。 非零傳回值表示許可權和參數的驗證成功,而且系統已接受關機要求。
呼叫此函式時,呼叫端必須指定是否應該強制關閉具有未儲存變更的應用程式。 如果呼叫端選擇不要強制關閉這些應用程式,且主控台會話上正在執行未儲存變更的應用程式,則在使用者登入主控台會話中止關機、儲存變更、關閉應用程式或強制應用程式關閉之前,關機會保持進行中。 在此期間,除了主控台使用者之外,可能無法中止關機,而且可能不會起始另一個關機。
請注意,使用設定為TRUE的bForceAppsClosed參數值呼叫此函式,可避免這種情況。 請記住,這樣做可能會導致資料遺失。
Windows Server 2003 和 Windows XP: 如果電腦已鎖定,且 bForceAppsClosed 參數為 FALSE,則最後一個錯誤碼 會ERROR_MACHINE_LOCKED。 如果系統尚未準備好處理要求,則會 ERROR_NOT_READY最後一個錯誤碼。 應用程式應該稍候一段時間,然後重試呼叫。 例如,如果關閉要求同時使用者嘗試登入系統,系統可能會無法讀取以起始關機,並傳回 ERROR_NOT_READY。 在此情況下,應用程式應該稍候一段時間,然後重試呼叫。
範例
如需範例,請參閱 顯示關機對話方塊。
注意
winreg.h 標頭會將 InitiateSystemShutdown 定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼,可能會導致編譯或執行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
規格需求
最低支援的用戶端 | Windows XP [傳統型應用程式 |UWP 應用程式] |
最低支援的伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
目標平台 | Windows |
標頭 | winreg.h (包含 Windows.h) |
程式庫 | Advapi32.lib |
Dll | Advapi32.dll |