Struct xcb::Connection

pub struct Connection { /* fields omitted */ }

Connection is the central object of XCB.

It handles all communications with the X server. It dispatches the requests, receives the replies, poll/wait the events. It also resolve the error and events from X server.

Connection is thread safe.

It internally wraps an xcb_connection_t object and will call xcb_disconnect when the Connection goes out of scope.

Implementations

impl Connection

pub fn connect(display_name: Option<&str>) -> ConnResult<(Connection, i32)>

Connects to the X server.

Connects to the X server specified by display_name. If display_name is None, uses the value of the DISPLAY environment variable.

If no screen is preferred, the second member of the tuple is set to 0.

Example

fn main() -> xcb::Result<()> {
    let (conn, screen) = xcb::Connection::connect(None)?;
    Ok(())
}

pub fn connect_with_extensions(
    display_name: Option<&str>,
    mandatory: &[Extension],
    optional: &[Extension]
) -> ConnResult<(Connection, i32)>

Connects to the X server and cache extension data.

Connects to the X server specified by display_name. If display_name is None, uses the value of the DISPLAY environment variable.

Extension data specified by mandatory and optional is cached to allow the resolution of events and errors in these extensions.

If no screen is preferred, the second member of the tuple is set to 0.

Panics

Panics if one of the mandatory extension is not present.

Example

fn main() -> xcb::Result<()> {
    let (conn, screen) = xcb::Connection::connect_with_extensions(
        None, &[xcb::Extension::Input, xcb::Extension::Xkb], &[]
    )?;
    Ok(())
}

pub fn connect_to_fd(
    fd: RawFd,
    auth_info: Option<AuthInfo<'_>>
) -> ConnResult<Self>

Connects to the X server with an open socket file descriptor and optional authentification info.

Connects to an X server, given the open socket fd and the auth_info. The file descriptor fd is bidirectionally connected to an X server. If the connection should be unauthenticated, auth_info must be None.

pub fn connect_to_fd_with_extensions(
    fd: RawFd,
    auth_info: Option<AuthInfo<'_>>,
    mandatory: &[Extension],
    optional: &[Extension]
) -> ConnResult<Self>

Connects to the X server with an open socket file descriptor and optional authentification info.

Extension data specified by mandatory and optional is cached to allow the resolution of events and errors in these extensions.

Connects to an X server, given the open socket fd and the auth_info. The file descriptor fd is bidirectionally connected to an X server. If the connection should be unauthenticated, auth_info must be None.

Panics

Panics if one of the mandatory extension is not present.

pub fn connect_to_display_with_auth_info(
    display_name: Option<&str>,
    auth_info: AuthInfo<'_>
) -> ConnResult<(Connection, i32)>

Connects to the X server, using an authorization information.

Connects to the X server specified by display_name, using the authorization auth_info. If a particular screen on that server, it is returned in the second tuple member, which is otherwise set to 0.

pub fn connect_to_display_with_auth_info_and_extensions(
    display_name: Option<&str>,
    auth_info: AuthInfo<'_>,
    mandatory: &[Extension],
    optional: &[Extension]
) -> ConnResult<(Connection, i32)>

Connects to the X server, using an authorization information.

Extension data specified by mandatory and optional is cached to allow the resolution of events and errors in these extensions.

Connects to the X server specified by display_name, using the authorization auth_info. If a particular screen on that server, it is returned in the second tuple member, which is otherwise set to 0.

Panics

Panics if one of the mandatory extension is not present.

pub unsafe fn from_raw_conn(conn: *mut xcb_connection_t) -> Connection

builds a new Connection object from an available connection

Safety

The conn pointer must point to a valid xcb_connection_t

pub unsafe fn from_raw_conn_and_extensions(
    conn: *mut xcb_connection_t,
    mandatory: &[Extension],
    optional: &[Extension]
) -> Connection

Builds a new Connection object from an available connection and cache the extension data

Extension data specified by mandatory and optional is cached to allow the resolution of events and errors in these extensions.

Safety

The conn pointer must point to a valid xcb_connection_t

pub fn active_extensions(&self) -> impl Iterator<Item = Extension> + '_

Get the extensions activated for this connection.

You may use this to check if an optional extension is present or not.

