Class jabberwerx.MUCController

Extends jabberwerx.Controller.
Controller for working with Multi-User Chat (MUC).

Class Summary
Constructor Attributes	Constructor Name and Description
	jabberwerx.MUCController(client) Creates a new instance of MUCController with the given client.

Field Summary
Field Attributes	Field Name and Description
	escapeSearch Indicates if a muc room search value should be escaped before passing it to the server as part of a muc room iq:search query.

Fields borrowed from class jabberwerx.Controller:: client, name

Method Summary
Method Attributes	Method Name and Description
	cleanupEntity(entity) Cleanup given room on behalf of the client entity cache jabberwerx.EntitySet.
	destroy() Destroys this instance of MUCController.
	removeEntity(entity) Removes the given entity.
	room(jid) Retreives or creates a MUCRoom for the given JID.
	startSearch(muc, callback) Starts the process of searching for a room.
	submitSearch(muc, form, callback) Submits the filled-out search criteria to the MUC server.
	updateEntity(entity) Updates the given entity.

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

Class Detail

jabberwerx.MUCController(client)

Creates a new instance of MUCController with the given client. This method registers the newly created MUCController under the client's controllers as "muc" (e.g. access via client.controllers["muc"])

This class provides the following events:

jabberwerx.MUCContoller Events

Parameters:
{jabberwerx.Client} client: The client object to use for communicating to the server

Throws:
{TypeError}: If {client} is not an instance of jabberwerx.Client

Field Detail

{Boolean} escapeSearch

Indicates if a muc room search value should be escaped before passing it to the server as part of a muc room iq:search query.

The default value is {true}, which is to escape muc room search values

Method Detail

cleanupEntity(entity)

Cleanup given room on behalf of the client entity cache jabberwerx.EntitySet.

Parameters:
{jabberwerx.MUCRoom} entity: The entity to destroy

destroy()

Destroys this instance of MUCController.

removeEntity(entity)

Removes the given entity. This method is not called directly; instead call jabberwerx.Entity#remove.

This implementation uses the following algorithm:

If the room is currently active and the client is currently connected, exit the room (via jabberwerx.MUCRoom#exit.
Once the room is not active and/or the client is not connected, it is destroyed (via jabberwerx.Entity#destroy); this will ultimately trigger an "entityDestroyed" event for {entity}.

Parameters:
{jabberwerx.MUCRoom} entity: The entity to remove

Throws:
{TypeError}: if {entity} is not an instance of jabberwerx.MUCRoom

{jabberwerx.MUCRoom} room(jid)

Retreives or creates a MUCRoom for the given JID. This method implements the following algorithm:

If a MUCRoom already exists in the owning client for {jid}, that instance is returned.
A new MUCRoom is created for {jid}.
If there is an entity for {jid} but it is not a MUCRoom, the data from the original entity is applied to the new MUCRoom (via jabberwerx.Entity#apply), and the original entity is removed from the owning client.
The new MUCRoom is registered with the owning client (triggering an "entityCreated" event) and returned.

Parameters:
{jabberwerx.JID|String} jid: The room JID

Throws:
{jabberwerx.JID.InvalidJIDError}: if {jid} is not an instanceof jabberwerx.JID, and cannot be converted to one.

Returns:: {jabberwerx.MUCRoom} The room for {jid}

startSearch(muc, callback)

Starts the process of searching for a room. This method will return the search criteria from the MUC server through the callback.

Parameters:

{jabberwerx.JID | String} muc

The MUC server.

{Function} callback

Callback fired when a response is received or an error is encountered.

The callback has the following signature.

function callback(form, err) {
    form;    // The returned jabberwerx.XDataForm.
             // null if the method failed.
    err;     // Error explaining the failure,
             // undefined if the method succeeded.
}

Throws:
{jabberwerx.JID.InvalidJIDError}: if {muc} is not an instance of jabberwerx.JID, and cannot be converted to one
{TypeError}: If callback is undefined or not a function.

submitSearch(muc, form, callback)

Submits the filled-out search criteria to the MUC server. Returns the results through the callback.

Parameters:

{jabberwerx.JID | String} muc

The MUC server.

{jabberwerx.XDataForm} form

the filled-out search criteria.

{Function} callback

Callback fired when a response is received or an error is encountered.

The callback has the following signature.

function callback(form, err) {
    form;    // The returned jabberwerx.XDataForm.
             // null if the method failed.
    err;     // Error explaining the failure,
             // undefined if the method succeeded.
}

Throws:
{jabberwerx.JID.InvalidJIDError}: if {muc} is not an instance of jabberwerx.JID, and cannot be converted to one
{TypeError}: If callback is undefined or not a function.
{TypeError}: If form is not a jabberwerx.XDataForm.

updateEntity(entity)

Updates the given entity. This method is not called directly; instead call jabberwerx.Entity#update.

This implementation simply triggers an "entityUpdated" event with the given entity.

Parameters:
{jabberwerx.MUCRoom} entity: The entity to update

Throws:
{TypeError}: if {entity} is not an instance of jabberwerx.MUCRoom

Classes

Class jabberwerx.MUCController