From 5fd627b85be036ddec7a59175d3fb5aa2f7953a0 Mon Sep 17 00:00:00 2001 From: Badlop Date: Tue, 1 Apr 2008 10:11:39 +0000 Subject: [PATCH] * doc/api/Makefile: Report the correct ejabberd version. When cleaning, remove also erlang.png * src/mod_muc/mod_muc_room.erl: Update source code to prevent warning messages from EDoc * src/mod_pubsub/mod_pubsub.erl: Likewise * src/mod_pubsub/node_default.erl: Likewise * src/mod_pubsub/nodetree_default.erl: Likewise * src/mod_pubsub/nodetree_virtual.erl: Likewise * src/mod_pubsub/pubsub.hrl: Likewise SVN Revision: 1265 --- ChangeLog | 13 +++ doc/api/Makefile | 3 +- src/mod_muc/mod_muc_room.erl | 30 +++---- src/mod_pubsub/mod_pubsub.erl | 121 ++++++++++++++-------------- src/mod_pubsub/node_default.erl | 28 ++++--- src/mod_pubsub/nodetree_default.erl | 2 +- src/mod_pubsub/nodetree_virtual.erl | 2 +- src/mod_pubsub/pubsub.hrl | 4 +- 8 files changed, 113 insertions(+), 90 deletions(-) diff --git a/ChangeLog b/ChangeLog index ec4ad801e..a2422ac07 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,16 @@ +2008-04-01 Badlop + + * doc/api/Makefile: Report the correct ejabberd version. When + cleaning, remove also erlang.png + + * src/mod_muc/mod_muc_room.erl: Update source code to prevent + warning messages from EDoc + * src/mod_pubsub/mod_pubsub.erl: Likewise + * src/mod_pubsub/node_default.erl: Likewise + * src/mod_pubsub/nodetree_default.erl: Likewise + * src/mod_pubsub/nodetree_virtual.erl: Likewise + * src/mod_pubsub/pubsub.hrl: Likewise + 2008-04-01 Christophe Romain * src/ejabberdctl.template: Add firewalling port range definition diff --git a/doc/api/Makefile b/doc/api/Makefile index 66f399555..a4c8dbb7c 100644 --- a/doc/api/Makefile +++ b/doc/api/Makefile @@ -1,5 +1,5 @@ APPNAME = ejabberd -VSN = SVN +VSN = $(shell sed '/VERSION/!d;s/\(.*\)"\(.*\)"\(.*\)/\2/' ../../src/ejabberd.hrl) DOCDIR=. SRCDIR=../../src @@ -11,6 +11,7 @@ all: docs clean: rm -f *.html rm edoc-info + rm erlang.png docs: erl -noshell -run edoc_run application \ diff --git a/src/mod_muc/mod_muc_room.erl b/src/mod_muc/mod_muc_room.erl index 43918daa4..10b7d8a75 100644 --- a/src/mod_muc/mod_muc_room.erl +++ b/src/mod_muc/mod_muc_room.erl @@ -2818,21 +2818,21 @@ set_opts([], StateData) -> StateData; set_opts([{Opt, Val} | Opts], StateData) -> NSD = case Opt of - ?CASE_CONFIG_OPT(title); - ?CASE_CONFIG_OPT(allow_change_subj); - ?CASE_CONFIG_OPT(allow_query_users); - ?CASE_CONFIG_OPT(allow_private_messages); - ?CASE_CONFIG_OPT(public); - ?CASE_CONFIG_OPT(public_list); - ?CASE_CONFIG_OPT(persistent); - ?CASE_CONFIG_OPT(moderated); - ?CASE_CONFIG_OPT(members_by_default); - ?CASE_CONFIG_OPT(members_only); - ?CASE_CONFIG_OPT(allow_user_invites); - ?CASE_CONFIG_OPT(password_protected); - ?CASE_CONFIG_OPT(password); - ?CASE_CONFIG_OPT(anonymous); - ?CASE_CONFIG_OPT(logging); + title -> StateData#state{config = (StateData#state.config)#config{title = Val}}; + allow_change_subj -> StateData#state{config = (StateData#state.config)#config{allow_change_subj = Val}}; + allow_query_users -> StateData#state{config = (StateData#state.config)#config{allow_query_users = Val}}; + allow_private_messages -> StateData#state{config = (StateData#state.config)#config{allow_private_messages = Val}}; + public -> StateData#state{config = (StateData#state.config)#config{public = Val}}; + public_list -> StateData#state{config = (StateData#state.config)#config{public_list = Val}}; + persistent -> StateData#state{config = (StateData#state.config)#config{persistent = Val}}; + moderated -> StateData#state{config = (StateData#state.config)#config{moderated = Val}}; + members_by_default -> StateData#state{config = (StateData#state.config)#config{members_by_default = Val}}; + members_only -> StateData#state{config = (StateData#state.config)#config{members_only = Val}}; + allow_user_invites -> StateData#state{config = (StateData#state.config)#config{allow_user_invites = Val}}; + password_protected -> StateData#state{config = (StateData#state.config)#config{password_protected = Val}}; + password -> StateData#state{config = (StateData#state.config)#config{password = Val}}; + anonymous -> StateData#state{config = (StateData#state.config)#config{anonymous = Val}}; + logging -> StateData#state{config = (StateData#state.config)#config{logging = Val}}; max_users -> ServiceMaxUsers = get_service_max_users(StateData), MaxUsers = if diff --git a/src/mod_pubsub/mod_pubsub.erl b/src/mod_pubsub/mod_pubsub.erl index f70129de9..56fdb627b 100644 --- a/src/mod_pubsub/mod_pubsub.erl +++ b/src/mod_pubsub/mod_pubsub.erl @@ -33,7 +33,7 @@ %%% This module uses version 1.10 of the specification as a base. %%% Most of the specification is implemented. %%% Code is derivated from the original pubsub v1.7, functions concerning config may be rewritten. -%%% Code also inspired from the original PEP patch by Magnus Henoch +%%% Code also inspired from the original PEP patch by Magnus Henoch (mangeATfreemail.hu) %%% TODO %%% plugin: generate Reply (do not use broadcast atom anymore) @@ -190,7 +190,7 @@ init([ServerHost, Opts]) -> nodetree = NodeTree, plugins = Plugins}}. -%% @spec (Host, Opts) -> Plugins +%% @spec (Host, ServerHost, Opts) -> Plugins %% Host = mod_pubsub:host() Opts = [{Key,Value}] %% ServerHost = host() %% Key = atom() @@ -1121,19 +1121,19 @@ handle_authorization_response(Host, From, To, Packet, XFields) -> %% @doc

