Struct NativeClient 

pub struct NativeClient { /* private fields */ }

Blocking client for supported WeChat server operations.

Construct with Self::new, obtain an AccountState through approved login, then use methods such as Self::send_text or Self::sync. The state is passed mutably because authenticated responses can update credentials/routing. This client does not own a daemon, profile, send queue or recovery journal.

Implementations

impl NativeClient

pub fn group_mutation_raw( &self, state: &mut AccountState, request: &GroupRpc, ) -> Result<Vec<u8>>

impl NativeClient

pub fn group_detail_raw( &self, state: &mut AccountState, group: &str, ) -> Result<Vec<u8>>

impl NativeClient

pub fn group_inventory( &self, state: &mut AccountState, cursor: &[u8], ) -> Result<GroupMetadataPage>

pub fn lookup_contacts_raw( &self, state: &mut AccountState, ids: &[String], ) -> Result<Vec<u8>>

Verified native business payload, retained before strict contact decoding. Callers must protect this account data at rest. The transport’s global message bound applies; no identities or opaque fields are exposed in logs.

pub fn lookup_contacts_receipt( &self, state: &mut AccountState, ids: &[String], ) -> Result<MetadataReply<ContactLookup>>

pub fn lookup_room_receipt( &self, state: &mut AccountState, id: &str, version: u32, ) -> Result<MetadataReply<RoomRoster>>

pub fn lookup_room_raw( &self, state: &mut AccountState, id: &str, version: u32, ) -> Result<Vec<u8>>

pub fn init_contacts_receipt( &self, state: &mut AccountState, a: u32, b: u32, ) -> Result<MetadataReply<InitContactPage>>

impl NativeClient

pub fn logout(&self, state: &mut AccountState) -> Result<LogoutReply>

Submit one authenticated logout without renewal, retry or login fallback. An error can follow submission and must be treated as an unknown outcome.

impl NativeClient

pub fn recall_message( &self, state: &mut AccountState, recall: &MessageRecall, ) -> Result<MessageRecallReply>

Submit once without credential renewal, login fallback or automatic retry.

impl NativeClient

pub fn notify_read_session( &self, state: &mut AccountState, notification: &SessionReadNotification, ) -> Result<SessionReadReply>

Submit once, with no renewal, retry, or login fallback. A caller must retain the boundary and request identity before invoking this method.

impl NativeClient

pub fn new(options: NativeOptions) -> Result<Self>

Validate transport options. Construction itself makes no network request.

Examples found in repository

examples/support/mod.rs (line 14)

pub fn login() -> Result<(NativeClient, AccountState)> {
    let client = NativeClient::new(NativeOptions::default())?;
    let device = DeviceProfile::generate("UnifiedPCLinux x86_64".into())?;
    let qr_directory = wechat_platform::private_tempdir("wechat-protocol-example-")?;
    let qr_path = qr_directory.path().join("login.png");
    let mut attempt = client.start_qr_login(device, "Rust protocol example")?;
    let mut qr = wechat_platform::OpenOptions::new()
        .write(true)
        .create_new(true)
        .mode(0o600)
        .open(&qr_path)?;
    qr.write_all(&attempt.qr_png)?;
    drop(qr);
    eprintln!("Scan the private QR image: {}", qr_path.display());
    eprintln!("Approve this example on the test account's phone.");
    let deadline = Instant::now() + Duration::from_secs(600);
    loop {
        ensure!(Instant::now() < deadline, "Login example timed out");
        match client.poll_login_guarded(&mut attempt, deadline, || false) {
            Ok(LoginStatus::Approved) => {
                let state = client.complete_login(&mut attempt)?;
                eprintln!("Login complete; credentials remain in memory.");
                return Ok((client, state));
            }
            Ok(LoginStatus::Pending | LoginStatus::Scanned) => {}
            Ok(status) => bail!("Login stopped: {status:?}"),
            Err(error) if is_retryable_login_poll_error(&error) => {}
            Err(error) => return Err(error),
        }
        // Only polling an already issued challenge is repeated. QR creation,
        // credential exchange and sends are never automatically resubmitted.
        thread::sleep(Duration::from_secs(2));
    }
}

