From 0f3bd782c43c20a0022e288d4f6ab05db6beccbc Mon Sep 17 00:00:00 2001 From: Christophe Romain Date: Mon, 18 Oct 2010 16:53:21 +0200 Subject: [PATCH] documentation update (thanks to Karim Gemayel) --- src/mod_pubsub/pubsub.hrl | 241 ++++++++++++++++++++++---------------- 1 file changed, 139 insertions(+), 102 deletions(-) diff --git a/src/mod_pubsub/pubsub.hrl b/src/mod_pubsub/pubsub.hrl index ee21818b6..08f722672 100644 --- a/src/mod_pubsub/pubsub.hrl +++ b/src/mod_pubsub/pubsub.hrl @@ -35,112 +35,149 @@ %% ------------------------------- %% Pubsub types -%%% @type host() = string(). -%%%

host is the name of the PubSub service. For example, it can be -%%% "pubsub.localhost".

- -%%% @type pubsubNode() = [string()]. -%%%

A node is defined by a list of its ancestors. The last element is the name -%%% of the current node. For example: -%%% ```["home", "localhost", "cromain", "node1"]'''

- -%%% @type stanzaError() = #xmlelement{}. -%%% Example: -%%% ```{xmlelement, "error", -%%% [{"code", Code}, {"type", Type}], -%%% [{xmlelement, Condition, [{"xmlns", ?NS_STANZAS}], []}]}''' - -%%% @type pubsubIQResponse() = #xmlelement{}. -%%% Example: -%%% ```{xmlelement, "pubsub", -%%% [{"xmlns", ?NS_PUBSUB_EVENT}], -%%% [{xmlelement, "affiliations", [], -%%% []}]}''' - -%%% @type nodeOption() = {Option::atom(), Value::term()}. -%%% Example: -%%% ```{deliver_payloads, true}''' - -%%% @type nodeType() = string(). -%%%

The nodeType is a string containing the name of the PubSub -%%% plugin to use to manage a given node. For example, it can be -%%% "flat", "hometree" or "blog".

- -%%% @type jid() = #jid{ -%%% user = string(), -%%% server = string(), -%%% resource = string(), -%%% luser = string(), -%%% lserver = string(), -%%% lresource = string()}. - -%%% @type ljid() = {User::string(), Server::string(), Resource::string()}. - -%%% @type affiliation() = none | owner | publisher | outcast. -%%% @type subscription() = none | pending | unconfigured | subscribed. - -%%% internal pubsub index table --record(pubsub_index, {index, last, free}). - -%%% @type pubsubNode() = #pubsub_node{ -%%% nodeid = {Host::host(), Node::pubsubNode()}, -%%% parentid = Node::pubsubNode(), -%%% nodeidx = int(), -%%% type = nodeType(), -%%% options = [nodeOption()]}. -%%%

This is the format of the nodes table. The type of the table -%%% is: set,ram/disc.

-%%%

The parentid and type fields are indexed.

-%%% nodeidx can be anything you want. --record(pubsub_node, {nodeid, - id, - parents = [], - type = "flat", - owners = [], - options = [] - }). - -%%% @type pubsubState() = #pubsub_state{ -%%% stateid = {ljid(), nodeidx()}, -%%% items = [ItemId::string()], -%%% affiliation = affiliation(), -%%% subscriptions = [subscription()]}. -%%%

This is the format of the affiliations table. The type of the -%%% table is: set,ram/disc.

--record(pubsub_state, {stateid, - items = [], - affiliation = none, - subscriptions = [] +%% @type host() = string(). +%%

host is the name of the PubSub service. For example, it can be +%% <<"pubsub.localhost">>.

+ +%% @type nodeId() = binary(). +%%

A node is defined by a list of its ancestors. The last element is the name +%% of the current node. For example: +%% ```<<"/home/localhost/user">>'''

+ +%% @type nodeIdx() = integer(). + +%% @type itemId() = string(). + +%% @type subId() = string(). + +%% @type payload() = [#xmlelement{} | #xmlcdata{}]. + +%% @type stanzaError() = #xmlelement{}. +%% Example: +%% ```{xmlelement, "error", +%% [{"code", Code}, {"type", Type}], +%% [{xmlelement, Condition, [{"xmlns", ?NS_STANZAS}], []}]}''' +%% @type pubsubIQResponse() = #xmlelement{}. +%% Example: +%% ```{xmlelement, "pubsub", +%% [{"xmlns", ?NS_PUBSUB_EVENT}], +%% [{xmlelement, "affiliations", [], +%% []}]}''' + +%% @type nodeOption() = {Option, Value}. +%% Option = atom(), +%% Value = term(). +%% Example: +%% ```{deliver_payloads, true}''' + +%% @type nodeType() = string(). +%%

