ipworks
Class Xmpp

java.lang.Object
  |
  +--ipworks.Xmpp

public class Xmpp

extends java.lang.Object

The XMPP bean is used to create a lightweight messaging client using the XMPP (Jabber) protocol.

A call to the Connect method will perform the entire logon process after which a Connected event will fire indicating connection status. For simplicity, the entire interface is synchronous: the bean will not return until a call is completed.

After a successful connection, the bean will automatically begin the process of receiving the user's buddy list. The bean will parse the XML as it comes in from the server and will set the appropriate properties. Once the entire buddy list has been retrieved, a Sync event will fire.

Sending a message is as simple as calling a single method. One call to the SendMessage method will cause the bean to connect if it has not already done so, send the specified message to a specified user, and return to the original connection state.

The XMPP bean interface supports messaging, list and presence management. Other features of the XMPP protocol are supported through the SendCommand method and PITrail event.

Example (Connecting and Sending a Message)

 IMControl.Connect("myusername", "mypassword")
 IMControl.MessageText = "My Message"
 IMControl.SendMessage("ToUser") 

Example (Sending a Single Message)

 IMControl.User = "myusername"
 IMControl.Password = "mypassword"
 IMControl.MessageText = "My Message"
 IMControl.SendMessage("ToUser") 

Field Summary

static int	mtChat
static int	mtError
static int	mtGroupChat
static int	mtHeadline
static int	mtNormal
static int	pcAway
static int	pcChat
static int	pcDND
static int	pcOffline
static int	pcXA

Constructor Summary

Xmpp()

Method Summary

void	add(java.lang.String jabberId, java.lang.String name, java.lang.String groups) This method will add an entity to this entity's roster.
void	addXmppEventListener(ipworks.XmppEventListener l)
void	cancel(java.lang.String jabberId) This will cancel another entity's subscription to this entity's presence.
void	changePassword(java.lang.String password) This method will change the current user's password.
void	changePresence(int presenceCode, java.lang.String status) This method will set the availability and status of this entity.
java.lang.String	config(java.lang.String configurationString) Sets or retrieves a beanconfiguration setting.
void	connect(java.lang.String user, java.lang.String password) This method will connect the bean to the server.
void	disconnect() This method disconnects the bean from the server.
void	doEvents() This method processes events from the internal message queue.
java.lang.String	getAuthDomain() The domain under which the user will be authenticated.
java.lang.String	getAuthMethods() Controls how the bean authenticates itself with the XMPP server.
XMPPBuddyList	getBuddies() Collection of buddies in the buddy list.
ipworks.Firewall	getFirewall() A set of properties related to firewall access.
int	getIMPort() The server port for XMPP (default 5222).
java.lang.String	getIMServer() This is the instant messaging server.
java.lang.String	getMessageHTML() This is the HTML version of the current message.
java.lang.String	getMessageOtherData() This properties contains extra data elements for the current message.
java.lang.String	getMessageSubject() This is the subject of the current message.
java.lang.String	getMessageText() This is the plain text of the current message.
java.lang.String	getMessageThread() This is the thread name of the current message.
int	getMessageType() This is the type of the current message.
java.lang.String	getPassword() This is the user's password.
int	getPresence() This is the availability of the this entity.
java.lang.String	getResource() This is the resource for the current session.
java.lang.String	getServerDomain() The XMPP server's domain.
java.lang.String	getStatus() Description of the availability of this entity.
int	getTimeout() A timeout for the bean.
java.lang.String	getUser() The user portion of this entity's Jabber ID.
java.lang.String	getUserDomain() Gets or sets the domain value used for Jabber IDs
XMPPUserInfoList	getUserInfo() Collection of named registration fields.
void	interrupt() Interrupt the current method.
boolean	isConnected() This indicates the bean's login status.
void	probePresence(java.lang.String jabberId) Use this method to probe for another entity's presence.
void	queryRegister(java.lang.String XMPPServer) This method queries a server for the necessary registration fields.
void	register(java.lang.String XMPPServer) This method registers an account with a server.
void	remove(java.lang.String jabberId, java.lang.String name, java.lang.String group) This method will remove an entity from this entity's roster.
void	removeXmppEventListener(ipworks.XmppEventListener l)
void	retrieveRoster() This method will retreive this entity's roster from the server.
void	sendCommand(java.lang.String command) This method sends a command to the server.
java.lang.String	sendMessage(java.lang.String jabberId) This method will send a message to the specified user.
void	setAuthDomain(java.lang.String authDomain) The domain under which the user will be authenticated.
void	setAuthMethods(java.lang.String authMethods) Controls how the bean authenticates itself with the XMPP server.
void	setConnected(boolean connected) This indicates the bean's login status.
void	setFirewall(ipworks.Firewall firewall) A set of properties related to firewall access.
void	setIMPort(int IMPort) The server port for XMPP (default 5222).
void	setIMServer(java.lang.String IMServer) This is the instant messaging server.
void	setMessageHTML(java.lang.String messageHTML) This is the HTML version of the current message.
void	setMessageOtherData(java.lang.String messageOtherData) This properties contains extra data elements for the current message.
void	setMessageSubject(java.lang.String messageSubject) This is the subject of the current message.
void	setMessageText(java.lang.String messageText) This is the plain text of the current message.
void	setMessageThread(java.lang.String messageThread) This is the thread name of the current message.
void	setMessageType(int messageType) This is the type of the current message.
void	setPassword(java.lang.String password) This is the user's password.
void	setPresence(int presence) This is the availability of the this entity.
void	setResource(java.lang.String resource) This is the resource for the current session.
void	setServerDomain(java.lang.String serverDomain) The XMPP server's domain.
void	setStatus(java.lang.String status) Description of the availability of this entity.
void	setTimeout(int timeout) A timeout for the bean.
void	setUser(java.lang.String user) The user portion of this entity's Jabber ID.
void	setUserDomain(java.lang.String userDomain) Gets or sets the domain value used for Jabber IDs
void	setUserInfo(XMPPUserInfoList userInfo) Collection of named registration fields.
void	setUserInfoField(java.lang.String field, java.lang.String value) This method will add a user information field for registration.
void	subscribeTo(java.lang.String jabberId) Use this method to subscribe to another entity's presence.
void	unregister() This method cancels an account with the host.
void	unsubscribeTo(java.lang.String jabberId) This method cancels an account with the host.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mtNormal