pub fn push_connection(&self, state: &AccountState) -> Result<Connection>

pub fn start_qr_login( &self, device: DeviceProfile, computer_name: &str, ) -> Result<LoginAttempt>

Request one QR challenge for the supplied device. Display LoginAttempt::qr_png privately, poll for phone approval, then call Self::complete_login. This does not grant authorization by itself.

Examples found in repository

examples/support/mod.rs (line 18)

pub fn login() -> Result<(NativeClient, AccountState)> {
    let client = NativeClient::new(NativeOptions::default())?;
    let device = DeviceProfile::generate("UnifiedPCLinux x86_64".into())?;
    let qr_directory = wechat_platform::private_tempdir("wechat-protocol-example-")?;
    let qr_path = qr_directory.path().join("login.png");
    let mut attempt = client.start_qr_login(device, "Rust protocol example")?;
    let mut qr = wechat_platform::OpenOptions::new()
        .write(true)
        .create_new(true)
        .mode(0o600)
        .open(&qr_path)?;
    qr.write_all(&attempt.qr_png)?;
    drop(qr);
    eprintln!("Scan the private QR image: {}", qr_path.display());
    eprintln!("Approve this example on the test account's phone.");
    let deadline = Instant::now() + Duration::from_secs(600);
    loop {
        ensure!(Instant::now() < deadline, "Login example timed out");
        match client.poll_login_guarded(&mut attempt, deadline, || false) {
            Ok(LoginStatus::Approved) => {
                let state = client.complete_login(&mut attempt)?;
                eprintln!("Login complete; credentials remain in memory.");
                return Ok((client, state));
            }
            Ok(LoginStatus::Pending | LoginStatus::Scanned) => {}
            Ok(status) => bail!("Login stopped: {status:?}"),
            Err(error) if is_retryable_login_poll_error(&error) => {}
            Err(error) => return Err(error),
        }
        // Only polling an already issued challenge is repeated. QR creation,
        // credential exchange and sends are never automatically resubmitted.
        thread::sleep(Duration::from_secs(2));
    }
}

pub fn start_profile_qr_login( &self, device: DeviceProfile, computer_name: &str, key_info: &[u8], ) -> Result<LoginAttempt>

QR approval for an existing installation retains its selected key-info. This neither bypasses phone approval nor imports active authorization.

pub fn start_saved_device_login( &self, state: &AccountState, computer_name: &str, ) -> Result<LoginAttempt>

Initiates phone approval for an existing remembered device without a QR. The caller chooses this fallback explicitly; no automatic auth retries occur.

pub fn start_profile_saved_device_login( &self, device: &DeviceProfile, username: &str, auto_auth_key: &[u8], cookie: &[u8], key_info: &[u8], computer_name: &str, ) -> Result<LoginAttempt>

Use remembered official-profile trust without inventing active session keys.

pub fn poll_login(&self, attempt: &mut LoginAttempt) -> Result<LoginStatus>

Poll an existing challenge. Only LoginStatus::Approved permits Self::complete_login; expired/rejected/cancelled attempts must stop.

