This section explains how to use the desktop sharing feature where users can share their desktop applications. More...

Classes
struct	DesktopWindow
	A struct containing the properties of a shared desktop window. More...

struct	DesktopInput
	A struct containing a mouse or keyboard event. More...

struct	ShareWindow
	A struct which describes the properties of a window which can be shared. More...

Macros
#define	TT_DESKTOPINPUT_MAX 16

#define	TT_DESKTOPINPUT_KEYCODE_IGNORE 0xFFFFFFFF

#define	TT_DESKTOPINPUT_MOUSEPOS_IGNORE 0xFFFF

#define	TT_DESKTOPINPUT_KEYCODE_LMOUSEBTN 0x1000

#define	TT_DESKTOPINPUT_KEYCODE_RMOUSEBTN 0x1001

#define	TT_DESKTOPINPUT_KEYCODE_MMOUSEBTN 0x1002

Typedefs
typedef enum BitmapFormat	BitmapFormat
	The bitmap format used for a DesktopWindow.

typedef enum DesktopProtocol	DesktopProtocol
	The protocols supported for transferring a DesktopWindow.

typedef struct DesktopWindow	DesktopWindow
	A struct containing the properties of a shared desktop window.

typedef enum DesktopKeyState	DesktopKeyState
	The state of a key (or mouse button), i.e. if it's pressed or released.

typedef UINT32	DesktopKeyStates
	Mask of key states.

typedef struct DesktopInput	DesktopInput
	A struct containing a mouse or keyboard event.

typedef struct ShareWindow	ShareWindow
	A struct which describes the properties of a window which can be shared.

typedef enum TTKeyTranslate	TTKeyTranslate
	Translate to and from TeamTalk's intermediate key-codes (TTKEYCODE).

Enumerations
enum	BitmapFormat { BMP_NONE = 0 , BMP_RGB8_PALETTE = 1 , BMP_RGB16_555 = 2 , BMP_RGB24 = 3 , BMP_RGB32 = 4 }
	The bitmap format used for a DesktopWindow. More...

enum	DesktopProtocol { DESKTOPPROTOCOL_ZLIB_1 = 1 }
	The protocols supported for transferring a DesktopWindow. More...

enum	DesktopKeyState { DESKTOPKEYSTATE_NONE = 0x00000000 , DESKTOPKEYSTATE_DOWN = 0x00000001 , DESKTOPKEYSTATE_UP = 0x00000002 }
	The state of a key (or mouse button), i.e. if it's pressed or released. More...

enum	TTKeyTranslate { TTKEY_NO_TRANSLATE = 0 , TTKEY_WINKEYCODE_TO_TTKEYCODE = 1 , TTKEY_TTKEYCODE_TO_WINKEYCODE = 2 , TTKEY_MACKEYCODE_TO_TTKEYCODE = 3 , TTKEY_TTKEYCODE_TO_MACKEYCODE = 4 }
	Translate to and from TeamTalk's intermediate key-codes (TTKEYCODE). More...

Functions
TEAMTALKDLL_API INT32	TT_SendDesktopWindow (IN TTInstance lpTTInstance, IN const DesktopWindow lpDesktopWindow, IN BitmapFormat nConvertBmpFormat)
	Transmit a desktop window (bitmap) to users in the same channel.

TEAMTALKDLL_API TTBOOL	TT_CloseDesktopWindow (IN TTInstance *lpTTInstance)
	Close the current desktop session.

TEAMTALKDLL_API unsigned char *	TT_Palette_GetColorTable (IN BitmapFormat nBmpPalette, IN INT32 nIndex)
	Get RGB values of the palette for the bitmap format.

TEAMTALKDLL_API HWND	TT_Windows_GetDesktopActiveHWND (void)
	Get the handle (HWND) of the window which is currently active (focused) on the Windows desktop.

TEAMTALKDLL_API HWND	TT_Windows_GetDesktopHWND (void)
	Get the handle (HWND) of the Windows desktop (full desktop).

TEAMTALKDLL_API TTBOOL	TT_Windows_GetDesktopWindowHWND (IN INT32 nIndex, OUT HWND *lpHWnd)
	Enumerate all the handles (`HWND`) of visible windows. Increment `nIndex` until the function returns FALSE. Use TT_Windows_GetWindow() to get information about each window.

TEAMTALKDLL_API TTBOOL	TT_Windows_GetWindow (IN HWND hWnd, OUT ShareWindow *lpShareWindow)
	Get the properties of a window from its window handle (HWND).

TEAMTALKDLL_API INT32	TT_SendDesktopWindowFromHWND (IN TTInstance *lpTTInstance, IN HWND hWnd, IN BitmapFormat nBitmapFormat, IN DesktopProtocol nDesktopProtocol)
	Transmit the specified window in a desktop session.

TEAMTALKDLL_API TTBOOL	TT_PaintDesktopWindow (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN HDC hDC, IN INT32 XDest, IN INT32 YDest, IN INT32 nDestWidth, IN INT32 nDestHeight)
	Paint user's desktop window using a Windows' DC (device context).

TEAMTALKDLL_API TTBOOL	TT_PaintDesktopWindowEx (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN HDC hDC, IN INT32 XDest, IN INT32 YDest, IN INT32 nDestWidth, IN INT32 nDestHeight, IN INT32 XSrc, IN INT32 YSrc, IN INT32 nSrcWidth, IN INT32 nSrcHeight)
	Paint user's desktop window using a Windows' DC (device context).

