Struct x11rb_protocol::connect::Connect

pub struct Connect { /* private fields */ }

The connection handshake used to connect to the X11 server.

In order to connect to the X11 server, the client must send the server a request containing important pieces of client data. In response, the server sends the client a response containing one of the following:

• An error indicating that the setup request is malformed, or the setup otherwise failed.
• A request for further authorization data.
• The Setup for the connection, which contains server-specific information and is necessary for the client’s ability to communicate with the server.

This handshake contains four relevant methods:

• new, which creates the handshake and also returns the setup request to send to the server.
• buffer, which returns an &mut [u8] containing the buffer which is intended to hold the bytes received from the server.
• advance, which takes a usize indicating how many bytes were received from the server and advances the buffer.
• into_setup, which consumes this Connect and returns the full Setup.

Examples

Let’s say you have an object stream which implements Read and Write. In addition, you already have the connection family, the address of the connection, and the display. You can use the Connect to establish an X11 connection like so:

let family = Family::INTERNET;
let address = b"foobar";
let display = 0;

let (mut connect, setup_request) = Connect::new(family, address, display)?;

// send the setup request to the server
stream.write_all(&setup_request)?;

// receive the setup response from the server
loop {
    let adv = stream.read(connect.buffer())?;

    // if we've completed the setup, break out of the loop
    if connect.advance(adv) {
        break;
    }
}

// get the setup used for our connection
let setup = connect.into_setup()?;

If, instead, stream implements AsyncRead and AsyncWrite, the code would be identical, but with .await after read and write_all.

Implementations

impl Connect

pub fn with_authorization(
    protocol_name: Vec<u8>,
    protocol_data: Vec<u8>
) -> (Self, Vec<u8>)

Create a new Connect from the given authorization data.

This uses the provided protocol name and data to establish the connection, rather than the default protocol name and data found in Xauthority.

Example

let (connect, setup_request) = Connect::with_authorization(
    b"MIT-MAGIC-COOKIE-1".to_vec(),
    b"my_secret_password".to_vec(),
);

pub fn new(
    family: Family,
    address: &[u8],
    display: u16
) -> Result<(Self, Vec<u8>), ConnectError>

Create a new Connect from the information necessary to connect to the X11 server.

This returns the connection handshake object as well as the setup request to send to the server.

pub fn buffer(&mut self) -> &mut [u8]

Returns the buffer that needs to be filled with incoming data from the server.

After filling this buffer (using a method like Read::read), call Self::advance with the number of bytes read to indicate that the buffer has been filled.

pub fn advance(&mut self, bytes: usize) -> bool

Advance the internal buffer, given the number of bytes that have been read.

pub fn into_setup(self) -> Result<Setup, ConnectError>

Returns the setup provided by the server.

Errors

• If this method is called before the server returns all of the required data, it returns ConnectError::NotEnoughData.
• If the server fails to establish the X11 connection, the ConnectError::SetupFailed variant is returned.
• If the server failed to authenticate the user, the ConnectError::SetupAuthenticate error is returned.
• If the server failed to parse any of the above responses, the ConnectError::ParseError error is returned.

Trait Implementations

impl Debug for Connect

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl TryFrom<Connect> for Setup

type Error = ConnectError

The type returned in the event of a conversion error.

fn try_from(connect: Connect) -> Result<Self, Self::Error>

Performs the conversion.