Learn how to evaluate and integrate the VNC SDK

We're here if you need help.

Viewer.h

Creates a VNC-compatible Viewer app for a device you want to control from. (more...)

Data structures

Modifier and Type Name and Description
struct

vnc_Viewer_ConnectionCallback

Callback receiving state-change notifications for a Viewer.

struct

vnc_Viewer_FramebufferCallback

Callback receiving framebuffer event notifications for a Viewer.

struct

vnc_Viewer_ServerEventCallback

Callback receiving server event notifications for a Viewer.

struct

vnc_Viewer_AuthenticationCallback

Callback receiving requests for authentication for a Viewer.

struct

vnc_Viewer_PeerVerificationCallback

Callback receiving verification requests to check the peer’s identity.

Functions for managing the status of a viewer connection

Modifier and Type Name and Description
enum

vnc_Viewer_ConnectionStatus

Enumeration of connection statuses.

enum

vnc_Viewer_DisconnectFlags

Enumeration of disconnection flags.

function vnc_status_t

vnc_Viewer_setConnectionCallback(vnc_Viewer *viewer, const vnc_Viewer_ConnectionCallback *callback, void *userData)

Sets the callbacks for the Viewer to call when various events occur during its lifetime.

function vnc_ConnectionHandler *

vnc_Viewer_getConnectionHandler(vnc_Viewer *viewer)

Returns the viewer’s vnc_ConnectionHandler for accepting connections.

function vnc_Viewer_ConnectionStatus

vnc_Viewer_getConnectionStatus(vnc_Viewer *viewer)

Returns the status of the viewer’s connection.

function const char *

vnc_Viewer_getPeerAddress(vnc_Viewer *viewer)

Returns the address of the viewer’s server.

function vnc_status_t

vnc_Viewer_disconnect(vnc_Viewer *viewer)

Disconnects this viewer from the server.

function const char *

vnc_Viewer_getDisconnectReason(vnc_Viewer *viewer)

Returns a string ID representing the reason for the last viewer disconnection.

function const char *

vnc_Viewer_getDisconnectMessage(vnc_Viewer *viewer)

Returns a human-readable message sent by the server for the last disconnection, or NULL if the last disconnection was not initiated by the server.

Functions for managing the framebuffer

Modifier and Type Name and Description
function vnc_status_t

vnc_Viewer_setFramebufferCallback(vnc_Viewer *viewer, const vnc_Viewer_FramebufferCallback *callback, void *userData)

Sets the framebuffer callback for this viewer.

function vnc_status_t

vnc_Viewer_setViewerFb(vnc_Viewer *viewer, void *pixels, int pixelsBytes, const vnc_PixelFormat *pf, int width, int height, int stride)

Sets the viewer framebuffer.

function int

vnc_Viewer_getViewerFbWidth(vnc_Viewer *viewer)

Gets the width of the viewer framebuffer.

function int

vnc_Viewer_getViewerFbHeight(vnc_Viewer *viewer)

Gets the height of the viewer framebuffer.

function const vnc_PixelFormat *

vnc_Viewer_getViewerFbPixelFormat(vnc_Viewer *viewer)

Gets the pixel format of the viewer framebuffer.

function const vnc_DataBuffer *

vnc_Viewer_getViewerFbData(vnc_Viewer *viewer, int x, int y, int w, int h)

Returns the viewer framebuffer data for the given rectangle.

function int

vnc_Viewer_getViewerFbStride(vnc_Viewer *viewer)

Returns the stride of the viewer framebuffer data in pixels, that is, the number of pixels from the start of each row until the start of the next.

Functions for managing server events

Modifier and Type Name and Description
function vnc_status_t

vnc_Viewer_setServerEventCallback(vnc_Viewer *viewer, const vnc_Viewer_ServerEventCallback *callback, void *userData)

Sets the server event callback for this viewer.

Functions for sending input

Modifier and Type Name and Description
enum

vnc_Viewer_MouseButton

Enumeration of mouse buttons.

enum

vnc_Viewer_MouseWheel

Enumeration of mouse wheel directions.

function vnc_status_t

