2 out of 6 rated this helpful - Rate this topic

WTSSendMessage function

Applies to: desktop apps only

Displays a message box on the client desktop of a specified Remote Desktop Services session.

Syntax

Copy

BOOL WTSSendMessage(
  __in   HANDLE hServer,
  __in   DWORD SessionId,
  __in   LPTSTR pTitle,
  __in   DWORD TitleLength,
  __in   LPTSTR pMessage,
  __in   DWORD MessageLength,
  __in   DWORD Style,
  __in   DWORD Timeout,
  __out  DWORD *pResponse,
  __in   BOOL bWait
);

Parameters

hServer [in]

A handle to an RD Session Host server. Specify a handle opened by the WTSOpenServer function, or specify WTS_CURRENT_SERVER_HANDLE to indicate the RD Session Host server on which your application is running.

SessionId [in]

A Remote Desktop Services session identifier. To indicate the current session, specify WTS_CURRENT_SESSION. You can use the WTSEnumerateSessions function to retrieve the identifiers of all sessions on a specified RD Session Host server.

To send a message to another user's session, you need to have the Message permission. For more information, see Remote Desktop Services Permissions. To modify permissions on a session, use the Remote Desktop Services Configuration administrative tool.

pTitle [in]

A pointer to a null-terminated string for the title bar of the message box.

TitleLength [in]

The length, in bytes, of the title bar string.

pMessage [in]

A pointer to a null-terminated string that contains the message to display.

MessageLength [in]

The length, in bytes, of the message string.

Style [in]

The contents and behavior of the message box. This value is typically MB_OK. For a complete list of values, see the uType parameter of the MessageBox function.

Timeout [in]

The time, in seconds, that the WTSSendMessage function waits for the user's response. If the user does not respond within the time-out interval, the pResponse parameter returns IDTIMEOUT. If the Timeout parameter is zero, WTSSendMessage waits indefinitely for the user to respond.

pResponse [out]

A pointer to a variable that receives the user's response, which can be one of the following values.

Value	Meaning
IDABORT 3	Abort
IDCANCEL 2	Cancel
IDCONTINUE 11	Continue
IDIGNORE 5	Ignore
IDNO 7	No
IDOK 1	OK
IDRETRY 4	Retry
IDTRYAGAIN 10	Try Again
IDYES 6	Yes
IDASYNC 32001 (0x7D01)	The bWait parameter was FALSE, so the function returned without waiting for a response.
IDTIMEOUT 32000 (0x7D00)	The bWait parameter was TRUE and the time-out interval elapsed.

bWait [in]

If TRUE, WTSSendMessage does not return until the user responds or the time-out interval elapses. If the Timeout parameter is zero, the function does not return until the user responds.

If FALSE, the function returns immediately and the pResponse parameter returns IDASYNC. Use this method for simple information messages (such as print job–notification messages) that do not need to return the user's response to the calling program.

Return value

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Requirements

Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	Wtsapi32.h
Library	Wtsapi32.lib
DLL	Wtsapi32.dll
Unicode and ANSI names	WTSSendMessageW (Unicode) and WTSSendMessageA (ANSI)

The console utlity MSG.EXE calls WTSSendMessage to send a popup message to a remote computer. Example: MSG * /server:foo "Please log off - doing maintenance" sends the popup message "Please log off - doing maintenance" to the computer named foo.

Attempting to send a popup message via WTSSendMessage to a remote computer running XP SP2 or Vista will fail with ERROR_ACCESS_DENIED. WTSOpenServer succeeds but the send fails. It will fail even if the caller has full administrative rights on the target computer.

The is due to the addition of a new DWORD registry value AllowRemoteRPC under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Terminal Server. The default value is 0, which rejects the receipt of remote popup messages (even if the sender has administrative rights).

There is no Group Policy setting available to enable it (May 2008). This is unfortunate because it means that there is no obvious way for an IT site administrator to send alert popup messages to clients without pre-installing an agent.

[If you do know of a way for a Domain Admin to send a popup msg to a virgin Vista/XP box please update this entry. -Gideon7]

Windows Server 2008: The default value for AllowRemoteRPC is 1. This means that the above issue does not prevent receipt of alert popups on Windows Server 2008. [It also confirms my suspicion that the Vista default is overly restrictive, as the W2K8 team apparently doesn't think it is a security risk. -Gideon7]

History

1/20/2008
Gideon7

6/9/2009
Gideon7

You can use an ADM template to set AllowRemoteRPC to 1 for XP/Vista

Use this ADM Template to create a GPO for setting AllowRemoteRPC on your domain:

CLASS MACHINE
CATEGORY "Windows Components"
CATEGORY "Terminal Services"
KEYNAME "SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services"

POLICY !!ALLOW_TSMANAGER
#if version >= 4
SUPPORTED !!WinXP
#endif
EXPLAIN !!ALLOW_TSMANAGER_EXPLAIN
ACTIONLISTON
VALUENAME "AllowRemoteRPC" VALUE NUMERIC 1
END ACTIONLISTON
ACTIONLISTOFF
VALUENAME "AllowRemoteRPC" VALUE NUMERIC 0
END ACTIONLISTOFF
END POLICY

End Category
End Category

[strings]
WinXP="At least Windows XP Professional or Windows 2003 Server"
ALLOW_TSMANAGER="Allow access from Terminal Services Manager"
ALLOW_TSMANAGER_EXPLAIN="Allows administrators to use the Terminal Services Manager to remote control the user session."