Create new pubsub nodes

%%

In addition to method-specific error conditions, there are several general reasons why the node creation request might fail:

%%
    -%%
  • The service does not support node creation. -%%
  • Only entities that are registered with the service are allowed to create nodes but the requesting entity is not registered. -%%
  • The requesting entity does not have sufficient privileges to create nodes. -%%
  • The requested NodeID already exists. -%%
  • The request did not include a NodeID and "instant nodes" are not supported. +%%
  • The service does not support node creation.
    • +%%
  • Only entities that are registered with the service are allowed to create nodes but the requesting entity is not registered.
    • +%%
  • The requesting entity does not have sufficient privileges to create nodes.
    • +%%
  • The requested NodeID already exists.
    • +%%
  • The request did not include a NodeID and "instant nodes" are not supported.
    • %%
%%

ote: node creation is a particular case, error return code is evaluated at many places:

%%
    -%%
  • iq_pubsub checks if service supports node creation (type exists) -%%
  • create_node checks if instant nodes are supported -%%
  • create_node asks node plugin if entity have sufficient privilege -%%
  • nodetree create_node checks if nodeid already exists -%%
  • node plugin create_node just sets default affiliation/subscription +%%
  • iq_pubsub checks if service supports node creation (type exists)
    • +%%
  • create_node checks if instant nodes are supported
    • +%%
  • create_node asks node plugin if entity have sufficient privilege
    • +%%
  • nodetree create_node checks if nodeid already exists
    • +%%
  • node plugin create_node just sets default affiliation/subscription
    • %%
