pubsub: Document the new structs and their fields.
This commit is contained in:
parent
58a1d80b77
commit
71dc5ad6c8
3 changed files with 127 additions and 14 deletions
|
@ -36,18 +36,18 @@ macro_rules! get_attr {
|
||||||
}
|
}
|
||||||
|
|
||||||
macro_rules! generate_attribute {
|
macro_rules! generate_attribute {
|
||||||
($elem:ident, $name:tt, {$($a:ident => $b:tt),+,}) => (
|
($(#[$meta:meta])* $elem:ident, $name:tt, {$($(#[$a_meta:meta])* $a:ident => $b:tt),+,}) => (
|
||||||
generate_attribute!($elem, $name, {$($a => $b),+});
|
generate_attribute!($(#[$meta])* $elem, $name, {$($(#[$a_meta])* $a => $b),+});
|
||||||
);
|
);
|
||||||
($elem:ident, $name:tt, {$($a:ident => $b:tt),+,}, Default = $default:ident) => (
|
($(#[$meta:meta])* $elem:ident, $name:tt, {$($(#[$a_meta:meta])* $a:ident => $b:tt),+,}, Default = $default:ident) => (
|
||||||
generate_attribute!($elem, $name, {$($a => $b),+}, Default = $default);
|
generate_attribute!($(#[$meta])* $elem, $name, {$($(#[$a_meta])* $a => $b),+}, Default = $default);
|
||||||
);
|
);
|
||||||
($elem:ident, $name:tt, {$($a:ident => $b:tt),+}) => (
|
($(#[$meta:meta])* $elem:ident, $name:tt, {$($(#[$a_meta:meta])* $a:ident => $b:tt),+}) => (
|
||||||
|
$(#[$meta])*
|
||||||
#[derive(Debug, Clone, PartialEq)]
|
#[derive(Debug, Clone, PartialEq)]
|
||||||
pub enum $elem {
|
pub enum $elem {
|
||||||
$(
|
$(
|
||||||
#[doc=$b]
|
$(#[$a_meta])*
|
||||||
#[doc="value for this attribute."]
|
|
||||||
$a
|
$a
|
||||||
),+
|
),+
|
||||||
}
|
}
|
||||||
|
@ -68,12 +68,12 @@ macro_rules! generate_attribute {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
);
|
);
|
||||||
($elem:ident, $name:tt, {$($a:ident => $b:tt),+}, Default = $default:ident) => (
|
($(#[$meta:meta])* $elem:ident, $name:tt, {$($(#[$a_meta:meta])* $a:ident => $b:tt),+}, Default = $default:ident) => (
|
||||||
|
$(#[$meta])*
|
||||||
#[derive(Debug, Clone, PartialEq)]
|
#[derive(Debug, Clone, PartialEq)]
|
||||||
pub enum $elem {
|
pub enum $elem {
|
||||||
$(
|
$(
|
||||||
#[doc=$b]
|
$(#[$a_meta])*
|
||||||
#[doc="value for this attribute."]
|
|
||||||
$a
|
$a
|
||||||
),+
|
),+
|
||||||
}
|
}
|
||||||
|
@ -101,7 +101,8 @@ macro_rules! generate_attribute {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
);
|
);
|
||||||
($elem:ident, $name:tt, bool) => (
|
($(#[$meta:meta])* $elem:ident, $name:tt, bool) => (
|
||||||
|
$(#[$meta])*
|
||||||
#[derive(Debug, Clone, PartialEq)]
|
#[derive(Debug, Clone, PartialEq)]
|
||||||
pub enum $elem {
|
pub enum $elem {
|
||||||
/// True value, represented by either 'true' or '1'.
|
/// True value, represented by either 'true' or '1'.
|
||||||
|
|
|
@ -4,7 +4,10 @@
|
||||||
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
// 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/.
|
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
||||||
|
|
||||||
|
/// The `http://jabber.org/protocol/pubsub#event` protocol.
|
||||||
pub mod event;
|
pub mod event;
|
||||||
|
|
||||||
|
/// The `http://jabber.org/protocol/pubsub` protocol.
|
||||||
pub mod pubsub;
|
pub mod pubsub;
|
||||||
|
|
||||||
pub use self::event::PubSubEvent;
|
pub use self::event::PubSubEvent;
|
||||||
|
|
|
@ -4,6 +4,8 @@
|
||||||
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
// 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/.
|
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
||||||
|
|
||||||
|
#![deny(missing_docs)]
|
||||||
|
|
||||||
use try_from::TryFrom;
|
use try_from::TryFrom;
|
||||||
|
|
||||||
use minidom::Element;
|
use minidom::Element;
|
||||||
|
@ -20,71 +22,108 @@ use pubsub::{NodeName, ItemId, Subscription, SubscriptionId};
|
||||||
// TODO: a better solution would be to split this into a query and a result elements, like for
|
// TODO: a better solution would be to split this into a query and a result elements, like for
|
||||||
// XEP-0030.
|
// XEP-0030.
|
||||||
generate_element_with_children!(
|
generate_element_with_children!(
|
||||||
|
/// A list of affiliations you have on a service, or on a node.
|
||||||
Affiliations, "affiliations", PUBSUB,
|
Affiliations, "affiliations", PUBSUB,
|
||||||
attributes: [
|
attributes: [
|
||||||
|
/// The optional node name this request pertains to.
|
||||||
node: Option<NodeName> = "node" => optional,
|
node: Option<NodeName> = "node" => optional,
|
||||||
],
|
],
|
||||||
children: [
|
children: [
|
||||||
|
/// The actual list of affiliation elements.
|
||||||
affiliations: Vec<Affiliation> = ("affiliation", PUBSUB) => Affiliation
|
affiliations: Vec<Affiliation> = ("affiliation", PUBSUB) => Affiliation
|
||||||
]
|
]
|
||||||
);
|
);
|
||||||
|
|
||||||
generate_attribute!(
|
generate_attribute!(
|
||||||
|
/// A list of possible affiliations to a node.
|
||||||
AffiliationAttribute, "affiliation", {
|
AffiliationAttribute, "affiliation", {
|
||||||
|
/// You are a member of this node, you can subscribe and retrieve items.
|
||||||
Member => "member",
|
Member => "member",
|
||||||
|
|
||||||
|
/// You don’t have a specific affiliation with this node, you can only subscribe to it.
|
||||||
None => "none",
|
None => "none",
|
||||||
|
|
||||||
|
/// You are banned from this node.
|
||||||
Outcast => "outcast",
|
Outcast => "outcast",
|
||||||
|
|
||||||
|
/// You are an owner of this node, and can do anything with it.
|
||||||
Owner => "owner",
|
Owner => "owner",
|
||||||
|
|
||||||
|
/// You are a publisher on this node, you can publish and retract items to it.
|
||||||
Publisher => "publisher",
|
Publisher => "publisher",
|
||||||
|
|
||||||
|
/// You can publish and retract items on this node, but not subscribe or retrive items.
|
||||||
PublishOnly => "publish-only",
|
PublishOnly => "publish-only",
|
||||||
}
|
}
|
||||||
);
|
);
|
||||||
|
|
||||||
generate_element_with_only_attributes!(
|
generate_element_with_only_attributes!(
|
||||||
|
/// An affiliation element.
|
||||||
Affiliation, "affiliation", PUBSUB, [
|
Affiliation, "affiliation", PUBSUB, [
|
||||||
|
/// The node this affiliation pertains to.
|
||||||
node: NodeName = "node" => required,
|
node: NodeName = "node" => required,
|
||||||
|
|
||||||
|
/// The affiliation you currently have on this node.
|
||||||
affiliation: AffiliationAttribute = "affiliation" => required,
|
affiliation: AffiliationAttribute = "affiliation" => required,
|
||||||
]
|
]
|
||||||
);
|
);
|
||||||
|
|
||||||
generate_element_with_children!(
|
generate_element_with_children!(
|
||||||
|
/// Request to configure a new node.
|
||||||
Configure, "configure", PUBSUB,
|
Configure, "configure", PUBSUB,
|
||||||
child: (
|
child: (
|
||||||
|
/// The form to configure it.
|
||||||
form: Option<DataForm> = ("x", DATA_FORMS) => DataForm
|
form: Option<DataForm> = ("x", DATA_FORMS) => DataForm
|
||||||
)
|
)
|
||||||
);
|
);
|
||||||
|
|
||||||
generate_element_with_only_attributes!(
|
generate_element_with_only_attributes!(
|
||||||
|
/// Request to create a new node.
|
||||||
Create, "create", PUBSUB, [
|
Create, "create", PUBSUB, [
|
||||||
|
/// The node name to create, if `None` the service will generate one.
|
||||||
node: Option<NodeName> = "node" => optional,
|
node: Option<NodeName> = "node" => optional,
|
||||||
]
|
]
|
||||||
);
|
);
|
||||||
|
|
||||||
generate_element_with_only_attributes!(
|
generate_element_with_only_attributes!(
|
||||||
|
/// Request for a default node configuration.
|
||||||
Default, "default", PUBSUB, [
|
Default, "default", PUBSUB, [
|
||||||
|
/// The node targetted by this request, otherwise the entire service.
|
||||||
node: Option<NodeName> = "node" => optional,
|
node: Option<NodeName> = "node" => optional,
|
||||||
|
|
||||||
// TODO: do we really want to support collection nodes?
|
// TODO: do we really want to support collection nodes?
|
||||||
// type: String = "type" => optional,
|
// type: String = "type" => optional,
|
||||||
]
|
]
|
||||||
);
|
);
|
||||||
|
|
||||||
generate_element_with_children!(
|
generate_element_with_children!(
|
||||||
|
/// A request for a list of items.
|
||||||
Items, "items", PUBSUB,
|
Items, "items", PUBSUB,
|
||||||
attributes: [
|
attributes: [
|
||||||
// TODO: should be an xs:positiveInteger, that is, an unbounded int ≥ 1.
|
// TODO: should be an xs:positiveInteger, that is, an unbounded int ≥ 1.
|
||||||
|
/// Maximum number of items returned.
|
||||||
max_items: Option<u32> = "max_items" => optional,
|
max_items: Option<u32> = "max_items" => optional,
|
||||||
|
|
||||||
|
/// The node queried by this request.
|
||||||
node: NodeName = "node" => required,
|
node: NodeName = "node" => required,
|
||||||
|
|
||||||
|
/// The subscription identifier related to this request.
|
||||||
subid: Option<SubscriptionId> = "subid" => optional,
|
subid: Option<SubscriptionId> = "subid" => optional,
|
||||||
],
|
],
|
||||||
children: [
|
children: [
|
||||||
|
/// The actual list of items returned.
|
||||||
items: Vec<Item> = ("item", PUBSUB) => Item
|
items: Vec<Item> = ("item", PUBSUB) => Item
|
||||||
]
|
]
|
||||||
);
|
);
|
||||||
|
|
||||||
|
/// An item from a PubSub node.
|
||||||
#[derive(Debug, Clone)]
|
#[derive(Debug, Clone)]
|
||||||
pub struct Item {
|
pub struct Item {
|
||||||
payload: Option<Element>,
|
/// The payload of this item, in an arbitrary namespace.
|
||||||
id: Option<ItemId>,
|
pub payload: Option<Element>,
|
||||||
|
|
||||||
|
/// The 'id' attribute of this item.
|
||||||
|
pub id: Option<ItemId>,
|
||||||
}
|
}
|
||||||
|
|
||||||
impl TryFrom<Element> for Item {
|
impl TryFrom<Element> for Item {
|
||||||
|
@ -116,49 +155,71 @@ impl From<Item> for Element {
|
||||||
}
|
}
|
||||||
|
|
||||||
generate_element_with_children!(
|
generate_element_with_children!(
|
||||||
|
/// The options associated to a subscription request.
|
||||||
Options, "options", PUBSUB,
|
Options, "options", PUBSUB,
|
||||||
attributes: [
|
attributes: [
|
||||||
|
/// The JID affected by this request.
|
||||||
jid: Jid = "jid" => required,
|
jid: Jid = "jid" => required,
|
||||||
|
|
||||||
|
/// The node affected by this request.
|
||||||
node: Option<NodeName> = "node" => optional,
|
node: Option<NodeName> = "node" => optional,
|
||||||
|
|
||||||
|
/// The subscription identifier affected by this request.
|
||||||
subid: Option<SubscriptionId> = "subid" => optional,
|
subid: Option<SubscriptionId> = "subid" => optional,
|
||||||
],
|
],
|
||||||
child: (
|
child: (
|
||||||
|
/// The form describing the subscription.
|
||||||
form: Option<DataForm> = ("x", DATA_FORMS) => DataForm
|
form: Option<DataForm> = ("x", DATA_FORMS) => DataForm
|
||||||
)
|
)
|
||||||
);
|
);
|
||||||
|
|
||||||
generate_element_with_children!(
|
generate_element_with_children!(
|
||||||
|
/// Request to publish items to a node.
|
||||||
Publish, "publish", PUBSUB,
|
Publish, "publish", PUBSUB,
|
||||||
attributes: [
|
attributes: [
|
||||||
|
/// The target node for this operation.
|
||||||
node: NodeName = "node" => required,
|
node: NodeName = "node" => required,
|
||||||
],
|
],
|
||||||
children: [
|
children: [
|
||||||
|
/// The items you want to publish.
|
||||||
items: Vec<Item> = ("item", PUBSUB) => Item
|
items: Vec<Item> = ("item", PUBSUB) => Item
|
||||||
]
|
]
|
||||||
);
|
);
|
||||||
|
|
||||||
generate_element_with_children!(
|
generate_element_with_children!(
|
||||||
|
/// The options associated to a publish request.
|
||||||
PublishOptions, "publish-options", PUBSUB,
|
PublishOptions, "publish-options", PUBSUB,
|
||||||
child: (
|
child: (
|
||||||
|
/// The form describing these options.
|
||||||
form: Option<DataForm> = ("x", DATA_FORMS) => DataForm
|
form: Option<DataForm> = ("x", DATA_FORMS) => DataForm
|
||||||
)
|
)
|
||||||
);
|
);
|
||||||
|
|
||||||
generate_attribute!(Notify, "notify", bool);
|
generate_attribute!(
|
||||||
|
/// Whether a retract request should notify subscribers or not.
|
||||||
|
Notify, "notify", bool
|
||||||
|
);
|
||||||
|
|
||||||
generate_element_with_children!(
|
generate_element_with_children!(
|
||||||
|
/// A request to retract some items from a node.
|
||||||
Retract, "retract", PUBSUB,
|
Retract, "retract", PUBSUB,
|
||||||
attributes: [
|
attributes: [
|
||||||
|
/// The node affected by this request.
|
||||||
node: NodeName = "node" => required,
|
node: NodeName = "node" => required,
|
||||||
|
|
||||||
|
/// Whether a retract request should notify subscribers or not.
|
||||||
notify: Notify = "notify" => default,
|
notify: Notify = "notify" => default,
|
||||||
],
|
],
|
||||||
children: [
|
children: [
|
||||||
|
/// The items affected by this request.
|
||||||
items: Vec<Item> = ("item", PUBSUB) => Item
|
items: Vec<Item> = ("item", PUBSUB) => Item
|
||||||
]
|
]
|
||||||
);
|
);
|
||||||
|
|
||||||
|
/// Indicate that the subscription can be configured.
|
||||||
#[derive(Debug, Clone)]
|
#[derive(Debug, Clone)]
|
||||||
pub struct SubscribeOptions {
|
pub struct SubscribeOptions {
|
||||||
|
/// If `true`, the configuration is actually required.
|
||||||
required: bool,
|
required: bool,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -199,59 +260,107 @@ impl From<SubscribeOptions> for Element {
|
||||||
}
|
}
|
||||||
|
|
||||||
generate_element_with_only_attributes!(
|
generate_element_with_only_attributes!(
|
||||||
|
/// A request to subscribe a JID to a node.
|
||||||
Subscribe, "subscribe", PUBSUB, [
|
Subscribe, "subscribe", PUBSUB, [
|
||||||
|
/// The JID being subscribed.
|
||||||
jid: Jid = "jid" => required,
|
jid: Jid = "jid" => required,
|
||||||
|
|
||||||
|
/// The node to subscribe to.
|
||||||
node: Option<NodeName> = "node" => optional,
|
node: Option<NodeName> = "node" => optional,
|
||||||
]
|
]
|
||||||
);
|
);
|
||||||
|
|
||||||
generate_element_with_children!(
|
generate_element_with_children!(
|
||||||
|
/// A request for current subscriptions.
|
||||||
Subscriptions, "subscriptions", PUBSUB,
|
Subscriptions, "subscriptions", PUBSUB,
|
||||||
attributes: [
|
attributes: [
|
||||||
|
/// The node to query.
|
||||||
node: Option<NodeName> = "node" => optional,
|
node: Option<NodeName> = "node" => optional,
|
||||||
],
|
],
|
||||||
children: [
|
children: [
|
||||||
|
/// The list of subscription elements returned.
|
||||||
subscription: Vec<SubscriptionElem> = ("subscription", PUBSUB) => SubscriptionElem
|
subscription: Vec<SubscriptionElem> = ("subscription", PUBSUB) => SubscriptionElem
|
||||||
]
|
]
|
||||||
);
|
);
|
||||||
|
|
||||||
generate_element_with_children!(
|
generate_element_with_children!(
|
||||||
|
/// A subscription element, describing the state of a subscription.
|
||||||
SubscriptionElem, "subscription", PUBSUB,
|
SubscriptionElem, "subscription", PUBSUB,
|
||||||
attributes: [
|
attributes: [
|
||||||
|
/// The JID affected by this subscription.
|
||||||
jid: Jid = "jid" => required,
|
jid: Jid = "jid" => required,
|
||||||
|
|
||||||
|
/// The node affected by this subscription.
|
||||||
node: Option<NodeName> = "node" => optional,
|
node: Option<NodeName> = "node" => optional,
|
||||||
|
|
||||||
|
/// The subscription identifier for this subscription.
|
||||||
subid: Option<SubscriptionId> = "subid" => optional,
|
subid: Option<SubscriptionId> = "subid" => optional,
|
||||||
|
|
||||||
|
/// The state of the subscription.
|
||||||
subscription: Option<Subscription> = "subscription" => optional,
|
subscription: Option<Subscription> = "subscription" => optional,
|
||||||
],
|
],
|
||||||
child: (
|
child: (
|
||||||
|
/// The options related to this subscription.
|
||||||
subscribe_options: Option<SubscribeOptions> = ("subscribe-options", PUBSUB) => SubscribeOptions
|
subscribe_options: Option<SubscribeOptions> = ("subscribe-options", PUBSUB) => SubscribeOptions
|
||||||
)
|
)
|
||||||
);
|
);
|
||||||
|
|
||||||
generate_element_with_only_attributes!(
|
generate_element_with_only_attributes!(
|
||||||
|
/// An unsubscribe request.
|
||||||
Unsubscribe, "unsubscribe", PUBSUB, [
|
Unsubscribe, "unsubscribe", PUBSUB, [
|
||||||
|
/// The JID affected by this request.
|
||||||
jid: Jid = "jid" => required,
|
jid: Jid = "jid" => required,
|
||||||
|
|
||||||
|
/// The node affected by this request.
|
||||||
node: Option<NodeName> = "node" => optional,
|
node: Option<NodeName> = "node" => optional,
|
||||||
|
|
||||||
|
/// The subscription identifier for this subscription.
|
||||||
subid: Option<SubscriptionId> = "subid" => optional,
|
subid: Option<SubscriptionId> = "subid" => optional,
|
||||||
]
|
]
|
||||||
);
|
);
|
||||||
|
|
||||||
|
/// Main payload used to communicate with a PubSub service.
|
||||||
|
///
|
||||||
|
/// `<pubsub xmlns="http://jabber.org/protocol/pubsub"/>`
|
||||||
#[derive(Debug, Clone)]
|
#[derive(Debug, Clone)]
|
||||||
pub enum PubSub {
|
pub enum PubSub {
|
||||||
|
/// Request to create a new node, with optional suggested name and suggested configuration.
|
||||||
Create {
|
Create {
|
||||||
|
/// The create request.
|
||||||
create: Create,
|
create: Create,
|
||||||
|
|
||||||
|
/// The configure request for the new node.
|
||||||
configure: Option<Configure>
|
configure: Option<Configure>
|
||||||
},
|
},
|
||||||
|
|
||||||
|
/// Request to publish items to a node, with optional options.
|
||||||
Publish {
|
Publish {
|
||||||
|
/// The publish request.
|
||||||
publish: Publish,
|
publish: Publish,
|
||||||
|
|
||||||
|
/// The options related to this publish request.
|
||||||
publish_options: Option<PublishOptions>
|
publish_options: Option<PublishOptions>
|
||||||
},
|
},
|
||||||
|
|
||||||
|
/// A list of affiliations you have on a service, or on a node.
|
||||||
Affiliations(Affiliations),
|
Affiliations(Affiliations),
|
||||||
|
|
||||||
|
/// Request for a default node configuration.
|
||||||
Default(Default),
|
Default(Default),
|
||||||
|
|
||||||
|
/// A request for a list of items.
|
||||||
Items(Items),
|
Items(Items),
|
||||||
|
|
||||||
|
/// A request to retract some items from a node.
|
||||||
Retract(Retract),
|
Retract(Retract),
|
||||||
|
|
||||||
|
/// A request about a subscription.
|
||||||
Subscription(SubscriptionElem),
|
Subscription(SubscriptionElem),
|
||||||
|
|
||||||
|
/// A request for current subscriptions.
|
||||||
Subscriptions(Subscriptions),
|
Subscriptions(Subscriptions),
|
||||||
|
|
||||||
|
/// An unsubscribe request.
|
||||||
Unsubscribe(Unsubscribe),
|
Unsubscribe(Unsubscribe),
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue