Class jabberwerx.PrivacyList

Extends jabberwerx.JWModel.

Representation of a XEP-0016 privacy list. This class manages a privacy list to block (or removing blocking of) specific JIDs. It does not provide for any other allow/deny logic from XEP-0016.

Class Summary
Constructor Attributes	Constructor Name and Description
	jabberwerx.PrivacyList(listNode, ctrl) Creates a new PrivacyList with the given <list/> and PrivacyListController.

Field Summary
Field Attributes	Field Name and Description
<static>	jabberwerx.PrivacyList.ALL Instruct PrivacyList to add no children to 'item' element.
<static>	jabberwerx.PrivacyList.IQ Instruct PrivacyList to block 'iq' stanzas.
<static>	jabberwerx.PrivacyList.MESSAGE Instruct PrivacyList to block 'message' stanzas.
<static>	jabberwerx.PrivacyList.PRESENCE_IN Instruct PrivacyList to block 'presence' stanzas coming in.
<static>	jabberwerx.PrivacyList.PRESENCE_OUT Instruct PrivacyList to block 'presence' stanzas going out.

Method Summary
Method Attributes	Method Name and Description
	blockJid(jid, stanzas) Block the given JID.
	destroy() Destroys this privacy list.
	getBlockedJids() Retrieves the list of blocked JIDs.
	getBlockedStanzas(jid) Retrieve the list of stanzas blocked for the specified JID.
	getName() Retreives the name of this privacy list.
	remove(cb) Removes the list from the server.
	unblockJid(jid) Unblock the given JID.
	update(cb) Updates the server with this privacy list's current state.
	wasUnserialized() Called just after this object is unserialized.
	willBeSerialized() Called just prior to this object being serialized.

Methods borrowed from class jabberwerx.JWModel:: applyEvent, event, shouldBeSavedWithGraph
Methods borrowed from class jabberwerx.JWBase:: getClassName, graphUnserialized, init, invocation, shouldBeSerializedInline, toString

Class Detail

jabberwerx.PrivacyList(listNode, ctrl)

Creates a new PrivacyList with the given <list/> and PrivacyListController.

NOTE: This type should not be created directly. Instead use jabberwerx.PrivacyListController#fetch.

Parameters:
{Element} listNode: The element representing the list
{jabberwerx.PrivacyListController} ctrl: The owning controller

Throws:
{TypeError}: If {listNode} is not a <list/> element; or if {ctrl} is not a PrivacyListController

See:: XEP-0016: Privacy Lists

Field Detail

<static> jabberwerx.PrivacyList.ALL

Instruct PrivacyList to add no children to 'item' element. This blocks all of the stanzas.

<static> jabberwerx.PrivacyList.IQ

Instruct PrivacyList to block 'iq' stanzas.

<static> jabberwerx.PrivacyList.MESSAGE

Instruct PrivacyList to block 'message' stanzas.

<static> jabberwerx.PrivacyList.PRESENCE_IN

Instruct PrivacyList to block 'presence' stanzas coming in.

<static> jabberwerx.PrivacyList.PRESENCE_OUT

Instruct PrivacyList to block 'presence' stanzas going out.

Method Detail

blockJid(jid, stanzas)

Block the given JID. This method adds an item to the privacy list with type is "jid", action is "deny", and value is {jid}.

NOTE: this method does not update the server. Call #update to commit changes to this privacy list.

Parameters:

{String|jabberwerx.JID} jid

The JID to block

{String[]} stanzas Optional

The list of stanzas to block. All stanzas will be blocked if this parameter is NULL or undefined.

The possible values in this list are:

Throws:
{jabberwerx.JID.InvalidJIDError}: If {jid} is not valid
{TypeError}: If {stanzas} is defined and not an array.
{TypeError}: If an item in {stanzas} is not one of the constants defined below (i.e. jabberwerx.PrivacyList.MESSAGE).

destroy()

Destroys this privacy list. This method removes any event callbacks it registered.

{jabberwerx.JID[]} getBlockedJids()

Retrieves the list of blocked JIDs. The returned list is a snapshot of the JIDs marked as blocked at the time this method is called.

Returns:: {jabberwerx.JID[]} The list of blocked JIDs

{String[]} getBlockedStanzas(jid)

Retrieve the list of stanzas blocked for the specified JID. The possible values in the returned list are:

Parameters:
{String|jabberwerx.JID} jid: The JID for which we're searching.

Throws:
{jabberwerx.JID.InvalidJIDError}: If {jid} is not valid

Returns:: {String[]} The list of stanzas being blocked.

{String} getName()

Retreives the name of this privacy list.

Returns:: {String} The list name

remove(cb)

Removes the list from the server. This method also calls #destroy on this PrivacyList object.

If a callback is provided, it's signature is expected to match following:

 function callback(err) {
     this;       // this PrivacyList object
     err;        // the <error/> element, or undefined if
                 // successful
 }

Parameters:
{Function} cb Optional: The callback

Throws:
{TypeError}: If {cb} is not undefined and not a function

unblockJid(jid)

Unblock the given JID. This method removes an item from the privacy list where the type is "jid", action is "deny", and value is equal to {jid}.

NOTE: this method does not update the server. Call #update to commit changes to this privacy list.

Parameters:
{String|jabberwerx.JID} jid: The JID to unblock

Throws:
{jabberwerx.JID.InvalidJIDError}: If {jid} is not valid

update(cb)

Updates the server with this privacy list's current state. This method sends the current list to the server. It first sends <presence type='unavailable'/> to each newly blocked JID, and resends the last <presence/> update if any JIDs were unblocked.

This method will ultimately trigger the "privacyListUpdated" event if successful, or "errorEncountered" event if the update failed.

The value of {cb} is either "undefined" or a function matching the following:

 function callback(err) {
     this;   // this jabberwerx.PrivacyList
     err;    // undefined if the update succeeded, or
             // the <error/> element if update failed
 }

Parameters:
{Function} cb Optional: The callback to execute when updated

Throws:
{TypeError}: If {cb} is not undefined and not a function

wasUnserialized()

Called just after this object is unserialized. This method unserializes the underlying <list/> element into its DOM representation.

willBeSerialized()

Called just prior to this object being serialized. This method serializes the underlying <list/> element into its XML representation.

Classes

Class jabberwerx.PrivacyList