Overview

Module mod_pubsub_odbc [erl svg]

• Description
• Data Types
• Function Index
• Function Details

Copyright © 2006-2012 ProcessOne

Version: 3.0.0-alpha-5, May 23 2012 07:15:13

Behaviours: gen_mod, gen_server.

Authors: Christophe Romain (christophe.romain@process-one.net) [web site: http://www.process-one.net/].

References

• See XEP-0060: Pubsub for the latest version of the PubSub specification. This module uses version 1.12 of the specification as a base. Most of the specification is implemented. Functions concerning configuration should be rewritten.

  Support for subscription-options and multi-subscribe features was added by Brian Cully (bjc AT kublai.com). Subscriptions and options are stored in the pubsub_subscription table, with a link to them provided by the subscriptions field of pubsub_state. For information on subscription-options and mulit-subscribe see XEP-0060 sections 6.1.6, 6.2.3.1, 6.2.3.5, and 6.3. For information on subscription leases see XEP-0060 section 12.18.

Description

Data Types

accessModel()

accessModel() = open | presence | roster | authorize | whitelist

affiliation()

affiliation() = none | owner | publisher | 'publish-only' | member | outcast

bareUsr()

bareUsr() = {User, Server, Resource}

• User = undefined | binary()
• Server = binary()
• Resource = undefined

features()

features() = [Feature]

• Feature = string()

fullUsr()

fullUsr() = {User, Server, Resource}

• User = undefined | binary()
• Server = binary()
• Resource = undefined | binary()

host()

host() = hostPubsub() | hostPEP()

hostPEP()

hostPEP() = {User, Server, Resource}

• User = binary()
• Server = binary()
• Resource = undefined

hostPubsub()

hostPubsub() = binary()

hostPubsub is the name of the PubSub service. For example, it can be pubsub.localhost.

itemId()

itemId() = binary()

An itemId is the name of an Item. It can be anything. For example: 38964 my-tune FD6SBE6a27d

jidComponent()

jidComponent() = {jid, Raw, Node, Domain, Resource}

• Raw = binary()
• Node = undefined
• Domain = binary()
• Resource = undefined

jidContact()

jidContact() = {jid, Raw, Node, Domain, Resource}

• Raw = binary()
• Node = binary()
• Domain = binary()
• Resource = undefined

jidEntity()

jidEntity() = {jid, Raw, Node, Domain, Resource}

• Raw = binary()
• Node = undefined | binary()
• Domain = binary()
• Resource = undefined | binary()

ljid()

ljid() = {User, Server, Resource}

• User = undefined | binary()
• Server = binary()
• Resource = undefined | binary()

nodeId()

nodeId() = binary()

A nodeId 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

nodeIdx()

nodeIdx() = integer()

nodeOption()

nodeOption() = {Option, Value}

Option = atom() Value = term().

      {deliver_payloads, true}

nodeType()

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".

now()

now() = {Megaseconds, Seconds, Microseconds}

• Megaseconds = integer()
• Seconds = integer()
• Microseconds = integer()

payload()

payload() = [] | [#xmlel{}]

pubsubIQResponse()

pubsubIQResponse() = #xmlel{}

Example:

         #xmlel{name = 'pubsub',
                ns = ?NS_PUBSUB,
                children = [
                  #xmlel{name = 'affiliations'
                         ns = ?NS_PUBSUB
                  }
                ]
               }

pubsubIndex()

pubsubIndex() = {pubsub_index, Index, Last, Free}

Index = atom() Last = nodeIdx() Free = [nodeIdx()].

pubsubItem()

pubsubItem() = {pubsub_item, Id, NodeIdx, Creation, Modification, Payload}

• Id = {itemId(), nodeIdx()}
• NodeIdx = nodeIdx()
• Creation = {now(), bareUsr()}
• Modification = {now(), fullUsr()}
• Payload = payload()

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

pubsubLastItem()

pubsubLastItem() = {pubsub_last_item, NodeId, ItemId, Creation, Payload}

• NodeId = nodeIdx()
• ItemId = itemId()
• Creation = {now(), bareUsr()}
• Payload = payload()

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

pubsubNode()

pubsubNode() = {pubsub_node, Id, Idx, Parents, Type, Owners, Options}

• Id = {host(), nodeId()}
• Idx = nodeIdx()
• Parents = [nodeId()]
• Type = nodeType()
• Owners = [bareUsr()]
• 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.

idx is an integer.

pubsubState()

pubsubState() = {pubsub_state, Id, NodeIdx, Items, Affiliation, Subscriptions}

• Id = {fullUsr(), nodeIdx()}
• NodeIdx = 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.

pubsubSubscription()

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.

stanzaError()

stanzaError() = #xmlel{}

Example:

         #xmlel{name = 'error'
                ns = ?NS_STANZAS,
                attrs = [
                  #xmlattr{
                    name = 'code',
                    ns = ?NS_STANZAS,
                    value = Code
                  },
                attrs = [
                  #xmlattr{
                    name = 'type',
                    ns = ?NS_STANZAS,
                    value = Type
                  }
                ]}

subId()

subId() = binary()

subOption()

subOption() = {Option, Value}

Option = atom() Value = term().

subscription()

subscription() = none | pending | unconfigured | subscribed

Function Index

Function Details

add_extended_headers/2 *

add_headers/4 *

add_message_type/2 *

add_opt/3 *

add_shim_headers/2 *

adhoc_request/6 *

Processes an Ad Hoc Command.

affiliation_to_string/1

Convert an affiliation type from atom to string.

broadcast/7 *

broadcast/8 *

broadcast/9 *

broadcast_config_notification/6 *