TEAMTALKDLL_API TTBOOL	TT_MacOS_GetWindow (IN INT32 nIndex, OUT ShareWindow *lpShareWindow)
	Enumerate all windows on the desktop. Increment `nIndex` until the function returns FALSE. Use TT_MacOS_GetWindowFromWindowID() to get information about the window, e.g. title, dimensions, etc.

TEAMTALKDLL_API TTBOOL	TT_MacOS_GetWindowFromWindowID (IN INT64 nWindowID, OUT ShareWindow *lpShareWindow)
	Get information about a window by passing its handle (`CGWindowID`).

TEAMTALKDLL_API INT32	TT_SendDesktopFromWindowID (IN TTInstance *lpTTInstance, IN INT64 nWindowID, IN BitmapFormat nBitmapFormat, IN DesktopProtocol nDesktopProtocol)
	Transmit the specified window in a desktop session.

TEAMTALKDLL_API TTBOOL	TT_SendDesktopCursorPosition (IN TTInstance *lpTTInstance, IN UINT16 nPosX, IN UINT16 nPosY)
	Send the position of mouse cursor to users in the same channel.

TEAMTALKDLL_API TTBOOL	TT_SendDesktopInput (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN const DesktopInput lpDesktopInputs[TT_DESKTOPINPUT_MAX], IN INT32 nDesktopInputCount)
	Send a mouse or keyboard event to a shared desktop window.

TEAMTALKDLL_API DesktopWindow *	TT_AcquireUserDesktopWindow (IN TTInstance *lpTTInstance, IN INT32 nUserID)
	Acquire a user's desktop window (bitmap image).

TEAMTALKDLL_API DesktopWindow *	TT_AcquireUserDesktopWindowEx (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN BitmapFormat nBitmapFormat)
	Same as TT_AcquireUserDesktopWindow() except an extra option for converting bitmap to a different format.

TEAMTALKDLL_API TTBOOL	TT_ReleaseUserDesktopWindow (IN TTInstance lpTTInstance, IN DesktopWindow lpDesktopWindow)
	Release memory allocated by the DesktopWindow.

TEAMTALKDLL_API INT32	TT_DesktopInput_KeyTranslate (TTKeyTranslate nTranslate, IN const DesktopInput lpDesktopInputs, OUT DesktopInput lpTranslatedDesktopInputs, IN INT32 nDesktopInputCount)
	Translate platform key-code to and from TeamTalk's intermediate format.

TEAMTALKDLL_API INT32	TT_DesktopInput_Execute (IN const DesktopInput *lpDesktopInputs, IN INT32 nDesktopInputCount)
	Execute desktop (mouse or keyboard) input.

Detailed Description

This section explains how to use the desktop sharing feature where users can share their desktop applications.

A user can transmit a desktop window to other users in a channel by passing the handle of a window to the TeamTalk client instance. The client instance then converts the window to a bitmap image which is transmitted to the server. The server then forwards the bitmap image to all other users in the channel.

To transmit a desktop window the user's UserAccount must have the USERRIGHT_TRANSMIT_DESKTOP.

Sections:

Send Desktop Window (or bitmap)

Before sending a desktop window to a channel the handle (identifier) of the window to share must first be found. Windows, Mac and Linux (X11) have different ways of locating the window handle.

Instead of using a window handle it's also possible to simply send a raw bitmap by calling TT_SendDesktopWindow().

Windows Desktop Sharing

TeamTalk for Windows provides the following functions for obtaining different HWNDs:

TT_Windows_GetDesktopActiveHWND()
- Get the HWND of the window which has focus.
TT_Windows_GetDesktopHWND()
- Get the HWND of the Windows desktop.
TT_Windows_GetDesktopWindowHWND()
- Enumerate all visible windows.
TT_Windows_GetWindow()
- Get information about a window, e.g. window title, size, etc.

Once the HWND of the window to share has been found use the following function for sending the window to the channel:

TT_SendDesktopWindowFromHWND()

Mac OS Desktop Sharing

TeamTalk for Mac OS provides the following functions for obtaining desktop window handles:

TT_MacOS_GetWindow()
- Enumerate all active windows.
TT_MacOS_GetWindowFromWindowID()
- Get information about a window, e.g. window title, size, etc.

Once the handle (CGWindowID) of the window to share has been found use the following function for sending the window to the channel:

TT_SendDesktopFromWindowID()

Linux Desktop Sharing

TeamTalk for Linux does not provide helper functions for getting the handle of a X11 window. This is in order to avoid linking the TeamTalk DLL to X11. Instead it is recommended to check out TeamTalk Qt Client Example (qtTeamTalk) which shows how to convert X11 windows to bitmaps and use TT_SendDesktopWindow() for transmission.

Displaying Shared Desktop Window (or bitmap)

When a shared desktop window is received the event CLIENTEVENT_USER_DESKTOPWINDOW is posted to the local client instance. TT_AcquireUserDesktopWindow() can then be called to obtain a bitmap image of the shared window.

Desktop Cursor Sharing

It is also possible to share the position of the mouse cursor when sharing a desktop window. Use TT_SendDesktopCursorPosition() to transmit the position of the mouse cursor. When the position is received the event CLIENTEVENT_USER_DESKTOPCURSOR is posted to the local client instance with the mouse coordinates.

Remote Desktop Access

If a user has shared a desktop window it's possible for other users in the same channel to take over control of mouse and keyboard on the computer sharing the desktop window.

To access a remote desktop the user's UserAccount must have the userright USERRIGHT_TRANSMIT_DESKTOPINPUT.

Receive Desktop Input

In order for a client instance to allow remote desktop access it is required to first subscribe to desktop input from the user who wants access to the shared desktop window. This is done by calling TT_DoSubscribe() along with the user-id and subscription SUBSCRIBE_DESKTOPINPUT. Once desktop input (mouse or keyboard input) is received from a remote user the CLIENTEVENT_USER_DESKTOPINPUT event will be posted to the client instance. The actual mouse or keyboard input can then be obtained by accessing the DesktopInput member of the TTMessage. Afterwards TT_DesktopInput_Execute() can be used to execute the mouse or keyboard input.

Transmit Desktop Input

The remote user who wants to transmit mouse or keyboard input to the user sharing a desktop window can use TT_SendDesktopInput(). Remember that the user sharing the desktop window must have enabled the subscription SUBSCRIBE_DESKTOPINPUT.

Desktop Input and Keyboard Layouts

It can be quite troublesome to handle keyboard input since each key-code depends on the OS and the regional settings on the OS. E.g. on a German keyboard the Z key is located where the Y key is on a US keyboard. The German keyboard also has letters which don't even appear on a US keyboard.

Because of the issues with keyboard layouts and regional settings the TeamTalk API provides TT_DesktopInput_KeyTranslate() which can be used to translate a keyboard's scan-code to an intermediate format. If e.g. a client instance is running Windows then TT_DesktopInput_KeyTranslate() can be called with TTKEY_WINKEYCODE_TO_TTKEYCODE which converts the scan-code on a Windows keyboard to TeamTalk's intermediate format (TTKEYCODE). To be able to execute the key-code once it's received it must be converted back again from TeamTalk's intermediate format to the platform where the application is running. I.e. if the TTKEYCODE is received on a Mac then TT_DesktopInput_KeyTranslate() must be called with TTKEY_TTKEYCODE_TO_MACKEYCODE.

Translation of key-codes to TTKEYCODE-format.

When a key is pressed the OS generates a scan-code which denotes the location of the key on the keyboard. In order to generate the same key-press on a remote computer this scan-code must be converted to an intermediate format. The reason the scan-code cannot be sent directly is that the remote computer might use a different keyboard layout or run an operating system which has other values for the scan-codes.