public static final int mtNormal

See Also:

Constant Field Values

mtChat

public static final int mtChat

See Also:

Constant Field Values

mtGroupChat

public static final int mtGroupChat

See Also:

Constant Field Values

mtHeadline

public static final int mtHeadline

See Also:

Constant Field Values

mtError

public static final int mtError

See Also:

Constant Field Values

pcOffline

public static final int pcOffline

See Also:

Constant Field Values

pcChat

public static final int pcChat

See Also:

Constant Field Values

pcAway

public static final int pcAway

See Also:

Constant Field Values

pcXA

public static final int pcXA

See Also:

Constant Field Values

pcDND

public static final int pcDND

See Also:

Constant Field Values

Constructor Detail

Xmpp

public Xmpp()

Method Detail

getAuthDomain

public java.lang.String getAuthDomain()

The domain under which the user will be authenticated.

Set this value if the user must authenticate via a third party authentication service that requires a different domain than the XMPP user's registered domain.

setAuthDomain

public void setAuthDomain(java.lang.String authDomain)
                   throws IPWorksException

The domain under which the user will be authenticated.

Set this value if the user must authenticate via a third party authentication service that requires a different domain than the XMPP user's registered domain.

IPWorksException

getAuthMethods

public java.lang.String getAuthMethods()

Controls how the bean authenticates itself with the XMPP server.

AuthMethods is a comma-separated list of authentication methods to be enabled on the bean, listed in order of preference. When authenticating, the bean will pick the first method in the list that is supported by the server.

The special value * (default) may be supplied to cause the bean to enable all supported authentication methods in order of presumed security. The XMPP bean currently supports the following values for AuthMethods , listed in order of most secure to least secure:

• SASL/DIGEST-MD5
• AuthIQ/Digest
• SASL/PLAIN
• AuthIQ/Plaintext

setAuthMethods

public void setAuthMethods(java.lang.String authMethods)
                    throws IPWorksException

Controls how the bean authenticates itself with the XMPP server.

AuthMethods is a comma-separated list of authentication methods to be enabled on the bean, listed in order of preference. When authenticating, the bean will pick the first method in the list that is supported by the server.

The special value * (default) may be supplied to cause the bean to enable all supported authentication methods in order of presumed security. The XMPP bean currently supports the following values for AuthMethods , listed in order of most secure to least secure:

• SASL/DIGEST-MD5
• AuthIQ/Digest
• SASL/PLAIN
• AuthIQ/Plaintext

IPWorksException

getBuddies

public XMPPBuddyList getBuddies()

Collection of buddies in the buddy list.

After a Sync event is fired, this property will contain a collection of all buddies in the buddy list. The buddy list will be updated by the server when a successful call to RetrieveRoster has been made.

This collection is indexed from 0 to Count - 1.

isConnected

public boolean isConnected()

This indicates the bean's login status.

This value shows whether or not the bean has successfully logged into the IMServer . It will not be true until a successful Connected event has fired.

setConnected

public void setConnected(boolean connected)
                  throws IPWorksException

This indicates the bean's login status.

This value shows whether or not the bean has successfully logged into the IMServer . It will not be true until a successful Connected event has fired.

IPWorksException

getFirewall

public ipworks.Firewall getFirewall()

A set of properties related to firewall access.

This is a FIREWALL type property which contains fields describing the firewall through which the bean will attempt to connect.

setFirewall

