Enums

enum vnc_Server_CaptureMethod¶

Enumeration of screen capture methods.

See

vnc_Server_setCaptureMethod()

Values:

vnc_Server_CaptureOptimal = 0¶

Use the optimal capture method for the platform.

This is the default.

vnc_Server_CaptureFallback¶

Use a fallback capture method under Windows and Linux.

This is likely to be slower, but may solve rendering glitches with certain third-party applications. Not supported under Mac OS X.

enum vnc_Server_Permissions¶

Enumeration of session permissions that can be granted to a connecting Viewer.

(Flags can be combined into a mask.)

See

vnc_Server_SecurityCallback::authenticateUser

Values:

vnc_Server_PermView = 0x01¶

Grants a Viewer permission to see the screen.

Rarely omitted.

vnc_Server_PermKeyboard = 0x02¶

Grants a Viewer permission to inject keyboard events.

vnc_Server_PermPointer = 0x04¶

Grants a Viewer permission to inject mouse and touch events.

vnc_Server_PermClipboard = 0x08¶

Grants a Viewer permission to copy and paste text to and from the Server.

vnc_Server_PermAnnotation = 0x10¶

Grants a Viewer permission to draw on the Server screen.

vnc_Server_PermSelectDisplay = 0x20¶

Grants a Viewer pemission to select the Server’s display.

vnc_Server_PermListen = 0x40¶

Grants a Viewer pemission to listen to the Server.

vnc_Server_PermAll = 0x7fffffff¶

Grants a Viewer a full set of permissions (that is, all of the above).

enum vnc_Server_DisconnectFlags¶

Enumeration of disconnection flags.

See

vnc_Server_disconnect(), vnc_Server_disconnectAll()

Since

1.1

Values:

vnc_Server_DisconnectAlert = 1¶

The disconnection message is deemed to be sufficiently important that the Viewer should alert the Viewer user.

vnc_Server_DisconnectReconnect = 2¶

Set the peer’s vnc_Viewer_CanReconnect flag, that is, the Server informs the Viewer that the server may start again soon.

enum vnc_Server_EncryptionLevel¶

Enumeration of encryption levels.

See

vnc_Server_setEncryptionLevel()

Values:

vnc_Server_EncryptionLevel_Default = 0¶

Use strong encryption.

This is the default.

vnc_Server_EncryptionLevel_Maximum¶

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

vnc_Server_EncryptionLevel_AllowUnencrypted¶

Allow the negotation of encryption levels, including no encryption.

Use with caution. Requires a Third-Party Connectivity Add-on.

Functions

vnc_Server *vnc_Server_create(const char *agentPath)¶

Creates a Server.

Note only one vnc_Server should exist in your application at a time.

The Server captures the current session, which may be switched-out or otherwise not visible on the console.

Return

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

See

Use vnc_Server_createService() to create a Server which captures the console.

Parameters

• agentPath -

  The full path to the vncagent executable, or NULL to specify that vncagent is in the same directory as the app binary at run-time. If you provide a directory, the executable must be called vncagent (vncagent.exe on Windows); if you have renamed vncagent then the filename must be provided.

Return Value

• FileError -

  vncagent could not be found, or the file specified does not exist

• AgentError -

  vncagent cannot be executed or its version number does not match that of the SDK

• UnexpectedCall -

  A vnc_Server already exists in your application

vnc_Server *vnc_Server_createService(const char *agentPath)¶

Creates a Server running as a service.

Note only one vnc_Server should exist in your application at a time.

The Server captures the machine’s console, which may be a logged-in user session or a login prompt. Running as a service requires elevated privileges, and must be done from a Windows Service (Windows), a launch daemon (Mac), or a root process (Linux).

On Windows, the vncagent executable must be located within either the %ProgramFiles% or %ProgramFiles(x86)% directories in order to allow the injection of secure key sequences (e.g. Ctrl-Alt-Del).

On Mac OS X, an instance of vncagent must separately be run in each graphical session as a launch agent. The agentPath provided here must match the path of these launch agents in order that the SDK can communicate with them.

Return

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

See

Use vnc_Server_create() to create a Server which captures the current session.

Since

1.1

Parameters

• agentPath -

  The path to the vncagent executable (see vnc_Server_create() for details).

Return Value

• AgentError -

  vncagent cannot be found or its version number does not match that of the SDK

• UnexpectedCall -

  A vnc_Server already exists in your application

void vnc_Server_destroy(vnc_Server *server)¶

Destroys the Server.

Any Viewers still connected will be disconnected, and the peer’s vnc_Viewer_CanReconnect flag will be set, indicating that server may start again soon. If this is not desired, call vnc_Server_disconnectAll() without the vnc_Server_DisconnectReconnect flag before destroying the Server.

Parameters

• server -

  The current Server.

vnc_status_t vnc_Server_setConnectionCallback(vnc_Server *server, const vnc_Server_ConnectionCallback *callback, void *userData)¶

Sets connection-related callbacks for the Server.

Return

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

Parameters