Example

    // Xkb is mandatory, Input is optional
    let (conn, screen) = xcb::Connection::connect_with_extensions(
        None, &[xcb::Extension::Xkb], &[xcb::Extension::Input]
    )?;
    // now we check if Input is present or not
    let has_input_ext = conn.active_extensions().any(|e| e == xcb::Extension::Input);

pub fn get_raw_conn(&self) -> *mut xcb_connection_t

Returns the inner ffi xcb_connection_t pointer

pub fn into_raw_conn(self) -> *mut xcb_connection_t

Consumes this object, returning the inner ffi xcb_connection_t pointer

pub fn get_maximum_request_length(&self) -> u32

Returns the maximum request length that this server accepts.

In the absence of the BIG-REQUESTS extension, returns the maximum request length field from the connection setup data, which may be as much as 65535. If the server supports BIG-REQUESTS, then the maximum request length field from the reply to the BigRequestsEnable request will be returned instead.

Note that this length is measured in four-byte units, making the theoretical maximum lengths roughly 256kB without BIG-REQUESTS and 16GB with.

pub fn prefetch_maximum_request_length(&self)

Prefetch the maximum request length without blocking.

Without blocking, does as much work as possible toward computing the maximum request length accepted by the X server.

Invoking this function may send the crate::bigreq::Enable request, but will not block waiting for the reply. Connection::get_maximum_request_length will return the prefetched data after possibly blocking while the reply is retrieved.

Note that in order for this function to be fully non-blocking, the application must previously have called crate::bigreq::prefetch_extension_data.

pub fn generate_id<T: XidNew>(&self) -> T

Allocates an XID for a new object.

Returned value is typically used in requests such as CreateWindow.

Example

let window: x::Window = conn.generate_id();

pub fn flush(&self) -> ConnResult<()>

Forces any buffered output to be written to the server.

Forces any buffered output to be written to the server. Blocks until the write is complete.

There are several occasions ones want to flush the connection. One of them is before entering or re-entering the event loop after performing unchecked requests.

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

Blocks and returns the next event or error from the server.

Example

use xcb::x;
fn main() -> xcb::Result<()> {
    // ...
    loop {
        let event = match conn.wait_for_event() {
            Err(xcb::Error::Connection(err)) => {
                panic!("unexpected I/O error: {}", err);
            }
            Err(xcb::Error::Protocol(xcb::ProtocolError::X(x::Error::Font(err)))) => {
                // may be this particular error is fine?
                continue;
            }
            Err(xcb::Error::Protocol(err)) => {
                panic!("unexpected protocol error: {:#?}", err);
            }
            Ok(event) => event,
        };
        match event {
            xcb::Event::X(x::Event::KeyPress(ev)) => {
                // do stuff with the key press
            }
            // handle other events
            _ => {
                break Ok(());
            }
        }
    }
 }

pub fn poll_for_event(&self) -> Result<Option<Event>>

Returns the next event or error from the server without blocking.

Returns the next event or error from the server, if one is available. If no event is available, that might be because an I/O error like connection close occurred while attempting to read the next event, in which case the connection is shut down when this function returns.

pub fn poll_for_queued_event(&self) -> ProtocolResult<Option<Event>>

Returns the next event without reading from the connection.

This is a version of Connection::poll_for_event that only examines the event queue for new events. The function doesn’t try to read new events from the connection if no queued events are found.

This function is useful for callers that know in advance that all interesting events have already been read from the connection. For example, callers might use Connection::wait_for_reply and be interested only of events that preceded a specific reply.

pub fn get_setup(&self) -> &Setup

Access the data returned by the server.

Accessor for the data returned by the server when the connection was initialized. This data includes

• the server’s required format for images,
• a list of available visuals,
• a list of available screens,
• the server’s maximum request length (in the absence of the BIG-REQUESTS extension),
• and other assorted information.

See the X protocol specification for more details.

pub fn has_error(&self) -> ConnResult<()>

Test whether the connection has shut down due to a fatal error.

Some errors that occur in the context of a connection are unrecoverable. When such an error occurs, the connection is shut down and further operations on the connection have no effect.

pub fn send_request<R>(&self, req: &R) -> R::Cookie where
    R: Request, 

Send a request to the X server.

This function never blocks. A cookie is returned to keep track of the request. If the request expect a reply, the cookie can be used to retrieve the reply

