WTSCreateListenerA function (wtsapi32.h)

Article
02/09/2023

Creates a new Remote Desktop Services listener or configures an existing listener.

Syntax

BOOL WTSCreateListenerA(
  [in] HANDLE              hServer,
  [in] PVOID               pReserved,
  [in] DWORD               Reserved,
  [in] LPSTR               pListenerName,
  [in] PWTSLISTENERCONFIGA pBuffer,
  [in] DWORD               flag
);

Parameters

[in] hServer

A handle to an RD Session Host server. Always set this parameter to WTS_CURRENT_SERVER_HANDLE.

[in] pReserved

This parameter is reserved. Always set this parameter to NULL.

[in] Reserved

This parameter is reserved. Always set this parameter to zero.

[in] pListenerName

A pointer to a null-terminated string that contains the name of the listener to create or configure.

[in] pBuffer

A pointer to a WTSLISTENERCONFIG structure that contains configuration information for the listener.

[in] flag

The purpose of the call. This parameter can be one of the following values.

WTS_LISTENER_CREATE (1 (0x1))

Create a new listener.

WTS_LISTENER_UPDATE (16 (0x10))

Update the settings of an existing listener.

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 the GetLastError function.

Remarks

This function creates or configures a listener that uses Remote Desktop Protocol (RDP). Always set the version member of the WTSLISTENERCONFIG structure that is pointed to by the pBuffer parameter to one.

This function does not create or configure the security descriptor of the listener. When you call this function to create a new listener, the function assigns the default security descriptor to the new listener. To modify the security descriptor, call the WTSSetListenerSecurity function. For more information about security descriptors, see SECURITY_DESCRIPTOR.

This function does not validate the settings for the new listener. Be sure that the settings are valid before calling this function.

Note

The wtsapi32.h header defines WTSCreateListener 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 7
Minimum supported server	Windows Server 2008 R2
Target Platform	Windows
Header	wtsapi32.h
Library	Wtsapi32.lib
DLL	Wtsapi32.dll