vnc_Viewer_sendClipboardText(vnc_Viewer *viewer, const char *text)

Copies the given text to the server’s clipboard.

function vnc_status_t

vnc_Viewer_sendPointerEvent(vnc_Viewer *viewer, int x, int y, int buttonState, vnc_bool_t rel)

Sends a pointer event to the server.

function vnc_status_t

vnc_Viewer_sendScrollEvent(vnc_Viewer *viewer, int delta, vnc_Viewer_MouseWheel axis)

Sends a scroll wheel event to the server.

function vnc_status_t

vnc_Viewer_sendKeyDown(vnc_Viewer *viewer, vnc_uint31_t keysym, int keyCode)

Sends a key down (press) event to the server.

function vnc_status_t

vnc_Viewer_sendKeyUp(vnc_Viewer *viewer, int keyCode)

Sends a key up (release) event to the server.

function vnc_status_t

vnc_Viewer_releaseAllKeys(vnc_Viewer *viewer)

Send key up events for all currently pressed keys.

Functions for managing connection negotiation

Modifier and Type Name and Description
enum

vnc_Viewer_PictureQuality

Enumeration of picture quality levels.

enum

vnc_Viewer_EncryptionLevel

Enumeration of encryption levels.

function vnc_status_t

vnc_Viewer_setAuthenticationCallback(vnc_Viewer *viewer, const vnc_Viewer_AuthenticationCallback *callback, void *userData)

Sets the callback to be called when a username and/or password is required.

function vnc_status_t

vnc_Viewer_sendAuthenticationResponse(vnc_Viewer *viewer, vnc_bool_t ok, const char *user, const char *passwd)

Provides the SDK with the result of a username/password request.

function vnc_status_t

vnc_Viewer_setPeerVerificationCallback(vnc_Viewer *viewer, const vnc_Viewer_PeerVerificationCallback *callback, void *userData)

Sets the callbacks to be called to verify the identity of the peer (server).

function vnc_status_t

vnc_Viewer_sendPeerVerificationResponse(vnc_Viewer *viewer, vnc_bool_t ok)

Provides the SDK with the response to the vnc_Viewer_PeerVerificationCallback::verifyPeer request.

function vnc_AnnotationManager *

vnc_Viewer_getAnnotationManager(vnc_Viewer *viewer)

Obtains the Viewer’s vnc_AnnotationManager for handling annotation operations.

function vnc_Viewer_PictureQuality

vnc_Viewer_getPictureQuality(vnc_Viewer *viewer)

Returns the viewer’s current picture quality.

function vnc_status_t

vnc_Viewer_setPictureQuality(vnc_Viewer *viewer, vnc_Viewer_PictureQuality quality)

Sets the desired picture quality of the session from the range of options enumerated by vnc_Viewer_PictureQuality.

function vnc_MessagingManager *

vnc_Viewer_getMessagingManager(vnc_Viewer *viewer)

Obtains the Viewer’s Messaging Manager for handling messaging.

function vnc_status_t

vnc_Viewer_setEncryptionLevel(vnc_Viewer *viewer, vnc_Viewer_EncryptionLevel level)

Sets the desired encryption level of the session from the range of options enumerated by vnc_Viewer_EncryptionLevel.

function vnc_Viewer_EncryptionLevel

vnc_Viewer_getEncryptionLevel(vnc_Viewer *viewer)

Returns the Viewer’s current encryption level.

Functions

Modifier and Type Name and Description
function vnc_Viewer *

vnc_Viewer_create()

Creates and returns a new viewer.

function void

vnc_Viewer_destroy(vnc_Viewer *viewer)

Destroys the viewer.

Detailed description

Creates a VNC-compatible Viewer app for a device you want to control from.

A Viewer runs on the device that you want to remotely control from. It provides a framebuffer which is kept up to date with the Server device screen, and has functions for sending input events to the Server.

To get started, make sure you’ve initialized the SDK with vnc_init(). Then use vnc_Viewer_create() to create one vnc_Viewer for each connection made to a server. Set up the framebuffer and associated callbacks using vnc_Viewer_setViewerFb() and vnc_Viewer_setFramebufferCallback(), and set up callbacks to provide authentication credentials using vnc_Viewer_setAuthenticationCallback().

