diff --git a/src/presence.rs b/src/presence.rs index e81358fb8853fa83d3e379b93ade6a3467e27678..8bde17801226156970b6065ebdb4f546632412d3 100644 --- a/src/presence.rs +++ b/src/presence.rs @@ -5,8 +5,6 @@ // License, v. 2.0. If a copy of the MPL was not distributed with this // file, You can obtain one at http://mozilla.org/MPL/2.0/. -#![allow(missing_docs)] - use try_from::TryFrom; use std::str::FromStr; use std::collections::BTreeMap; @@ -22,12 +20,23 @@ use ns; /// Should be implemented on every known payload of a ``. pub trait PresencePayload: TryFrom + Into {} +/// Specifies the availability of an entity or resource. #[derive(Debug, Clone, PartialEq)] pub enum Show { + /// Not an actual show value, but an indication there is no show set. None, + + /// The entity or resource is temporarily away. Away, + + /// The entity or resource is actively interested in chatting. Chat, + + /// The entity or resource is busy (dnd = "Do Not Disturb"). Dnd, + + /// The entity or resource is away for an extended period (xa = "eXtended + /// Away"). Xa, } @@ -70,22 +79,41 @@ impl IntoElements for Show { } } -pub type Lang = String; -pub type Status = String; +type Lang = String; +type Status = String; -pub type Priority = i8; +type Priority = i8; +/// #[derive(Debug, Clone, PartialEq)] pub enum Type { /// This value is not an acceptable 'type' attribute, it is only used /// internally to signal the absence of 'type'. None, + + /// An error has occurred regarding processing of a previously sent + /// presence stanza; if the presence stanza is of type "error", it MUST + /// include an child element (refer to [XMPP‑CORE]). Error, + + /// A request for an entity's current presence; SHOULD be generated only by + /// a server on behalf of a user. Probe, + + /// The sender wishes to subscribe to the recipient's presence. Subscribe, + + /// The sender has allowed the recipient to receive their presence. Subscribed, + + /// The sender is no longer available for communication. Unavailable, + + /// The sender is unsubscribing from the receiver's presence. Unsubscribe, + + /// The subscription request has been denied or a previously granted + /// subscription has been canceled. Unsubscribed, } @@ -132,17 +160,34 @@ impl IntoAttributeValue for Type { /// The main structure representing the `` stanza. #[derive(Debug, Clone)] pub struct Presence { + /// The sender of this presence. pub from: Option, + + /// The recipient of this presence. pub to: Option, + + /// The identifier, unique on this stream, of this stanza. pub id: Option, + + /// The type of this presence stanza. pub type_: Type, + + /// The availability of the sender of this presence. pub show: Show, + + /// A localised list of statuses defined in this presence. pub statuses: BTreeMap, + + /// The sender’s resource priority, if negative it won’t receive messages + /// that haven’t been directed to it. pub priority: Priority, + + /// A list of payloads contained in this presence. pub payloads: Vec, } impl Presence { + /// Create a new presence of this type. pub fn new(type_: Type) -> Presence { Presence { from: None, @@ -156,31 +201,40 @@ impl Presence { } } + /// Set the emitter of this presence, this should only be useful for + /// servers and components, as clients can only send presences from their + /// own resource (which is implicit). pub fn with_from(mut self, from: Option) -> Presence { self.from = from; self } + /// Set the recipient of this presence, this is only useful for directed + /// presences. pub fn with_to(mut self, to: Option) -> Presence { self.to = to; self } + /// Set the identifier for this presence. pub fn with_id(mut self, id: Option) -> Presence { self.id = id; self } + /// Set the availability information of this presence. pub fn with_show(mut self, show: Show) -> Presence { self.show = show; self } + /// Set the priority of this presence. pub fn with_priority(mut self, priority: i8) -> Presence { self.priority = priority; self } + /// Set the payloads of this presence. pub fn with_payloads(mut self, payloads: Vec) -> Presence { self.payloads = payloads; self