public void setFirewall(ipworks.Firewall firewall)
                 throws IPWorksException

A set of properties related to firewall access.

This is a FIREWALL type property which contains fields describing the firewall through which the bean will attempt to connect.

IPWorksException

getIMPort

public int getIMPort()

The server port for XMPP (default 5222).

A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.

setIMPort

public void setIMPort(int IMPort)
               throws IPWorksException

The server port for XMPP (default 5222).

A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.

IPWorksException

getIMServer

public java.lang.String getIMServer()

This is the instant messaging server.

This is the instant messaging server to which the bean will connect when the Connect method is called. The IMServer property must contain a valid XMPP (Jabber) server, or any subsequent calls to the Connect method will fail.

setIMServer

public void setIMServer(java.lang.String IMServer)
                 throws IPWorksException

This is the instant messaging server.

This is the instant messaging server to which the bean will connect when the Connect method is called. The IMServer property must contain a valid XMPP (Jabber) server, or any subsequent calls to the Connect method will fail.

IPWorksException

getMessageHTML

public java.lang.String getMessageHTML()

This is the HTML version of the current message.

If the user wishes to send any HTML as a part of the message, it must be set in the MessageHTML property. The HTML must be an entire HTML document, including the <html> and <body> tags. If the HTML has unbalanced tags, the XMPP bean will fail with an error.

setMessageHTML

public void setMessageHTML(java.lang.String messageHTML)
                    throws IPWorksException

This is the HTML version of the current message.

If the user wishes to send any HTML as a part of the message, it must be set in the MessageHTML property. The HTML must be an entire HTML document, including the <html> and <body> tags. If the HTML has unbalanced tags, the XMPP bean will fail with an error.

IPWorksException

getMessageOtherData

public java.lang.String getMessageOtherData()

This properties contains extra data elements for the current message.

MessageOtherData will contain zero or more complete XML elements associated with the message, but which are not defined in the Jabber specification.

setMessageOtherData

public void setMessageOtherData(java.lang.String messageOtherData)
                         throws IPWorksException

This properties contains extra data elements for the current message.

MessageOtherData will contain zero or more complete XML elements associated with the message, but which are not defined in the Jabber specification.

IPWorksException

getMessageSubject

public java.lang.String getMessageSubject()

This is the subject of the current message.

MessageSubject will contain any subject associated with the message. Most Jabber clients will ignore the subject unless the message is of type "headline".

setMessageSubject

public void setMessageSubject(java.lang.String messageSubject)
                       throws IPWorksException

This is the subject of the current message.

MessageSubject will contain any subject associated with the message. Most Jabber clients will ignore the subject unless the message is of type "headline".

IPWorksException

getMessageText

public java.lang.String getMessageText()

This is the plain text of the current message.

MessageText is the plain text version of the current message, taken from the message's "body" child element. The text in this property is automatically escaped to ensure valid XML parsing on the other end.

setMessageText

public void setMessageText(java.lang.String messageText)
                    throws IPWorksException

This is the plain text of the current message.

MessageText is the plain text version of the current message, taken from the message's "body" child element. The text in this property is automatically escaped to ensure valid XML parsing on the other end.

IPWorksException

getMessageThread

public java.lang.String getMessageThread()

This is the thread name of the current message.

MessageThread will contain the name of the thread associated with the message. Threads are usefull for tracking messages of type "chat" or "groupchat".

setMessageThread

public void setMessageThread(java.lang.String messageThread)
                      throws IPWorksException

This is the thread name of the current message.

MessageThread will contain the name of the thread associated with the message. Threads are usefull for tracking messages of type "chat" or "groupchat".

IPWorksException

getMessageType

public int getMessageType()

This is the type of the current message.

MessageType is the type of the message as specified in the XMPP RFC. The possible values are defined in the protocol specification as follows:

normal (mtNormal - 0)

A single message.

chat (mtChat - 1)

A message sent in the context of two-way chat between two entities.

groupchat (mtGroupChat - 2)

A message sent in the context of multi-user chat among multiple entities.

headline (mtHeadline - 3)

A message that represents one of a list of items (e.g., in a news feed or information ticker).

error (mtError - 4)

A message returned to a sender specifying an error associated with a previous message sent by the sender to an intended recipient.

setMessageType

public void setMessageType(int messageType)
                    throws IPWorksException

This is the type of the current message.

MessageType is the type of the message as specified in the XMPP RFC. The possible values are defined in the protocol specification as follows:

normal (mtNormal - 0)

A single message.

chat (mtChat - 1)

A message sent in the context of two-way chat between two entities.

groupchat (mtGroupChat - 2)

A message sent in the context of multi-user chat among multiple entities.

headline (mtHeadline - 3)

A message that represents one of a list of items (e.g., in a news feed or information ticker).

error (mtError - 4)

A message returned to a sender specifying an error associated with a previous message sent by the sender to an intended recipient.

IPWorksException

getPassword

