Struct breadx::display::BasicDisplay

pub struct BasicDisplay<Conn> { /* fields omitted */ }

An implementor of Display and AsyncDisplay that requires &mut access in order to use.

This is the standard implementation of a display for the X11 protocol. In addition to storing the connection to the server and the setup information received from the server, it contains the event queues, pending item map, and provides XIDs and sequence numbers.

It is recommended to create an instance of this object via DisplayConnection::create(), since that function uses the system’s variables in order to connect to the X11 server. However, niche use cases who need to communicate with the X server in other ways should use [BasicDisplay::from_connection].

Connection Poisoning

If a panic occurs while sending/receiving along the connection, or if a future involving sending/receiving across the connection is dropped, the connection may be “poisoned”. Attempting to use the connection after it is poisoned will result in a panic, since the current state of the BasicDisplay is invalid and will result in invalid communications with the X11 server. The exact semantics of what, exactly, will cause a connection poisoning are not well defined at the moment. However, the connection should never be poisoned during normal operation of the BasicDisplay.

Mutability

BasicDisplay requires an &mut reference for most operations, including sending and receiving requests and replies. Although this “inherited mutability”, as we call it, may be convenient for architectures of programs where multiple objects require access to the X server, it allows the connection to prevent undefined behavior from occurring. To quote the rust std documentation for std::cell:

The more common inherited mutability, where one must have unique access to mutate a value, is one of the key language elements that enables Rust to reason strongly about pointer aliasing, statically preventing crash bugs. Because of that, inherited mutability is preferred, and interior mutability is something of a last resort.

That being said, the CellDisplay object is preferred over using RefCell<BasicDisplay>, since it uses several different cell types in order to reduce reentrant panics. However, using SyncDisplay instead of Mutex<BasicDisplay> may not be preferred depending on your use case. See the documentation for SyncDisplay for more information.

Implementations

impl<Conn> BasicDisplay<Conn>

pub fn connection(&self) -> &Conn

Get the connection that this display wraps around. Modifying the connection may have unexpected results.

Panics

Panics if the connection has been poisoned.

Example

use breadx::display::DisplayConnection;

let conn = DisplayConnection::create(None, None).unwrap();
conn.connection();

pub fn connection_mut(&mut self) -> &mut Conn

Get a mutable reference to the connection.

Panics

Panics if the connection has been poisoned.

Example

use breadx::display::DisplayConnection;

let mut conn = DisplayConnection::create(None, None).unwrap();
conn.connection_mut();

impl<Conn: Connection> BasicDisplay<Conn>

pub fn from_connection(
    connection: Conn,
    default_screen: usize,
    auth_info: Option<AuthInfo>
) -> Result<Self>

Establishes this display using an inner connection type. This receives setup information from the server on the other side of the connection in order to populate the display.

In order to produce the Setup, from_connection sends a SetupRequest object across the provided connection. This SetupRequest is populated with the AuthInfo provided by either the user, or the file specified by the XAUTHORITY environment variable if the auth_info parameter is None. Once the Setup has been received, it is stored in the BasicDisplay and the BasicDisplay is considered valid. Finally, default_screen is used to dictate the default screen this display uses.

