Struct x11rb_protocol::connect::Connect

source ·
pub struct Connect { /* private fields */ }
Expand description

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§

source§

impl Connect

source

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(),
);
source

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.

source

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.

source

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

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

source

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§

source§

impl Debug for Connect

source§

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

Formats the value using the given formatter. Read more
source§

impl TryFrom<Connect> for Setup

§

type Error = ConnectError

The type returned in the event of a conversion error.
source§

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

Performs the conversion.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.