gpsd_json/protocol/
v3.rs

1//! GPSD JSON Protocol Version 3 implementation
2//!
3//! This module implements version 3 of the GPSD JSON protocol, which is
4//! the current stable protocol used by GPSD 3.x releases.
5//!
6//! The protocol defines a set of request commands that clients can send
7//! to GPSD and response messages that GPSD sends back. All communication
8//! uses newline-delimited JSON format.
9//!
10//! # Protocol Overview
11//!
12//! - Commands start with '?' and end with ';'
13//! - Responses are JSON objects with a "class" field indicating message type
14//! - Data can be streamed continuously or polled on demand
15//!
16//! # References
17//!
18//! Based on the GPSD project protocol specification:
19//! - [GPSD Protocol Documentation](https://gpsd.io/gpsd_json.html)
20//! - [Protocol Version History](https://gitlab.com/gpsd/gpsd)
21
22use crate::{
23    client::GpsdJsonProtocol,
24    protocol::{GpsdJsonRequest, GpsdJsonResponse},
25};
26
27/// Request message types and builders
28pub mod request;
29/// Response message types and parsers
30pub mod response;
31/// Common data types used in protocol messages
32pub mod types;
33
34/// Protocol version 3 major version number
35///
36/// Reference: [release-3.25](https://gitlab.com/gpsd/gpsd/-/blob/release-3.25/SConscript?ref_type=tags#L226)
37pub const API_VERSION_MAJOR: i32 = 3;
38
39/// Protocol version 3 minor version number
40///
41/// This library supports protocol version 3.15 and later
42pub const API_VERSION_MINOR: i32 = 15;
43
44/// Protocol version 3 implementation marker
45///
46/// This struct implements the `GpsdJsonProtocol` trait for version 3
47/// of the GPSD JSON protocol.
48#[derive(Debug)]
49pub struct V3;
50
51impl GpsdJsonProtocol for V3 {
52    const API_VERSION_MAJOR: i32 = API_VERSION_MAJOR;
53    const API_VERSION_MINOR: i32 = API_VERSION_MINOR;
54
55    type Request = request::Message;
56    type Response = response::Message;
57}
58
59/// Type alias for version 3 response messages
60///
61/// This is a convenience alias for `response::Message` that makes it
62/// clear we're working with protocol v3 responses.
63pub type ResponseMessage = response::Message;
64impl GpsdJsonResponse for ResponseMessage {}
65
66/// Type alias for version 3 request messages
67///
68/// This is a convenience alias for `request::Message` that makes it
69/// clear we're working with protocol v3 requests.
70pub type RequestMessage = request::Message;
71
72impl GpsdJsonRequest for RequestMessage {
73    /// Converts a request message into a GPSD command string
74    ///
75    /// Each request type is formatted according to the GPSD protocol:
76    /// - Simple commands: `?COMMAND;`
77    /// - Commands with parameters: `?COMMAND={"json":"params"};`
78    fn to_command(&self) -> String {
79        match self {
80            RequestMessage::Devices => "?DEVICES;".into(),
81            RequestMessage::Watch(Some(watch)) => {
82                format!("?WATCH={};", serde_json::to_string(watch).unwrap())
83            }
84            RequestMessage::Watch(None) => "?WATCH;".into(),
85            RequestMessage::Device(Some(device)) => {
86                format!("?DEVICE={};", serde_json::to_string(device).unwrap())
87            }
88            RequestMessage::Device(None) => "?DEVICE;".into(),
89            RequestMessage::Poll => "?POLL;".into(),
90            RequestMessage::Version => "?VERSION;".into(),
91        }
92    }
93}
gpsd_json/protocol/v3.rs

gpsd_json/protocol/
v3.rs