• server -

  The current Server.

• callback -

  The new connection event callback.

int vnc_Server_getConnectionCount(vnc_Server *server)¶

Returns the total number of Viewers currently connected to the Server.

Since

1.1

vnc_status_t vnc_Server_setSecurityCallback(vnc_Server *server, const vnc_Server_SecurityCallback *callback, void *userData)¶

Sets security-related callbacks for the Server.

Return

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

Parameters

• server -

  The current Server.

• callback -

  The new security event callback.

vnc_status_t vnc_Server_setPermissions(vnc_Server *server, vnc_Connection *connection, int perms)¶

Changes permissions for a Viewer mid-session.

Return

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

Parameters

• server -

  The current Server.

• connection -

  The Viewer whose permissions to change.

• perms -

  Any combination of the vnc_Server_Permissions flags, or 0 (no permissions) to render the session ineffective.

int vnc_Server_getPermissions(vnc_Server *server, vnc_Connection *connection)¶

Gets the set of current permissions for a Viewer.

Return

Zero or more of the vnc_Server_Permissions flags.

Parameters

• server -

  The current Server.

• connection -

  The Viewer whose permissions to get.

vnc_status_t vnc_Server_setAgentCallback(vnc_Server *server, const vnc_Server_AgentCallback *callback, void *userData)¶

Sets agent-related callbacks for the Server.

These are not used on Android.

Return

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

Since

1.1

Parameters

• server -

  The current Server.

• callback -

  The new agent event callback.

vnc_bool_t vnc_Server_isAgentReady(vnc_Server *server)¶

Determines if the vncagent process is ready and available to capture the display and inject input events.

If the vncagent is not ready, then the display cannot be captured at present. This could be because it is starting up or being restarted due to a user logout, or an error. On Linux, this can also indicate that the X server is not running. On Android, vncagent is not used and this function will always return vnc_true.

See vnc_Server_setAgentCallback() for receiving callbacks when the agent process starts and stops.

Since

1.1

Parameters

• server -

  The current Server.

Return Value

• vnc_true -

  The vncagent process is ready

• vnc_false -

  The vncagent process is not ready or not running.

void vnc_Server_setFriendlyName(vnc_Server *server, const char *name)¶

Specifies a friendly name for the Server, to send to connected Viewers.

By default, this is the device’s hostname, plus the display number where appropriate.

Parameters

• server -

  The current Server.

• name -

  The UTF-8-encoded friendly name.

vnc_ConnectionHandler *vnc_Server_getConnectionHandler(vnc_Server *server)¶

Obtains the Server’s vnc_ConnectionHandler for performing connection operations.

Typically, a vnc_ConnectionHandler is passed to vnc_CloudListener_create() to start the Server listening for connections. However, you can reverse this methodology and pass it to vnc_CloudConnector_create() instead in order to connect to listening Viewers if you want (see Viewer.h for more information).

Return

A vnc_ConnectionHandler, valid for the lifetime of the Server.

Parameters

• server -

  The current Server.

const char *vnc_Server_getPeerAddress(vnc_Server *server, vnc_Connection *connection)¶

Returns the address of a particular connected Viewer.

The format of the null-terminated string is [vnccloud:<cloud-address>]:<id> Note the string is only guaranteed to be valid until the next method call.

Return

A NULL-terminated string in the format [vnccloud:<cloud-address>]:<id>.

Parameters

• server -

  The current Server.

• connection -

  The connection whose Cloud address you want. You can obtain a vnc_Connection from your callback function vnc_Server_ConnectionCallback::connectionStarted.

void vnc_Server_disconnect(vnc_Server *server, vnc_Connection *connection, const char *message, int flags)¶

Disconnects a particular Viewer, optionally specifying a message.

See

vnc_Viewer_getDisconnectMessage()

Parameters

• server -

  The current Server.

• connection -

  The connection to terminate. You can obtain a vnc_Connection from your callback function vnc_Server_ConnectionCallback::connectionStarted.

• message -

  The message to send to the Viewer.

• flags -

  Zero or more of the vnc_Server_DisconnectFlags flags.

void vnc_Server_disconnectAll(vnc_Server *server, const char *message, int flags)¶

Disconnects all Viewers, optionally specifying a message.

See

vnc_Viewer_getDisconnectMessage()

Parameters

• server -

  The current Server.

• message -

  The message to send to all Viewers.

• flags -

  Zero or more of the vnc_Server_DisconnectFlags flags.

vnc_status_t vnc_Server_setBlacklist(vnc_Server *server, int threshold, int timeout)¶

Specifies a blacklist threshold and timeout for the Server.

By default, the threshold is 5, which means that a Viewer failing to authenticate five times in a row is blacklisted for the default timeout of 10 seconds. This guards against brute-force and dictionary attacks.

To completely disable blacklisting, set threshold and timeout to 0. For security reasons this is not recommended.

Return

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

Parameters

• server -

  The current Server.

• threshold -

  A number of unsuccessful authentication attempts before blacklisting.