The nodeType is a string containing the name of the PubSub +%% plugin to use to manage a given node. For example, it can be +%% "flat", "hometree" or "blog".

+ +%% @type jid() = {jid, User, Server, Resource, LUser, LServer, LResource}. +%% User = string(), +%% Server = string(), +%% Resource = string(), +%% LUser = string(), +%% LServer = string(), +%% LResource = string(). + +%% @type ljid() = {User, Server, Resource}. +%% User = string(), +%% Server = string(), +%% Resource = string(). + +%% @type affiliation() = 'none' | 'owner' | 'publisher' | 'publish-only' | 'member' | 'outcast'. + +%% @type subscription() = 'none' | 'pending' | 'unconfigured' | 'subscribed'. + + +%% @type pubsubIndex() = {pubsub_index, Index, Last, Free}. +%% Index = atom(), +%% Last = integer(), +%% Free = [integer()]. +%% internal pubsub index table +-record(pubsub_index, +{ + index, + last, + free }). -%%% @type pubsubItem() = #pubsub_item{ -%%% itemid = {ItemId::string(), nodeidx()}, -%%% creation = {now(), ljid()}, -%%% modification = {now(), ljid()}, -%%% payload = XMLContent::string()}. -%%%

This is the format of the published items table. The type of the -%%% table is: set,disc,fragmented.

--record(pubsub_item, {itemid, - creation = {unknown,unknown}, - modification = {unknown,unknown}, - payload = [] - }). - - -%% @type pubsubSubscription() = #pubsub_subscription{ -%% subid = string(), -%% state_key = {ljid(), pubsubNodeId()}, -%% options = [{atom(), term()}] -%% }. +%% @type pubsubNode() = {pubsub_node, NodeId, Id, Parents, Type, Owners, Options}. +%% NodeId = {host() | ljid(), nodeId()}, +%% Id = nodeIdx(), +%% Parents = [nodeId()], +%% Type = nodeType(), +%% Owners = [ljid()], +%% Options = [nodeOption()]. +%%

This is the format of the nodes table. The type of the table +%% is: set,ram/disc.

+%%

The Parents and type fields are indexed.

+%% id can be anything you want. +-record(pubsub_node, +{ + nodeid, + id, + parents = [], + type = "flat", + owners = [], + options = [] +}). + +%% @type pubsubState() = {pubsub_state, StateId, Items, Affiliation, Subscriptions}. +%% StateId = {ljid(), nodeIdx()}, +%% Items = [itemId()], +%% Affiliation = affiliation(), +%% Subscriptions = [{subscription(), subId()}]. +%%

This is the format of the affiliations table. The type of the +%% table is: set,ram/disc.

+-record(pubsub_state, +{ + stateid, + items = [], + affiliation = 'none', + subscriptions = [] +}). + +%% @type pubsubItem() = {pubsub_item, ItemId, Creation, Modification, Payload}. +%% ItemId = {itemId(), nodeIdx()}, +%% Creation = {now(), ljid()}, +%% Modification = {now(), ljid()}, +%% Payload = payload(). +%%

This is the format of the published items table. The type of the +%% table is: set,disc,fragmented.

+-record(pubsub_item, +{ + itemid, + creation = {'unknown','unknown'}, + modification = {'unknown','unknown'}, + payload = [] +}). + +%% @type pubsubSubscription() = {pubsub_subscription, SubId, Options}. +%% SubId = subId(), +%% Options = [nodeOption()]. %%

This is the format of the subscriptions table. The type of the %% table is: set,ram/disc.

--record(pubsub_subscription, {subid, options}). +-record(pubsub_subscription, +{ + subid, + options +}). -%% @type pubsubLastItem() = #pubsub_last_item{ -%% nodeid = nodeidx(), -%% itemid = string(), -%% payload = XMLContent::string()}. +%% @type pubsubLastItem() = {pubsub_last_item, NodeId, ItemId, Creation, Payload}. +%% NodeId = nodeIdx(), +%% ItemId = itemId(), +%% Creation = {now(),ljid()}, +%% Payload = payload(). %%

This is the format of the last items table. it stores last item payload %% for every node

--record(pubsub_last_item, {nodeid, itemid, creation, payload}). - +-record(pubsub_last_item, +{ + nodeid, + itemid, + creation, + payload +}). -- 2.40.0