create_node(Host, ServerHost, Node, Owner, Type) -> create_node(Host, ServerHost, Node, Owner, Type, all, []). @@ -1245,9 +1245,9 @@ create_node(Host, ServerHost, Node, Owner, GivenType, Access, Configuration) -> %% @doc

Delete specified node and all childs.

%%

There are several reasons why the node deletion request might fail:

%%
    -%%
  • The requesting entity does not have sufficient privileges to delete the node. -%%
  • The node is the root collection node, which cannot be deleted. -%%
  • The specified node does not exist. +%%
  • The requesting entity does not have sufficient privileges to delete the node.
    • +%%
  • The node is the root collection node, which cannot be deleted.
    • +%%
  • The specified node does not exist.
    • %%
delete_node(_Host, [], _Owner) -> %% Node is the root @@ -1299,20 +1299,20 @@ delete_nodes(Host, Owner) -> %% Node = pubsubNode() %% From = jid() %% JID = jid() -%% @doc

Accepts or rejects subcription requests on a PubSub node.

%% @see node_default:subscribe_node/5 +%% @doc

Accepts or rejects subcription requests on a PubSub node.

%%

There are several reasons why the subscription request might fail:

%%
    -%%
  • The bare JID portions of the JIDs do not match. -%%
  • The node has an access model of "presence" and the requesting entity is not subscribed to the owner's presence. -%%
  • The node has an access model of "roster" and the requesting entity is not in one of the authorized roster groups. -%%
  • The node has an access model of "whitelist" and the requesting entity is not on the whitelist. -%%
  • The service requires payment for subscriptions to the node. -%%
  • The requesting entity is anonymous and the service does not allow anonymous entities to subscribe. -%%
  • The requesting entity has a pending subscription. -%%
  • The requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast). -%%
  • The node does not support subscriptions. -%%
  • The node does not exist. +%%
  • The bare JID portions of the JIDs do not match.
    • +%%
  • The node has an access model of "presence" and the requesting entity is not subscribed to the owner's presence.
    • +%%
  • The node has an access model of "roster" and the requesting entity is not in one of the authorized roster groups.
    • +%%
  • The node has an access model of "whitelist" and the requesting entity is not on the whitelist.
    • +%%
  • The service requires payment for subscriptions to the node.
    • +%%
  • The requesting entity is anonymous and the service does not allow anonymous entities to subscribe.
    • +%%
  • The requesting entity has a pending subscription.
    • +%%
  • The requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast).
    • +%%
  • The node does not support subscriptions.
    • +%%
  • The node does not exist.
    • %%
subscribe_node(Host, Node, From, JID) -> Subscriber = case jlib:string_to_jid(JID) of @@ -1385,7 +1385,7 @@ subscribe_node(Host, Node, From, JID) -> {result, Result} end. -%% @spec (Host, Noce, From, JID) -> {error, Reason} | {result, []} +%% @spec (Host, Noce, From, JID, SubId) -> {error, Reason} | {result, []} %% Host = host() %% Node = pubsubNode() %% From = jid() @@ -1395,12 +1395,12 @@ subscribe_node(Host, Node, From, JID) -> %% @doc

Unsubscribe JID from the Node.

%%

There are several reasons why the unsubscribe request might fail:

%%
    -%%
  • The requesting entity has multiple subscriptions to the node but does not specify a subscription ID. -%%
  • The request does not specify an existing subscriber. -%%
  • The requesting entity does not have sufficient privileges to unsubscribe the specified JID. -%%
  • The node does not exist. -%%
  • The request specifies a subscription ID that is not valid or current. -%% +%%
  • The requesting entity has multiple subscriptions to the node but does not specify a subscription ID.
    • +%%
  • The request does not specify an existing subscriber.
    • +%%
  • The requesting entity does not have sufficient privileges to unsubscribe the specified JID.
    • +%%
  • The node does not exist.
    • +%%
  • The request specifies a subscription ID that is not valid or current.
    • +%%