To connect to a Server, call vnc_Viewer_getConnectionHandler() to obtain a vnc_ConnectionHandler for use with vnc_CloudConnector_connect() (or vnc_CloudListener_create()), and start the process of connecting.

When a connection is in progress, any defined vnc_Viewer_ConnectionCallback::connecting callback is called. Then, any defined vnc_Viewer_PeerVerificationCallback::verifyPeer callback is called. vnc_Viewer_sendPeerVerificationResponse() is used to indicate if the peer is valid. Next, the vnc_Viewer_AuthenticationCallback::requestUserCredentials callback is called, and the user-supplied credentials are submitted using vnc_Viewer_sendAuthenticationResponse().

After authentication is complete, any defined vnc_Viewer_ConnectionCallback::connected callback is called. The vnc_Viewer_FramebufferCallback::serverFbSizeChanged callback is then called with the size of the server’s framebuffer, and the vnc_Viewer_FramebufferCallback::viewerFbUpdated callback is called each time new pixel data is received. Typically, vnc_Viewer_getViewerFbData() is used to obtain the viewer framebuffer data for window painting purposes.

Any keyboard or mouse input to be sent to the server is done using the functions vnc_Viewer_sendKeyDown(), vnc_Viewer_sendKeyUp(), vnc_Viewer_sendPointerEvent() and vnc_Viewer_sendScrollEvent().

The viewer can end the connection by calling vnc_Viewer_disconnect(). When the viewer has cleanly disconnected, or the connection was terminated by the peer, the vnc_Viewer_ConnectionCallback::disconnected callback is called. The reason for disconnection is available as a string ID in the callback, and also from vnc_Viewer_getDisconnectReason().

Once you’ve finished with the viewer, it should be destroyed with vnc_Viewer_destroy(), and the SDK can be shutdown and any resources cleaned up with vnc_shutdown().

Functions for managing the status of a viewer connection

enum vnc_Viewer_ConnectionStatus

Enumeration of connection statuses.

These are returned by vnc_Viewer_getConnectionStatus() to query the status of the connection for a given viewer.

Values:

vnc_Viewer_Disconnected

The viewer is not connected to a server.

vnc_Viewer_Connecting

The viewer is negotiating a connection to a server (includes authentication).

vnc_Viewer_Connected

The viewer is connected to a server.

vnc_Viewer_Disconnecting

vnc_Viewer_disconnect() has been called but we’ve not yet disconnected from the server.

enum vnc_Viewer_DisconnectFlags

Enumeration of disconnection flags.

Values:

vnc_Viewer_AlertUser = 1

The disconnection message could be shown to the user.

This is set if the server sent this flag with its disconnection message, or the viewer disconnected due to an error.

vnc_Viewer_CanReconnect = 2

The connection has been broken, but a reconnection attempt may succeed.

vnc_status_t vnc_Viewer_setConnectionCallback(vnc_Viewer *viewer, const vnc_Viewer_ConnectionCallback *callback, void *userData)

Sets the callbacks for the Viewer to call when various events occur during its lifetime.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • callback -

    The new connection callback.

Return Value
  • InvalidArgument -

    The callback is invalid

vnc_ConnectionHandler *vnc_Viewer_getConnectionHandler(vnc_Viewer *viewer)

Returns the viewer’s vnc_ConnectionHandler for accepting connections.

The connection handler must not be used after the viewer has been destroyed; any Cloud listener using this viewer must be destroyed before the viewer itself.

vnc_Viewer_ConnectionStatus vnc_Viewer_getConnectionStatus(vnc_Viewer *viewer)

Returns the status of the viewer’s connection.

See vnc_Viewer_ConnectionStatus() for possible values.

const char *vnc_Viewer_getPeerAddress(vnc_Viewer *viewer)

Returns the address of the viewer’s server.

The format of the string is [vnccloud:<cloud-address>] for VNC Cloud addresses. The string is only guaranteed to be valid until the next call to any SDK function.

Return
The address as a NULL-terminated string, or NULL in the case of an error, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

Return Value
  • UnexpectedCall -

    The viewer is not connected

vnc_status_t vnc_Viewer_disconnect(vnc_Viewer *viewer)

Disconnects this viewer from the server.

Sets the disconnection reason to ViewerClosedConnection. This method does nothing if the viewer is not currently connected. Once disconnected you may subsequently connect the viewer to the same server again.

Return
vnc_success.
Parameters
  • viewer -

    The Viewer.

const char *vnc_Viewer_getDisconnectReason(vnc_Viewer *viewer)

Returns a string ID representing the reason for the last viewer disconnection.

Returns NULL if there have not been any disconnections, or the viewer has been connected again since the last disconnection.

Some of the connection reasons are sent by the server to explain the reason for ending the connection. These disconnection reasons are free-form and a third-party server may send reasons not on this list. To help diagnosing the cause of the disconnection, vnc_Viewer_getDisconnectMessage() can be used to get a human-readable message sent by the server which explains the reason. Possible reasons sent by the server are:

  • AuthFailure: the viewer user did not provide appropriate credentials
  • ConnTimeout: the connection reached its maximum duration
  • IdleTimeout: the connection timed out after no activity. This can happen when the connection is being established if the requested credentials are not sent within a reasonable amount of time.
  • ServerShutdown: the server process has shut down (the disconnection message may include further details)
  • ServerSuspended: the server machine is going in suspend mode
  • TooManySecFail: too many security failures have occurred in a short space of time, so the server has rejected the connection
  • UserSwitch: the server machine is switching desktops, causing a temporary disconnection.

In addition, ServerClosedConnection indicates a normal disconnection initiated by the server.

Some of the reasons occur when the viewer initiates the disconnection, in which case the list of possible disconnection reasons is known in advance. Possible reasons known to the viewer are:

  • CloudAuthenticationFailed: the Cloud password or address is incorrect
  • CloudConnectionRefused: the local Cloud address does not have permission to connect to the server’s Cloud address
  • CloudTargetNotFound: there is no server listening on the Cloud address
  • DataStoreError: there is no data store
  • ViewerCancelledAuthentication: authentication was cancelled by calling vnc_Viewer_sendAuthenticationResponse() with ok as vnc_false
  • ViewerClosedConnection: the connection was closed by calling vnc_Viewer_disconnect()
  • ViewerRejectedConnection: the connection was rejected by the viewer not accepting the connection security or peer identity via the vnc_Viewer_PeerVerificationCallback::verifyPeer callback.

Finally, some of the reasons can occur both from the viewer or server, or somewhere in between! Possible reasons are:

  • ConnectivityError: a connection to the server could not be established, or there was an error reading or writing to the peer
  • ConnectionDropped: the connection was closed at the transport level, with no closing handshake
  • ConnectionNegotiationError: the connection could not be established due to an error during negotiation with the peer; consult the debug logs for more information.
  • ConnectionResolveError: a specified Direct TCP hostname or IP address is malformed, or is not legitimate (e.g. DNS lookup fails), or the resolver service cannot be reached; consult the debug logs for more information.

If cause is not recognized, the reason will be Unknown; please consult the debug logs for more information on the underlying cause of the disconnection.

const char *vnc_Viewer_getDisconnectMessage(vnc_Viewer *viewer)

Returns a human-readable message sent by the server for the last disconnection, or NULL if the last disconnection was not initiated by the server.

If the reason for the disconnection originated at the viewer end then there is no message, since the reason string comes from a known set of possibilities.

Functions for managing the framebuffer

vnc_status_t vnc_Viewer_setFramebufferCallback(vnc_Viewer *viewer, const vnc_Viewer_FramebufferCallback *callback, void *userData)

Sets the framebuffer callback for this viewer.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

  • callback -

    The new framebuffer callback.

Return Value
  • InvalidArgument -

    The callback is invalid

vnc_status_t vnc_Viewer_setViewerFb(vnc_Viewer *viewer, void *pixels, int pixelsBytes, const vnc_PixelFormat *pf, int width, int height, int stride)