public java.lang.String getPassword()

This is the user's password.

This must be set before a connection is attempted. If a call to the Connect method is made specifying a password, the Password property will contain that password.

setPassword

public void setPassword(java.lang.String password)
                 throws IPWorksException

This is the user's password.

This must be set before a connection is attempted. If a call to the Connect method is made specifying a password, the Password property will contain that password.

IPWorksException

getPresence

public int getPresence()

This is the availability of the this entity.

When the bean completes the initial log in, it will send information telling other entities subscribed to this entity's presence that it is online. The application must provide different status and availability information as the user changes them.

The Presence property has one of four values representing general information about the user's status as defined in the Jabber protocol specification:

pcOffline (0)

Invisible: JabberId is offline.

pcChat (1)

Available: JabberId is online.

pcAway (2)

Away: JabberId is online, but the user is away from their computer.

pcXA (3)

Extended Away: JabberId is online, but the user is away from their computerfor an extended period of time.

pcDND (4)

Do not Disturb: JabberId is online, but is busy and does not wish to be disturbed.

By default, the bean sets the client presence to pcChat , meaning that the user is available. To change the initial status sent by the bean set Presence to the desired presence before calling Connect .

Note: offline is not officially supported by the XMPP specification, however some XMPP server implementations may recognize the value. Setting the client's presence state to this value may cause the server to respond with an Error .

The Status property is a pure-text string representing the user's presence information. Its value maybe be any random string, including the empty string, "".

Whenever the value in Presence or Status are changed, the bean will send that information to the server. If the application or user wishes to associate a specific status message with a new presence value, it should use the ChangePresence method. ChangePresence will update both the Presence and Status properties, and then send that information to the server.

setPresence

public void setPresence(int presence)
                 throws IPWorksException

This is the availability of the this entity.

When the bean completes the initial log in, it will send information telling other entities subscribed to this entity's presence that it is online. The application must provide different status and availability information as the user changes them.

The Presence property has one of four values representing general information about the user's status as defined in the Jabber protocol specification:

pcOffline (0)

Invisible: JabberId is offline.

pcChat (1)

Available: JabberId is online.

pcAway (2)

Away: JabberId is online, but the user is away from their computer.

pcXA (3)

Extended Away: JabberId is online, but the user is away from their computerfor an extended period of time.

pcDND (4)

Do not Disturb: JabberId is online, but is busy and does not wish to be disturbed.

By default, the bean sets the client presence to pcChat , meaning that the user is available. To change the initial status sent by the bean set Presence to the desired presence before calling Connect .

Note: offline is not officially supported by the XMPP specification, however some XMPP server implementations may recognize the value. Setting the client's presence state to this value may cause the server to respond with an Error .

The Status property is a pure-text string representing the user's presence information. Its value maybe be any random string, including the empty string, "".

Whenever the value in Presence or Status are changed, the bean will send that information to the server. If the application or user wishes to associate a specific status message with a new presence value, it should use the ChangePresence method. ChangePresence will update both the Presence and Status properties, and then send that information to the server.

IPWorksException

getResource

public java.lang.String getResource()

This is the resource for the current session.

Whenever an entity logs in to an XMPP (Jabber) server, it must provide account information as well as a resource. Resources allow multiple clients to log in using the same account. The server will forward all messages and PI data aimed at a specific resource to that resource. If a command or message is to be sent to a Jabber ID with no specified resource, the server will push that command or message out to all connected resources.

setResource

public void setResource(java.lang.String resource)
                 throws IPWorksException

This is the resource for the current session.

Whenever an entity logs in to an XMPP (Jabber) server, it must provide account information as well as a resource. Resources allow multiple clients to log in using the same account. The server will forward all messages and PI data aimed at a specific resource to that resource. If a command or message is to be sent to a Jabber ID with no specified resource, the server will push that command or message out to all connected resources.

IPWorksException

getServerDomain

public java.lang.String getServerDomain()

The XMPP server's domain.

The domain of the XMPP server itself. Set this value if the domain of the server is different from the DNS name of the IMServer .

setServerDomain

public void setServerDomain(java.lang.String serverDomain)
                     throws IPWorksException

The XMPP server's domain.

The domain of the XMPP server itself. Set this value if the domain of the server is different from the DNS name of the IMServer .

IPWorksException

getStatus

public java.lang.String getStatus()

Description of the availability of this entity.

When the bean completes the initial log in, it will send information telling other entities subscribed to this entity's presence that it is online. The application must provide different status and availability information as the user changes them.

The Presence property has one of four values representing general information about the user's status as defined in the Jabber protocol specification:

pcOffline (0)

Invisible: JabberId is offline.

pcChat (1)

Available: JabberId is online.

pcAway (2)

Away: JabberId is online, but the user is away from their computer.

pcXA (3)

Extended Away: JabberId is online, but the user is away from their computerfor an extended period of time.

pcDND (4)