unsubscribe_node(Host, Node, From, JID, SubId) -> Subscriber = case jlib:string_to_jid(JID) of error -> {"", "", ""}; @@ -1423,12 +1423,12 @@ unsubscribe_node(Host, Node, From, JID, SubId) -> %%

The permission to publish an item must be verified by the plugin implementation.

%%

There are several reasons why the publish request might fail:

%%
    -%%
  • The requesting entity does not have sufficient privileges to publish. -%%
  • The node does not support item publication. -%%
  • The node does not exist. -%%
  • The payload size exceeds a service-defined limit. -%%
  • The item contains more than one payload element or the namespace of the root payload element does not match the configured namespace for the node. -%%
  • The request does not match the node configuration. +%%
  • The requesting entity does not have sufficient privileges to publish.
    • +%%
  • The node does not support item publication.
    • +%%
  • The node does not exist.
    • +%%
  • The payload size exceeds a service-defined limit.
    • +%%
  • The item contains more than one payload element or the namespace of the root payload element does not match the configured namespace for the node.
    • +%%
  • The request does not match the node configuration.
    • %%
publish_item(Host, ServerHost, Node, Publisher, "", Payload) -> %% if publisher does not specify an ItemId, the service MUST generate the ItemId @@ -1524,12 +1524,12 @@ publish_item(Host, ServerHost, Node, Publisher, ItemId, Payload) -> %%

The permission to delete an item must be verified by the plugin implementation.

%%

There are several reasons why the item retraction request might fail:

%%
    -%%
  • The publisher does not have sufficient privileges to delete the requested item. -%%
  • The node or item does not exist. -%%
  • The request does not specify a node. -%%
  • The request does not include an element or the element does not specify an ItemId. -%%
  • The node does not support persistent items. -%%
  • The service does not support the deletion of items. +%%
  • The publisher does not have sufficient privileges to delete the requested item.
    • +%%
  • The node or item does not exist.
    • +%%
  • The request does not specify a node.
    • +%%
  • The request does not include an element or the element does not specify an ItemId.
    • +%%
  • The node does not support persistent items.
    • +%%
  • The service does not support the deletion of items.
    • %%
delete_item(Host, Node, Publisher, ItemId) -> delete_item(Host, Node, Publisher, ItemId, false). @@ -1580,10 +1580,10 @@ delete_item(Host, Node, Publisher, ItemId, ForceNotify) -> %% @doc

Delete all items of specified node owned by JID.

%%

There are several reasons why the node purge request might fail:

%%
    -%%
  • The node or service does not support node purging. -%%
  • The requesting entity does not have sufficient privileges to purge the node. -%%
  • The node is not configured to persist items. -%%
  • The specified node does not exist. +%%
  • The node or service does not support node purging.
    • +%%
  • The requesting entity does not have sufficient privileges to purge the node.
    • +%%
  • The node is not configured to persist items.
    • +%%
  • The specified node does not exist.
    • %%
