Struct Connection

pub struct Connection<T> {
    pub is_initialized: bool,
    pub stream: Option<T>,
    pub timeout: Option<u64>,
    pub proxy_addr: Option<(String, u16)>,
    pub addr: (String, u16),
}

Represents a TCP connection to a Minecraft server. Supports optional SOCKS5 proxy connections.

Type Parameters

• T: Underlying TCP stream type, usually TcpStream.

Fields

• stream: Optionally holds the active TCP stream.
• timeout: Optional timeout duration in milliseconds for connection and I/O.
• proxy_addr: Optional SOCKS5 proxy address as (host, port).
• addr: Target Minecraft server address (host, port).

Fields

is_initialized: bool

stream: Option<T>

timeout: Option<u64>

proxy_addr: Option<(String, u16)>

addr: (String, u16)

Implementations

impl Connection<TcpStream>

pub fn new(addr: (String, u16)) -> Self

Creates a new Connection instance with the target server address.

The connection is not yet established.

Example

use mc_ping::connection::Connection;

let mut conn = Connection::new(("play.example.com".to_string(), 25565)).await;

pub async fn connect(&mut self) -> Result<Self>

Establishes a connection to the Minecraft server.

If a SOCKS5 proxy is set via proxy_socks5(), the connection will be established through that proxy. Otherwise, it connects directly.

DNS resolution depends on the “resolve” feature flag:

• Without “resolve” feature: domain names are not supported (must be IP).
• With “resolve” feature enabled: domain names are resolved asynchronously.

Errors

Returns error if connection, proxy connection, or DNS resolution fails.

Example

use mc_ping::connection::Connection;

let mut conn = Connection::new(("example.com".to_string(), 25565)).await;
conn = conn.connect().await?;

pub fn timeout(self, timeout: u64) -> Result<Self>

Sets the timeout for connection and I/O operations (milliseconds).

Errors

Returns error if called before initialization.

Example

use mc_ping::connection::Connection;

let mut conn = Connection::new(("127.0.0.1".to_string(), 25565)).await;
conn.timeout(5000).await?;

pub fn proxy_socks5(self, proxy_addr: (String, u16)) -> Result<Self>

Sets the SOCKS5 proxy address to use for connections.

Errors

Returns error if called before initialization.

Example

use mc_ping::connection::Connection;

let mut conn = Connection::new(("127.0.0.1".to_string(), 25565)).await;
conn.proxy_socks5(("127.0.0.1".to_string(), 1080)).await?;

pub async fn send_handshake(&mut self) -> Result<()>

Sends the Minecraft handshake packet to the server.

This prepares the connection for status query or login.

Errors

Returns error if the stream is not connected or writing fails.

Example

use mc_ping::connection::Connection;

let mut conn = Connection::new(("127.0.0.1".to_string(), 25565)).await;
conn = conn.connect().await?;
conn.send_handshake().await?;

pub async fn get_status(&mut self) -> Result<ServerStatus>

Sends a status query and reads the server response.

Assumes handshake has already been sent.

Errors

Returns error if sending or reading packets fails, or if parsing fails.

Example

use mc_ping::connection::Connection;

let mut conn = Connection::new(("localhost".to_string(), 25565)).await;
conn = conn.connect().await?;
conn.send_handshake().await?;
let status = conn.get_status().await?;
println!("Status: {:?}", status);

pub async fn ping(&mut self) -> Result<ServerStatus>

Performs a full ping: sends handshake, status query, and parses the response.

Convenient for one-step status check.

Errors

Returns error if any step (network or parsing) fails.

Example

use mc_ping::connection::Connection;

let mut conn = Connection::new(("play.example.com".to_string(), 25565)).await;
conn = conn.connect().await?;
let status = conn.ping().await?;
println!("Server status: {:?}", status);