Do not Disturb: JabberId is online, but is busy and does not wish to be disturbed.

By default, the bean sets the client presence to pcChat , meaning that the user is available. To change the initial status sent by the bean set Presence to the desired presence before calling Connect .

Note: offline is not officially supported by the XMPP specification, however some XMPP server implementations may recognize the value. Setting the client's presence state to this value may cause the server to respond with an Error .

The Status property is a pure-text string representing the user's presence information. Its value maybe be any random string, including the empty string, "".

Whenever the value in Presence or Status are changed, the bean will send that information to the server. If the application or user wishes to associate a specific status message with a new presence value, it should use the ChangePresence method. ChangePresence will update both the Presence and Status properties, and then send that information to the server.

setStatus

public void setStatus(java.lang.String status)
               throws IPWorksException

Description of the availability of this entity.

When the bean completes the initial log in, it will send information telling other entities subscribed to this entity's presence that it is online. The application must provide different status and availability information as the user changes them.

The Presence property has one of four values representing general information about the user's status as defined in the Jabber protocol specification:

pcOffline (0)

Invisible: JabberId is offline.

pcChat (1)

Available: JabberId is online.

pcAway (2)

Away: JabberId is online, but the user is away from their computer.

pcXA (3)

Extended Away: JabberId is online, but the user is away from their computerfor an extended period of time.

pcDND (4)

Do not Disturb: JabberId is online, but is busy and does not wish to be disturbed.

By default, the bean sets the client presence to pcChat , meaning that the user is available. To change the initial status sent by the bean set Presence to the desired presence before calling Connect .

Note: offline is not officially supported by the XMPP specification, however some XMPP server implementations may recognize the value. Setting the client's presence state to this value may cause the server to respond with an Error .

The Status property is a pure-text string representing the user's presence information. Its value maybe be any random string, including the empty string, "".

Whenever the value in Presence or Status are changed, the bean will send that information to the server. If the application or user wishes to associate a specific status message with a new presence value, it should use the ChangePresence method. ChangePresence will update both the Presence and Status properties, and then send that information to the server.

IPWorksException

getTimeout

public int getTimeout()

A timeout for the bean.

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion, or an error condition is encountered.

If Timeout is set to a positive value, the bean will wait for the operation to complete before returning control.

The bean will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the bean throws an IPWorksException raises an IPWorksException exception .

Please note that by default, all timeouts are inactivity timeouts , i.e. the timeout period is extended by Timeout seconds when data is successfully sent or received.

Optionally, the behaviour of the bean may be changed to absolute timeouts , i.e. the bean will wait for a maximum of Timeout seconds since the beginning of the operation, without extending the timeout period during communications.

This behavior is controlled by theAbsoluteTimeoutconfiguration setting.

The default value for the Timeout property is 60 (seconds).

setTimeout

public void setTimeout(int timeout)
                throws IPWorksException

A timeout for the bean.

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion, or an error condition is encountered.

If Timeout is set to a positive value, the bean will wait for the operation to complete before returning control.

The bean will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the bean throws an IPWorksException raises an IPWorksException exception .

Please note that by default, all timeouts are inactivity timeouts , i.e. the timeout period is extended by Timeout seconds when data is successfully sent or received.

Optionally, the behaviour of the bean may be changed to absolute timeouts , i.e. the bean will wait for a maximum of Timeout seconds since the beginning of the operation, without extending the timeout period during communications.

This behavior is controlled by theAbsoluteTimeoutconfiguration setting.

The default value for the Timeout property is 60 (seconds).

IPWorksException

getUser

public java.lang.String getUser()

The user portion of this entity's Jabber ID.

The User property is a unique username associated with this entity and set at time of registration under the field "user".

setUser

public void setUser(java.lang.String user)
             throws IPWorksException

The user portion of this entity's Jabber ID.

The User property is a unique username associated with this entity and set at time of registration under the field "user".

IPWorksException

getUserDomain

public java.lang.String getUserDomain()

Gets or sets the domain value used for Jabber IDs

A Jabber ID (JID) is a unique identifier of the format " User @ Domain / Resource ". user@domain denotes the account by username and domain. The Resource is given during the login process to distinguish individual connections under the same account. If the IMServer contains multiple domains, this property setting allows the user to specify the domain under which to login.

If Domain is empty, the value in IMServer is used by default when creating the client's JID.

setUserDomain

public void setUserDomain(java.lang.String userDomain)
                   throws IPWorksException

Gets or sets the domain value used for Jabber IDs

A Jabber ID (JID) is a unique identifier of the format " User @ Domain / Resource ". user@domain denotes the account by username and domain. The Resource is given during the login process to distinguish individual connections under the same account. If the IMServer contains multiple domains, this property setting allows the user to specify the domain under which to login.

If Domain is empty, the value in IMServer is used by default when creating the client's JID.

IPWorksException

getUserInfo

public XMPPUserInfoList getUserInfo()

