pub struct AprsIsClient { /* private fields */ }Expand description
Async TCP client for APRS-IS.
Owns a single TCP connection to an APRS-IS server, handles the login handshake, and exposes line-at-a-time read/write methods.
Not Clone and not Send-across-the-await — typical usage is to own
it from a single task.
§TLS support
This client speaks plaintext TCP only. APRS-IS T2 servers also
support TLS on port 24580 — to use it, build the connection
yourself with your preferred TLS library (e.g. tokio-rustls or
tokio-native-tls) and use the line-level helpers at the crate
root (crate::build_login_string, crate::format_is_packet,
crate::AprsIsLine):
use aprs_is::{AprsIsConfig, AprsIsLine, build_login_string, format_is_packet};
// 1. TLS handshake against `core.aprs2.net:24580` using your TLS library.
// 2. Send the result of `build_login_string(&config)` over the stream.
// 3. Read lines from the stream and parse them with `AprsIsLine::parse`.
// 4. Send packets formatted via `format_is_packet`.The library deliberately does not bundle a TLS implementation so callers can choose their preferred backend.
Implementations§
Source§impl AprsIsClient
impl AprsIsClient
Sourcepub async fn connect(config: AprsIsConfig) -> Result<AprsIsClient, AprsIsError>
pub async fn connect(config: AprsIsConfig) -> Result<AprsIsClient, AprsIsError>
Connect to the APRS-IS server and perform the login handshake.
Performs TCP connect, sends the login string, and returns as soon
as the socket is writable. Login verification (the # logresp
line) is reported asynchronously via AprsIsEvent::LoggedIn
from next_event.
Times out after CONNECT_TIMEOUT (10 seconds) during TCP connect.
§Errors
Returns AprsIsError::Connect if TCP connect fails or times out,
or AprsIsError::Write if the login string cannot be sent.
Sourcepub async fn connect_with_retry(
config: AprsIsConfig,
max_attempts: Option<u32>,
) -> Result<AprsIsClient, AprsIsError>
pub async fn connect_with_retry( config: AprsIsConfig, max_attempts: Option<u32>, ) -> Result<AprsIsClient, AprsIsError>
Connect with exponential backoff.
Retries the TCP connection up to max_attempts times, doubling
the delay from 1 second up to a cap of 60 seconds between attempts.
Pass None for max_attempts to retry forever.
§Errors
Returns the last AprsIsError after exhausting all attempts.
Sourcepub async fn reconnect(&mut self) -> Result<(), AprsIsError>
pub async fn reconnect(&mut self) -> Result<(), AprsIsError>
Reconnect to the APRS-IS server after a disconnect.
Drops the current connection (if any) and performs a fresh connect + login. Preserves the configuration.
§Errors
Returns AprsIsError::Connect if the TCP connect fails or
AprsIsError::Write if the login string cannot be sent.
Sourcepub async fn next_event(&mut self) -> Result<AprsIsEvent, AprsIsError>
pub async fn next_event(&mut self) -> Result<AprsIsEvent, AprsIsError>
Read the next event from the server.
Returns when a complete line arrives or the connection closes.
This is a blocking read — wrap in a tokio::select! with a
keepalive timer if you need concurrency.
§Errors
Returns AprsIsError::Read on socket errors.
Sourcepub async fn send_packet(
&mut self,
source: &str,
destination: &str,
path: &[&str],
data: &str,
) -> Result<(), AprsIsError>
pub async fn send_packet( &mut self, source: &str, destination: &str, path: &[&str], data: &str, ) -> Result<(), AprsIsError>
Send a formatted APRS packet to the server.
The packet is formatted as source>destination,path:data\r\n via
crate::format_is_packet and written to the TCP socket.
§Errors
Returns AprsIsError::Write if the write fails.
Sourcepub async fn send_raw_line(&mut self, line: &str) -> Result<(), AprsIsError>
pub async fn send_raw_line(&mut self, line: &str) -> Result<(), AprsIsError>
Send a raw line to the server (must already be CRLF-terminated).
Use this for custom formatting or to forward packets from RF.
§Errors
Returns AprsIsError::Write if the write fails.
Sourcepub async fn send_keepalive(&mut self) -> Result<(), AprsIsError>
pub async fn send_keepalive(&mut self) -> Result<(), AprsIsError>
Send a keepalive comment line unconditionally.
Sends # aprs-is keepalive\r\n to the server. Call this
on a timer or use maybe_send_keepalive
to only send if the interval has elapsed.
§Errors
Returns AprsIsError::Write if the write fails.
Sourcepub async fn maybe_send_keepalive(&mut self) -> Result<(), AprsIsError>
pub async fn maybe_send_keepalive(&mut self) -> Result<(), AprsIsError>
Send a keepalive if the keepalive interval has elapsed.
No-op if less than KEEPALIVE_INTERVAL has passed since the
last write of any kind (keepalive or packet).
§Errors
Returns AprsIsError::Write if the write fails.
Sourcepub const fn config(&self) -> &AprsIsConfig
pub const fn config(&self) -> &AprsIsConfig
Get the configuration this client was created with.
Sourcepub async fn shutdown(self) -> Result<(), AprsIsError>
pub async fn shutdown(self) -> Result<(), AprsIsError>
Gracefully shut down the TCP connection.
§Errors
Returns AprsIsError::Write if the shutdown flush fails.