TeamTalk 4 C-API DLL  Version 4.5A
Desktop Sharing

A user can transmit a desktop window to other users in a channel by passing the handle of a window to the TeamTalk client DLL. The TeamTalk client 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. More...

Classes

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

Typedefs

typedef enum BitmapFormat BitmapFormat
 The bitmap format used for a DesktopWindow. More...
 
typedef enum DesktopProtocol DesktopProtocol
 The protocols supported for transferring a DesktopWindow. More...
 
typedef struct DesktopWindow DesktopWindow
 A struct containing the properties of a shared desktop window. More...
 
typedef struct ShareWindow ShareWindow
 A struct which describes the properties of a window which can be shared. More...
 

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...
 

Functions

TEAMTALKDLL_API INT32 TT_SendDesktopWindow (IN TTInstance *lpTTInstance, IN const VOID *lpBitmap, IN INT32 nBitmapSize, IN const DesktopWindow *lpDesktopWindow, IN BitmapFormat nConvertBmpFormat)
 Transmit a desktop window (bitmap) to users in the same channel. More...
 
TEAMTALKDLL_API BOOL TT_CloseDesktopWindow (IN TTInstance *lpTTInstance)
 Close the current desktop session. More...
 
TEAMTALKDLL_API unsigned char * TT_Palette_GetColorTable (IN BitmapFormat nBmpPalette, IN INT32 nIndex)
 Get RGB values of the palette for the bitmap format. More...
 
TEAMTALKDLL_API HWND TT_Windows_GetDesktopActiveHWND ()
 Get the handle (HWND) of the window which is currently active (focused) on the Windows desktop. More...
 
TEAMTALKDLL_API HWND TT_Windows_GetDesktopHWND ()
 Get the handle (HWND) of the Windows desktop (full desktop). More...
 
TEAMTALKDLL_API BOOL 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. More...
 
TEAMTALKDLL_API BOOL TT_Windows_GetWindow (IN HWND hWnd, OUT ShareWindow *lpShareWindow)
 Get the properties of a window from its window handle (HWND). More...
 
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. More...
 
TEAMTALKDLL_API BOOL 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). More...
 
TEAMTALKDLL_API BOOL 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). More...
 
TEAMTALKDLL_API BOOL 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. More...
 
TEAMTALKDLL_API BOOL TT_MacOS_GetWindowFromWindowID (IN INT64 nWindowID, OUT ShareWindow *lpShareWindow)
 Get information about a window by passing its handle (CGWindowID). More...
 
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. More...
 
TEAMTALKDLL_API BOOL TT_SendDesktopCursorPosition (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN INT32 nPosX, IN INT32 nPosY)
 Send the position of mouse cursor to users in the same channel. More...
 
TEAMTALKDLL_API BOOL TT_GetUserDesktopWindow (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN OUT VOID *lpBitmap, IN OUT INT32 *lpnBitmapSize, OUT DesktopWindow *lpDesktopWindow)
 Get a user's desktop window (bitmap image). More...
 
TEAMTALKDLL_API BOOL TT_GetUserDesktopCursor (IN TTInstance *lpTTInstance, IN INT32 nSrcUserID, IN INT32 nDestUserID, OUT INT32 *lpnPosX, OUT INT32 *lpnPosY)
 Get the mouse cursor position of a user. More...
 

Detailed Description

A user can transmit a desktop window to other users in a channel by passing the handle of a window to the TeamTalk client DLL. The TeamTalk client 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.

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:

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

Mac OS Desktop Sharing

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

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

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 Qt Client Example (TeamTalk4) 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 WM_TEAMTALK_USER_DESKTOPWINDOW is posted to the local client instance. TT_GetUserDesktopWindow() 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 WM_TEAMTALK_USER_DESKTOPCURSOR is posted to the local client instance. TT_GetUserDesktopCursor() can then be used to obtain the cursor position.

Typedef Documentation

typedef enum BitmapFormat BitmapFormat

The bitmap format used for a DesktopWindow.

The protocols supported for transferring a DesktopWindow.

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

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_GetUserDesktopWindow() or the bitmap which should be transmitted using TT_SendDesktopWindow().

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()

Enumeration Type Documentation

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 size of a 16-bit bitmap is 4095 blocks of 102 by 20 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.

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.

Function Documentation