Collection of named registration fields.

Before a registration can be attempted, the application should use the QueryRegister method to poll the host to which the user wishes to register. This will gather all of the necessary fields that the user must send to the server, and will populate the UserInfo collection accordingly. After a successful query, all entries in UserInfo values will be empty strings.

The possible registration fields are defined in the Jabber protocol specification as follows:

instructions

Special instructions sent from the server.

username

The username to be associated with this account.

password

The initial password for this account.

name

The user's name.

email

The user's email address.

address

The user's physical address.

city

The user's city of residence.

state

The user's state (for United States citizens).

zip

The user's postal code (for United States citizens).

phone

The user's phone number.

url

The user's website.

date

The date of registration.

misc

Any miscellaneous data.

text

Any extra text (potentially for a personal bio).

remove

Specifies a request to unregister.

After the user has set all of the values in UserInfo , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

If the bean is not already connected when this method is called, it will connect, poll the registration fields, and then disconnect.

This collection is a hashtable type of collection, in which the field string is used as the key to the desired XMPP user info object.

setUserInfo

public void setUserInfo(XMPPUserInfoList userInfo)
                 throws IPWorksException

Collection of named registration fields.

Before a registration can be attempted, the application should use the QueryRegister method to poll the host to which the user wishes to register. This will gather all of the necessary fields that the user must send to the server, and will populate the UserInfo collection accordingly. After a successful query, all entries in UserInfo values will be empty strings.

The possible registration fields are defined in the Jabber protocol specification as follows:

instructions

Special instructions sent from the server.

username

The username to be associated with this account.

password

The initial password for this account.

name

The user's name.

email

The user's email address.

address

The user's physical address.

city

The user's city of residence.

state

The user's state (for United States citizens).

zip

The user's postal code (for United States citizens).

phone

The user's phone number.

url

The user's website.

date

The date of registration.

misc

Any miscellaneous data.

text

Any extra text (potentially for a personal bio).

remove

Specifies a request to unregister.

After the user has set all of the values in UserInfo , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

If the bean is not already connected when this method is called, it will connect, poll the registration fields, and then disconnect.

This collection is a hashtable type of collection, in which the field string is used as the key to the desired XMPP user info object.

IPWorksException

add

public void add(java.lang.String jabberId,
                java.lang.String name,
                java.lang.String groups)
         throws IPWorksException

This method will add an entity to this entity's roster.

JabberId is the Jabber ID of the entity to be added. It should be of form "user@host". If no hostname is specified, the bean will assume the user's account is with the server in IMServer , and will append that hostname to JabberId before sendng the request.

Name will contain the name that is to be associated with JabberId in this entity's roster. It may be the empty string, "".

Groups is either the empty string ("") or a comma- separated list of groups to which JabberId is to be added. If JabberId already exists in the buddy list, it will be updated to exist only in the specified groups. A buddy's group list can also be modified by the Buddies property.

The Add method will make a subscription request to the presence of the specified JabberId . Upon receiving this request, the server will add an entry into this user's buddy list with a subscription of type subscriptionNone (0) if there was no previous entry (if this user has already allowed JabberId to subscribe to this user's presence, there will already be an entry of type subscriptionFrom (2)). If the contact chooses to allow the subscription, the server will update the entry and a BuddyUpdate event will fire with the new subscription value ( subscriptionTo (1) if this is a new contact, or subscriptionBoth (3) if the contact is now mutual).

The XMPP protocol permits XMPP (Jabber) clients to communicate with foreign IM networks such as AIM, MSN, SMS, and others through the use of gateway servers that translate between the foreign protocol and XMPP. When sending or receiving presence information, messages, or subscription requests, Domain will be a gateway for the foreign network on which the contact resides and with which this user has registered an account for that foreign network. The Register method can be used to register with a foreign network gateway.

IPWorksException

cancel

public void cancel(java.lang.String jabberId)
            throws IPWorksException

This will cancel another entity's subscription to this entity's presence.

If for any reason the user should want to undo a previously granted subscription, this can be achieved through the Cancel method. The method will unsubscribe the target from this user's presence, thus preventing the target from seeing this user in the future.

IPWorksException

changePassword

public void changePassword(java.lang.String password)
                    throws IPWorksException

This method will change the current user's password.

This method changes the current user's password to the password that is specified. The bean must be connected to the server when this method is called.

IPWorksException

changePresence

public void changePresence(int presenceCode,
                           java.lang.String status)
                    throws IPWorksException

This method will set the availability and status of this entity.

PresenceCode should correspond the possible values of the Presence property:

pcOffline (0)

Invisible: JabberId is offline.

pcChat (1)

Available: JabberId is online.

pcAway (2)

Away: JabberId is online, but the user is away from their computer.

pcXA (3)

Extended Away: JabberId is online, but the user is away from their computerfor an extended period of time.

pcDND (4)

Do not Disturb: JabberId is online, but is busy and does not wish to be disturbed.

