Files
file	rfbclient.h

Data Structures
struct	rfbVNCRec
	vncrec More...

struct	rfbClientData
	client data More...

struct	AppData
	app data (belongs into rfbClient?) More...

union	rfbCredential
	For GetCredentialProc callback function to return. More...

struct	rfbClient

struct	rfbClientProtocolExtension

Macros
#define	rfbClientSwap16IfLE(s) ((char )&client->endianTest ? ((((s) & 0xff) << 8) \| (((s) >> 8) & 0xff)) : (s))

#define	rfbClientSwap32IfLE(l)

#define	rfbClientSwap64IfLE(l)

#define	FLASH_PORT_OFFSET 5400

#define	LISTEN_PORT_OFFSET 5500

#define	TUNNEL_PORT_OFFSET 5500

#define	SERVER_PORT_OFFSET 5900

#define	DEFAULT_CONNECT_TIMEOUT 60

#define	DEFAULT_READ_TIMEOUT 0

#define	DEFAULT_SSH_CMD "/usr/bin/ssh"

#define	DEFAULT_TUNNEL_CMD (DEFAULT_SSH_CMD " -f -L %L:localhost:%R %H sleep 20")

#define	DEFAULT_VIA_CMD (DEFAULT_SSH_CMD " -f -L %L:%H:%R %G sleep 20")

#define	rfbCredentialTypeX509 1

#define	rfbCredentialTypeUser 2

#define	rfbX509CrlVerifyNone 0 /* No CRL checking is performed */

#define	rfbX509CrlVerifyClient 1 /* Only the leaf server certificate is checked */

#define	rfbX509CrlVerifyAll 2 /* All certificates in the server chain are checked */

Typedefs
typedef void(*	HandleTextChatProc) (struct _rfbClient client, int value, char text)
	Handles a text chat message. More...

typedef void(*	HandleXvpMsgProc) (struct _rfbClient *client, uint8_t version, uint8_t opcode)
	Handles XVP server messages. More...

typedef void(*	HandleKeyboardLedStateProc) (struct _rfbClient *client, int value, int pad)

typedef rfbBool(*	HandleCursorPosProc) (struct _rfbClient *client, int x, int y)

typedef void(*	SoftCursorLockAreaProc) (struct _rfbClient *client, int x, int y, int w, int h)

typedef void(*	SoftCursorUnlockScreenProc) (struct _rfbClient *client)

typedef void(*	GotFrameBufferUpdateProc) (struct _rfbClient *client, int x, int y, int w, int h)
	Callback indicating that a rectangular area of the client's framebuffer was updated. More...

typedef void(*	FinishedFrameBufferUpdateProc) (struct _rfbClient *client)
	Callback indicating that a client has completely processed an rfbFramebufferUpdate message sent by a server. More...

typedef char (	GetPasswordProc) (struct _rfbClient *client)

typedef rfbCredential (	GetCredentialProc) (struct _rfbClient *client, int credentialType)

typedef rfbBool(*	MallocFrameBufferProc) (struct _rfbClient *client)

typedef void(*	GotXCutTextProc) (struct _rfbClient client, const char text, int textlen)

typedef void(*	BellProc) (struct _rfbClient *client)

typedef void(*	GotCursorShapeProc) (struct _rfbClient *client, int xhot, int yhot, int width, int height, int bytesPerPixel)
	Called when a cursor shape update was received from the server. More...

typedef void(*	GotCopyRectProc) (struct _rfbClient *client, int src_x, int src_y, int w, int h, int dest_x, int dest_y)

typedef void(*	GotFillRectProc) (struct _rfbClient *client, int x, int y, int w, int h, uint32_t colour)

typedef void(*	GotBitmapProc) (struct _rfbClient client, const uint8_t buffer, int x, int y, int w, int h)

typedef rfbBool(*	GotJpegProc) (struct _rfbClient client, const uint8_t buffer, int length, int x, int y, int w, int h)

typedef rfbBool(*	LockWriteToTLSProc) (struct _rfbClient *client)

typedef rfbBool(*	UnlockWriteToTLSProc) (struct _rfbClient *client)

typedef void(*	rfbClientLogProc) (const char *format,...)

Functions
rfbBool	HandleCursorShape (rfbClient *client, int xhot, int yhot, int width, int height, uint32_t enc)
	Handles XCursor and RichCursor shape updates from the server. More...

void	listenForIncomingConnections (rfbClient *viewer)

int	listenForIncomingConnectionsNoFork (rfbClient *viewer, int usec_timeout)

rfbBool	ConnectToRFBServer (rfbClient client, const char hostname, int port)

rfbBool	ConnectToRFBRepeater (rfbClient client, const char repeaterHost, int repeaterPort, const char *destHost, int destPort)

void	SetClientAuthSchemes (rfbClient client, const uint32_t authSchemes, int size)

rfbBool	InitialiseRFBConnection (rfbClient *client)

rfbBool	SetFormatAndEncodings (rfbClient *client)
	Sends format and encoding parameters to the server. More...

