broadcastSettingChanged

>>-broadcastSettingChanged--+-----------+----------------------><
                            +-(timeOut)-+

Causes the Windows operating system to send a message, (the WM_SETTINGCHANGE message,) to every top-level window on the Desktop informing them that a system-wide setting has changed. Well-written applications will then reload any system settings that they use.

An example of one use for this might be an installer program setting an environment variable, such as the PATH. Then a call to broadcastSettingChanged would cause all open applications to update their reference to the environment, without the necessity of a reboot.

There are two variations of calling this method. When called with no arguments, the message is broadcast and returns immediately. When called with the time out parameter, the message is broadcast and does not return until every window on the Desktop has acknowledged the message, or timed out.

The problem with using a time out and waiting for acknowledgment is that, if a window is not responding, or several windows are slow to respond, it may take a very long time to return. The problem with not using a time out and returning immediately is that the caller will have no way of knowing when every window has received the message. Generally this is not a problem, but it is up to the programmer to decide how she wants to use this method.

The time out value is specified in milliseconds. For each window, the operating system will wait up to the time out for a response before going on to the next window. Typically a time out value of 5000 (5 seconds) is used, and this is the default.

The single optional argument is:

timeOut

The time, in milliseconds, to wait for each window to acknowledge it received the setting changed message. Specifying 0 or a negative number will cause the default time out of 5000 to be used. (5000 is a typical value used by applications.)

Return value:

0

The setting changed message was broadcast successfully. If no time out argument was used, then this is all it means. If a time out value was used, then all top-level windows have acknowledged receiving the message.

-1

The setting changed message was broadcast, but one or more windows timed out. This return can only happen when the time out parameter is used.

-x

A number less than -1 indicates a system error occurred. This value is the negation of the system error code. I.e., if the return is -1400, the system error code was 1400. System error codes can be looked up in the MSDN library or the Windows Platform SDK. Microsoft makes these references available on the Internet.

+x

A number greater than 0 would be a window result of broadcasting the setting changed message and would not be an error. It is unlikely that this would occur.

Example:

ret = winmgr~broadcastSettingChanged(1000)