Sets the viewer framebuffer.

The pixel data received from the server will be rendered into the buffer in the given pixel format, scaled to fit the given size, and with the given stride.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

  • pixels -

    Pointer to the framebuffer to receive pixel data. The buffer must be large enough, i.e. stride * height pixels. Alternatively, pass NULL for a buffer owned by the SDK to be allocated for you.

  • pixelsBytes -

    The size in bytes of the buffer pointed to by pixels (ignored if pixels is NULL).

  • pf -

    Pixel format for the pixel data.

  • width -

    The width of the framebuffer.

  • height -

    The height of the framebuffer

  • stride -

    The stride of the framebuffer, i.e. the number of pixels from the start of one row to the next. If specified as zero then the width is used. Note that this is specified in terms of pixels, not bytes.

Return Value
  • InvalidArgument -

    width or height is zero or negative, the stride is invalid, or the pixels buffer is not large enough

int vnc_Viewer_getViewerFbWidth(vnc_Viewer *viewer)

Gets the width of the viewer framebuffer.

int vnc_Viewer_getViewerFbHeight(vnc_Viewer *viewer)

Gets the height of the viewer framebuffer.

const vnc_PixelFormat *vnc_Viewer_getViewerFbPixelFormat(vnc_Viewer *viewer)

Gets the pixel format of the viewer framebuffer.

const vnc_DataBuffer *vnc_Viewer_getViewerFbData(vnc_Viewer *viewer, int x, int y, int w, int h)

Returns the viewer framebuffer data for the given rectangle.

The returned object is valid until the next call to vnc_Viewer_getViewerFbData() or vnc_Viewer_setViewerFb(). The stride of the data is given by vnc_Viewer_getViewerFbStride().

Return
Returns the data buffer, or NULL on error, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

  • x -

    The left edge of the rectangle.

  • y -

    The top edge of the rectangle.

  • w -

    The width of the rectangle.

  • h -

    The height of the rectangle.

Return Value
  • InvalidArgument -

    w or h are zero or negative, or the rectangle is not fully contained within the framebuffer

int vnc_Viewer_getViewerFbStride(vnc_Viewer *viewer)

Returns the stride of the viewer framebuffer data in pixels, that is, the number of pixels from the start of each row until the start of the next.

Return
The stride in pixels.
Parameters
  • viewer -

    The Viewer.

Functions for managing server events

vnc_status_t vnc_Viewer_setServerEventCallback(vnc_Viewer *viewer, const vnc_Viewer_ServerEventCallback *callback, void *userData)

Sets the server event callback for this viewer.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

  • callback -

    The new server event callback.

Return Value
  • InvalidArgument -

    The callback is invalid

Functions for sending input

enum vnc_Viewer_MouseButton

Enumeration of mouse buttons.

Here “left” and “right” refer to logical buttons, which may not correspond to the physical orientation of the buttons if using a left-handed mouse.

Values:

vnc_Viewer_MouseButtonLeft = 1

The logical left mouse button.

vnc_Viewer_MouseButtonMiddle = 2

The logical middle mouse button.

vnc_Viewer_MouseButtonRight = 4

The logical right mouse button.

enum vnc_Viewer_MouseWheel

Enumeration of mouse wheel directions.

Values:

vnc_Viewer_MouseWheelHorizontal = 1

The horizontal scroll wheel.

vnc_Viewer_MouseWheelVertical = 2

The vertical scroll wheel.

vnc_status_t vnc_Viewer_sendClipboardText(vnc_Viewer *viewer, const char *text)

Copies the given text to the server’s clipboard.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

  • text -

    The UTF-8 encoded text.

Return Value
  • InvalidArgument -

    text is NULL

vnc_status_t vnc_Viewer_sendPointerEvent(vnc_Viewer *viewer, int x, int y, int buttonState, vnc_bool_t rel)

Sends a pointer event to the server.

If rel is vnc_false then x and y give the absolute position of the mouse pointer in viewer framebuffer coordinates with 0,0 at the top-left of the framebuffer. If rel is vnc_true then x and y give the relative movement delta in “mickeys”.