In addition, this function also tries to establish bigreq support, and if it does it enables the corresponding variables in the `BasicDisplay.

Errors

If the server returns error code 0, this function will return BreadError::FailedToConnect, indicating that the server refused our connection. If the server returns error code 2, this function will return BreadError::FailedToAuthorize, indicating that the AuthInfo provided either by the user or the “XAUTHORITY” is invalid. This function may also return an IO error if a system error occurs while communicating with the server.

In addition, this function may also return BreadError::BadObjectRead if the Setup provided by the server is invalid, but this will likely never occur unless a malicious X11 server is used.

Example

use breadx::display::BasicDisplay;
use std::net::TcpStream;

let server = TcpStream::connect("127.0.0.1:60000")?;
let conn = BasicDisplay::from_connection(server, 0, None)?;

impl<Conn: AsyncConnection + Unpin> BasicDisplay<Conn>

pub async fn from_connection_async(
    connection: Conn,
    default_screen: usize,
    auth_info: Option<AuthInfo>
) -> Result<Self>

Establishes this display using an inner connection type. This receives setup information from the server on the other side of the connection in order to populate the display. This method uses async types in order to ensure that the operation is non-blocking.

See BasicDisplay::from_connection for more information.

Example

use async_io::Async;
use blocking::unblock;
use breadx::display::BasicDisplay;
use std::net::TcpStream;

let server = blocking::unblock(|| TcpStream::connect("127.0.0.1:60000")).await?;
let server = Async::new(server)?;
let conn = BasicDisplay::from_connection_async(server, 0, None).await?;

impl BasicDisplay<NameConnection>

pub fn create(
    name: Option<Cow<'_, str>>,
    auth_info: Option<AuthInfo>
) -> Result<Self>

Create a new connection to the X server, given an optional name and authorization information.

This function instantiates a new NameConnection using either the name specification string passed by the user, or the environment variable “DISPLAY” if the name parameter is None. The NameConnection is either a TCP stream connected to port 60000 + X on the host, where X is the display number, or a Unix socket connection to one of the X11 system sockets.

Once the NameConnection is created, it is passed into BasicDisplay::from_connection method to establish the BasicDisplay.

This is the recommended way to create a BasicDisplay object, since most system running an X11 server expect the user to use the “DISPLAY” variable in order to connect to it. from_connection should only be used for niche use cases.

Errors

In addition to the errors that from_connection can return, this method may return BreadError::UnableToParseConnection if the name string is improperly formatted, or an IO error if a system error occurs while trying to connect to the server.

Example

Connect to the default X11 server, as specified by the environment variables.

use breadx::DisplayConnection;

let conn = DisplayConnection::create(None, None)?;

Connect to the server on display 3, using the authorization info read from a file.

use breadx::{AuthInfo, DisplayConnection};
use std::fs::File;

let mut file = File::open("my_auth_info.txt")?;
let mut auth_info = AuthInfo::from_stream(&mut file).expect("AuthInfo not found");
let conn = DisplayConnection::create(Some(":3".into()), Some(auth_info.remove(0)))?;

impl BasicDisplay<AsyncNameConnection>

pub async fn create_async(
    name: Option<Cow<'_, str>>,
    auth_info: Option<AuthInfo>
) -> Result<Self>

Create a new connection to the X server, given an optional name and authorization information, async redox. See DisplayConnection::create() for more information regarding this function.

Trait Implementations

impl<Connect: AsyncConnection + Unpin> AsyncDisplay for BasicDisplay<Connect>

fn poll_wait(&mut self, cx: &mut Context<'_>) -> Poll<Result>

Poll the current status of waiting for more input. There is no default implementation; the buffering strategy depends on the implementor. If this is called after a Poll::Ready is returned, it is assumed that the user wants to wait again.

fn begin_send_request_raw(
    &mut self,
    req: RequestInfo,
    _cx: &mut Context<'_>
) -> PollOr<(), RequestInfo>

Begin sending a raw request to the server. In order to poll the status of this operation, use the poll_send_request_raw function.

fn poll_send_request_raw(&mut self, cx: &mut Context<'_>) -> Poll<Result<u16>>

Poll an ongoing raw request operation. It should return Poll::Ready once the bytes passed in from begin_send_request_raw have been sent.

impl<Conn: Debug> Debug for BasicDisplay<Conn>

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

Formats the value using the given formatter.

impl<Connect: Connection> Display for BasicDisplay<Connect>

fn wait(&mut self) -> Result

Wait for something to happen on the connection.

fn send_request_raw(&mut self, request_info: RequestInfo) -> Result<u16>

Send a request across the connection, given the monomorphized request info.

fn synchronize(&mut self) -> Result

Synchronize this display, ensuring that all data sent across it has been replied to.

fn resolve_request_raw(&mut self, req_id: u16) -> Result<PendingReply>

Resolve for a request, returning only the raw data of the reply. The default implementation assumes that the reply is not zero-sized.

fn wait_for_event(&mut self) -> Result<Event>

Wait for an event to be sent from the X server.

fn wait_for_special_event(&mut self, xid: XID) -> Result<Event>

Wait for a special event to be sent from the X server. See wait_for_event for more information on how it functions.

impl<Conn> DisplayBase for BasicDisplay<Conn>

fn setup(&self) -> &StaticSetup

Get the Setup object that defines the X11 connection.

fn default_screen_index(&self) -> usize

Get the default screen index.

fn next_request_number(&mut self) -> u64

Generate the next request number to be used to define a request.

fn has_pending_event(&self) -> bool

Tell if there are any items currently in the queue.

fn push_event(&mut self, event: Event)

Push an event into this display’s event queue.

fn pop_event(&mut self) -> Option<Event>

Pop an event from this display’s event queue. See push_event for more information.

fn generate_xid(&mut self) -> Option<XID>

Generate an XID within appropriate bounds. Returns None if our XIDs are exhausted.

fn add_pending_item(&mut self, req_id: u16, item: PendingItem)

Add a PendingItem to this display’s map.

fn get_pending_item(&mut self, req_id: u16) -> Option<PendingItem>

Clone a PendingItem from this display’s map and return it. See add_pending_item for more information.

fn take_pending_item(&mut self, req_id: u16) -> Option<PendingItem>

Remove a PendingItem from this display’s map. See add_pending_item for more information.

fn create_special_event_queue(&mut self, xid: XID)

Create a new special event queue.

fn push_special_event(&mut self, xid: XID, event: Event) -> Result<(), Event>

Push an event into the special event queue. See create_special_event_queue for more information.

fn pop_special_event(&mut self, xid: XID) -> Option<Event>

Pop an event from the special event queue. See create_special_event_queue for more information.

fn delete_special_event_queue(&mut self, xid: XID)

Delete a special event queue. See create_special_event_queue for more information.

fn checked(&self) -> bool

Whether or not zero-length replies are checked.

fn set_checked(&mut self, checked: bool)

Set whether or not zero-length replies are checked. See checked for more information.

fn bigreq_enabled(&self) -> bool

Whether or not this display uses the bigreq extension, whereas requests consisting of over 262140 bytes are allowed to be sent over the connection.

fn max_request_len(&self) -> usize

The current maximum request length. This is the maximum number of bytes the server can handle at a time.

fn get_extension_opcode(&mut self, key: &[u8; 24]) -> Option<u8>

Get the opcode for an extension.

fn set_extension_opcode(&mut self, key: [u8; 24], opcode: u8)

Set the opcode for an extension. See get_extension_opcode for more information.

fn wm_protocols_atom(&self) -> Option<NonZeroU32>

Get the WM_PROTOCOLS atom, which we cache in the display.

fn set_wm_protocols_atom(&mut self, a: NonZeroU32)

Set the WM_PROTOCOLS atom. See wm_protocols_atom for more information.

fn add_pending_request(&mut self, req_id: u16, pereq: PendingRequest)

Insert a pending request into this display. This simply wraps the PendingRequest into a PendingItem and then calls add_pending_item.

fn get_pending_request(&mut self, req_id: u16) -> Option<PendingRequest>

Get a pending request from this display. This calls get_pending_item and returns None if the object is not a pending request.

fn take_pending_request(&mut self, req_id: u16) -> Option<PendingRequest>

Take a pending request from this display. This calls take_pending_item, inserting the object back into the map if it is not a request.

fn add_pending_reply(&mut self, req_id: u16, perep: PendingReply)

Insert a pending reply into this display. This simply wraps the PendingRequest into a PendingItem and then calls add_pending_item.

fn take_pending_reply(&mut self, req_id: u16) -> Option<PendingReply>

Take a pending reply from this display. This calls take_pending_item, inserting the object back into the map if it is not a reply.

fn add_pending_error(&mut self, req_id: u16, err: BreadError)

Insert a pending error into this display. This simply wraps the BreadError into a PendingItem and then calls add_pending_item.

fn check_for_pending_error(&mut self, req_id: u16) -> Result

Check this display for the pending error. This calls take_pending_item and returns Ok if the object if not an error.

fn screens(&self) -> &[StaticScreen]

Get the list of screens in this display.

fn default_screen(&self) -> &StaticScreen

Get the default screen in this display.

fn default_root(&self) -> Window

Get the default root for this display.

fn default_white_pixel(&self) -> u32

Get the default pixel used for the white color.

fn default_black_pixel(&self) -> u32

Get the default pixel used for the black color.

fn default_visual_id(&self) -> Visualid

Get the default visual ID for the screen.

fn default_visual(&self) -> &Visualtype

Get the default visual for the default screen.

fn default_colormap(&self) -> Colormap

Get the colormap for the default screen.

fn visual_id_to_visual(&self, id: Visualid) -> Option<&Visualtype>

Get a visual type from a visual ID.

fn get_scanline_pad(&self, depth: u8) -> usize

Get the scanline pad for a certain depth.

fn depth_of_visual(&self, id: Visualid) -> Option<u8>

Get the depth of the specified visual ID.

impl<Conn> From<BasicDisplay<Conn>> for CellDisplay<Conn>

fn from(display: BasicDisplay<Conn>) -> Self

Convert a BasicDisplay into a CellDisplay.