TEAMTALKDLL_API INT32 TT_SendDesktopWindow ( IN TTInstance lpTTInstance,
IN const VOID *  lpBitmap,
IN INT32  nBitmapSize,
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 WM_TEAMTALK_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 WM_TEAMTALK_USER_DESKTOPWINDOW event.

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

Note
Requires server version 4.3.0.1490 or later.
Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
lpBitmapPointer to bitmap buffer.
nBitmapSizeSize of bitmap buffer lpBitmap in bytes. The size of the bitmap can be calculated using the DesktopWindow-struct's nBytesPerLine multiplied by the nHeight.
lpDesktopWindowProperties of the bitmap. Set the nSessionID property to 0.
nConvertBmpFormatBefore 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()
TEAMTALKDLL_API BOOL 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 WM_TEAMTALK_USER_DESKTOPWINDOW event.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
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
nBmpPaletteThe bitmap format. Currently only BMP_RGB8_PALETTE is supported.
nIndexThe 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.
TEAMTALKDLL_API HWND TT_Windows_GetDesktopActiveHWND ( )

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

TEAMTALKDLL_API HWND TT_Windows_GetDesktopHWND ( )

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

TEAMTALKDLL_API BOOL 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 BOOL 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.

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

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
hWndWindows handle for the window to transmit.
nBitmapFormatBitmap format to use for the transmitted image.
nDesktopProtocolThe protocol to use for transmitting the image.
Returns
See TT_SendDesktopWindow().
TEAMTALKDLL_API BOOL 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.

TEAMTALKDLL_API BOOL 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_GetUserDesktopWindow() 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDThe user's ID.
hDCThe handle to the Windows device context.
XDestCoordinate of left corner where to start painting.
YDestCoordinate or top corner where to start painting.
nDestWidthThe width of the image.
nDestHeightThe height of the image.
XSrcThe left coordinate in the source bitmap of where to start reading.
YSrcThe top left coordinate in the source bitmap of where to start reading.
nSrcWidthThe number of width pixels to read from source bitmap.
nSrcHeightThe 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_GetUserDesktopWindow()
TEAMTALKDLL_API BOOL 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 BOOL TT_MacOS_GetWindowFromWindowID ( IN INT64  nWindowID,
OUT ShareWindow lpShareWindow 
)

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

See Also
TT_MacOS_GetWindow()
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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nWindowIDThe handle of the window which should be converted to bitmap and sent to the server.
nBitmapFormatBitmap format to use for the transmitted image.
nDesktopProtocolThe protocol to use for transmitting the image.
Returns
See TT_SendDesktopWindow().
TEAMTALKDLL_API BOOL TT_SendDesktopCursorPosition ( IN TTInstance lpTTInstance,
IN INT32  nUserID,
IN INT32  nPosX,
IN INT32  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.

Note
Requires server version 4.3.0.1490 or later.
Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDFor now set to 0.
nPosXX coordinate of mouse cursor. Max is 65535.
nPosYY coordinate of mouse cursor. Max is 65535.
See Also
TT_SendDesktopWindow()
TEAMTALKDLL_API BOOL TT_GetUserDesktopWindow ( IN TTInstance lpTTInstance,
IN INT32  nUserID,
IN OUT VOID *  lpBitmap,
IN OUT INT32 *  lpnBitmapSize,
OUT DesktopWindow lpDesktopWindow 
)

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

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

A desktop window is simply a bitmap image. This method is used for copying the user's bitmap image to a pre-allocated buffer.

To know the properties of the bitmap call this method with lpBitmap set to NULL and extract the properties in lpDesktopWindow. The size of the buffer to allocate will be nBytesPerLine multiplied by nHeight in the DesktopWindow.

For BMP_RGB8_PALETTE bitmaps check out TT_Palette_GetColorTable().

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDThe user's ID.
lpBitmapPointer to a pre-allocated buffer where the bitmap data will be copied to. Pass NULL to query the byte size of the bitmap, so it can be written to lpnBitmapSize and lpDesktopWindow.
lpnBitmapSizeSize of the allocated bitmap buffer lpBitmap. If lpBitmap is NULL the size of the bitmap will be written to this parameter.
lpDesktopWindowThe properties of the shared desktop window. Pass NULL to lpBitmap to query the properties of the desktop window.
Returns
FALSE if there's no active desktop window for this user.
See Also
TT_SendDesktopWindow()
TEAMTALKDLL_API BOOL TT_GetUserDesktopCursor ( IN TTInstance lpTTInstance,
IN INT32  nSrcUserID,
IN INT32  nDestUserID,
OUT INT32 *  lpnPosX,
OUT INT32 *  lpnPosY 
)

Get the mouse cursor position of a user.

The mouse cursor position will be available when the WM_TEAMTALK_USER_DESKTOPCURSOR is received and there's an active desktop session.

A mouse cursor position is transmitted using TT_SendDesktopCursorPosition().

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nSrcUserIDThe owner of the cursor.
nDestUserIDThe owner of the desktop session where the cursor is pointing to.
lpnPosXOutput parameter for X coordinate.
lpnPosYOutput parameter for Y coordinate.