Attempting to use coordinates outside of the viewer framebuffer will result in an undefined behaviour.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
Return Value
  • InvalidArgument -

    buttonState is invalid

vnc_status_t vnc_Viewer_sendScrollEvent(vnc_Viewer *viewer, int delta, vnc_Viewer_MouseWheel axis)

Sends a scroll wheel event to the server.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

  • delta -

    The number of scroll wheel “ticks”. You may need to reduce the value provided by a high-resolution scroll device to get appropriate behavior (for example, one tick is equivalent to a distance of 120 in the Win32 API). If delta is negative then the movement is upwards or towards the left, if positive then the movement is downwards or towards the right.

  • axis -

    The scroll axis (either vnc_Viewer_MouseWheelHorizontal or vnc_Viewer_MouseWheelVertical).

Return Value
  • InvalidArgument -

    axis is invalid

vnc_status_t vnc_Viewer_sendKeyDown(vnc_Viewer *viewer, vnc_uint31_t keysym, int keyCode)

Sends a key down (press) event to the server.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

  • keysym -

    The keysym value representing the meaning of the pressed key. Use vnc_unicodeToKeysym() to convert a unicode character to a keysym. See vnc/Keyboard.h for common keysym values for non-character keys.

  • keyCode -

    An integer code representing the physical key which has been pressed. The SDK only uses this to match up the corresponding call to vnc_Viewer_sendKeyUp().

vnc_status_t vnc_Viewer_sendKeyUp(vnc_Viewer *viewer, int keyCode)

Sends a key up (release) event to the server.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

  • keyCode -

    An integer code representing the physical key which has been released. If there was no prior call to vnc_Viewer_sendKeyDown() for this keyCode, it is simply ignored.

vnc_status_t vnc_Viewer_releaseAllKeys(vnc_Viewer *viewer)

Send key up events for all currently pressed keys.

Typically you call this when the viewer loses keyboard focus.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

Functions for managing connection negotiation

enum vnc_Viewer_PictureQuality

Enumeration of picture quality levels.

Values:

vnc_Viewer_PictureQuality_Auto = 0

Auto quality means that the viewer selects an appropriate encoding and colour level based on its own line speed estimate.

vnc_Viewer_PictureQuality_High = 1
vnc_Viewer_PictureQuality_Medium = 2
vnc_Viewer_PictureQuality_Low = 3
enum vnc_Viewer_EncryptionLevel

Enumeration of encryption levels.

See
vnc_Viewer_setEncryptionLevel()

Values:

vnc_Viewer_EncryptionLevel_Default = 0

Use strong encryption.

This is the default.

vnc_Viewer_EncryptionLevel_Maximum

Use the strongest available encryption, possibly at the cost of speed.

vnc_status_t vnc_Viewer_setAuthenticationCallback(vnc_Viewer *viewer, const vnc_Viewer_AuthenticationCallback *callback, void *userData)

Sets the callback to be called when a username and/or password is required.

If these are not provided then UI will be rendered into the framebuffer asking the user to provide the required information.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

  • callback -

    The new authentication callback.

Return Value

vnc_status_t vnc_Viewer_sendAuthenticationResponse(vnc_Viewer *viewer, vnc_bool_t ok, const char *user, const char *passwd)

Provides the SDK with the result of a username/password request.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

  • ok -

    This should be vnc_false if the user cancelled the password dialog.

  • user -

    This must not be NULL if needUser was vnc_true in the username/password request, otherwise it is ignored.

  • passwd -

    This must not be NULL if needPasswd was vnc_true in the username/password request, otherwise it is ignored.

Return Value
  • UnexpectedCall -

    The session is not waiting for a username/password response

  • InvalidArgument -

    user or passwd was requested but is NULL

vnc_status_t vnc_Viewer_setPeerVerificationCallback(vnc_Viewer *viewer, const vnc_Viewer_PeerVerificationCallback *callback, void *userData)

Sets the callbacks to be called to verify the identity of the peer (server).

