diff --git a/crates/core/src/bc/mod.rs b/crates/core/src/bc/mod.rs index 26298e0..0791328 100644 --- a/crates/core/src/bc/mod.rs +++ b/crates/core/src/bc/mod.rs @@ -28,14 +28,14 @@ //! which are binary data in the bc media packet format //! -/// `model` contains the structure of the messages such as headers and payloads +/// Contains the structure of the messages such as headers and payloads pub mod model; -/// `de` contains code related to the deserialisation of the bc packets +/// Contains code related to the deserialisation of the bc packets pub mod de; -/// `ser` contains code related to the serialisation of the bc packets +/// `Contains code related to the serialisation of the bc packets pub mod ser; -/// `xml` contains the know xml payloads +/// Contains the structs for the know xmls of payloads and extension pub mod xml; mod xml_crypto; diff --git a/crates/core/src/bc/model.rs b/crates/core/src/bc/model.rs index e0c9e12..7c2864c 100644 --- a/crates/core/src/bc/model.rs +++ b/crates/core/src/bc/model.rs @@ -42,7 +42,7 @@ pub struct Bc { #[derive(Debug, PartialEq, Eq)] #[allow(clippy::large_enum_variant)] pub enum BcBody { - /// Legacy is unsupported except for login where it is + /// Legacy is unsupported except for login where it is used /// to negociate the initial login and upgrade to modern LegacyMsg(LegacyMsg), /// Modern is the current reolink protocol it is mostly @@ -53,20 +53,20 @@ pub enum BcBody { /// Modern messages have two payloads split by the `payload_offset` in the header /// /// The first payload is extension which describes the second payload. If the -/// `payload_offset` is `0` then their is no `extension` usually because it has -/// already been negociated in a previous message and it is `None` +/// `payload_offset` is `0` then their is no `extension` (usually because it has +/// already been negociated in a previous message) and it is `None` /// /// The second payload contains the actual data of interest and is all bytes after -/// the `payload_offset` up to the `body_len`. If `payload_offset` equals `body_len` -/// then there is not payload and it is `None` +/// the `payload_offset` up to the `body_len`. If `payload_offset` +/// equals `body_len` then there is not payload and it is `None` /// -/// If payload_offset is `0` and equal to `body_len` then there is neither `extension` -/// or `payload` these are header only messages. This usually occurs to acknoledge receipt +/// If `payload_offset` is `0` and equal to `body_len` then there is neither +/// `extension` or `payload` these are header only messages. This usually occurs to acknoledge receipt /// of a command. In such cases the header `response_code` should be checked. /// #[derive(Debug, Default, PartialEq, Eq)] pub struct ModernMsg { - /// Extension describes the following payload such as which `channel_id` it is for + /// Extension describes the following payload such as which channel id it is for pub extension: Option, /// Primary payload which is dependant on MsgID pub payload: Option, @@ -103,25 +103,25 @@ pub(super) struct BcHeader { /// descriptions of the Body (the application dictates these) #[derive(Debug, PartialEq, Eq)] pub struct BcMeta { - /// Message ID dictaes the major content of the messahe + /// Message ID dictaes the major content of the message pub msg_id: u32, /// In most cases 0 but can be other values for NVRs pub channel_id: u8, /// In most cases this is unimportant but 0 means Clear Stream while 1 means Fluent stream - /// This is only really on `MSG_ID_VIDEO` streams when the SD `subStreams` are requested + /// This is only really used during `[MSG_ID_VIDEO]` streams when the SD `subStreams` are requested pub stream_type: u8, /// On modern messages this is the response code - /// When sending a command it is set to `0` but the reply can be - /// - `200` means OK + /// When sending a command it is set to `0`. The reply from the camera can be + /// - `200` for OK /// - `400` for bad request - /// A malformed packet will return a non `400` code + /// A malformed packet will return a `400` code pub response_code: u16, /// A message ID is used to match replies with requests. The camera will parrot back - /// in its reply to a message this same `msg_num` + /// this number in its reply /// - /// Also if there are multiple replies split over multiple messages such as in - /// streams talk or when sending a firmware update they will all have the same - /// `msg_num` + /// If there a message is too long to fit in one packet it will be split over multiple + /// messages all with the same `msg_num` (this can happing in video streams, talk and when + /// sending a firmware update) pub msg_num: u16, /// The class is mostly an unknown quanitiy but does dictate the size of the header /// know values are @@ -242,13 +242,13 @@ impl BcHeader { } } - /// Constuct a `BcHeader` from a `BcMeta` + /// Constuct a [`BcHeader`] from a [`BcMeta`] /// /// This requires additional data such as the `body_len` /// /// # Parameters /// - /// * `meta` - the `BcMeta` to convert + /// * `meta` - the [`BcMeta`] to convert /// /// * `body_len` - The length of the body (extension and payload) in bytes /// diff --git a/crates/core/src/bc/xml.rs b/crates/core/src/bc/xml.rs index 5d41268..0ddc393 100644 --- a/crates/core/src/bc/xml.rs +++ b/crates/core/src/bc/xml.rs @@ -33,7 +33,7 @@ impl Default for BcPayloads { #[derive(PartialEq, Eq, Default, Debug, YaDeserialize, YaSerialize)] #[yaserde(rename = "body")] pub struct BcXml { - /// Encryption xml are negociated during login and contain the NONCE + /// Encryption xml is received during login and contain the NONCE #[yaserde(rename = "Encryption")] pub encryption: Option, /// LoginUser xml is used during modern login @@ -83,7 +83,7 @@ impl Extension { /// Encryption xml #[derive(PartialEq, Eq, Default, Debug, YaDeserialize, YaSerialize)] pub struct Encryption { - /// XML Version always "1.1" + /// XML Version #[yaserde(attribute)] pub version: String, #[yaserde(rename = "type")] @@ -96,7 +96,7 @@ pub struct Encryption { /// LoginUser xml #[derive(PartialEq, Eq, Default, Debug, YaDeserialize, YaSerialize)] pub struct LoginUser { - /// XML Version always "1.1" + /// XML Version #[yaserde(attribute)] pub version: String, /// Username to login as @@ -112,7 +112,7 @@ pub struct LoginUser { /// LoginNet xml #[derive(PartialEq, Eq, Debug, YaDeserialize, YaSerialize)] pub struct LoginNet { - /// XML Version always "1.1" + /// XML Version #[yaserde(attribute)] pub version: String, /// Type of connection usually LAN (even on wifi) @@ -179,7 +179,7 @@ pub struct Resolution { /// This xml is used to request a stream to start #[derive(PartialEq, Eq, Default, Debug, YaDeserialize, YaSerialize)] pub struct Preview { - /// XML Version always "1.1" + /// XML Version #[yaserde(attribute)] pub version: String, @@ -198,7 +198,7 @@ pub struct Preview { /// This is used to describe the subsequent payload passed the `payload_offset` #[derive(PartialEq, Eq, Debug, YaDeserialize, YaSerialize)] pub struct Extension { - /// XML Version always "1.1" + /// XML Version #[yaserde(attribute)] pub version: String, /// If the subsequent payload is binary this will be set to 1. Otherwise it is ommited @@ -233,7 +233,7 @@ impl Default for Extension { /// SystemGeneral xml #[derive(PartialEq, Eq, Default, Debug, YaDeserialize, YaSerialize)] pub struct SystemGeneral { - /// XML Version always "1.1" + /// XML Version #[yaserde(attribute)] pub version: String, @@ -270,7 +270,7 @@ pub struct SystemGeneral { /// Norm xml #[derive(PartialEq, Eq, Default, Debug, YaDeserialize, YaSerialize)] pub struct Norm { - /// XML Version always "1.1" + /// XML Version #[yaserde(attribute)] pub version: String, // This is usually just `"NTSC"` @@ -280,18 +280,18 @@ pub struct Norm { /// LedState xml #[derive(PartialEq, Eq, Default, Debug, YaDeserialize, YaSerialize)] pub struct LedState { - /// XML Version always "1.1" + /// XML Version #[yaserde(attribute)] pub version: String, - /// Channel ID of camera to change its LED + /// Channel ID of camera to get/set its LED state #[yaserde(rename = "channelId")] pub channel_id: u32, - /// LED Version, observed value is "2" + /// LED Version, observed value is "2". Should be None when setting the LedState #[yaserde(rename = "ledVersion")] pub led_version: Option, /// State of the IR LEDs values are "auto", "open", "close" pub state: String, - /// State of the LED status light (blue on light), vallues are "open", "close" + /// State of the LED status light (blue on light), values are "open", "close" #[yaserde(rename = "lightState")] pub light_state: String, } diff --git a/crates/core/src/bc_protocol.rs b/crates/core/src/bc_protocol.rs index ce7b355..a349537 100644 --- a/crates/core/src/bc_protocol.rs +++ b/crates/core/src/bc_protocol.rs @@ -74,13 +74,13 @@ impl BcCamera { /// # Parameters /// /// * `host` - The address of the camera either ip address or hostname string is ok but - /// `SocketAddr` is fine too + /// [`std::net::SocketAddr`] is fine too /// /// * `channel_id` - The channel ID this is usually zero unless using a NVR /// /// # Returns /// - /// returns either an error of the camera + /// returns either an error or the camera /// pub fn new_with_addr(host: T, channel_id: u8) -> Result { let addr_iter = match host.to_socket_addrs() { diff --git a/crates/core/src/bc_protocol/connection.rs b/crates/core/src/bc_protocol/connection.rs index f2695a2..2b853f3 100644 --- a/crates/core/src/bc_protocol/connection.rs +++ b/crates/core/src/bc_protocol/connection.rs @@ -13,7 +13,7 @@ use std::thread::JoinHandle; use std::time::Duration; /// A shareable connection to a camera. Handles serialization of messages. To send/receive, call -/// .subscribe() with a message ID. You can use the BcSubscription to send or receive only +/// .[subscribe()] with a message ID. You can use the BcSubscription to send or receive only /// messages with that ID; each incoming message is routed to its appropriate subscriber. /// /// There can be only one subscriber per kind of message at a time. diff --git a/crates/core/src/bc_protocol/errors.rs b/crates/core/src/bc_protocol/errors.rs index 3eb3434..55c07c5 100644 --- a/crates/core/src/bc_protocol/errors.rs +++ b/crates/core/src/bc_protocol/errors.rs @@ -9,11 +9,11 @@ pub enum Error { #[error(display = "Communication error")] Communication(#[error(source)] std::io::Error), - /// Errors raised during deserlization + /// Error raised during deserlization #[error(display = "Deserialization error")] Deserialization(#[error(source)] super::bc::de::Error), - /// Errors raised during serlization + /// Error raised during serlization #[error(display = "Serialization error")] Serialization(#[error(source)] super::bc::ser::Error), @@ -30,8 +30,7 @@ pub enum Error { why: &'static str, }, - /// Raised when a connection is dropped. This can be for many reasons - /// and is usually not helpful + /// Raised when a connection is dropped. #[error(display = "Dropped connection")] DroppedConnection(#[error(source)] std::sync::mpsc::RecvError), @@ -39,7 +38,7 @@ pub enum Error { #[error(display = "Timeout")] Timeout, - /// Raised when connection is dropped because the RX_TIMEOUT is reach + /// Raised when connection is dropped because the timeout is reach #[error(display = "Dropped connection")] TimeoutDisconnected, diff --git a/crates/core/src/bc_protocol/ledstate.rs b/crates/core/src/bc_protocol/ledstate.rs index 91259de..6be34d8 100644 --- a/crates/core/src/bc_protocol/ledstate.rs +++ b/crates/core/src/bc_protocol/ledstate.rs @@ -2,7 +2,7 @@ use super::{BcCamera, Error, Result, RX_TIMEOUT}; use crate::bc::{model::*, xml::*}; impl BcCamera { - /// Get the LEDState xml which contains the LED status of the camera + /// Get the [LedState] xml which contains the LED status of the camera pub fn get_ledstate(&mut self) -> Result { let connection = self .connection @@ -48,7 +48,7 @@ impl BcCamera { } } - /// Set the led lights using the LEDState xml + /// Set the led lights using the [LedState] xml pub fn set_ledstate(&mut self, mut led_state: LedState) -> Result<()> { let connection = self .connection diff --git a/crates/core/src/bc_protocol/stream.rs b/crates/core/src/bc_protocol/stream.rs index 94d70c5..39f0c01 100644 --- a/crates/core/src/bc_protocol/stream.rs +++ b/crates/core/src/bc_protocol/stream.rs @@ -8,6 +8,9 @@ use crate::{ }; /// The stream from the camera will be using one of these formats +/// +/// This is used as part of `StreamOutput` to give hints about +/// the format of the stream #[derive(Debug, PartialEq, Eq, Hash, Copy, Clone)] pub enum StreamFormat { /// H264 (AVC) video format @@ -20,10 +23,10 @@ pub enum StreamFormat { ADPCM, } -/// Convience type for the error raised by the StreamOutput trait +/// Convience type for the error raised by the [StreamOutput] trait pub type StreamOutputError = Result<()>; -/// The method `start_stream` requires a structure with this trait to pass the +/// The method [`BcCamera::start_video()`] requires a structure with this trait to pass the /// audio and video data back to pub trait StreamOutput { /// This is the callback raised when audio data is received @@ -38,7 +41,7 @@ impl BcCamera { /// /// # Parameters /// - /// * `data_outs` - This should be a struct that implements the `StreamOutput` trait + /// * `data_outs` - This should be a struct that implements the [`StreamOutput`] trait /// /// * `stream_name` - The name of the stream either `"mainStream"` for HD or `"subStream"` for SD /// diff --git a/crates/core/src/bc_protocol/version.rs b/crates/core/src/bc_protocol/version.rs index 870e61e..2781421 100644 --- a/crates/core/src/bc_protocol/version.rs +++ b/crates/core/src/bc_protocol/version.rs @@ -2,7 +2,7 @@ use super::{BcCamera, Error, Result, RX_TIMEOUT}; use crate::bc::{model::*, xml::*}; impl BcCamera { - /// Request the VersionInfo xml + /// Request the [VersionInfo] xml pub fn version(&self) -> Result { let connection = self .connection diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs index 981820d..551fe87 100644 --- a/crates/core/src/lib.rs +++ b/crates/core/src/lib.rs @@ -3,7 +3,7 @@ //! //! Neolink-Core is a rust library for interacting with reolink and family cameras. //! -//! Most high level camera controls are in the `neolink_core::bc_protocol` module +//! Most high level camera controls are in the [`bc_protocol`] module //! //! A camera can be initialised with //! @@ -19,12 +19,12 @@ //! # let camera = BcCamera::new_with_addr("camera_ip_address", channel_id); //! camera.login("username", "password"); //! ``` -//! For further commands see the `BcCamera` struct. +//! For further commands see the [`bc_protocol::BcCamera`] struct. //! -/// `bc` module contains low level BC structures and formats +/// Contains low level BC structures and formats pub mod bc; -/// `bc_protocol` contains high level interfaces for the camera +/// Contains high level interfaces for the camera pub mod bc_protocol; #[derive(Debug)]