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 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_setServerPointerCallback(vnc_Viewer *viewer, const vnc_Viewer_ServerPointerCallback *callback, void *userData)¶

Sets the server pointer callback for this viewer.

Return

vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.

Since

1.10

Parameters

• viewer -

  The Viewer.

• callback -

  The new server event callback.

Return Value

• InvalidArgument -

  The callback is invalid

void vnc_Viewer_setServerPointerFbPixelFormat(vnc_Viewer *viewer, const vnc_PixelFormat *pf)¶

Sets the pixel format of the pointer framebuffer.

If not set, the pixel format will be vnc_PixelFormat_rgb888.

Since

1.10

Parameters

• viewer -

  The Viewer.

• pf -

  Pixel format for the pixel data.

void vnc_Viewer_setServerPointerPosPeriod(vnc_Viewer *viewer, int periodMs)¶

Sets the rate with which serverPointerPos callback will be called.

Since

1.10

Parameters

• viewer -

  The Viewer.

• periodMs -

  The period in milliseconds between serverPointerPos calls.

int vnc_Viewer_getServerPointerFbWidth(vnc_Viewer *viewer)¶

Gets the width of the pointer framebuffer.

int vnc_Viewer_getServerPointerFbHeight(vnc_Viewer *viewer)¶

Gets the height of the pointer framebuffer.

int vnc_Viewer_getServerPointerXOffset(vnc_Viewer *viewer)¶

Gets the X offset of the “hotspot” of the pointer.

int vnc_Viewer_getServerPointerYOffset(vnc_Viewer *viewer)¶

Gets the Y offset of the “hotspot” of the pointer.

const vnc_PixelFormat *vnc_Viewer_getServerPointerFbPixelFormat(vnc_Viewer *viewer)¶

Gets the pixel format of the pointer framebuffer.

const vnc_DataBuffer *vnc_Viewer_getServerPointerFbData(vnc_Viewer *viewer)¶

Gets the current mouse cursor image from the Server for rendering locally.

The returned object is valid until the next call to vnc_Viewer_getServerPointerFbData().

Return

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

Since

1.10

Parameters

• viewer -

  The Viewer.

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

• viewer -

  The Viewer.

• x -

  The X coordinate.

• y -

  The Y coordinate.

• buttonState -

  A bitmask containing zero or more of vnc_Viewer_MouseButtonLeft, vnc_Viewer_MouseButtonMiddle and vnc_Viewer_MouseButtonRight, indicating which buttons are down, if any.

• rel -

  Whether the event is relative or absolute.

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_Viewer_EncryptionLevel_Server = 255¶

Respect the server’s choice of encryption level.

This means the viewer will allow connections to third-party servers, but also represents the weakest security, and may open the user up to man-in-the-middle type attacks. Use with caution. Note: to enable this feature, you will need a Third Party Connectivity Add-on code - contact RealVNC for more information.

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

• InvalidArgument -

  The vnc_Viewer_AuthenticationCallback::requestUserCredentials callback is NULL

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

• InvalidArgument -

  The vnc_Viewer_PeerVerificationCallback::verifyPeer callback is NULL

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_status_t vnc_Viewer_enableAudio(vnc_Viewer *viewer, vnc_bool_t enable)¶

Enables receipt of audio from the Server by the Viewer.

The audio stream will be automatically negotiated with the peer endpoint, if possible, and any received audio data will be played back via the device’s default audio mixer. By default, this is disabled and no audio channel will be negotiated.

Return

vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.

Since

1.9

Parameters

• viewer -

  The Viewer.

• enable -

  vnc_true to enable audio playback, vnc_false to disable.

Return Value

• PeerNotSupported -

  The peer endpoint does not support audio

• NotSupported -

  This platform does not support audio

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.

vnc_DisplayManager *vnc_Viewer_getDisplayManager(vnc_Viewer *viewer)¶

Obtains the Viewer’s vnc_DisplayManager, for managing the list of displays made available by the Server to the Viewer.

Return

A vnc_DisplayManager or NULL on error, in which case call vnc_getLastError() to get the error code.

Since

1.8.0

Parameters

• viewer -

  The current Viewer.

Return Value

• NotSupported -

  Display management is not supported on the Server’s platform.

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

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.