rfbBool	SendIncrementalFramebufferUpdateRequest (rfbClient *client)

rfbBool	SendFramebufferUpdateRequest (rfbClient *client, int x, int y, int w, int h, rfbBool incremental)
	Sends a framebuffer update request to the server. More...

rfbBool	SendScaleSetting (rfbClient *client, int scaleSetting)

rfbBool	SendPointerEvent (rfbClient *client, int x, int y, int buttonMask)
	Sends a pointer event to the server. More...

rfbBool	SendExtDesktopSize (rfbClient *client, uint16_t width, uint16_t height)
	Sends a SetDesktopSize event to the server. More...

rfbBool	SendKeyEvent (rfbClient *client, uint32_t key, rfbBool down)
	Sends a key event to the server. More...

rfbBool	SendExtendedKeyEvent (rfbClient *client, uint32_t keysym, uint32_t keycode, rfbBool down)
	The same as SendKeyEvent, except a key code will be sent along with the symbol if the server supports extended key events. More...

rfbBool	SendClientCutText (rfbClient client, char str, int len)
	Places a string on the server's clipboard. More...

rfbBool	HandleRFBServerMessage (rfbClient *client)
	Handles messages from the RFB server. More...

rfbBool	TextChatSend (rfbClient client, char text)
	Sends a text chat message to the server. More...

rfbBool	TextChatOpen (rfbClient *client)
	Opens a text chat window on the server. More...

rfbBool	TextChatClose (rfbClient *client)
	Closes the text chat window on the server. More...

rfbBool	TextChatFinish (rfbClient *client)

rfbBool	PermitServerInput (rfbClient *client, int enabled)

rfbBool	SendXvpMsg (rfbClient *client, uint8_t version, uint8_t code)

void	PrintPixelFormat (rfbPixelFormat *format)

rfbBool	SupportsClient2Server (rfbClient *client, int messageType)

rfbBool	SupportsServer2Client (rfbClient *client, int messageType)

void	rfbClientSetClientData (rfbClient client, void tag, void *data)
	Associates a client data tag with the given pointer. More...

void *	rfbClientGetClientData (rfbClient client, void tag)
	Returns a pointer to the client data associated with the given tag. More...

void	rfbClientRegisterExtension (rfbClientProtocolExtension *e)

rfbBool	ReadFromRFBServer (rfbClient client, char out, unsigned int n)

rfbBool	WriteToRFBServer (rfbClient client, const char buf, unsigned int n)

int	FindFreeTcpPort (void)

rfbSocket	ListenAtTcpPort (int port)

rfbSocket	ListenAtTcpPortAndAddress (int port, const char *address)

rfbSocket	ConnectClientToTcpAddr (unsigned int host, int port)
	Tries to connect to an IPv4 host. More...

rfbSocket	ConnectClientToTcpAddr6 (const char *hostname, int port)
	Tries to connect to an IPv4 or IPv6 host. More...

rfbSocket	ConnectClientToUnixSock (const char *sockFile)
	Tries to connect to a Unix socket. More...

rfbSocket	ConnectClientToTcpAddrWithTimeout (unsigned int host, int port, unsigned int timeout)
	Tries to connect to an IPv4 host using the given timeout value. More...

rfbSocket	ConnectClientToTcpAddr6WithTimeout (const char *hostname, int port, unsigned int timeout)
	Tries to connect to an IPv4 or IPv6 host using the given timeout value. More...

rfbSocket	ConnectClientToUnixSockWithTimeout (const char *sockFile, unsigned int timeout)
	Tries to connect to a Unix socket using the given timeout value. More...

rfbSocket	AcceptTcpConnection (rfbSocket listenSock)

rfbBool	SetNonBlocking (rfbSocket sock)

rfbBool	SetBlocking (rfbSocket sock)

rfbBool	SetDSCP (rfbSocket sock, int dscp)

rfbBool	StringToIPAddr (const char str, unsigned int addr)

rfbBool	SameMachine (rfbSocket sock)

int	WaitForMessage (rfbClient *client, unsigned int usecs)
	Waits for an RFB message to arrive from the server. More...

rfbClient *	rfbGetClient (int bitsPerSample, int samplesPerPixel, int bytesPerPixel)
	Allocates and returns a pointer to an rfbClient structure. More...

rfbBool	rfbInitClient (rfbClient client, int argc, char **argv)
	Initializes the client. More...

void	rfbClientCleanup (rfbClient *client)
	Cleans up the client structure and releases the memory allocated for it. More...

Variables
rfbBool	rfbEnableClientLogging

rfbClientLogProc	rfbClientLog

rfbClientLogProc	rfbClientErr

rfbBool	errorMessageOnReadFailure

Detailed Description

Macro Definition Documentation

◆ DEFAULT_CONNECT_TIMEOUT

#define DEFAULT_CONNECT_TIMEOUT 60

Definition at line 88 of file rfbclient.h.

◆ DEFAULT_READ_TIMEOUT

#define DEFAULT_READ_TIMEOUT 0

Definition at line 89 of file rfbclient.h.

◆ DEFAULT_SSH_CMD

