Struct ControlMessage 

pub struct ControlMessage {
    pub status_code: u16,
    pub lines: Vec<String>,
}

A parsed control protocol response message.

ControlMessage represents a complete response from Tor’s control interface, containing the status code and all response lines. It provides methods to check success/failure and access the response content.

Protocol Format

Control protocol responses consist of:

• A 3-digit status code (similar to HTTP)
• One or more content lines

Status code ranges:

• 2xx: Success (command accepted)
• 4xx: Temporary failure (try again later)
• 5xx: Permanent failure (command rejected)
• 6xx: Asynchronous event notification

Example

use stem_rs::ControlSocket;

let mut socket = ControlSocket::connect_port("127.0.0.1:9051".parse()?).await?;

socket.send("GETINFO version").await?;
let msg = socket.recv().await?;

// Check if successful
if msg.is_ok() {
    // Get first line content
    println!("Version: {}", msg.content());
} else {
    // Handle error
    println!("Error {}: {}", msg.status_code, msg.content());
}

Fields

status_code: u16

The 3-digit status code from the response.

Common status codes:

• 250: Command successful
• 251: Resource exhausted
• 451: Resource temporarily unavailable
• 500: Syntax error
• 510: Unrecognized command
• 515: Authentication required/failed
• 550: Unspecified error
• 650: Asynchronous event

lines: Vec<String>

The content lines from the response.

For single-line responses, this contains one element. For multi-line responses, each line is a separate element. For data responses, the data block content is included.

Implementations

impl ControlMessage

pub fn is_ok(&self) -> bool

Checks if the response indicates success.

Returns true if the status code is in the 2xx range (200-299), indicating the command was accepted and executed successfully.

Returns

true if status_code is between 200 and 299 inclusive.

Example

use stem_rs::socket::ControlMessage;

let success = ControlMessage {
    status_code: 250,
    lines: vec!["OK".to_string()],
};
assert!(success.is_ok());

let error = ControlMessage {
    status_code: 515,
    lines: vec!["Authentication failed".to_string()],
};
assert!(!error.is_ok());

pub fn content(&self) -> &str

Returns the first line of response content.

For most responses, this is the primary content. For multi-line responses, use all_content to get all lines.

Returns

The first line of content, or an empty string if there are no lines.

Example

use stem_rs::socket::ControlMessage;

let msg = ControlMessage {
    status_code: 250,
    lines: vec!["version=0.4.7.1".to_string()],
};
assert_eq!(msg.content(), "version=0.4.7.1");

let empty = ControlMessage {
    status_code: 250,
    lines: vec![],
};
assert_eq!(empty.content(), "");

pub fn all_content(&self) -> String

Returns all response lines joined with newlines.

Combines all content lines into a single string, separated by newline characters (\n). Useful for multi-line responses.

Returns

All lines joined with \n separators.

Example

use stem_rs::socket::ControlMessage;

let msg = ControlMessage {
    status_code: 250,
    lines: vec![
        "version=0.4.7.1".to_string(),
        "config-file=/etc/tor/torrc".to_string(),
        "OK".to_string(),
    ],
};
assert_eq!(
    msg.all_content(),
    "version=0.4.7.1\nconfig-file=/etc/tor/torrc\nOK"
);

pub fn raw_content(&self) -> String

Returns the raw protocol representation of the response.

Reconstructs the response in control protocol format with status codes and CRLF line endings. Useful for debugging or logging.

Returns

The response formatted as it would appear on the wire.

Example

use stem_rs::socket::ControlMessage;

let msg = ControlMessage {
    status_code: 250,
    lines: vec![
        "version=0.4.7.1".to_string(),
        "OK".to_string(),
    ],
};
assert_eq!(msg.raw_content(), "250-version=0.4.7.1\r\n250 OK\r\n");

Trait Implementations

impl Clone for ControlMessage

fn clone(&self) -> ControlMessage

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ControlMessage

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

Formats the value using the given formatter.