Struct VncServer

Source

pub struct VncServer { /* private fields */ }

Expand description

Represents a VNC server instance.

This struct manages the VNC framebuffer, connected clients, and handles server-wide events.

Implementations§

Source §

impl VncServer

Source

pub fn new( width: u16, height: u16, desktop_name: String, password: Option<String>, ) -> (Self, UnboundedReceiver<ServerEvent>)

Creates a new VncServer instance.

This function initializes the framebuffer, sets up desktop name and password, and prepares channels for server events.

§Arguments

width - The width of the VNC framebuffer.
height - The height of the VNC framebuffer.
desktop_name - The name of the desktop to be advertised to clients.
password - An optional password for client authentication.

§Returns

A tuple containing:

The VncServer instance itself.
An mpsc::UnboundedReceiver<ServerEvent> to receive events generated by the server.

Source

pub async fn listen(&self, port: u16) -> Result<(), Error>

Starts the VNC server, listening for incoming client connections on the specified port.

This function enters an infinite loop, accepting new TCP connections and spawning a new asynchronous task to handle each client.

§Arguments

port - The TCP port on which the server will listen for connections.

§Returns

Ok(()) if the server starts successfully and listens indefinitely.

§Errors

Returns Err(std::io::Error) if there is an issue binding to the port or accepting connections.

Source

pub fn framebuffer(&self) -> &Framebuffer

Returns a reference to the server’s Framebuffer.

This allows external components to inspect or modify the framebuffer content.

§Returns

A reference to the Framebuffer instance.

Source

pub fn framebuffer_mut(&mut self) -> &mut Framebuffer

Returns a mutable reference to the server’s Framebuffer.

This allows external components to modify the framebuffer, including resizing.

§Returns

A mutable reference to the Framebuffer instance.

Source

pub async fn send_cut_text_to_all(&self, text: String) -> Result<(), Error>

Sends the provided cut text (clipboard) to all currently connected VNC clients.

§Arguments

text - The string content to be sent as cut text.

§Returns

Ok(()) if the text is successfully queued for sending to all clients.

§Errors

Returns Err(std::io::Error) if an error occurs during the sending process to any client.

Source

pub async fn connect_reverse( &self, host: String, port: u16, ) -> Result<usize, Error>

Establishes a direct reverse VNC connection to a client viewer.

This method initiates an outbound TCP connection to a VNC viewer listening for reverse connections. The function spawns a background task to handle the connection lifecycle, including performing the VNC handshake, spawning a message handler task, and processing client events. Task handles, write stream handles, and client IDs are stored for proper cleanup during server shutdown.

§Arguments

host - The hostname or IP address of the VNC viewer.
port - The port on which the VNC viewer is listening.

§Returns

Ok(client_id) if the reverse connection is successfully established.

§Errors

Returns Err(std::io::Error) if the connection fails or a client ID overflow occurs.

Source

pub async fn connect_repeater( &self, repeater_host: String, repeater_port: u16, repeater_id: String, ) -> Result<usize, Error>

Connects the VNC server to a VNC repeater, establishing a reverse connection.

This allows a client behind a NAT or firewall to connect to the server through a VNC repeater proxy. The function spawns a background task to handle the connection lifecycle, including performing the repeater handshake, VNC handshake, spawning a message handler task, and processing client events. Task handles, write stream handles, and client IDs are stored for proper cleanup during server shutdown.

The function waits for the repeater connection to be established before returning the client ID to the caller.

§Arguments

repeater_host - The hostname or IP address of the VNC repeater.
repeater_port - The port of the VNC repeater.
repeater_id - The ID to use when connecting to the repeater.

§Returns

Ok(client_id) if the connection to the repeater is successfully established, where client_id is the unique identifier assigned to the new repeater client.

§Errors

Returns Err(std::io::Error) if a client ID counter overflow occurs, or if there is an issue connecting to the repeater or handling the client.

Source

pub async fn find_client( &self, client_id: usize, ) -> Option<Arc<RwLock<VncClient>>>

Finds a client by its ID.