pub fn poll_login_guarded( &self, attempt: &mut LoginAttempt, deadline: Instant, cancelled: impl Fn() -> bool + Send + Sync + 'static, ) -> Result<LoginStatus>

The guard bounds the temporary LAN listener even while a blocking poll or upload is in flight. It must not perform blocking work itself.

Examples found in repository

examples/support/mod.rs (line 31)

pub fn login() -> Result<(NativeClient, AccountState)> {
    let client = NativeClient::new(NativeOptions::default())?;
    let device = DeviceProfile::generate("UnifiedPCLinux x86_64".into())?;
    let qr_directory = wechat_platform::private_tempdir("wechat-protocol-example-")?;
    let qr_path = qr_directory.path().join("login.png");
    let mut attempt = client.start_qr_login(device, "Rust protocol example")?;
    let mut qr = wechat_platform::OpenOptions::new()
        .write(true)
        .create_new(true)
        .mode(0o600)
        .open(&qr_path)?;
    qr.write_all(&attempt.qr_png)?;
    drop(qr);
    eprintln!("Scan the private QR image: {}", qr_path.display());
    eprintln!("Approve this example on the test account's phone.");
    let deadline = Instant::now() + Duration::from_secs(600);
    loop {
        ensure!(Instant::now() < deadline, "Login example timed out");
        match client.poll_login_guarded(&mut attempt, deadline, || false) {
            Ok(LoginStatus::Approved) => {
                let state = client.complete_login(&mut attempt)?;
                eprintln!("Login complete; credentials remain in memory.");
                return Ok((client, state));
            }
            Ok(LoginStatus::Pending | LoginStatus::Scanned) => {}
            Ok(status) => bail!("Login stopped: {status:?}"),
            Err(error) if is_retryable_login_poll_error(&error) => {}
            Err(error) => return Err(error),
        }
        // Only polling an already issued challenge is repeated. QR creation,
        // credential exchange and sends are never automatically resubmitted.
        thread::sleep(Duration::from_secs(2));
    }
}

pub fn complete_login(&self, attempt: &mut LoginAttempt) -> Result<AccountState>

Exchange an approved challenge for secret account credentials once. Keep the returned state in memory or an encrypted application vault.

Examples found in repository

examples/support/mod.rs (line 33)

pub fn login() -> Result<(NativeClient, AccountState)> {
    let client = NativeClient::new(NativeOptions::default())?;
    let device = DeviceProfile::generate("UnifiedPCLinux x86_64".into())?;
    let qr_directory = wechat_platform::private_tempdir("wechat-protocol-example-")?;
    let qr_path = qr_directory.path().join("login.png");
    let mut attempt = client.start_qr_login(device, "Rust protocol example")?;
    let mut qr = wechat_platform::OpenOptions::new()
        .write(true)
        .create_new(true)
        .mode(0o600)
        .open(&qr_path)?;
    qr.write_all(&attempt.qr_png)?;
    drop(qr);
    eprintln!("Scan the private QR image: {}", qr_path.display());
    eprintln!("Approve this example on the test account's phone.");
    let deadline = Instant::now() + Duration::from_secs(600);
    loop {
        ensure!(Instant::now() < deadline, "Login example timed out");
        match client.poll_login_guarded(&mut attempt, deadline, || false) {
            Ok(LoginStatus::Approved) => {
                let state = client.complete_login(&mut attempt)?;
                eprintln!("Login complete; credentials remain in memory.");
                return Ok((client, state));
            }
            Ok(LoginStatus::Pending | LoginStatus::Scanned) => {}
            Ok(status) => bail!("Login stopped: {status:?}"),
            Err(error) if is_retryable_login_poll_error(&error) => {}
            Err(error) => return Err(error),
        }
        // Only polling an already issued challenge is repeated. QR creation,
        // credential exchange and sends are never automatically resubmitted.
        thread::sleep(Duration::from_secs(2));
    }
}

pub fn refresh_qr_login(&self, attempt: &LoginAttempt) -> Result<LoginAttempt>

Replace an expired, unscanned QR while preserving installation key-info.

pub fn renew_session( &self, previous: &AccountState, computer_name: &str, ) -> Result<AccountState>

One trusted AutoAuth exchange, retaining identity and replacing selected key sections atomically in the returned value. Does not silently fall back to QR.

pub fn experimental_call_rpc( &self, state: &mut AccountState, route: CallHostRoute, request: &[u8], ) -> Result<Vec<u8>>

Perform one experimental call host RPC using its fixed CGI/path pair. The owner must first retain its intent, hold account mutation authority and fence account/logout generations. This method does not retry uncertain operations. An active Ax policy is unsupported here; there is no ordinary packing fallback. Returned CommonResponse/application results still need their own checks. Accepted cookie updates follow normal native transport.

pub fn experimental_call_rpc_guarded( &self, state: &mut AccountState, route: CallHostRoute, request: &[u8], before_submit: impl FnOnce() -> Result<()>, ) -> Result<Vec<u8>>

As Self::experimental_call_rpc, with one final owner check after handshake/preparation and before handing business bytes to transport. A guard cannot retract bytes after transport handoff. Handshake traffic can already have occurred when this guard stops the business request.

pub fn sync(&self, state: &mut AccountState, cursor: &[u8]) -> Result<SyncBatch>

Fetch one scene-6 sync page. An empty cursor starts an initial sync. Returned commands include their original payloads. Persist and handle all required commands before committing the returned cursor; this call does not write history or manage a checkpoint for the application.

Examples found in repository

examples/sync_once.rs (line 10)

fn main() -> anyhow::Result<()> {
    if std::env::args().skip(1).any(|arg| arg == "--help") {
        println!("sync_once: approve a test-account QR login and summarize one initial sync page.");
        return Ok(());
    }
    let (client, mut state) = support::login()?;
    let batch = client.sync(&mut state, &[])?;
    let mut messages = 0;
    for command in &batch.commands {
        if command.id == 5 {
            let _message =
                wechat_protocol::wire::decode_add_message(&command.payload, &state.own_username)?;
            messages += 1;
        }
    }
    println!(
        "commands={} add_messages={} other_commands={} continuation={}",
        batch.commands.len(),
        messages,
        batch.commands.len() - messages,
        batch.continuation
    );
    // This is a preview, not a sync consumer: all raw commands remain in `batch`,
    // and we never save its returned cursor. A persistent client must retain and
    // handle every required command before committing that cursor.
    println!("Preview only. No history or sync cursor was saved.");
    Ok(())
}

pub fn sync_scene( &self, state: &mut AccountState, cursor: &[u8], scene: u32, ) -> Result<SyncBatch>

pub fn heartbeat( &self, state: &mut AccountState, cursor: &[u8], ) -> Result<Heartbeat>

Request heartbeat hints for a committed sync cursor. Hints are not message contents; the application still needs to fetch and handle sync commands.

pub fn send_text( &self, state: &mut AccountState, destination: &str, content: &str, created_at: u32, client_message_id: u32, ) -> Result<TextSendResult>

Submit exactly once. An I/O error after submission is an uncertain outcome; services must persist the intent and must not automatically retry this call.

destination is an exact WeChat username, not a display name or daemon account ID. created_at is Unix seconds; client_message_id is a nonzero protocol ID derived with wire::client_message_id from the caller’s task ID. Check acceptance and both returned-identity matches in the receipt. No official-profile history is written by this method.

Examples found in repository

examples/send_text.rs (line 23)

fn main() -> anyhow::Result<()> {
    let args: Vec<_> = std::env::args().skip(1).collect();
    if args.iter().any(|arg| arg == "--help") {
        println!("send_text RECIPIENT TASK_ID TEXT\nUses a fresh test-account QR login and submits once.");
        return Ok(());
    }
    ensure!(args.len() == 3, "Usage: send_text RECIPIENT TASK_ID TEXT");
    let (recipient, task_id, text) = (&args[0], &args[1], &args[2]);
    let client_id = wire::client_message_id(task_id.as_bytes());
    ensure!(client_id != 0, "Choose another nonempty task ID");
    // Validate arguments before requesting any login. A real application records
    // this operation and timestamp before submitting it, and retains its result.
    wire::text_send_request(recipient, text, wire::unix_time()?, client_id)?;
    let (client, mut state) = support::login()?;
    let created_at = wire::unix_time()?;
    let receipt = client
        .send_text(&mut state, recipient, text, created_at, client_id)
        .context(
            "Send outcome may be uncertain. Investigate before submitting this operation again",
        )?;
    println!("{}", serde_json::to_string_pretty(&receipt)?);
    ensure!(receipt.accepted, "The server rejected this text send");
    ensure!(
        receipt.returned_destination_matches && receipt.returned_client_id_matches,
        "Receipt identity mismatch; investigate before submitting again"
    );
    Ok(())
}

pub fn send_text_with_source( &self, state: &mut AccountState, destination: &str, content: &str, created_at: u32, client_message_id: u32, source: Option<&str>, ) -> Result<TextSendResult>

Submit text with optional native message-source XML. For a simple send use Self::send_text. This has the same single-submission/uncertainty contract.

pub fn lookup_contacts( &self, state: &mut AccountState, usernames: &[String], ) -> Result<ContactLookup>

Look up exact usernames on the server. The returned records are not automatically written into a local profile.

pub fn lookup_room( &self, state: &mut AccountState, room_id: &str, version: u32, ) -> Result<RoomRoster>

pub fn init_contacts( &self, state: &mut AccountState, contact_sequence: u32, room_sequence: u32, ) -> Result<InitContactPage>

pub fn download_avatars( &self, state: &mut AccountState, usernames: &[String], ) -> Result<Vec<AvatarBytes>>

pub fn download_voice_chunk( &self, state: &mut AccountState, server_message_id: u64, total_length: u32, offset: u32, ) -> Result<VoiceChunk>

pub fn cdn_config(&self, state: &mut AccountState) -> Result<CdnConfig>

pub fn large_cdn_config( &self, state: &mut AccountState, route: LargeCdnRoute, ) -> Result<CdnConfig>

pub fn send_share( &self, state: &mut AccountState, destination: &str, client_id: &str, created_at: u32, content: &str, ) -> Result<MediaSendResult>

Submit a URL card once through the app-message carrier. The caller owns the durable intent and must inspect an uncertain submission outcome.

pub fn send_quote( &self, state: &mut AccountState, destination: &str, client_id: &str, created_at: u32, content: &str, ) -> Result<MediaSendResult>

Submit a quoted reply once. The caller owns the persisted XML, intent and uncertain-submission handling, as for other app-message sends.

pub fn send_quote_with_source( &self, state: &mut AccountState, destination: &str, client_id: &str, created_at: u32, content: &str, source: Option<&str>, ) -> Result<MediaSendResult>

pub fn reserve_file_upload( &self, state: &mut AccountState, destination: &str, progress_client_id: &str, file_name: &str, plaintext_bytes: usize, md5: &str, ) -> Result<FileUploadReservation>

Reserve one file-upload message. An uncertain response must not be retried automatically; retain the returned receipt with the send intent.

pub fn send_file( &self, state: &mut AccountState, destination: &str, client_id: &str, created_at: u32, upload: &UploadedMedia, ) -> Result<MediaSendResult>

pub fn send_file_with_reservation( &self, state: &mut AccountState, destination: &str, client_id: &str, created_at: u32, upload: &UploadedMedia, reservation: Option<&FileUploadReservation>, ) -> Result<MediaSendResult>

pub fn send_image( &self, state: &mut AccountState, destination: &str, client_id: &str, upload: &UploadedImage, ) -> Result<MediaSendResult>

pub fn send_video( &self, state: &mut AccountState, destination: &str, client_id: &str, upload: &UploadedVideo, play_seconds: u32, ) -> Result<MediaSendResult>

pub fn send_voice( &self, state: &mut AccountState, destination: &str, client_id: &str, created_at: u32, duration_ms: u32, encoded: &[u8], ) -> Result<MediaSendResult>

Submit one voice note, as consecutive byte ranges when it exceeds one request. Each range is sent once; an error after the first submission is an uncertain outcome that the caller must not retry automatically.

impl NativeClient

pub fn contact_sync( &self, state: &mut AccountState, cursor: &[u8], message_cursor: &[u8], continuation: bool, ) -> Result<ContactSyncBatch>

Trait Implementations

impl PersonalTransport for NativeClient

fn call_rpc( &self, state: &mut AccountState, route: CallHostRoute, request: &[u8], ) -> Result<Vec<u8>>