By default, the bean sets the client presence to pcChat , meaning that the user is available. To change the initial status sent by the bean set Presence to the desired presence before calling Connect .

Note: offline is not officially supported by the XMPP specification, however some XMPP server implementations may recognize the value. Setting the client's presence state to this value may cause the server to respond with an Error .

Status can be any random string, including the empty string "".

IPWorksException

config

public java.lang.String config(java.lang.String configurationString)
                        throws IPWorksException

Sets or retrieves a beanconfiguration setting.

Config is a generic method available in every bean. It is used to set and retrieveconfiguration settingsfor the bean.

Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the bean, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY , you must call Config("PROPERTY=VALUE") , where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY") . The value will be returned as a string.

IPWorksException

connect

public void connect(java.lang.String user,
                    java.lang.String password)
             throws IPWorksException

This method will connect the bean to the server.

The Connect method performs the entire connection routine. This includes connection to the IMServer , user logon and authentication, and session initialization.

The Connected event will not fire until all these steps are complete. The event will fire for either of two situations: a) the bean has successfully completed a login; or b) the login process has failed. Once the event has fired, the Connected property will be set accordingly.

Since Connect is called with a user and password specified, the User and Password properties will updated accordingly.

IPWorksException

disconnect

public void disconnect()
                throws IPWorksException

This method disconnects the bean from the server.

The Disconnect method will send the disconnect command to the notification server. Upon disconnection, a Disconnected event will be fired.

IPWorksException

doEvents

public void doEvents()
              throws IPWorksException

This method processes events from the internal message queue.

When DoEvents is called, the bean processes any available events. If no events are available, it waits for a preset period of time, and then returns.

IPWorksException

interrupt

public void interrupt()
               throws IPWorksException

Interrupt the current method.

If there is no method in progress, Interrupt simply returns doing nothing.

IPWorksException

probePresence

public void probePresence(java.lang.String jabberId)
                   throws IPWorksException

Use this method to probe for another entity's presence.

In the case that the user needs to update a particular entity's presence this method can be used to retrieve it. After a successfull call, the server will either respond with the last known presence for Jabber , or will send a presence element of type "error". In either case, the respond will be returned by a Presence event.

IPWorksException

queryRegister

public void queryRegister(java.lang.String XMPPServer)
                   throws IPWorksException

This method queries a server for the necessary registration fields.

Before a registration can be attempted, the application should use the QueryRegister method to poll the host to which the user wishes to register. This will gather all of the necessary fields that the user must send to the server, and will populate the UserInfo collection accordingly. After a successful query, all entries in UserInfo values will be empty strings.

The possible registration fields are defined in the Jabber protocol specification as follows:

instructions

Special instructions sent from the server.

username

The username to be associated with this account.

password

The initial password for this account.

name

The user's name.

email

The user's email address.

address

The user's physical address.

city

The user's city of residence.

state

The user's state (for United States citizens).

zip

The user's postal code (for United States citizens).

phone

The user's phone number.

url

The user's website.

date

The date of registration.

misc

Any miscellaneous data.

text

Any extra text (potentially for a personal bio).

remove

Specifies a request to unregister.

After the user has set all of the values in UserInfo , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

If the bean is not already connected when this method is called, it will connect, poll the registration fields, and then disconnect.

IPWorksException

register

public void register(java.lang.String XMPPServer)
              throws IPWorksException

This method registers an account with a server.

Before a registration can be attempted, the application should use the QueryRegister method to poll the host to which the user wishes to register. This will gather all of the necessary fields that the user must send to the server, and will populate the UserInfo collection accordingly. After a successful query, all entries in UserInfo values will be empty strings.

The possible registration fields are defined in the Jabber protocol specification as follows:

instructions

Special instructions sent from the server.

username

The username to be associated with this account.

password

The initial password for this account.

name

The user's name.

email

The user's email address.

address

The user's physical address.

city

The user's city of residence.

state

The user's state (for United States citizens).

zip

The user's postal code (for United States citizens).

phone

The user's phone number.

url

The user's website.

date

The date of registration.

misc

Any miscellaneous data.

text

Any extra text (potentially for a personal bio).

remove

Specifies a request to unregister.

After the user has set all of the values in UserInfo , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

If the bean is not already connected when this method is called, it will connect, poll the registration fields, and then disconnect.

A new account can be registered at any time, including while the bean is logged into the host under an existing account.

IPWorksException

remove

public void remove(java.lang.String jabberId,
                   java.lang.String name,
                   java.lang.String group)
            throws IPWorksException

This method will remove an entity from this entity's roster.

JabberId is the Jabber ID of the entity to be removed. It should be of form "user@host". If no hostname is specified, the bean will assume the user's account is with the server in IMServer , and will append that hostname to JabberId before sendng the request.

Name should contain the name that is to be associated with JabberId in this entity's roster. It may be the empty string, "".