#define DEFAULT_SSH_CMD "/usr/bin/ssh"

Definition at line 91 of file rfbclient.h.

◆ DEFAULT_TUNNEL_CMD

#define DEFAULT_TUNNEL_CMD (DEFAULT_SSH_CMD " -f -L %L:localhost:%R %H sleep 20")

Definition at line 92 of file rfbclient.h.

◆ DEFAULT_VIA_CMD

#define DEFAULT_VIA_CMD (DEFAULT_SSH_CMD " -f -L %L:%H:%R %G sleep 20")

Definition at line 94 of file rfbclient.h.

◆ FLASH_PORT_OFFSET

#define FLASH_PORT_OFFSET 5400

Definition at line 83 of file rfbclient.h.

◆ LISTEN_PORT_OFFSET

#define LISTEN_PORT_OFFSET 5500

Examples: SDLvncviewer.c.

Definition at line 84 of file rfbclient.h.

◆ rfbClientSwap16IfLE

#define rfbClientSwap16IfLE ( s ) (*(char *)&client->endianTest ? ((((s) & 0xff) << 8) | (((s) >> 8) & 0xff)) : (s))

Definition at line 64 of file rfbclient.h.

◆ rfbClientSwap32IfLE

#define rfbClientSwap32IfLE ( l )

Value:

    (*(char *)&client->endianTest ? ((((l) >> 24) & 0x000000ff) | \
                             (((l) & 0x00ff0000) >> 8)  | \
                             (((l) & 0x0000ff00) << 8)  | \
                             (((l) & 0x000000ff) << 24))  : (l))

Definition at line 67 of file rfbclient.h.

◆ rfbClientSwap64IfLE

#define rfbClientSwap64IfLE ( l )

Value:

    (*(char *)&client->endianTest ? ((((l) >> 56 ) & 0x00000000000000ffULL) | \
                             (((l) & 0x00ff000000000000ULL) >> 40)  | \
                             (((l) & 0x0000ff0000000000ULL) >> 24)  | \
                             (((l) & 0x000000ff00000000ULL) >> 8)  | \
                             (((l) & 0x00000000ff000000ULL) << 8)  | \
                             (((l) & 0x0000000000ff0000ULL) << 24)  | \
                             (((l) & 0x000000000000ff00ULL) << 40)  | \
                             (((l) & 0x00000000000000ffULL) << 56))  : (l))

Definition at line 73 of file rfbclient.h.

◆ rfbCredentialTypeUser

#define rfbCredentialTypeUser 2

Examples: SDLvncviewer.c.

Definition at line 162 of file rfbclient.h.

◆ rfbCredentialTypeX509

#define rfbCredentialTypeX509 1

Definition at line 161 of file rfbclient.h.

◆ rfbX509CrlVerifyAll

#define rfbX509CrlVerifyAll 2 /* All certificates in the server chain are checked */

Definition at line 169 of file rfbclient.h.

◆ rfbX509CrlVerifyClient

#define rfbX509CrlVerifyClient 1 /* Only the leaf server certificate is checked */

Definition at line 168 of file rfbclient.h.

◆ rfbX509CrlVerifyNone

#define rfbX509CrlVerifyNone 0 /* No CRL checking is performed */

Definition at line 167 of file rfbclient.h.

◆ SERVER_PORT_OFFSET

#define SERVER_PORT_OFFSET 5900

Definition at line 86 of file rfbclient.h.

◆ TUNNEL_PORT_OFFSET

#define TUNNEL_PORT_OFFSET 5500

Definition at line 85 of file rfbclient.h.

Typedef Documentation

◆ BellProc

typedef void(* BellProc) (struct _rfbClient *client)

Definition at line 220 of file rfbclient.h.

◆ FinishedFrameBufferUpdateProc

typedef void(* FinishedFrameBufferUpdateProc) (struct _rfbClient *client)

Callback indicating that a client has completely processed an rfbFramebufferUpdate message sent by a server.

This is called exactly once per each handled rfbFramebufferUpdate message.

Parameters

client The client which finished processing an rfbFramebufferUpdate

Definition at line 215 of file rfbclient.h.

◆ GetCredentialProc

typedef rfbCredential*(* GetCredentialProc) (struct _rfbClient *client, int credentialType)

Definition at line 217 of file rfbclient.h.

◆ GetPasswordProc

typedef char*(* GetPasswordProc) (struct _rfbClient *client)

Definition at line 216 of file rfbclient.h.

◆ GotBitmapProc

typedef void(* GotBitmapProc) (struct _rfbClient *client, const uint8_t *buffer, int x, int y, int w, int h)

Definition at line 231 of file rfbclient.h.

◆ GotCopyRectProc

typedef void(* GotCopyRectProc) (struct _rfbClient *client, int src_x, int src_y, int w, int h, int dest_x, int dest_y)

Definition at line 229 of file rfbclient.h.

◆ GotCursorShapeProc

typedef void(* GotCursorShapeProc) (struct _rfbClient *client, int xhot, int yhot, int width, int height, int bytesPerPixel)