The intermediate format for storing key-codes in TeamTalk is TTKEYCODE. Here's a table which shows how the keys on a US 104-keys keyboard are translated to TTKEYCODE.

   Symbol      | Shifted Symbol | Location | TTKEYCODE
   --------------------------------------------------
   Esc         |                |          | 0x0001
   1           | !              |          | 0x0002
   2           | @              |          | 0x0003
   3           | #              |          | 0x0004
   4           | $              |          | 0x0005
   5           | %              |          | 0x0006
   6           | ^              |          | 0x0007
   7           | &              |          | 0x0008
   8           |                |          | 0x0009
   9           | (              |          | 0x000a
   0           | )              |          | 0x000b
   -           | _              |          | 0x000c
   =           | +              |          | 0x000d
   Backspace   |                |          | 0x000e
   Tab         |                |          | 0x000f
   Q           |                |          | 0x0010
   W           |                |          | 0x0011
   E           |                |          | 0x0012
   R           |                |          | 0x0013
   T           |                |          | 0x0014
   Y           |                |          | 0x0015
   U           |                |          | 0x0016
   I           |                |          | 0x0017
   O           |                |          | 0x0018
   P           |                |          | 0x0019
   [           | {              |          | 0x001a
   ]           | }              |          | 0x001b
   Enter       |                |          | 0x001c
   Ctrl        |                | Left     | 0x001d
   A           |                |          | 0x001e
   S           |                |          | 0x001f
   D           |                |          | 0x0020
   F           |                |          | 0x0021
   G           |                |          | 0x0022
   H           |                |          | 0x0023
   J           |                |          | 0x0024
   K           |                |          | 0x0025
   L           |                |          | 0x0026
   ;           |                |          | 0x0027
   '           |                |          | 0x0028
   `           |                |          | 0x0029
   Shift       |                | Left     | 0x002a
   \\          | |              |          | 0x002b
   Z           |                |          | 0x002c
   X           |                |          | 0x002d
   C           |                |          | 0x002e
   V           |                |          | 0x002f
   B           |                |          | 0x0030
   N           |                |          | 0x0031
   M           |                |          | 0x0032
   ,           | <              |          | 0x0033
   .           | >              |          | 0x0034
   /           | ?              |          | 0x0035
   Shift       |                | Right    | 0x0036
   \*          |                |          | 0x0037
   Alt         |                |          | 0x0038
   Space bar   |                |          | 0x0039
   Caps Lock   |                |          | 0x003a
   F1          |                |          | 0x003b
   F2          |                |          | 0x003c
   F3          |                |          | 0x003d
   F4          |                |          | 0x003e
   F5          |                |          | 0x003f
   F6          |                |          | 0x0040
   F7          |                |          | 0x0041
   F8          |                |          | 0x0042
   F9          |                |          | 0x0043
   Num Lock    |                | Numpad   | 0x0044
   Scroll Lock |                |          | 0x0046
   Home        | 7              | Numpad   | 0x0047
   Up arrow    | 8              | Numpad   | 0x0048
   PgUp        | 9              | Numpad   | 0x0049
   -           |                | Numpad   | 0x004a
   Left arrow  | 4              | Numpad   | 0x004b
   5           |                | Numpad   | 0x004c
   Right arrow | 6              | Numpad   | 0x004d
   +           |                | Numpad   | 0x004e
   End         | 1              | Numpad   | 0x004f
   Down arrow  | 2              | Numpad   | 0x0050
   PgDn        | 3              | Numpad   | 0x0051
   Insert      | 0              | Numpad   | 0x0052
   Delete      |                | Numpad   | 0x0053
   F11         |                |          | 0x0057
   F12         |                |          | 0x0058
   Break       | Pause          |          | 0x0100
   Enter       |                | Numpad   | 0x011c
   Ctrl        |                | Right    | 0x011d
   /           |                | Numpad   | 0x0135
   SysRq       | Print Scrn     |          | 0x0137
   Alt         |                | Right    | 0x0138
   Home        |                | Funcpad  | 0x0147
   Up arrow    |                | Funcpad  | 0x0148
   Page Up     |                | Funcpad  | 0x0149
   Left arrow  |                | Funcpad  | 0x014b
   Right arrow |                | Funcpad  | 0x014d
   End         |                | Funcpad  | 0x014f
   Down arrow  |                | Funcpad  | 0x0150
   Page Down   |                | Funcpad  | 0x0151
   Insert      |                | Funcpad  | 0x0152
   Delete      |                | Funcpad  | 0x0153
   Windows     |                | Left     | 0x015b
   Windows     |                | Right    | 0x015c
   Menu        |                |          | 0x015d
               |                |          | 
   <           |                | Non-US   | 0x0056
               |                |          | 
   Mouse btn   |                | Left     | 0x1000
   Mouse btn   |                | Right    | 0x1001
   Mouse btn   |                | Middle   | 0x1002

Macro Definition Documentation

◆ TT_DESKTOPINPUT_MAX

#define TT_DESKTOPINPUT_MAX 16

The maximum number DesktopInput instances which can be sent by TT_SendDesktopInput().

Definition at line 162 of file TeamTalk.h.

◆ TT_DESKTOPINPUT_KEYCODE_IGNORE

#define TT_DESKTOPINPUT_KEYCODE_IGNORE 0xFFFFFFFF

If uKeyCode in DesktopInput is set to TT_DESKTOPINPUT_KEYCODE_IGNORE it means no key (or mouse button) was pressed in the desktop input event and TT_DesktopInput_Execute() will ignore the value.

Definition at line 171 of file TeamTalk.h.

◆ TT_DESKTOPINPUT_MOUSEPOS_IGNORE

#define TT_DESKTOPINPUT_MOUSEPOS_IGNORE 0xFFFF

If uMousePosX or uMousePosY in DesktopInput are set to TT_DESKTOPINPUT_MOUSEPOS_IGNORE it means the mouse position is ignored when calling TT_DesktopInput_Execute().

Definition at line 179 of file TeamTalk.h.

◆ TT_DESKTOPINPUT_KEYCODE_LMOUSEBTN

#define TT_DESKTOPINPUT_KEYCODE_LMOUSEBTN 0x1000

If uKeyCode of DesktopInput is set to TT_DESKTOPINPUT_KEYCODE_LMOUSEBTN then TT_DesktopInput_Execute() will see the key-code as a left mouse button click.

Definition at line 187 of file TeamTalk.h.

◆ TT_DESKTOPINPUT_KEYCODE_RMOUSEBTN

#define TT_DESKTOPINPUT_KEYCODE_RMOUSEBTN 0x1001

If uKeyCode of DesktopInput is set to TT_DESKTOPINPUT_KEYCODE_RMOUSEBTN then TT_DesktopInput_Execute() will see the key-code as a right mouse button click.

Definition at line 195 of file TeamTalk.h.

◆ TT_DESKTOPINPUT_KEYCODE_MMOUSEBTN

#define TT_DESKTOPINPUT_KEYCODE_MMOUSEBTN 0x1002

If uKeyCode of DesktopInput is set to TT_DESKTOPINPUT_KEYCODE_MMOUSEBTN then TT_DesktopInput_Execute() will see the key-code as a middle mouse button click.

Definition at line 203 of file TeamTalk.h.

Typedef Documentation

◆ BitmapFormat

typedef enum BitmapFormat BitmapFormat

The bitmap format used for a DesktopWindow.

◆ DesktopProtocol

typedef enum DesktopProtocol DesktopProtocol

The protocols supported for transferring a DesktopWindow.

So far only one, UDP-based, protocol is supported.

◆ DesktopWindow

typedef struct DesktopWindow DesktopWindow

A struct containing the properties of a shared desktop window.

The desktop window is a description of the bitmap which can be retrieved using TT_AcquireUserDesktopWindow() or the bitmap which should be transmitted using TT_SendDesktopWindow().

◆ DesktopKeyState

typedef enum DesktopKeyState DesktopKeyState

The state of a key (or mouse button), i.e. if it's pressed or released.

See also: DesktopInput

◆ DesktopKeyStates

typedef UINT32 DesktopKeyStates

Mask of key states.

Definition at line 1015 of file TeamTalk.h.

◆ DesktopInput

typedef struct DesktopInput DesktopInput

A struct containing a mouse or keyboard event.

The DesktopInput struct is used for desktop access where a remote user can control mouse or keybaord on a shared desktop. Check out section Remote Desktop Access on how to use remote desktop access.

◆ ShareWindow

typedef struct ShareWindow ShareWindow

A struct which describes the properties of a window which can be shared.

See also: TT_Windows_GetDesktopWindowHWND(); TT_Windows_GetWindow(); TT_MacOS_GetWindow(); TT_MacOS_GetWindowFromWindowID()

◆ TTKeyTranslate

typedef enum TTKeyTranslate TTKeyTranslate

Translate to and from TeamTalk's intermediate key-codes (TTKEYCODE).

See also: CLIENTEVENT_USER_DESKTOPINPUT

Enumeration Type Documentation

◆ BitmapFormat

enum BitmapFormat

The bitmap format used for a DesktopWindow.

Enumerator
BMP_NONE	Used to denote nothing selected.
BMP_RGB8_PALETTE	The bitmap is a 256-colored bitmap requiring a palette. The default 256 colored palette is the Netscape browser-safe palette. Use TT_Palette_GetColorTable() to access or change the palette. The maximum size of a 8-bit bitmap is 4095 blocks of 120 by 34 pixels.
BMP_RGB16_555	The bitmap is a 16-bit colored bitmap. The maximum pixels.
BMP_RGB24	The bitmap is a 24-bit colored bitmap. The maximum size of a 24-bit bitmap is 4095 blocks of 85 by 16 pixels.
BMP_RGB32	The bitmap is a 32-bit colored bitmap. The maximum size of a 32-bit bitmap is 4095 blocks of 51 by 20 pixels.

Definition at line 934 of file TeamTalk.h.

◆ DesktopProtocol

enum DesktopProtocol

The protocols supported for transferring a DesktopWindow.

So far only one, UDP-based, protocol is supported.

Enumerator
DESKTOPPROTOCOL_ZLIB_1	Desktop protocol based on ZLIB for image compression and UDP for data transmission.

Definition at line 961 of file TeamTalk.h.

◆ DesktopKeyState

enum DesktopKeyState

The state of a key (or mouse button), i.e. if it's pressed or released.

See also: DesktopInput

Enumerator
DESKTOPKEYSTATE_NONE	The key is ignored.
DESKTOPKEYSTATE_DOWN	The key is pressed.
DESKTOPKEYSTATE_UP	The key is released.

Definition at line 1004 of file TeamTalk.h.

◆ TTKeyTranslate

enum TTKeyTranslate

Translate to and from TeamTalk's intermediate key-codes (TTKEYCODE).

See also: CLIENTEVENT_USER_DESKTOPINPUT

Enumerator
TTKEY_NO_TRANSLATE	Perform no translation.
TTKEY_WINKEYCODE_TO_TTKEYCODE	Translate from Windows scan-code to TTKEYCODE. The Windows scan-code can be retrieved in Windows' `WM_KEYDOWN` and `WM_KEYUP` event.
TTKEY_TTKEYCODE_TO_WINKEYCODE	Translate from TTKEYCODE to Windows scan-code.
TTKEY_MACKEYCODE_TO_TTKEYCODE	Translate from Mac OS X Carbon `kVK_*` key-code to TTKEYCODE. The Mac OS X key-codes are defined in Carbon's API.
TTKEY_TTKEYCODE_TO_MACKEYCODE	Translate from TTKEYCODE to Mac OS X Carbon `kVK_*` key-code.

Definition at line 7728 of file TeamTalk.h.

Function Documentation

◆ TT_SendDesktopWindow()

TEAMTALKDLL_API INT32 TT_SendDesktopWindow	(	IN TTInstance *	lpTTInstance,
		IN const DesktopWindow *	lpDesktopWindow,
		IN BitmapFormat	nConvertBmpFormat
	)

Transmit a desktop window (bitmap) to users in the same channel.

When TT_SendDesktopWindow() is called the first time a new desktop session will be started. To update the current desktop session call TT_SendDesktopWindow() again once the previous desktop transmission has finished. Tracking progress of the current desktop transmission is done by checking for the CLIENTEVENT_DESKTOPWINDOW_TRANSFER event. While the desktop transmission is active the flag CLIENT_TX_DESKTOP will be set on the local client instance.

If the desktop window (bitmap) changes size (width/height) or format a new desktop session will be started. Also if the user changes channel a new desktop session will be started. Check nSessionID of DesktopWindow to see if a new desktop session is started or the CLIENTEVENT_USER_DESKTOPWINDOW event.

Remote users will get the CLIENTEVENT_USER_DESKTOPWINDOW event and can call TT_AcquireUserDesktopWindow() to retrieve the desktop window.

User rights required:

USERRIGHT_TRANSMIT_DESKTOP

Parameters

lpTTInstance	Pointer to client instance created by TT_InitTeamTalk.
lpDesktopWindow	Properties of the bitmap. Set the `nSessionID` property to 0.
nConvertBmpFormat	Before transmission convert the bitmap to this format.

Returns: TRUE if desktop window is queued for transmission. FALSE if nBitmapSize is invalid or if a desktop transmission is already active.; -1 on error. 0 if bitmap has no changes. Greater than 0 on success.

See also: TT_CloseDesktopWindow(); TT_SendDesktopCursorPosition()

◆ TT_CloseDesktopWindow()

TEAMTALKDLL_API TTBOOL TT_CloseDesktopWindow ( IN TTInstance * lpTTInstance )

Close the current desktop session.

Closing the desktop session will cause the users receiving the current desktop session to see the desktop session ID change to 0 in the CLIENTEVENT_USER_DESKTOPWINDOW event.

Parameters

lpTTInstance Pointer to client instance created by TT_InitTeamTalk.

◆ TT_Palette_GetColorTable()

TEAMTALKDLL_API unsigned char * TT_Palette_GetColorTable	(	IN BitmapFormat	nBmpPalette,
		IN INT32	nIndex
	)

Get RGB values of the palette for the bitmap format.

This currently only applies to bitmaps of format BMP_RGB8_PALETTE.

Note that the pointer returned is non-const which means the palette can be overwritten with a custom palette. The custom palette will then be used internally during bitmap conversion.

Parameters

nBmpPalette	The bitmap format. Currently only BMP_RGB8_PALETTE is supported.
nIndex	The index in the color table of the RGB values to extract.

Returns: Pointer to RGB colors. First byte is Red, second Blue and third Green. Returns NULL if the color-index is invalid.

◆ TT_Windows_GetDesktopActiveHWND()

TEAMTALKDLL_API HWND TT_Windows_GetDesktopActiveHWND ( void )

Get the handle (HWND) of the window which is currently active (focused) on the Windows desktop.

◆ TT_Windows_GetDesktopHWND()

TEAMTALKDLL_API HWND TT_Windows_GetDesktopHWND ( void )

Get the handle (HWND) of the Windows desktop (full desktop).

◆ TT_Windows_GetDesktopWindowHWND()

TEAMTALKDLL_API TTBOOL TT_Windows_GetDesktopWindowHWND	(	IN INT32	nIndex,
		OUT HWND *	lpHWnd
	)

Enumerate all the handles (HWND) of visible windows. Increment nIndex until the function returns FALSE. Use TT_Windows_GetWindow() to get information about each window.

◆ TT_Windows_GetWindow()

TEAMTALKDLL_API TTBOOL TT_Windows_GetWindow	(	IN HWND	hWnd,
		OUT ShareWindow *	lpShareWindow
	)

Get the properties of a window from its window handle (HWND).

◆ TT_SendDesktopWindowFromHWND()

TEAMTALKDLL_API INT32 TT_SendDesktopWindowFromHWND	(	IN TTInstance *	lpTTInstance,
		IN HWND	hWnd,
		IN BitmapFormat	nBitmapFormat,
		IN DesktopProtocol	nDesktopProtocol
	)

Transmit the specified window in a desktop session.

Same as TT_SendDesktopWindow() except the properties for the DesktopWindow are extracted automatically.

Parameters

lpTTInstance	Pointer to client instance created by TT_InitTeamTalk.
hWnd	Windows handle for the window to transmit.
nBitmapFormat	Bitmap format to use for the transmitted image.
nDesktopProtocol	The protocol to use for transmitting the image.

Returns: See TT_SendDesktopWindow().

◆ TT_PaintDesktopWindow()

TEAMTALKDLL_API TTBOOL TT_PaintDesktopWindow	(	IN TTInstance *	lpTTInstance,
		IN INT32	nUserID,
		IN HDC	hDC,
		IN INT32	XDest,
		IN INT32	YDest,
		IN INT32	nDestWidth,
		IN INT32	nDestHeight
	)

Paint user's desktop window using a Windows' DC (device context).

Same as calling TT_PaintDesktopWindowEx() like this:

TT_PaintDesktopWindowEx(lpTTInstance, nUserID, hDC, 
                        XDest, YDest, nDestWidth,
                        nDestHeight, 0, 0, 
                        'src_bmp_width', 'src_bmp_height');

src_bmp_width and src_bmp_height are extracted internally from the source image.

◆ TT_PaintDesktopWindowEx()

TEAMTALKDLL_API TTBOOL TT_PaintDesktopWindowEx	(	IN TTInstance *	lpTTInstance,
		IN INT32	nUserID,
		IN HDC	hDC,
		IN INT32	XDest,
		IN INT32	YDest,
		IN INT32	nDestWidth,
		IN INT32	nDestHeight,
		IN INT32	XSrc,
		IN INT32	YSrc,
		IN INT32	nSrcWidth,
		IN INT32	nSrcHeight
	)

Paint user's desktop window using a Windows' DC (device context).

An application can either paint a bitmap by using TT_AcquireUserDesktopWindow() which provides a pointer to a bitmap or the application can ask the client instance to paint the image using this function.

Typically this paint operation will be called in the WM_PAINT message. Here is how the client instance paints internally:

StretchDIBits(hDC, nPosX, nPosY, nWidth, nHeight, XSrc, YSrc, 
              nSrcWidth, nSrcHeight, frame_buf, &bmi,
              DIB_RGB_COLORS, SRCCOPY);

Parameters

lpTTInstance	Pointer to client instance created by TT_InitTeamTalk.
nUserID	The user's ID.
hDC	The handle to the Windows device context.
XDest	Coordinate of left corner where to start painting.
YDest	Coordinate or top corner where to start painting.
nDestWidth	The width of the image.
nDestHeight	The height of the image.
XSrc	The left coordinate in the source bitmap of where to start reading.
YSrc	The top left coordinate in the source bitmap of where to start reading.
nSrcWidth	The number of width pixels to read from source bitmap.
nSrcHeight	The number of height pixels to read from source bitmap.

Returns: TRUE on success. FALSE on error, e.g. if user doesn't exist.

See also: TT_AcquireUserDesktopWindow()

◆ TT_MacOS_GetWindow()

TEAMTALKDLL_API TTBOOL TT_MacOS_GetWindow	(	IN INT32	nIndex,
		OUT ShareWindow *	lpShareWindow
	)

Enumerate all windows on the desktop. Increment nIndex until the function returns FALSE. Use TT_MacOS_GetWindowFromWindowID() to get information about the window, e.g. title, dimensions, etc.

◆ TT_MacOS_GetWindowFromWindowID()

TEAMTALKDLL_API TTBOOL TT_MacOS_GetWindowFromWindowID	(	IN INT64	nWindowID,
		OUT ShareWindow *	lpShareWindow
	)

Get information about a window by passing its handle (CGWindowID).

See also: TT_MacOS_GetWindow()

◆ TT_SendDesktopFromWindowID()

TEAMTALKDLL_API INT32 TT_SendDesktopFromWindowID	(	IN TTInstance *	lpTTInstance,
		IN INT64	nWindowID,
		IN BitmapFormat	nBitmapFormat,
		IN DesktopProtocol	nDesktopProtocol
	)

Transmit the specified window in a desktop session.

Same as TT_SendDesktopWindow() except the properties for the DesktopWindow are extracted automatically.

Parameters

lpTTInstance	Pointer to client instance created by TT_InitTeamTalk.
nWindowID	The handle of the window which should be converted to bitmap and sent to the server.
nBitmapFormat	Bitmap format to use for the transmitted image.
nDesktopProtocol	The protocol to use for transmitting the image.

Returns: See TT_SendDesktopWindow().

◆ TT_SendDesktopCursorPosition()

TEAMTALKDLL_API TTBOOL TT_SendDesktopCursorPosition	(	IN TTInstance *	lpTTInstance,
		IN UINT16	nPosX,
		IN UINT16	nPosY
	)

Send the position of mouse cursor to users in the same channel.

It's only possible to send the mouse cursor position if there's a desktop session which is currently active.

User rights required:

USERRIGHT_TRANSMIT_DESKTOP

Parameters

lpTTInstance	Pointer to client instance created by TT_InitTeamTalk.
nPosX	X coordinate of mouse cursor.
nPosY	Y coordinate of mouse cursor.

See also: TT_SendDesktopWindow()

◆ TT_SendDesktopInput()

TEAMTALKDLL_API TTBOOL TT_SendDesktopInput	(	IN TTInstance *	lpTTInstance,
		IN INT32	nUserID,
		IN const DesktopInput	lpDesktopInputs[TT_DESKTOPINPUT_MAX],
		IN INT32	nDesktopInputCount
	)

Send a mouse or keyboard event to a shared desktop window.

If a user is sharing a desktop window it's possible for a remote user to take control of mouse and keyboard input on the remote computer. Read section Transmit Desktop Input on how to transmit desktop input to a shared window.

When the remote user receives the issued DesktopInput the event CLIENTEVENT_USER_DESKTOPINPUT is posted to the client instance sharing the desktop window.

User rights required:

USERRIGHT_TRANSMIT_DESKTOPINPUT

Parameters

lpTTInstance	Pointer to client instance created by TT_InitTeamTalk.
nUserID	The user's ID who owns the shared desktop window and should receive desktop input.
lpDesktopInputs	An array of DesktopInput structs which should be transmitted to the user. Internally in the client instance each user ID has an internal queue which can contain a maximum of 100 DesktopInput structs.
nDesktopInputCount	Must be less or equal to TT_DESKTOPINPUT_MAX.

Returns: FALSE If user doesn't exist or if desktop input queue is full or if nUserID doesn't subscribe to desktop input.

◆ TT_AcquireUserDesktopWindow()

TEAMTALKDLL_API DesktopWindow * TT_AcquireUserDesktopWindow	(	IN TTInstance *	lpTTInstance,
		IN INT32	nUserID
	)

Acquire a user's desktop window (bitmap image).

A user's desktop window can be extracted when the CLIENTEVENT_USER_DESKTOPWINDOW is received.

When the DesktopWindow is no longer needed call TT_ReleaseUserDesktopWindow() to release the memory allocated by the client instance.

A desktop window is simply a bitmap image. This method is used for retrieving the user's bitmap image.

For BMP_RGB8_PALETTE bitmaps check out TT_Palette_GetColorTable().

To convert bitmap to a different format use TT_AcquireUserDesktopWindowEx().

Parameters

lpTTInstance	Pointer to client instance created by TT_InitTeamTalk.
nUserID	The user's ID.

Returns: NULL If there's no active desktop window for this user.

See also: TT_SendDesktopWindow()

◆ TT_AcquireUserDesktopWindowEx()

TEAMTALKDLL_API DesktopWindow * TT_AcquireUserDesktopWindowEx	(	IN TTInstance *	lpTTInstance,
		IN INT32	nUserID,
		IN BitmapFormat	nBitmapFormat
	)

Same as TT_AcquireUserDesktopWindow() except an extra option for converting bitmap to a different format.

It is highly adviced to use TT_AcquireUserDesktopWindow() since converting to a different bitmap format is very inefficient.

Parameters

lpTTInstance	Pointer to client instance created by TT_InitTeamTalk.
nUserID	The user's ID.
nBitmapFormat	The bitmap format to convert to.

Returns: NULL If there's no active desktop window for this user.

◆ TT_ReleaseUserDesktopWindow()

TEAMTALKDLL_API TTBOOL TT_ReleaseUserDesktopWindow	(	IN TTInstance *	lpTTInstance,
		IN DesktopWindow *	lpDesktopWindow
	)

Release memory allocated by the DesktopWindow.

Parameters

lpTTInstance	Pointer to client instance created by TT_InitTeamTalk.
lpDesktopWindow	Pointer to DesktopWindow to release.

See also: TT_AcquireUserDesktopWindow()

◆ TT_DesktopInput_KeyTranslate()

TEAMTALKDLL_API INT32 TT_DesktopInput_KeyTranslate	(	TTKeyTranslate	nTranslate,
		IN const DesktopInput *	lpDesktopInputs,
		OUT DesktopInput *	lpTranslatedDesktopInputs,
		IN INT32	nDesktopInputCount
	)

Translate platform key-code to and from TeamTalk's intermediate format.

Section Translation of key-codes to TTKEYCODE-format. has a table which shows how the keys on a US 104-keyboard are translated to TeamTalk's intermediate format.

Section Desktop Input and Keyboard Layouts explains how to transmit key-codes.

Parameters

nTranslate	The key-code format to translate to and from.
lpDesktopInputs	An array of DesktopInput structs to translate.
lpTranslatedDesktopInputs	A pre-allocated array of DesktopInput struct to hold the translated desktop input.
nDesktopInputCount	The number of elements to translate in `lpDesktopInputs`.

Returns: The number of translated DesktopInput stucts. If value is different from nDesktopInputCount then some uKeyCode values could not be translated and have been assigned the value TT_DESKTOPINPUT_KEYCODE_IGNORE.

See also: TT_SendDesktopInput(); TT_DesktopInput_Execute()

◆ TT_DesktopInput_Execute()

TEAMTALKDLL_API INT32 TT_DesktopInput_Execute	(	IN const DesktopInput *	lpDesktopInputs,
		IN INT32	nDesktopInputCount
	)

Execute desktop (mouse or keyboard) input.

When executed either a key-press, key-release or mouse move will take place on the computer running the client instance. Remember to calculate the offsets for the mouse cursor prior to this call. The mouse position will be relative to the screen resolution.

The content of the DesktopInput struct must been translated to the platform's key-code format prior to this call. I.e. uKeyCode must be a either a Windows scan-code, Mac OS X Carbon key-code or one of the mouse buttons: TT_DESKTOPINPUT_KEYCODE_LMOUSEBTN, TT_DESKTOPINPUT_KEYCODE_RMOUSEBTN, TT_DESKTOPINPUT_KEYCODE_MMOUSEBTN.

Parameters

lpDesktopInputs	The mouse or keyboard inputs.
nDesktopInputCount	The number of elements in `lpDesktopInputs`.

Returns: The number of mouse and keyboard events inserted.

See also: TT_DesktopInput_KeyTranslate()

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Send Desktop Window (or bitmap)

Windows Desktop Sharing

Mac OS Desktop Sharing

Linux Desktop Sharing

Displaying Shared Desktop Window (or bitmap)

Desktop Cursor Sharing

Remote Desktop Access

Receive Desktop Input

Transmit Desktop Input

Desktop Input and Keyboard Layouts

Translation of key-codes to TTKEYCODE-format.

Macro Definition Documentation

◆ TT_DESKTOPINPUT_MAX

◆ TT_DESKTOPINPUT_KEYCODE_IGNORE

◆ TT_DESKTOPINPUT_MOUSEPOS_IGNORE

◆ TT_DESKTOPINPUT_KEYCODE_LMOUSEBTN

◆ TT_DESKTOPINPUT_KEYCODE_RMOUSEBTN

◆ TT_DESKTOPINPUT_KEYCODE_MMOUSEBTN

Typedef Documentation

◆ BitmapFormat

◆ DesktopProtocol

◆ DesktopWindow

◆ DesktopKeyState

◆ DesktopKeyStates

◆ DesktopInput

◆ ShareWindow

◆ TTKeyTranslate

Enumeration Type Documentation

◆ BitmapFormat

◆ DesktopProtocol

◆ DesktopKeyState

◆ TTKeyTranslate

Function Documentation

◆ TT_SendDesktopWindow()

◆ TT_CloseDesktopWindow()

◆ TT_Palette_GetColorTable()

◆ TT_Windows_GetDesktopActiveHWND()

◆ TT_Windows_GetDesktopHWND()

◆ TT_Windows_GetDesktopWindowHWND()

◆ TT_Windows_GetWindow()

◆ TT_SendDesktopWindowFromHWND()

◆ TT_PaintDesktopWindow()

◆ TT_PaintDesktopWindowEx()

◆ TT_MacOS_GetWindow()

◆ TT_MacOS_GetWindowFromWindowID()

◆ TT_SendDesktopFromWindowID()

◆ TT_SendDesktopCursorPosition()

◆ TT_SendDesktopInput()

◆ TT_AcquireUserDesktopWindow()

◆ TT_AcquireUserDesktopWindowEx()

◆ TT_ReleaseUserDesktopWindow()

◆ TT_DesktopInput_KeyTranslate()

◆ TT_DesktopInput_Execute()