purge_node(Host, Node, Owner) -> Action = fun(#pubsub_node{type = Type, options = Options}) -> @@ -1670,7 +1670,7 @@ get_items(Host, Node) -> %% @spec (Host, Node, LJID) -> any() %% Host = host() %% Node = pubsubNode() -%% LJID = {U,S,""} +%% LJID = {U, S, []} %% @doc

Resend the items of a node to the user.

send_all_items(Host, Node, LJID) -> send_items(Host, Node, LJID, all). @@ -1949,7 +1949,8 @@ set_subscriptions(Host, Node, From, EntitiesEls) -> end. -% @spec (OwnerUser, OwnerServer, {SubscriberUser, SubscriberServer, _}, AllowedGroups) +%% @spec (OwnerUser, OwnerServer, {SubscriberUser, SubscriberServer, SubscriberResource}, AllowedGroups) +%% -> {PresenceSubscription, RosterGroup} get_roster_info(OwnerUser, OwnerServer, {SubscriberUser, SubscriberServer, _}, AllowedGroups) -> {Subscription, Groups} = ejabberd_hooks:run_fold( @@ -2022,11 +2023,11 @@ service_jid(Host) -> _ -> {jid, "", Host, "", "", Host, ""} end. -%% @spec (LJID, PresenceDelivery) -> boolean() +%% @spec (LJID, Subscription, PresenceDelivery) -> boolean() %% LJID = jid() %% Subscription = atom() %% PresenceDelivery = boolean() -%% @doc

Check if a notification must be delivered or not +%% @doc

Check if a notification must be delivered or not.

is_to_delivered(_, none, _) -> false; is_to_delivered(_, pending, _) -> false; is_to_delivered(_, _, false) -> true; @@ -2325,8 +2326,8 @@ is_caps_notify(Host, Node, Caps) -> %%

There are several reasons why the default node configuration options request might fail:

%%
    -%%
  • The service does not support node configuration. -%%
  • The service does not support retrieval of default node configuration. +%%
  • The service does not support node configuration.
    • +%%
  • The service does not support retrieval of default node configuration.
    • %%
get_configure(Host, Node, From, Lang) -> Action = @@ -2460,11 +2461,11 @@ get_configure_xfields(_Type, Options, _Owners, Lang) -> %%

There are several reasons why the node configuration request might fail:

%%
    -%%
  • The service does not support node configuration. -%%
  • The requesting entity does not have sufficient privileges to configure the node. -%%
  • The request did not specify a node. -%%
  • The node has no configuration options. -%%
  • The specified node does not exist. +%%
  • The service does not support node configuration.
    • +%%
  • The requesting entity does not have sufficient privileges to configure the node.
    • +%%
  • The request did not specify a node.
    • +%%
  • The node has no configuration options.
    • +%%
  • The specified node does not exist.
    • %%
set_configure(Host, Node, From, Els, Lang) -> case xml:remove_cdata(Els) of diff --git a/src/mod_pubsub/node_default.erl b/src/mod_pubsub/node_default.erl index 2c0c044cb..fc4194c32 100644 --- a/src/mod_pubsub/node_default.erl +++ b/src/mod_pubsub/node_default.erl @@ -79,9 +79,9 @@ %% API definition %% ================ -%% @spec (Host) -> any() +%% @spec (Host, ServerHost, Opts) -> any() %% Host = mod_pubsub:host() -%% ServerHost = host() +%% ServerHost = mod_pubsub:host() %% Opts = list() %% @doc

Called during pubsub modules initialisation. Any pubsub plugin must %% implement this function. It can return anything.

@@ -109,8 +109,9 @@ init(_Host, _ServerHost, _Opts) -> end, ok. -%% @spec (Host) -> any() +%% @spec (Host, ServerHost) -> any() %% Host = mod_pubsub:host() +%% ServerHost = host() %% @doc

Called during pubsub modules termination. Any pubsub plugin must %% implement this function. It can return anything.

terminate(_Host, _ServerHost) -> @@ -172,10 +173,11 @@ features() -> "subscription-notifications" ]. -%% @spec (Host, Node, Owner, Access) -> bool() +%% @spec (Host, ServerHost, Node, ParentNode, Owner, Access) -> bool() %% Host = mod_pubsub:host() %% ServerHost = mod_pubsub:host() %% Node = mod_pubsub:pubsubNode() +%% ParentNode = mod_pubsub:pubsubNode() %% Owner = mod_pubsub:jid() %% Access = all | atom() %% @doc Checks if the current user has the permission to create the requested node @@ -246,7 +248,7 @@ delete_node(Host, Removed) -> end, Removed), {result, {default, broadcast, Removed}}. -%% @spec (Host, Node, Sender, Subscriber, AccessModel, SendLast) -> +%% @spec (Host, Node, Sender, Subscriber, AccessModel, SendLast, PresenceSubscription, RosterGroup) -> %% {error, Reason} | {result, Result} %% @doc

Accepts or rejects subcription requests on a PubSub node.

%%