Called when a cursor shape update was received from the server.

The decoded cursor shape will be in client->rcSource. It's up to the application to do something with this, e.g. draw into a viewer's window. If you want the server to draw the cursor into the framebuffer, be careful not to announce remote cursor support, i.e. not include rfbEncodingXCursor or rfbEncodingRichCursor in SetFormatAndEncodings().

Definition at line 228 of file rfbclient.h.

◆ GotFillRectProc

typedef void(* GotFillRectProc) (struct _rfbClient *client, int x, int y, int w, int h, uint32_t colour)

Definition at line 230 of file rfbclient.h.

◆ GotFrameBufferUpdateProc

typedef void(* GotFrameBufferUpdateProc) (struct _rfbClient *client, int x, int y, int w, int h)

Callback indicating that a rectangular area of the client's framebuffer was updated.

As a server will usually send several rects per rfbFramebufferUpdate message, this callback is usually called multiple times per rfbFramebufferUpdate message.

Parameters

client	The client whose framebuffer was (partially) updated
x	The x-coordinate of the upper left corner of the updated rectangle
y	The y-coordinate of the upper left corner of the updated rectangle
w	The width of the updated rectangle
h	The heigth of the updated rectangle

Definition at line 208 of file rfbclient.h.

◆ GotJpegProc

typedef rfbBool(* GotJpegProc) (struct _rfbClient *client, const uint8_t *buffer, int length, int x, int y, int w, int h)

Definition at line 232 of file rfbclient.h.

◆ GotXCutTextProc

typedef void(* GotXCutTextProc) (struct _rfbClient *client, const char *text, int textlen)

Definition at line 219 of file rfbclient.h.

◆ HandleCursorPosProc

typedef rfbBool(* HandleCursorPosProc) (struct _rfbClient *client, int x, int y)

Definition at line 195 of file rfbclient.h.

◆ HandleKeyboardLedStateProc

typedef void(* HandleKeyboardLedStateProc) (struct _rfbClient *client, int value, int pad)

Definition at line 194 of file rfbclient.h.

◆ HandleTextChatProc

typedef void(* HandleTextChatProc) (struct _rfbClient *client, int value, char *text)

Handles a text chat message.

If your application should accept text messages from the server, define a function with this prototype and set client->HandleTextChat to a pointer to that function subsequent to your rfbGetClient() call.

Parameters

client	The client which called the text chat handler
value	text length if text != NULL, or one of rfbTextChatOpen, rfbTextChatClose, rfbTextChatFinished if text == NULL
text	The text message from the server

Definition at line 183 of file rfbclient.h.

◆ HandleXvpMsgProc

typedef void(* HandleXvpMsgProc) (struct _rfbClient *client, uint8_t version, uint8_t opcode)

Handles XVP server messages.

If your application sends XVP messages to the server, you'll want to handle the server's XVP_FAIL and XVP_INIT responses. Define a function with this prototype and set client->HandleXvpMsg to a pointer to that function subsequent to your rfbGetClient() call.

Parameters

client	The client which called the XVP message handler
version	The highest XVP extension version that the server supports
opcode	The opcode. 0 is XVP_FAIL, 1 is XVP_INIT

Definition at line 193 of file rfbclient.h.

◆ LockWriteToTLSProc

typedef rfbBool(* LockWriteToTLSProc) (struct _rfbClient *client)

Definition at line 233 of file rfbclient.h.

◆ MallocFrameBufferProc

typedef rfbBool(* MallocFrameBufferProc) (struct _rfbClient *client)

Definition at line 218 of file rfbclient.h.

◆ rfbClientLogProc

typedef void(* rfbClientLogProc) (const char *format,...)

Definition at line 499 of file rfbclient.h.

◆ SoftCursorLockAreaProc

typedef void(* SoftCursorLockAreaProc) (struct _rfbClient *client, int x, int y, int w, int h)

Definition at line 196 of file rfbclient.h.

◆ SoftCursorUnlockScreenProc

typedef void(* SoftCursorUnlockScreenProc) (struct _rfbClient *client)

Definition at line 197 of file rfbclient.h.

◆ UnlockWriteToTLSProc

typedef rfbBool(* UnlockWriteToTLSProc) (struct _rfbClient *client)

Deprecated:

Definition at line 234 of file rfbclient.h.

Function Documentation

◆ AcceptTcpConnection()

rfbSocket AcceptTcpConnection ( rfbSocket listenSock )

◆ ConnectClientToTcpAddr()

rfbSocket ConnectClientToTcpAddr	(	unsigned int	host,
		int	port
	)

Tries to connect to an IPv4 host.

Parameters

host	Binary IPv4 address
port	Port

Returns: A blocking socket or RFB_INVALID_SOCKET if the connection failed

◆ ConnectClientToTcpAddr6()

rfbSocket ConnectClientToTcpAddr6	(	const char *	hostname,
		int	port
	)

Tries to connect to an IPv4 or IPv6 host.

Parameters

hostname	A hostname or IP address
port	Port

Returns: A blocking socket or RFB_INVALID_SOCKET if the connection failed

◆ ConnectClientToTcpAddr6WithTimeout()

rfbSocket ConnectClientToTcpAddr6WithTimeout	(	const char *	hostname,
		int	port,
		unsigned int	timeout
	)

Tries to connect to an IPv4 or IPv6 host using the given timeout value.

Parameters

hostname	A hostname or IP address
port	Port
timeout	The time in seconds to wait for a connection

Returns: A nonblocking socket or RFB_INVALID_SOCKET if the connection failed

◆ ConnectClientToTcpAddrWithTimeout()

rfbSocket ConnectClientToTcpAddrWithTimeout	(	unsigned int	host,
		int	port,
		unsigned int	timeout
	)

Tries to connect to an IPv4 host using the given timeout value.

Parameters

host	Binary IPv4 address
port	Port
timeout	The time in seconds to wait for a connection

Returns: A nonblocking socket or RFB_INVALID_SOCKET if the connection failed

◆ ConnectClientToUnixSock()

rfbSocket ConnectClientToUnixSock ( const char * sockFile )

Tries to connect to a Unix socket.

Parameters

sockFile Path of the socket file

Returns: A blocking socket or RFB_INVALID_SOCKET if the connection failed

◆ ConnectClientToUnixSockWithTimeout()

rfbSocket ConnectClientToUnixSockWithTimeout	(	const char *	sockFile,
		unsigned int	timeout
	)

Tries to connect to a Unix socket using the given timeout value.

Parameters

sockFile	Path of the socket file
timeout	The time in seconds to wait for a connection

Returns: A nonblocking socket or RFB_INVALID_SOCKET if the connection failed

◆ ConnectToRFBRepeater()

rfbBool ConnectToRFBRepeater	(	rfbClient *	client,
		const char *	repeaterHost,
		int	repeaterPort,
		const char *	destHost,
		int	destPort
	)

◆ ConnectToRFBServer()

rfbBool ConnectToRFBServer	(	rfbClient *	client,
		const char *	hostname,
		int	port
	)

◆ FindFreeTcpPort()

int FindFreeTcpPort ( void )

◆ HandleCursorShape()

rfbBool HandleCursorShape	(	rfbClient *	client,
		int	xhot,
		int	yhot,
		int	width,
		int	height,
		uint32_t	enc
	)

Handles XCursor and RichCursor shape updates from the server.

We emulate cursor operating on the frame buffer (that is why we call it "software cursor"). This decodes the received cursor shape and hands it over to GotCursorShapeProc, if set.

◆ HandleRFBServerMessage()

rfbBool HandleRFBServerMessage ( rfbClient * client )

Handles messages from the RFB server.

You must call this function intermittently so LibVNCClient can parse messages from the server. For example, if your app has a draw loop, you could place a call to this function within that draw loop.

Note: You must call WaitForMessage() before you call this function.

Parameters

client The client which will handle the RFB server messages

Returns: true if the client was able to handle the RFB server messages, false otherwise

Examples: SDLvncviewer.c, ppmtest.c, and vnc2mpg.c.

Here is the caller graph for this function:

◆ InitialiseRFBConnection()

rfbBool InitialiseRFBConnection ( rfbClient * client )

◆ ListenAtTcpPort()

rfbSocket ListenAtTcpPort ( int port )

◆ ListenAtTcpPortAndAddress()

rfbSocket ListenAtTcpPortAndAddress	(	int	port,
		const char *	address
	)

◆ listenForIncomingConnections()

void listenForIncomingConnections ( rfbClient * viewer )

◆ listenForIncomingConnectionsNoFork()

int listenForIncomingConnectionsNoFork	(	rfbClient *	viewer,
		int	usec_timeout
	)

◆ PermitServerInput()

rfbBool PermitServerInput	(	rfbClient *	client,
		int	enabled
	)

◆ PrintPixelFormat()

void PrintPixelFormat ( rfbPixelFormat * format )

◆ ReadFromRFBServer()

rfbBool ReadFromRFBServer	(	rfbClient *	client,
		char *	out,
		unsigned int	n
	)

◆ rfbClientCleanup()

void rfbClientCleanup ( rfbClient * client )

Cleans up the client structure and releases the memory allocated for it.

You should call this when you're done with the rfbClient structure that you allocated with rfbGetClient().

Note: rfbClientCleanup() does not touch client->frameBuffer.

Parameters

client The client to clean up

Examples: SDLvncviewer.c, and ppmtest.c.

◆ rfbClientGetClientData()

void* rfbClientGetClientData	(	rfbClient *	client,
		void *	tag
	)

Returns a pointer to the client data associated with the given tag.

See the the documentation for rfbClientSetClientData() for a discussion of how you can use client data.

Parameters

client	The client from which to get the client data
tag	The tag which identifies the client data

Returns: a pointer to the client data

Examples: SDLvncviewer.c.

◆ rfbClientRegisterExtension()

void rfbClientRegisterExtension ( rfbClientProtocolExtension * e )

◆ rfbClientSetClientData()

