3.3.4.1 WsdrInitiateShutdown (Opnum 0)

  • Article

The WsdrInitiateShutdown method is used to initiate the shutdown of the remote computer.<14>

 unsigned long WsdrInitiateShutdown(
   [ in ] handle_t Binding,
   [ in, unique ] PREG_UNICODE_STRING lpMessage,
   [ in ] unsigned long dwGracePeriod,
   [ in ] unsigned long dwShudownFlags,
   [ in ] unsigned long dwReason,
   [ in, unique ] PREG_UNICODE_STRING lpClientHint);

Binding: Primitive RPC handle that identifies a particular client/server binding.

lpMessage: Null-terminated Unicode string that contains the message to display during the shutdown waiting period. If this parameter is NULL, no message MUST be displayed.

dwGracePeriod: Number of seconds to wait before shutting down.

dwShudownFlags: A set of bit flags in little-endian format used as a mask to indicate shutdown options. The value is constructed from zero or more bit flags from the following table, with the exception that flag "B" cannot be combined with "C" or "D".


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

G

F

E

D

C

B

0

A

The bits are defined as follows.

Value

Meaning

A

0x00000001

All applications SHOULD be terminated unconditionally. An alternate for this field is SHUTDOWN_FORCE_OTHERS.

B

0x00000004

Restart computer. Cannot be used with "C" or "D". An alternate name for this field is SHUTDOWN_RESTART.

C

0x00000008

The shutdown SHOULD turn off the computer. Cannot be used with "B" or "D". An alternate name for this field is SHUTDOWN_POWEROFF.

D

0x00000010

The shutdown SHOULD leave the computer powered but SHOULD NOT cause a reboot. Cannot be used with "B" or "C". An alternate name for this field is SHUTDOWN_NOREBOOT.

E

0x00000020

If a shutdown is currently in progress, setting this bit on a subsequent shutdown request SHOULD cause the ongoing request's waiting period to be ignored and SHOULD cause an immediate shutdown. An alternate name for this field is SHUTDOWN_GRACE_OVERRIDE.

F

0x00000040

The shutdown SHOULD install pending software updates before proceeding. An alternate name for this field is SHUTDOWN_INSTALL_UPDATES.

G

0x00000080

The shutdown SHOULD restart the computer and then restart any applications that have registered for restart. An alternate name for this field is SHUTDOWN_RESTARTAPPS.

All other bits MUST be zero and ignored upon receipt.

dwReason: Reason for initiating the shutdown (section 2.3). The dwReason SHOULD be used for log entries for the shutdown event.

lpClientHint: Used only for diagnostic purposes (logging the image file name of the process initiating a shutdown).

Return Values: The method returns ERROR_SUCCESS (0x00000000) on success; otherwise, it returns a nonzero error code.

On receiving this call, the server MUST perform the following validation step:

  • Verify that the caller has sufficient privileges to shut down the computer; otherwise, the server MUST return ERROR_BAD_NETPATH.

If there are other sessions logged on and "A" is not set, the server MUST return ERROR_SHUTDOWN_USERS_LOGGED_ON.

The shutdown SHOULD turn off the computer when "B," "C," and "D" are not set or when multiple bits are set.