This method searches through all connected clients to find the one with the specified ID.

§Arguments

client_id - The client ID to search for.

§Returns

Some(Arc<RwLock<VncClient>>) if the client is found, None otherwise.

Source

pub async fn disconnect_client(&self, client_id: usize) -> bool

Disconnects a specific client by its ID.

This method forcibly closes the TCP connection for the specified client, which will cause the client’s message handler to exit and trigger cleanup.

§Arguments

client_id - The client ID to disconnect.

§Returns

true if the client was found and disconnected, false if not found.

Source

pub fn clients_try_read( &self, ) -> Result<RwLockReadGuard<'_, Vec<Arc<RwLock<VncClient>>>>, TryLockError>

Attempts to acquire a read lock on the clients list without blocking.

This is used by JNI methods to avoid blocking the main thread and causing ANR. If the lock cannot be acquired immediately, returns an error.

§Returns

Ok(RwLockReadGuard) if the lock was acquired.

§Errors

Returns Err(TryLockError) if the lock could not be acquired immediately.

Source

pub fn clients_try_write( &self, ) -> Result<RwLockWriteGuard<'_, Vec<Arc<RwLock<VncClient>>>>, TryLockError>

Attempts to acquire a write lock on the clients list without blocking.

This is used by JNI methods to avoid blocking the main thread and causing ANR. If the lock cannot be acquired immediately, returns an error.

§Returns

Ok(RwLockWriteGuard) if the lock was acquired.

§Errors

Returns Err(TryLockError) if the lock could not be acquired immediately.

Source

pub fn get_client_ids(&self) -> Result<Vec<usize>, TryLockError>

Gets a snapshot of all connected client IDs without locking VncClient objects.

This method is safe to call from JNI without risk of ANR because it only locks the lightweight client_ids list, not the heavy VncClient objects.

§Returns

Ok(Vec<usize>) containing all active client IDs.

§Errors

Returns Err(TryLockError) if the lock cannot be acquired.

Source

pub async fn disconnect_all_clients(&self)

Disconnects all connected clients by cleanly shutting down their tasks and TCP connections.

This method performs a coordinated shutdown sequence to ensure both halves of each client’s TCP connection are properly closed. The order of operations is critical to avoid orphaned connections:

Abort all client tasks - Signals all message handler and event handler tasks to cancel
Wait for tasks to exit - Blocks until tasks complete, ensuring their Arc<VncClient> references are dropped
Clear client lists - Removes the final Arc<VncClient> references from the server’s client list, causing VncClient to drop and automatically close the read half of the TCP connection
Close write halves - Explicitly calls shutdown() on the write halves to close the write side of the TCP connection

After this sequence completes, both sides of the TCP connection are closed and the client will receive a disconnect notification.

§Notes

The caller should wrap this in a timeout to prevent indefinite blocking
The caller is responsible for calling Java-side cleanup (e.g., removing cursors) before invoking this method
All client IDs, task handles, and write streams are cleared from their respective lists

Source

pub async fn schedule_copy_rect( &self, x: u16, y: u16, width: u16, height: u16, dx: i16, dy: i16, )

Schedules a copy rectangle operation for all connected clients (standard VNC protocol style).

This method iterates through all clients and schedules the specified region to be sent using CopyRect encoding. This is the equivalent of standard VNC protocol’s rfbScheduleCopyRect function.

§Arguments

x - The X coordinate of the destination rectangle.
y - The Y coordinate of the destination rectangle.
width - The width of the rectangle.
height - The height of the rectangle.
dx - The X offset from destination to source (src_x = dest_x + dx).
dy - The Y offset from destination to source (src_y = dest_y + dy).

Source

pub async fn do_copy_rect( &self, x: u16, y: u16, width: u16, height: u16, dx: i16, dy: i16, ) -> Result<(), String>

Performs a copy rectangle operation in the framebuffer and schedules it for all clients.

This method first copies the specified region within the framebuffer memory, then schedules the copy operation to be sent to all connected clients. This is the equivalent of standard VNC protocol’s rfbDoCopyRect function.