• timeout -

  A number of seconds before a blacklisted Viewer can attempt to authenticate again.

Return Value

• InvalidArgument -

  timeout is zero or negative

void vnc_Server_serviceControlHandlerEx(vnc_Server *server, int dwControl, int dwEventType, void *lpEventData)¶

Handles a Windows Service control event.

When Server has been created via vnc_Server_createService(), then Windows Service control events must be forwarded to the Server so that active session can be determined. See the Win32 function RegisterServiceCtrlHandlerEx and the HandlerEx callback for more information.

This function can be called for all notifications received via your HandlerEx callback, but in particular it must be called for notifications where the control code (dwControl) is SERVICE_CONTROL_SESSIONCHANGE.

This method is designed to be called from the Service Control Dispatcher thread, rather than the thread which called vnc_init().

Since

1.1

Parameters

• dwControl -

  The control code passed to HandlerEx

• dwEventType -

  The type of event passed to HandlerEx

• lpEventData -

  The event data passed to HandlerEx

vnc_status_t vnc_Server_enableAudio(vnc_Server *server, vnc_bool_t enable)¶

Enables transmission of audio from the Server to the Viewer.

The audio stream will be automatically negotiated with the peer endpoint, if possible, and any audio data will be captured from the device’s default audio mixer. By default, this is enabled and the Server will attempt to negotiate an audio channel with any connecting viewers.

Return

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

Since

1.9

Parameters

• server -

  The Server.

• 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_Server_getAnnotationManager(vnc_Server *server)¶

Obtains the Server’s vnc_AnnotationManager for handling annotation operations.

Return

A vnc_AnnotationManager, valid for the lifetime of the Server.

Since

1.4

Parameters

• server -

  The current Server.

vnc_MessagingManager *vnc_Server_getMessagingManager(vnc_Server *server)¶

Obtains the Server’s vnc_MessagingManager for handling messaging.

Return

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

Since

1.5

Return Value

• NotEnabled -

  The Messaging feature is not enabled for this Server.

vnc_DisplayManager *vnc_Server_getDisplayManager(vnc_Server *server)¶

Obtains the Server’s vnc_DisplayManager, for managing the list of displays made available by the Server and for setting the Server’s capture method.

Return

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

Since

1.5

Parameters

• server -

  The current Server.

vnc_status_t vnc_Server_setEncryptionLevel(vnc_Server *server, vnc_Server_EncryptionLevel level)¶

Sets the desired encryption level of the session from the range of options enumerated by vnc_Server_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

• server -

  The current Server.

• level -

  The new encryption level.

Return Value

• InvalidArgument -

  The encryption level is invalid

vnc_Server_EncryptionLevel vnc_Server_getEncryptionLevel(vnc_Server *server, vnc_Connection *connection)¶

Returns the encryption level being used with an incoming connection, or the Server’s current encryption level if the connection is NULL.

Parameters

• server -

  The current Server.

• connection -

  The incoming connection or NULL.

vnc_status_t vnc_Server_setVncAuthPassword(vnc_Server *server, const char *password)¶

Set a password for use with third-party VNC Viewers, using VncAuth authentication.

Use in conjunction with vnc_Server_setEncryptionLevel(), setting the level to vnc_Server_EncryptionLevel_AllowUnencrypted, enabled by the Third-Party Connectivity add-on. If all requirements above are met, this password will be used instead of the vnc_Server_SecurityCallback callbacks.

Parameters

• server -

  The current Server.

• password -

  The VncAuth password.

Return Value

• UnexpectedCall -

  The Third-Party Connectivity Add-on is not available

vnc_status_t vnc_Server_setIdleTimeout(vnc_Server *server, int idleTimeout)¶

Sets the number of seconds to wait before disconnecting idle Viewers.

To turn off the idle timeout, use a value of 0.

Return

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

Parameters

• server -

  The current Server.

• idleTimeout -

  The idle timeout in seconds.

Return Value

• InvalidArgument -

  The idle timeout is invalid

int vnc_Server_getIdleTimeout(vnc_Server *server)¶

Gets the current number of seconds to wait before disconnecting idle Viewers.

A value of 0 indicates no timeout is set.

Parameters

• server -

  The current Server.

vnc_status_t vnc_Server_setInputEventsCallback(vnc_Server *server, const vnc_Server_InputEventsCallback *callback, void *userData)¶

Sets input control related callbacks for the Server.

Return

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

Parameters

• server -

  The current Server.

• callback -

  The new input event callbacks.

vnc_status_t vnc_Server_setCaptureMethod(vnc_Server *server, vnc_Server_CaptureMethod captureMethod)¶

Specifies the screen capture method used by the Server.

By default, an optimal method is chosen for each platform. In the unlikely event you experience screen capture issues under Windows or Linux, try the fallback method (this is not supported under Mac OS X).

Return

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

Parameters

• server -

  The current Server.

• captureMethod -

  One of the vnc_Server_CaptureMethod flags.

Return Value

• NotSupported -

  captureMethod is not supported on this platform.