void rfbClientSetClientData	(	rfbClient *	client,
		void *	tag,
		void *	data
	)

Associates a client data tag with the given pointer.

LibVNCClient has several events to which you can associate your own handlers. These handlers have the client structure as one of their parameters. Sometimes, you may want to make data from elsewhere in your application available to these handlers without using a global variable. To do this, you call rfbClientSetClientData() and associate the data with a tag. Then, your handler can call rfbClientGetClientData() and get the a pointer to the data associated with that tag.

Parameters

client	The client in which to set the client data
tag	A unique tag which identifies the data
data	A pointer to the data to associate with the tag

Examples: SDLvncviewer.c.

◆ rfbGetClient()

rfbClient* rfbGetClient	(	int	bitsPerSample,
		int	samplesPerPixel,
		int	bytesPerPixel
	)

Allocates and returns a pointer to an rfbClient structure.

This will probably be the first LibVNCClient function your client code calls. Most libVNCClient functions operate on an rfbClient structure, and this function allocates memory for that structure. When you're done with the rfbClient structure pointer this function returns, you should free the memory rfbGetClient() allocated by calling rfbClientCleanup().

A pixel is one dot on the screen. The number of bytes in a pixel will depend on the number of samples in that pixel and the number of bits in each sample. A sample represents one of the primary colors in a color model. The RGB color model uses red, green, and blue samples respectively. Suppose you wanted to use 16-bit RGB color: You would have three samples per pixel (one for each primary color), five bits per sample (the quotient of 16 RGB bits divided by three samples), and two bytes per pixel (the smallest multiple of eight bits in which the 16-bit pixel will fit). If you wanted 32-bit RGB color, you would have three samples per pixel again, eight bits per sample (since that's how 32-bit color is defined), and four bytes per pixel (the smallest multiple of eight bits in which the 32-bit pixel will fit.

Parameters

bitsPerSample	The number of bits in a sample
samplesPerPixel	The number of samples in a pixel
bytesPerPixel	The number of bytes in a pixel

Returns: a pointer to the allocated rfbClient structure

Examples: SDLvncviewer.c, ppmtest.c, and vnc2mpg.c.

Here is the caller graph for this function:

◆ rfbInitClient()

rfbBool rfbInitClient	(	rfbClient *	client,
		int *	argc,
		char **	argv
	)

Initializes the client.

The format is {PROGRAM_NAME, [OPTIONS]..., HOST}. This function does not initialize the program name if the rfbClient's program name is set already. The options are as follows:

Option	Description
-listen	Listen for incoming connections.
-listennofork	Listen for incoming connections without forking.
-play	Set this client to replay a previously recorded session.
-encodings	Set the encodings to use. The next item in the argv array is the encodings string, consisting of comma separated encodings like 'tight,ultra,raw'.
-compress	Set the compression level. The next item in the argv array is the compression level as an integer. Ranges from 0 (lowest) to 9 (highest).
-scale	Set the scaling level. The next item in the argv array is the scaling level as an integer. The screen will be scaled down by this factor.
-qosdscp	Set the Quality of Service Differentiated Services Code Point (QoS DSCP). The next item in the argv array is the code point as an integer.
-repeaterdest	Set a VNC repeater address. The next item in the argv array is the repeater's address as a string.

The host may include a port number (delimited by a ':').

Parameters

client	The client to initialize
argc	The number of arguments to the initializer
argv	The arguments to the initializer as an array of NULL terminated strings

Returns: true if the client was initialized successfully, false otherwise.

Examples: SDLvncviewer.c, ppmtest.c, and vnc2mpg.c.

Here is the caller graph for this function:

◆ SameMachine()

rfbBool SameMachine ( rfbSocket sock )

◆ SendClientCutText()

rfbBool SendClientCutText	(	rfbClient *	client,
		char *	str,
		int	len
	)

Places a string on the server's clipboard.

Use this function if you want to be able to copy and paste between the server and your application. For instance, when your application is notified that the user copied some text onto the clipboard, you would call this function to synchronize the server's clipboard with your local clipboard.

Parameters

client	The client structure through which to send the client cut text message
str	The string to send (doesn't need to be NULL terminated)
len	The length of the string

Returns: true if the client cut message was sent successfully, false otherwise

Examples: SDLvncviewer.c.

◆ SendExtDesktopSize()

rfbBool SendExtDesktopSize	(	rfbClient *	client,
		uint16_t	width,
		uint16_t	height
	)

Sends a SetDesktopSize event to the server.

Parameters

client	The client through which to send the SetDesktopSize event
width	The width of the update request rectangle
height	The height of the update request rectangle

Returns: true if the SetDesktopSize event was send successfully, false otherwise

Examples: SDLvncviewer.c.

◆ SendExtendedKeyEvent()

rfbBool SendExtendedKeyEvent	(	rfbClient *	client,
		uint32_t	keysym,
		uint32_t	keycode,
		rfbBool	down
	)

The same as SendKeyEvent, except a key code will be sent along with the symbol if the server supports extended key events.

Parameters

client	The client through which to send the key event
keysym	An rfbKeySym defined in rfb/keysym.h
keycode	An XT key code
down	true if this was a key down event, false otherwise

Returns: true if the extended key event is supported and was sent successfully, false otherwise

◆ SendFramebufferUpdateRequest()

rfbBool SendFramebufferUpdateRequest	(	rfbClient *	client,
		int	x,
		int	y,
		int	w,
		int	h,
		rfbBool	incremental
	)

Sends a framebuffer update request to the server.

A VNC client may request an update from the server at any time. You can also specify which portions of the screen you want updated. This can be handy if a pointer is at certain location and the user pressed a mouse button, for instance. Then you can immediately request an update of the region around the pointer from the server.

Note: The coordinate system is a left-handed Cartesian coordinate system with the Z axis (unused) pointing out of the screen. Alternately you can think of it as a right-handed Cartesian coordinate system with the Z axis pointing into the screen. The origin is at the upper left corner of the framebuffer.

Parameters

client	The client through which to send the request
x	The horizontal position of the update request rectangle
y	The vertical position of the update request rectangle
w	The width of the update request rectangle
h	The height of the update request rectangle
incremental	false: server sends rectangle even if nothing changed. true: server only sends changed parts of rectangle.

Returns: true if the update request was sent successfully, false otherwise

Examples: SDLvncviewer.c.

◆ SendIncrementalFramebufferUpdateRequest()

rfbBool SendIncrementalFramebufferUpdateRequest ( rfbClient * client )

◆ SendKeyEvent()

rfbBool SendKeyEvent	(	rfbClient *	client,
		uint32_t	key,
		rfbBool	down
	)

Sends a key event to the server.

If your application is not merely a VNC viewer (i.e. it controls the server), you'll want to send the keys that the user presses to the server. Use this function to do that.

Parameters

client	The client through which to send the key event
key	An rfbKeySym defined in rfb/keysym.h
down	true if this was a key down event, false otherwise

Returns: true if the key event was send successfully, false otherwise

Examples: SDLvncviewer.c.

◆ SendPointerEvent()

rfbBool SendPointerEvent	(	rfbClient *	client,
		int	x,
		int	y,
		int	buttonMask
	)

Sends a pointer event to the server.

A pointer event includes a cursor location and a button mask. The button mask indicates which buttons on the pointing device are pressed. Each button is represented by a bit in the button mask. A 1 indicates the button is pressed while a 0 indicates that it is not pressed. You may use these pre-defined button masks by ORing them together: rfbButton1Mask, rfbButton2Mask, rfbButton3Mask, rfbButton4Mask rfbButton5Mask

Note: The cursor location is relative to the client's framebuffer, not the client's screen itself.; The coordinate system is a left-handed Cartesian coordinate system with the Z axis (unused) pointing out of the screen. Alternately you can think of it as a right-handed Cartesian coordinate system with the Z axis pointing into the screen. The origin is at the upper left corner of the screen.

Parameters

client	The client through which to send the pointer event
x	the horizontal location of the cursor
y	the vertical location of the cursor
buttonMask	the button mask indicating which buttons are pressed

Returns: true if the pointer event was sent successfully, false otherwise

Examples: SDLvncviewer.c.

◆ SendScaleSetting()

rfbBool SendScaleSetting	(	rfbClient *	client,
		int	scaleSetting
	)

◆ SendXvpMsg()

rfbBool SendXvpMsg	(	rfbClient *	client,
		uint8_t	version,
		uint8_t	code
	)

◆ SetBlocking()

rfbBool SetBlocking ( rfbSocket sock )

◆ SetClientAuthSchemes()

void SetClientAuthSchemes	(	rfbClient *	client,
		const uint32_t *	authSchemes,
		int	size
	)

◆ SetDSCP()

rfbBool SetDSCP	(	rfbSocket	sock,
		int	dscp
	)

◆ SetFormatAndEncodings()

rfbBool SetFormatAndEncodings ( rfbClient * client )

Sends format and encoding parameters to the server.

Your application can modify the 'client' data structure directly. However some changes to this structure must be communicated back to the server. For instance, if you change the encoding to hextile, the server needs to know that it should send framebuffer updates in hextile format. Likewise if you change the pixel format of the framebuffer, the server must be notified about this as well. Call this function to propagate your changes of the local 'client' structure over to the server.

Encoding type
RFB protocol extensions announced via pseudo-encodings
Framebuffer pixel format (like RGB vs ARGB)
Remote cursor support
Parameters

client The client in which the format or encodings have been changed

Returns
true if the format or encodings were sent to the server successfully, false otherwise

Examples: SDLvncviewer.c.

◆ SetNonBlocking()

rfbBool SetNonBlocking ( rfbSocket sock )

◆ StringToIPAddr()

rfbBool StringToIPAddr	(	const char *	str,
		unsigned int *	addr
	)

◆ SupportsClient2Server()

rfbBool SupportsClient2Server	(	rfbClient *	client,
		int	messageType
	)

◆ SupportsServer2Client()

rfbBool SupportsServer2Client	(	rfbClient *	client,
		int	messageType
	)

◆ TextChatClose()

rfbBool TextChatClose ( rfbClient * client )

Closes the text chat window on the server.

Parameters

client The client through which to send the message

Returns: true if the window was closed successfully, false otherwise

◆ TextChatFinish()

rfbBool TextChatFinish ( rfbClient * client )

◆ TextChatOpen()

rfbBool TextChatOpen ( rfbClient * client )

Opens a text chat window on the server.

Parameters

client The client through which to send the message

Returns: true if the window was opened successfully, false otherwise

Examples: SDLvncviewer.c.

◆ TextChatSend()

rfbBool TextChatSend	(	rfbClient *	client,
		char *	text
	)

Sends a text chat message to the server.

Parameters

client	The client through which to send the message
text	The text to send

Returns: true if the text was sent successfully, false otherwise

◆ WaitForMessage()

int WaitForMessage	(	rfbClient *	client,
		unsigned int	usecs
	)

Waits for an RFB message to arrive from the server.

Before handling a message with HandleRFBServerMessage(), you must wait for your client to receive one. This function blocks until a message is received. You may specify a timeout in microseconds. Once this number of microseconds have elapsed, the function will return.

Parameters

client	The client to cause to wait until a message is received
usecs	The timeout in microseconds

Returns: the return value of the underlying select() call

Examples: SDLvncviewer.c, ppmtest.c, and vnc2mpg.c.

Here is the caller graph for this function:

◆ WriteToRFBServer()

rfbBool WriteToRFBServer	(	rfbClient *	client,
		const char *	buf,
		unsigned int	n
	)

Variable Documentation

◆ errorMessageOnReadFailure

rfbBool errorMessageOnReadFailure

extern

◆ rfbClientErr

rfbClientLogProc rfbClientErr

Examples: SDLvncviewer.c, and ppmtest.c.

Definition at line 500 of file rfbclient.h.

◆ rfbClientLog

rfbClientLogProc rfbClientLog

extern

Examples: SDLvncviewer.c, and ppmtest.c.

◆ rfbEnableClientLogging

rfbBool rfbEnableClientLogging

extern

Examples: SDLvncviewer.c.

Files

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ DEFAULT_CONNECT_TIMEOUT

◆ DEFAULT_READ_TIMEOUT

◆ DEFAULT_SSH_CMD

◆ DEFAULT_TUNNEL_CMD

◆ DEFAULT_VIA_CMD

◆ FLASH_PORT_OFFSET

◆ LISTEN_PORT_OFFSET

◆ rfbClientSwap16IfLE

◆ rfbClientSwap32IfLE

◆ rfbClientSwap64IfLE

◆ rfbCredentialTypeUser

◆ rfbCredentialTypeX509

◆ rfbX509CrlVerifyAll

◆ rfbX509CrlVerifyClient

◆ rfbX509CrlVerifyNone

◆ SERVER_PORT_OFFSET

◆ TUNNEL_PORT_OFFSET

Typedef Documentation

◆ BellProc

◆ FinishedFrameBufferUpdateProc

◆ GetCredentialProc

◆ GetPasswordProc

◆ GotBitmapProc

◆ GotCopyRectProc

◆ GotCursorShapeProc

◆ GotFillRectProc

◆ GotFrameBufferUpdateProc

◆ GotJpegProc

◆ GotXCutTextProc

◆ HandleCursorPosProc

◆ HandleKeyboardLedStateProc

◆ HandleTextChatProc

◆ HandleXvpMsgProc

◆ LockWriteToTLSProc

◆ MallocFrameBufferProc

◆ rfbClientLogProc

◆ SoftCursorLockAreaProc

◆ SoftCursorUnlockScreenProc

◆ UnlockWriteToTLSProc

Function Documentation

◆ AcceptTcpConnection()

◆ ConnectClientToTcpAddr()

◆ ConnectClientToTcpAddr6()

◆ ConnectClientToTcpAddr6WithTimeout()

◆ ConnectClientToTcpAddrWithTimeout()

◆ ConnectClientToUnixSock()

◆ ConnectClientToUnixSockWithTimeout()

◆ ConnectToRFBRepeater()

◆ ConnectToRFBServer()

◆ FindFreeTcpPort()

◆ HandleCursorShape()

◆ HandleRFBServerMessage()

◆ InitialiseRFBConnection()

◆ ListenAtTcpPort()

◆ ListenAtTcpPortAndAddress()

◆ listenForIncomingConnections()

◆ listenForIncomingConnectionsNoFork()

◆ PermitServerInput()

◆ PrintPixelFormat()

◆ ReadFromRFBServer()

◆ rfbClientCleanup()

◆ rfbClientGetClientData()

◆ rfbClientRegisterExtension()

◆ rfbClientSetClientData()

◆ rfbGetClient()

◆ rfbInitClient()

◆ SameMachine()

◆ SendClientCutText()

◆ SendExtDesktopSize()

◆ SendExtendedKeyEvent()

◆ SendFramebufferUpdateRequest()

◆ SendIncrementalFramebufferUpdateRequest()