Groups may be either the empty string ("") or a comma- separated list of groups from which JabberId is to be removed. If no group is specified, the buddy will be completely removed from the buddy list.

After calling the Remove method, the server will remove the entry from the server-side roster, and will push the result out to all connected resources. A BuddyUpdate event will fire with subscription of type subscriptionRemove , and the entry will be removed from the Jabber bean's internally stored list.

IPWorksException

retrieveRoster

public void retrieveRoster()
                    throws IPWorksException

This method will retreive this entity's roster from the server.

After the bean connects, it will automatically send a request to the server to retrieve the roster. However, should the user or application wish to update the entire roster, this method may be used to do so.

After a successfull call to the RetrieveRoster method, the server will respond with this entity's roster. The bean will parse the roster and fire the Sync event once per item. This event may also fire for each entity added to or removed from the roster.

IPWorksException

sendCommand

public void sendCommand(java.lang.String command)
                 throws IPWorksException

This method sends a command to the server.

The SendCommand method will send the Command parameter to the server. The command must be in valid XML format, and must be recognisable to the IMServer .

The SendCommand method should only be used by programmers or users who are connecting to non-standard servers whose command list is not covered by the bean. Any responses that are defined in the protocol specification will be returned by the appropriate event. Any non-standard IQ message will be returned by the IQ event. All other responses will be returned by the PITrail event.

IPWorksException

sendMessage

public java.lang.String sendMessage(java.lang.String jabberId)
                             throws IPWorksException

This method will send a message to the specified user.

JabberId is the intended recipient of the message. It is of the form user@domain/resource . If a resource is not supplied, all logged-in instances of the user's account will receive the message.

The bean associates several properties with messages it receives and sends. When it receives a message, the bean will parse out the corresponding values and set these properties before firing a MessageIn event. After the event returns control to the bean, the properties will be cleared (ie, they will be set to the empty string, "").

Before sending a message, the application should set the appropriate properties to be associated with the message. The bean will send only properties with non-empty string values (""), and will clear all properties after a successful send.

The associated properties are the following:

MessageType

the type of the message to be sent

MessageSubject

for "headline" type messages, this is the subject

MessageThread

for "chat" type messages, this is the thread on which the current message is a follow-up

MessageText

the plain text of the message

MessageHTML

the HTML version of the message

MessageOtherData

any extra data associated with the message but not required by the protocol.

Note: the XMPP bean will generate and return a unique identifier for each message sent. This identifier can be used to track messages in conjunction with various Jabber Extension Protocols.

IPWorksException

setUserInfoField

public void setUserInfoField(java.lang.String field,
                             java.lang.String value)
                      throws IPWorksException

This method will add a user information field for registration.

This method will search through UserInfo for the field name in Field and set the corresponding value to Value . If the field was not previously contained in UserInfo , it will automatically added.

Before a registration can be attempted, the application should use the QueryRegister method to poll the host to which the user wishes to register. This will gather all of the necessary fields that the user must send to the server, and will populate the UserInfo collection accordingly. After a successful query, all entries in UserInfo values will be empty strings.

The possible registration fields are defined in the Jabber protocol specification as follows:

instructions

Special instructions sent from the server.

username

The username to be associated with this account.

password

The initial password for this account.

name

The user's name.

email

The user's email address.

address

The user's physical address.

city

The user's city of residence.

state

The user's state (for United States citizens).

zip

The user's postal code (for United States citizens).

phone

The user's phone number.

url

The user's website.

date

The date of registration.

misc

Any miscellaneous data.

text

Any extra text (potentially for a personal bio).

remove

Specifies a request to unregister.

After the user has set all of the values in UserInfo , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

If the bean is not already connected when this method is called, it will connect, poll the registration fields, and then disconnect.

IPWorksException

subscribeTo

public void subscribeTo(java.lang.String jabberId)
                 throws IPWorksException

Use this method to subscribe to another entity's presence.

This method will send a request for a subscription to JabberId 's presence. If the entity allows the subscription, a new item will be stored in the buddy list with the appropriate subscription type. Otherwise, no change will take place.

IPWorksException

unregister

public void unregister()
                throws IPWorksException

This method cancels an account with the host.

If the user or application wishes to terminate an account with the IMServer it should make a call to this method. After a successful call, the account will be canceled and the bean will be logged off the server, but not disconnected.

IPWorksException

unsubscribeTo

public void unsubscribeTo(java.lang.String jabberId)
                   throws IPWorksException

This method cancels an account with the host.

If the user or application wishes to terminate an account with the IMServer it should make a call to this method. After a successful call, the account will be canceled and the bean will be logged off the server, but not disconnected.

IPWorksException

addXmppEventListener

public void addXmppEventListener(ipworks.XmppEventListener l)
                          throws java.util.TooManyListenersException

java.util.TooManyListenersException

removeXmppEventListener

public void removeXmppEventListener(ipworks.XmppEventListener l)