Example

    // Example of void request.
    // Error (if any) will be sent to the event loop (see `wait_for_event`).
    // In this case, the cookie can be discarded.
    conn.send_request(&x::CreateWindow {
        depth: x::COPY_FROM_PARENT as u8,
        wid: window,
        parent: screen.root(),
        x: 0,
        y: 0,
        width: 150,
        height: 150,
        border_width: 10,
        class: x::WindowClass::InputOutput,
        visual: screen.root_visual(),
        value_list: &[
            x::Cw::BackPixel(screen.white_pixel()),
            x::Cw::EventMask((x::EventMask::EXPOSURE | x::EventMask::KEY_PRESS).bits()),
        ],
    });

    // Example of request with reply. The error (if any) is obtained with the reply.
    let cookie = conn.send_request(&x::InternAtom {
        only_if_exists: true,
        name: "WM_PROTOCOLS",
    });
    let wm_protocols_atom: x::Atom = conn
            .wait_for_reply(cookie)?
            .atom();

pub fn send_request_checked<R>(&self, req: &R) -> CheckedVoidCookie where
    R: RequestWithoutReply, 

Send a checked request to the X server.

Checked requests do not expect a reply, but the returned cookie can be used to check for errors using Connection::check_request.

Example

    let cookie = conn.send_request_checked(&x::MapWindow { window });
    conn.check_request(cookie)?;

pub fn send_request_unchecked<R>(&self, req: &R) -> R::UncheckedCookie where
    R: RequestWithReply, 

Send an unchecked request to the X server.

Unchecked requests expect a reply that is to be retrieved by Connection::wait_for_reply_unchecked. Unchecked means that the error is not checked when the reply is fetched. Instead, the error will be sent to the event loop

Example

    let cookie = conn.send_request_unchecked(&x::InternAtom {
        only_if_exists: true,
        name: "WM_PROTOCOLS",
    });
    let wm_protocols_atom: Option<x::Atom> = conn
            .wait_for_reply_unchecked(cookie)?
            .map(|rep| rep.atom());

pub fn check_request(&self, cookie: CheckedVoidCookie) -> ProtocolResult<()>

Check a checked request for errors.

The cookie supplied to this function must have resulted from a call to Connection::send_request_checked. This function will block until one of two conditions happens. If an error is received, it will be returned. If a reply to a subsequent request has already arrived, no error can arrive for this request, so this function will return Ok(()).

Note that this function will perform a sync if needed to ensure that the sequence number will advance beyond that provided in cookie; this is a convenience to avoid races in determining whether the sync is needed.

Example

    conn.check_request(conn.send_request_checked(&x::MapWindow { window }))?;

pub fn wait_for_reply<C>(&self, cookie: C) -> Result<C::Reply> where
    C: CheckedCookieWithReply, 

Get the reply of a previous request, or an error if one occured.

Example

    let cookie = conn.send_request(&x::InternAtom {
        only_if_exists: true,
        name: "WM_PROTOCOLS",
    });
    let wm_protocols_atom: x::Atom = conn
            .wait_for_reply(cookie)?
            .atom();

pub fn wait_for_reply_unchecked<C>(
    &self,
    cookie: C
) -> ConnResult<Option<C::Reply>> where
    C: UncheckedCookieWithReply, 

Get the reply of a previous unchecked request.

If an error occured, None is returned and the error will be delivered to the event loop.

Example

    let cookie = conn.send_request_unchecked(&x::InternAtom {
        only_if_exists: true,
        name: "WM_PROTOCOLS",
    });
    let wm_protocols_atom: Option<x::Atom> = conn
            .wait_for_reply_unchecked(cookie)?  // connection error may happen
            .map(|rep| rep.atom());

pub fn total_read(&self) -> usize

Obtain number of bytes read from the connection.

Returns cumulative number of bytes received from the connection.

This retrieves the total number of bytes read from this connection, to be used for diagnostic/monitoring/informative purposes.

pub fn total_written(&self) -> usize

Obtain number of bytes written to the connection.

Returns cumulative number of bytes sent to the connection.

This retrieves the total number of bytes written to this connection, to be used for diagnostic/monitoring/informative purposes.

Trait Implementations

impl AsRawFd for Connection

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Drop for Connection

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Connection

impl Sync for Connection