If these are not provided for a VNC Cloud connection, the connection will continue regardless, since VNC Cloud automatically verifies peer identities for the connecting user. This check is for peace of mind only, and likely only to be useful if you have out-of-band access to a list of all potential Server identities.

If these are not provided for a Direct TCP connection, on the other hand, an identity verification dialog will automatically be displayed (rendered into the framebuffer), since the connecting user really should consider the risk of connecting to a MITM or other malicious entity.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

  • callback -

    The new peer verification callback.

Return Value

vnc_status_t vnc_Viewer_sendPeerVerificationResponse(vnc_Viewer *viewer, vnc_bool_t ok)

Provides the SDK with the response to the vnc_Viewer_PeerVerificationCallback::verifyPeer request.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The Viewer.

  • ok -

    vnc_true if the connection is approved, vnc_false if it should be rejected.

Return Value
  • UnexpectedCall -

    No peer verification is in progress

vnc_AnnotationManager *vnc_Viewer_getAnnotationManager(vnc_Viewer *viewer)

Obtains the Viewer’s vnc_AnnotationManager for handling annotation operations.

Return
A vnc_AnnotationManager, valid for the lifetime of the Viewer.
Since
1.4
Parameters
  • viewer -

    The current Viewer.

vnc_Viewer_PictureQuality vnc_Viewer_getPictureQuality(vnc_Viewer *viewer)

Returns the viewer’s current picture quality.

This returns the actual picture quality in use if the viewer is connected, or the last value set otherwise.

vnc_status_t vnc_Viewer_setPictureQuality(vnc_Viewer *viewer, vnc_Viewer_PictureQuality quality)

Sets the desired picture quality of the session from the range of options enumerated by vnc_Viewer_PictureQuality.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The current Viewer.

  • quality -

    The new picture quality.

Return Value
  • InvalidArgument -

    The picture quality is invalid

vnc_MessagingManager *vnc_Viewer_getMessagingManager(vnc_Viewer *viewer)

Obtains the Viewer’s Messaging Manager for handling messaging.

vnc_status_t vnc_Viewer_setEncryptionLevel(vnc_Viewer *viewer, vnc_Viewer_EncryptionLevel level)

Sets the desired encryption level of the session from the range of options enumerated by vnc_Viewer_EncryptionLevel.

This will not affect the encryption level of established connections.

If a Viewer and Server select different encryption levels, connections between them take place at the higher of their selected levels.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Parameters
  • viewer -

    The current Viewer.

  • level -

    The new encryption level.

Return Value
  • InvalidArgument -

    The encryption level is invalid

vnc_Viewer_EncryptionLevel vnc_Viewer_getEncryptionLevel(vnc_Viewer *viewer)

Returns the Viewer’s current encryption level.

This returns the actual encryption level in use if the Viewer is connected, or the last value set otherwise.

Functions

vnc_Viewer *vnc_Viewer_create(void)

Creates and returns a new viewer.

Return
Returns a new vnc_Viewer.

void vnc_Viewer_destroy(vnc_Viewer *viewer)

Destroys the viewer.

struct vnc_Viewer_ConnectionCallback
#include <Viewer.h>

Callback receiving state-change notifications for a Viewer.

Public Members

void(* vnc_Viewer_ConnectionCallback::connecting)(void *userData, vnc_Viewer *viewer)

Notification that is called when the viewer begins a connection attempt to the server.

This callback is optional.

When vnc_CloudConnector_connect() is called, the connecting callback will be invoked on the next turn of the event loop, so it is normally not useful to implement this callback, since the application’s UI state can be updated straight away.

If however the viewer creates connections using a Cloud listener, then the connecting callback is essential to implement. This is because each viewer object can only handle a single connection at a time, so it makes no sense to continue listening once the viewer has started handling a connection. If a second connection comes in, the viewer will not be able to accept it and an error will be logged. To stop listening, the Cloud listener should be destroyed from the connecting callback.

void(* vnc_Viewer_ConnectionCallback::connected)(void *userData, vnc_Viewer *viewer)

Notification that is called when the viewer successfully connects to a server (after authentication).

This callback is optional.

