diff options
Diffstat (limited to 'src/mod_pubsub/pubsub.hrl')
| -rw-r--r-- | src/mod_pubsub/pubsub.hrl | 372 |
1 files changed, 297 insertions, 75 deletions
diff --git a/src/mod_pubsub/pubsub.hrl b/src/mod_pubsub/pubsub.hrl index 9fd5ebd1c..832b4d8c4 100644 --- a/src/mod_pubsub/pubsub.hrl +++ b/src/mod_pubsub/pubsub.hrl @@ -21,6 +21,11 @@ %%% This file contains pubsub types definition. %%% ==================================================================== + +-include_lib("exmpp/include/exmpp.hrl"). +-include_lib("exmpp/include/exmpp_jid.hrl"). + + %% ------------------------------- %% Pubsub constants -define(ERR_EXTENDED(E,C), mod_pubsub:extended_error(E,C)). @@ -32,19 +37,176 @@ %% Would be nice to have it configurable. -define(MAX_PAYLOAD_SIZE, 60000). -%% ------------------------------- + +%% ------------ %% Pubsub types +%% ------------ + +%%% @type hostPubsub() = binary(). +%%% +%%% <p><tt>hostPubsub</tt> is the name of the PubSub service. For example, it can be +%%% <tt>pubsub.localhost</tt>.</p> + +-type(hostPubsub() :: binary()). + + +%%% @type hostPEP() = {User, Server, Resource} +%%% User = binary() +%%% Server = binary() +%%% Resource = undefined. + +-type(hostPEP() :: {User::binary(), Server::binary, Resource::undefined}). + + +%%% @type host() = hostPubsub() | hostPEP(). + +-type(host() :: hostPubsub() | hostPEP()). + + +%% TODO : move upper in exmpp +%%% @type nodeId() = binary(). +%%% +%%% <p>A <tt>nodeId</tt> is the name of a Node. It can be anything and may represent +%%% some hierarchical tree depending of the node type. +%%% For example: +%%% /home/localhost/user/node +%%% princely_musings +%%% http://jabber.org/protocol/tune +%%% My-Own_Node</p> + +-type(nodeId() :: binary()). + + +%%% @type itemId() = binary(). +%%% +%%% <p>An <tt>itemId</tt> is the name of an Item. It can be anything. +%%% For example: +%%% 38964 +%%% my-tune +%%% FD6SBE6a27d</p> + +-type(itemId() :: binary()). + + +%%% @type subId() = binary(). + +-type(subId() :: binary()). + + +%%% @type nodeType() = string(). +%%% +%%% <p>The <tt>nodeType</tt> is a string containing the name of the PubSub +%%% plugin to use to manage a given node. For example, it can be +%%% <tt>"flat"</tt>, <tt>"hometree"</tt> or <tt>"blog"</tt>.</p> + +-type(nodeType() :: string()). + + +%%% @type ljid() = {User, Server, Resource} +%%% User = undefined | binary() +%%% Server = binary() +%%% Resource = undefined | binary(). + +-type(ljid() :: {User::binary(), Server::binary(), Resource::binary()}). + + +%% TODO : move upper in exmpp +%%% @type jidComponent() = {jid, Raw, Node, Domain, Resource} +%%% Raw = binary() +%%% Node = undefined +%%% Domain = binary() +%%% Resource = undefined. + +-type(jidComponent() :: + #jid{raw::binary(), node::undefined, domain::binary(), resource::undefined}). + + +%% TODO : move upper in exmpp +%%% @type jidContact() = {jid, Raw, Node, Domain, Resource} +%%% Raw = binary() +%%% Node = binary() +%%% Domain = binary() +%%% Resource = undefined. + +-type(jidContact() :: + #jid{raw::binary(), node::binary(), domain::binary(), resource::undefined}). + + +%% TODO : move upper in exmpp +%%% @type jidEntity() = {jid, Raw, Node, Domain, Resource} +%%% Raw = binary() +%%% Node = undefined | binary() +%%% Domain = binary() +%%% Resource = undefined | binary(). + + +-type(jidEntity() :: + %% Contact bare JID + #jid{raw::binary(), node::binary(), domain::binary(), resource::undefined} | + %% Contact full JID + #jid{raw::binary(), node::binary(), domain::binary(), resource::binary()} | + %% Component bare JID + #jid{raw::binary(), node::undefined, domain::binary(), resource::undefined} | + %% Component full JID + #jid{raw::binary(), node::undefined, domain::binary(), resource::binary()}). + + +%%% @type bareUsr() = {User, Server, Resource} +%%% User = undefined | binary() +%%% Server = binary() +%%% Resource = undefined. + +-type(bareUsr() :: {User::binary(), Server::binary(), Resource::undefined} + | {User::undefined, Server::binary(), Resource::undefined}). + + +%%% @type fullUsr() = {User, Server, Resource} +%%% User = undefined | binary() +%%% Server = binary() +%%% Resource = undefined | binary(). + + +-type(fullUsr() :: {User::binary(), Server::binary(), Resource::undefined} + | {User::binary(), Server::binary(), Resource::binary()} + | {User::undefined, Server::binary(), Resource::undefined} + | {User::undefined, Server::binary(), Resource::binary()}). + + +%%% @type nodeIdx() = integer(). -%%% @type host() = string(). -%%% <p><tt>host</tt> is the name of the PubSub service. For example, it can be -%%% <tt>"pubsub.localhost"</tt>.</p> +-type(nodeIdx() :: integer()). + + +%%% @type now() = {Megaseconds, Seconds, Microseconds} +%%% Megaseconds = integer() +%%% Seconds = integer() +%%% Microseconds = integer(). + +-type(now() :: {Megaseconds::integer(), Seconds::integer(), Microseconds::integer()}). + + +%%% @type affiliation() = 'none' | 'owner' | 'publisher' |'publish-only' | 'member' | 'outcast'. + +-type(affiliation() :: 'none' | 'owner' | 'publisher' |'publish-only' | 'member' | 'outcast'). + + +%%% @type subscription() = 'none' | 'pending' | 'unconfigured' | 'subscribed'. + +-type(subscription() :: 'none' | 'pending' | 'unconfigured' | 'subscribed'). + + +%%% @type accessModel() = 'open' | 'presence' | 'roster' | 'authorize' | 'whitelist'. + +-type(accessModel() :: 'open' | 'presence' | 'roster' | 'authorize' | 'whitelist'). + + +%%% @type payload() = [] | [#xmlel{}]. + +-type(payload() :: [] | [#xmlel{}]). -%%% @type pubsubNode() = [string()]. -%%% <p>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"]'''</p> %%% @type stanzaError() = #xmlel{}. +%%% %%% Example: %%% ```#xmlel{name = 'error' %%% ns = ?NS_STANZAS, @@ -62,7 +224,11 @@ %%% } %%% ]}''' +-type(stanzaError() :: #xmlel{}). + + %%% @type pubsubIQResponse() = #xmlel{}. +%%% %%% Example: %%% ```#xmlel{name = 'pubsub', %%% ns = ?NS_PUBSUB, @@ -73,89 +239,145 @@ %%% ] %%% }''' -%%% @type nodeOption() = {Option::atom(), Value::term()}. +-type(pubsubIQResponse() :: #xmlel{}). + + +%%% @type features() = [Feature] +%%% Feature = string(). + +-type(features() :: [Feature::string()]). + +%%% @type nodeOption() = {Option, Value}. +%%% Option = atom() +%%% Value = term(). +%%% %%% Example: %%% ```{deliver_payloads, true}''' -%%% @type nodeType() = string(). -%%% <p>The <tt>nodeType</tt> is a string containing the name of the PubSub -%%% plugin to use to manage a given node. For example, it can be -%%% <tt>"flat"</tt>, <tt>"hometree"</tt> or <tt>"blog"</tt>.</p> +-type(nodeOption() :: {Option::atom(), Value::term()}). -%%% @type jid() = #jid{ -%%% user = string(), -%%% server = string(), -%%% resource = string(), -%%% luser = string(), -%%% lserver = string(), -%%% lresource = string()}. -%%% @type ljid() = {User::string(), Server::string(), Resource::string()}. +%%% @type subOption() = {Option, Value}. +%%% Option = atom() +%%% Value = term(). -%%% @type affiliation() = none | owner | publisher | outcast. -%%% @type subscription() = none | pending | unconfigured | subscribed. +-type(subOption() :: {Option::atom(), Value::term()}). -%%% 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()]}. +%%% @type pubsubIndex() = {pubsub_index, Index, Last, Free}. +%%% Index = atom() +%%% Last = nodeIdx() +%%% Free = [nodeIdx()]. +%%% +%%% Internal pubsub index table. + +-record(pubsub_index, + { + index :: atom(), + last :: integer(), + free :: [integer()] + }). + +-type(pubsubIndex() :: #pubsub_index{}). + + +%%% @type pubsubNode() = {pubsub_node, Id, Idx, Parents, Type, Owners, Options} +%%% Id = {host(), nodeId()} +%%% Idx = nodeIdx() +%%% Parents = [nodeId()] +%%% Type = nodeType() +%%% Owners = [bareUsr()] +%%% Options = [nodeOption()]. +%%% %%% <p>This is the format of the <tt>nodes</tt> table. The type of the table %%% is: <tt>set</tt>,<tt>ram/disc</tt>.</p> -%%% <p>The <tt>parentid</tt> and <tt>type</tt> fields are indexed.</p> -%%% <p><tt>nodeidx</tt> can be anything you want.</p> --record(pubsub_node, {nodeid, - id, - parents = [], - type = "flat", - owners = [], - options = [] - }). - -%%% @type pubsubState() = #pubsub_state{ -%%% stateid = {ljid(), nodeidx()}, -%%% items = [ItemId::string()], -%%% affiliation = affiliation(), -%%% subscriptions = [subscription()]}. +%%% <p>The <tt>parents</tt> and <tt>type</tt> fields are indexed.</p> +%%% <p><tt>idx</tt> is an integer.</p> + +-record(pubsub_node, + { + id :: {host(), nodeId()}, + idx :: nodeIdx(), + parents = [] :: [nodeId()], + type = "flat" :: nodeType(), + owners = [] :: [bareUsr()], + options = [] :: [nodeOption()] + }). + +-type(pubsubNode() :: #pubsub_node{}). + + +%%% @type pubsubState() = {pubsub_state, Id, Items, Affiliation, Subscriptions} +%%% Id = {fullUsr(), nodeIdx()} +%%% Items = [itemId()] +%%% Affiliation = affiliation() +%%% Subscriptions = [{subscription(), subId()}]. +%%% %%% <p>This is the format of the <tt>affiliations</tt> table. The type of the %%% table is: <tt>set</tt>,<tt>ram/disc</tt>.</p> --record(pubsub_state, {stateid, - items = [], - affiliation = none, - subscriptions = [] -}). - -%%% @type pubsubItem() = #pubsub_item{ -%%% itemid = {ItemId::string(), nodeidx()}, -%%% creation = {now(), ljid()}, -%%% modification = {now(), ljid()}, -%%% payload = XMLContent::string()}. + +-record(pubsub_state, + { + id :: {fullUsr(), nodeIdx()}, + items = [] :: [itemId()], + affiliation = 'none' :: affiliation(), + subscriptions = [] :: [{subscription(), subId()}] + }). + +-type(pubsubState() :: #pubsub_state{}). + + +%%% @type pubsubItem() = {pubsub_item, Id, Creation, Modification, Payload} +%%% Id = {itemId(), nodeIdx()} +%%% Creation = {now(), bareUsr()} +%%% Modification = {now(), fullUsr()} +%%% Payload = payload(). +%%% %%% <p>This is the format of the <tt>published items</tt> table. The type of the %%% table is: <tt>set</tt>,<tt>disc</tt>,<tt>fragmented</tt>.</p> --record(pubsub_item, {itemid, - creation = {unknown,unknown}, - modification = {unknown,unknown}, - payload = [] - }). - -%% @type pubsubSubscription() = #pubsub_subscription{ -%% subid = string(), -%% state_key = {ljid(), pubsubNodeId()}, -%% options = [{atom(), term()}] -%% }. + +-record(pubsub_item, + { + id :: {itemId(), nodeIdx()}, + creation = {unknown,unknown} :: {now(), bareUsr()}, + modification = {unknown,unknown} :: {now(), fullUsr()}, + payload = [] :: payload() + }). + +-type(pubsubItem() :: #pubsub_item{}). + + +%%% @type pubsubSubscription() = {pubsub_subscription, SubId, Options} +%%% SubId = subId() +%%% Options = [nodeOption()]. +%%% %% <p>This is the format of the <tt>subscriptions</tt> table. The type of the %% table is: <tt>set</tt>,<tt>ram/disc</tt>.</p> --record(pubsub_subscription, {subid, options}). -%% @type pubsubLastItem() = #pubsub_last_item{ -%% nodeid = nodeidx(), -%% itemid = string(), -%% creation = {now(), ljid()}, -%% payload = XMLContent::string()}. +-record(pubsub_subscription, + { + subid :: subId(), + options :: [subOption()] + }). + +-type(pubsubSubscription() :: #pubsub_subscription{}). + + +%%% @type pubsubLastItem() = {pubsub_last_item, NodeId, ItemId, Creation, Payload} +%%% NodeId = nodeIdx() +%%% ItemId = itemId() +%%% Creation = {now(), bareUsr()} +%%% Payload = payload(). +%%% %% <p>This is the format of the <tt>last items</tt> table. it stores last item payload %% for every node</p> --record(pubsub_last_item, {nodeid, itemid, creation, payload}). + +-record(pubsub_last_item, + { + nodeid :: nodeIdx(), + itemid :: itemId(), + creation :: {now(), bareUsr()}, + payload :: payload() + }). + +-type(pubsubLastItem() :: #pubsub_last_item{}). |