broadcast_created_node/5 *

broadcast_publish_item/9 *

broadcast_purge_node/5 *

broadcast_removed_node/5 *

broadcast_retract_items/6 *

broadcast_retract_items/7 *

caps_update/3

code_change/3

collection_shim/1 *

command_disco_info/3 *

create_node/5

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.

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

create_node/7 *

delete_item/4

Delete item from a PubSub node.

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.

delete_item/5 *

delete_node/3

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.

disco_features/3 *

disco_identity/3 *

disco_items/3 *

disco_local_features/5

disco_local_identity/5

disco_local_items/5

disco_sm_features/5

disco_sm_identity/5

disco_sm_items/5

do_route/7 *

escape/1

event_stanza/1 *

Build pubsub event stanza

event_stanza/2 *

event_stanza/3 *

event_stanza/5 *

event_stanza/6 *

event_stanza_with_delay/3 *

event_stanza_withmoreels/2 *

extended_error/2

extended_error/3

extended_headers/1 *

features/0 *

features/1 *

features/2 *

find_authorization_response/1 *

get_affiliations/3 *

Return the list of affiliations as an XMPP response.

get_allowed_items_call/6 *

get_allowed_items_call/7 *

get_cached_item/2

get_configure/5

get_configure_xfields/4 *

get_default/4 *

get_item/3

get_items/2

get_items/7 *

Return the items of a given node.

The number of items to return is limited by MaxItems.

The permission are not checked in this function.

To do

• We probably need to check that the user doing the query has the right to read the items.

get_max_items_node/1 *

get_option/2 *

get_option/3 *

get_options/5 *

get_options_helper/6 *

get_pending_nodes/3 *

get_presence_and_roster_permissions/5 *

get_resource_state/3 *

get_roster_info/4 *

get_subscriptions/3 *

get_subscriptions/4 *

Return the list of subscriptions as an XMPP response.

handle_authorization_response/5 *

handle_call/3

handle_cast/2

handle_info/2

host/1 *

in_subscription/6

init/1

init_nodes/4 *

init_plugins/3 *

Call the init/1 function for each plugin declared in the config file. The default plugin module is implicit.

The Erlang code for the plugin is located in a module called node_plugin. The 'node_' prefix is mandatory.

The modules are initialized in alphetical order and the list is checked and sorted to ensure that each module is initialized only once.

See node_flat:init/1 for an example implementation.

init_send_loop/2 *

iq_command/6 *

iq_disco_info/4 *

iq_disco_items/4 *

iq_get_vcard/1 *

iq_pubsub/6 *

iq_pubsub/8 *

iq_pubsub_owner/6 *

iq_sm/3

is_last_item_cache_enabled/1 *

is_to_deliver/5 *

Check if a notification must be delivered or not based on node and subscription options.

itemAttr/1 *

itemsEls/1 *

max_items/2 *

Return the maximum number of items for a given node.

Unlimited means that there is no limit in the number of items that can be stored.

To do

• In practice, the current data structure means that we cannot manage millions of items on a given node. This should be addressed in a new version.

nodeAttr/1 *

node_action/4

node_call/3 *

node plugin call.

node_disco_info/3 *

node_options/1 *

node_owners/3 *

Return list of node owners.

node_owners_call/2 *

node_subscriptions/6 *

node_subscriptions_bare/4 *

node_subscriptions_full/3 *

node_to_deliver/2 *

node_to_string/1

Convert a node type from pubsubNode to string.

notify_owners/6 *

odbc_conn/1 *

on_user_offline/3

out_subscription/4

payload_els_ns/1 *

Count occurence of XML elements in payload.

payload_els_ns/3 *

plugins/1 *

presence/2 *

presence_can_deliver/2 *

presence_probe/3

publish_item/6

Publish item to a PubSub node.

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.

purge_node/3 *

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.

purge_offline/1 *

read_sub/5 *

remove_user/2

select_type/3 *

select_type/4 *

send_authorization_approval/4 *

Send a message to JID with the supplied Subscription

send_authorization_request/2 *

send_items/6

Resend the items of a node to the user.

To do

• use cache-last-item feature

send_loop/1

send_pending_auth_events/3 *

Send a subscription approval form to Owner for all pending subscriptions on Host and Node.

send_pending_node_form/4 *

Sends the process pending subscriptions XForm for Host to Owner.

service_jid/1 *

Generate pubsub service JID.

set_affiliations/4 *

set_cached_item/5 *

set_configure/5

set_options/5 *

set_options_helper/5 *

set_subscriptions/4 *

set_xoption/3 *

start/2

start_link/2

state_can_deliver/2 *

stop/1

string_to_affiliation/1

Convert an affiliation type from string to atom.

string_to_node/1

string_to_subscription/1

Convert a subscription type from string to atom.

sub_option_can_deliver/3 *

sub_to_deliver/4 *

sub_with_options/1 *

sub_with_options/3 *

subid_shim/1 *

subscribe_node/5

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.

See also: node_flat:subscribe_node/5.

subscribed_nodes_by_jid/2 *

subscription_to_string/1

Convert a subscription type from atom to string.

terminate/2

terminate_plugins/4 *

transaction/3 *

transaction/4 *

plugin transaction handling.

transaction_on_nodes/3 *

transaction_retry/4 *

tree_action/3

tree_call/3 *

node tree plugin call.

uniqid/0 *

unset_cached_item/2 *

unsubscribe_node/5

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.

unsubscribe_user/2 *

update_auth/7 *

user_resource/3 *

user_resources/2 *

write_sub/4 *

Overview

Generated by EDoc, May 23 2012, 07:15:13.