void(* vnc_Viewer_ConnectionCallback::disconnected)(void *userData, vnc_Viewer *viewer, const char *reason, int flags)

Notification that is called when the viewer disconnects from the server.

This callback is optional.

Parameters

struct vnc_Viewer_FramebufferCallback
#include <Viewer.h>

Callback receiving framebuffer event notifications for a Viewer.

Public Members

void(* vnc_Viewer_FramebufferCallback::serverFbSizeChanged)(void *userData, vnc_Viewer *viewer, int w, int h)

Notification that the server’s framebuffer size has changed.

You may choose to resize the viewer framebuffer by calling vnc_Viewer_setViewerFb() from this function, for example, to maintain a consistent aspect ratio. This callback is optional.

Parameters
  • w -

    The width of the server’s framebuffer.

  • h -

    The height of the server’s framebuffer.

void(* vnc_Viewer_FramebufferCallback::viewerFbUpdated)(void *userData, vnc_Viewer *viewer, int x, int y, int w, int h)

Notification that the given rectangle of the viewer’s framebuffer has been updated with new pixel data.

This callback is optional.

struct vnc_Viewer_ServerEventCallback
#include <Viewer.h>

Callback receiving server event notifications for a Viewer.

Public Members

void(* vnc_Viewer_ServerEventCallback::serverClipboardTextChanged)(void *userData, vnc_Viewer *viewer, const char *text)

Notification that the server’s clipboard contains new text.

This callback is optional.

Parameters
  • text -

    The UTF-8 encoded text.

void(* vnc_Viewer_ServerEventCallback::serverFriendlyNameChanged)(void *userData, vnc_Viewer *viewer, const char *name)

Notification that the server’s friendly name has changed.

This callback is optional.

Parameters
  • name -

    The UTF-8 encoded name.

struct vnc_Viewer_AuthenticationCallback
#include <Viewer.h>

Callback receiving requests for authentication for a Viewer.

Public Members

void(* vnc_Viewer_AuthenticationCallback::requestUserCredentials)(void *userData, vnc_Viewer *viewer, vnc_bool_t needUser, vnc_bool_t needPasswd)

Request for a username and/or password.

Implementors should reply with a username and/or password either immediately or later, by calling vnc_Viewer_sendAuthenticationResponse(). This callback function is required if using a vnc_Viewer_AuthenticationCallback. This callback will not be triggered if no credentials are required.

Parameters
  • needUser -

    Whether a username must be supplied.

  • needPasswd -

    Whether a password must be supplied.

void(* vnc_Viewer_AuthenticationCallback::cancelUserCredentialsRequest)(void *userData, vnc_Viewer *viewer)

Notification to cancel a username and/or password request.

This can happen if the server closes the connection while the Viewer is waiting for the user to provide a username/password. This callback is optional.

struct vnc_Viewer_PeerVerificationCallback
#include <Viewer.h>

Callback receiving verification requests to check the peer’s identity.

Public Members

void(* vnc_Viewer_PeerVerificationCallback::verifyPeer)(void *userData, vnc_Viewer *viewer, const char *hexFingerprint, const char *catchphraseFingerprint, const vnc_DataBuffer *serverRsaPublic)

Request to verify the identity of the peer (the server).

Implementors should respond by calling vnc_Viewer_sendPeerVerificationResponse(). This callback function is required if using a vnc_Viewer_PeerVerificationCallback.

Apart from cancelPeerVerification, no further callbacks (such as disconnected) will be issued for this connection until peer verification has been completed succesfully.

Parameters
  • hexFingerprint -

    The hash of the server’s fingerprint, as a string of hexadecimal digits.

  • catchphraseFingerprint -

    The hash of the server’s fingerprint, as a catchphrase.

  • serverRsaPublic -

    The server’s public key, in the format returned by vnc_RsaKey_getDetails().

void(* vnc_Viewer_PeerVerificationCallback::cancelPeerVerification)(void *userData, vnc_Viewer *viewer)

Notification to cancel a prior request for peer verification.

This can happen if the server closes the connection while peer verification is in progress. This callback is optional.

×