WTSSendMessageA function (wtsapi32.h)

Article
02/09/2023

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

Syntax

BOOL WTSSendMessageA(
  [in]  HANDLE hServer,
  [in]  DWORD  SessionId,
  [in]  LPSTR  pTitle,
  [in]  DWORD  TitleLength,
  [in]  LPSTR  pMessage,
  [in]  DWORD  MessageLength,
  [in]  DWORD  Style,
  [in]  DWORD  Timeout,
  [out] DWORD  *pResponse,
  [in]  BOOL   bWait
);

Parameters

[in] hServer

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.

[in] SessionId

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.

[in] pTitle

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

[in] TitleLength

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

[in] pMessage

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

[in] MessageLength

The length, in bytes, of the message string.

[in] Style

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.

[in] Timeout

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.

[out] pResponse

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

IDABORT (3)

Abort

IDCANCEL (2)

Cancel

IDCONTINUE (11)

Continue

IDIGNORE (5)

Ignore

IDNO (7)

IDOK (1)

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.

[in] bWait

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.

Remarks

Note

The wtsapi32.h header defines WTSSendMessage as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	wtsapi32.h
Library	Wtsapi32.lib
DLL	Wtsapi32.dll

Share via