The mechanism works as follow: @@ -531,7 +533,12 @@ delete_item(Host, Node, Publisher, ItemId) -> end end. -%% @spec (TODO) +%% @spec (Host, Node, Owner) -> +%% {error, Reason::stanzaError()} | +%% {result, {default, broadcast}} +%% Host = mod_pubsub:host() +%% Node = mod_pubsub:pubsubNode() +%% Owner = mod_pubsub:jid() purge_node(Host, Node, Owner) -> OwnerKey = jlib:jid_tolower(jlib:jid_remove_resource(Owner)), case get_state(Host, Node, OwnerKey) of @@ -597,9 +604,10 @@ set_affiliation(Host, Node, Owner, Affiliation) -> set_state(Record), ok. -%% @spec (Host) -> [{Node,Subscription}] +%% @spec (Host, Owner) -> [{Node,Subscription}] %% Host = host() -%% JID = mod_pubsub:jid() +%% Owner = mod_pubsub:jid() +%% Node = mod_pubsub:pubsubNode() %% @doc

Return the current subscriptions for the given user

%%

The default module reads subscriptions in the main Mnesia %% pubsub_state table. If a plugin stores its data in the same @@ -679,7 +687,7 @@ get_state(Host, Node, JID) -> {error, ?ERR_ITEM_NOT_FOUND} end. -%% @spec (State) -> ok | {error, ?ERR_INTERNAL_SERVER_ERROR} +%% @spec (State) -> ok | {error, Reason::stanzaError()} %% State = mod_pubsub:pubsubStates() %% @doc

Write a state into database.

set_state(State) when is_record(State, pubsub_state) -> @@ -720,7 +728,7 @@ get_item(Host, Node, ItemId) -> {error, ?ERR_ITEM_NOT_FOUND} end. -%% @spec (Item) -> ok | {error, ?ERR_INTERNAL_SERVER_ERROR} +%% @spec (Item) -> ok | {error, Reason::stanzaError()} %% Item = mod_pubsub:pubsubItems() %% @doc

Write a state into database.

set_item(Item) when is_record(Item, pubsub_item) -> diff --git a/src/mod_pubsub/nodetree_default.erl b/src/mod_pubsub/nodetree_default.erl index 80eeefb31..0a36e3362 100644 --- a/src/mod_pubsub/nodetree_default.erl +++ b/src/mod_pubsub/nodetree_default.erl @@ -58,7 +58,7 @@ %% API definition %% ================ -%% @spec (Host) -> any() +%% @spec (Host, ServerHost, Opts) -> any() %% Host = mod_pubsub:host() %% ServerHost = host() %% Opts = list() diff --git a/src/mod_pubsub/nodetree_virtual.erl b/src/mod_pubsub/nodetree_virtual.erl index c931a1b4f..5ce256140 100644 --- a/src/mod_pubsub/nodetree_virtual.erl +++ b/src/mod_pubsub/nodetree_virtual.erl @@ -55,7 +55,7 @@ %% API definition %% ================ -%% @spec (Host) -> any() +%% @spec (Host, ServerHost, Opts) -> any() %% Host = mod_pubsub:host() %% ServerHost = host() %% Opts = list() diff --git a/src/mod_pubsub/pubsub.hrl b/src/mod_pubsub/pubsub.hrl index f2ecd6eeb..25f60c36d 100644 --- a/src/mod_pubsub/pubsub.hrl +++ b/src/mod_pubsub/pubsub.hrl @@ -16,7 +16,7 @@ %%% This software is copyright 2006-2008, Process-one. %%% %%% -%%% @copyright 2006-2008 Process-one +%%% copyright 2006-2008 Process-one %%% %%% This file contains pubsub types definition. %%% ==================================================================== @@ -122,7 +122,7 @@ %% @type pubsubPresence() = #pubsub_presence{ %% key = {Host::host(), User::string(), Server::string()}, -%% presence = list(). +%% presence = list()}. %%%

This is the format of the published presence table. The type of the %%% table is: set,ram.

-record(pubsub_presence, {key,