ipworksssl
Class Xmpps

java.lang.Object
  |
  +--ipworksssl.Xmpps

public class Xmpps

extends java.lang.Object

The XMPPS 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	fwNone
static int	fwSOCKS4
static int	fwSOCKS5
static int	fwTunnel
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
static int	sslAutomatic
static int	sslExplicit
static int	sslImplicit
static int	sslNone
static int	sstMachine
static int	sstPEMKey
static int	sstPFXBlob
static int	sstPFXFile
static int	sstUser
static int	stBoth
static int	stFrom
static int	stNone
static int	stRemove
static int	stTo

Constructor Summary

Xmpps()

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	addXmppsEventListener(XmppsEventListener l)
void	cancel(java.lang.String jabberId) This will cancel another entity's subscription to this entity's presence.
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.
int	getBuddyCount() This is the number of buddies in the buddy list.
java.lang.String	getBuddyGroup(int buddyIndex) This is a comma-separated list of each buddy's associated group names.
java.lang.String	getBuddyId(int buddyIndex) This is a list of the jabber ids in the buddy list.
int	getBuddySubscription(int buddyIndex) This is a list of the subscription status for each buddy.
java.lang.String	getFirewallHost() Name or IP address of firewall (optional).
java.lang.String	getFirewallPassword() A password if authentication is to be used when connecting through the firewall.
int	getFirewallPort() Port of the firewall to connect to.
int	getFirewallType() Determines the type of firewall to connect through.
java.lang.String	getFirewallUser() A user name if authentication is to be used connecting through a firewall.
int	getIMPort() The server port for secure XMPP (default 5223).
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	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	getOtherData() This properties contains extra data elements for 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.
byte[]	getSSLAcceptServerCert() Instructs the bean to unconditionally accept the server certificate that matches the supplied certificate.
byte[]	getSSLCertEncoded() The SSL certificate (PEM/base64 encoded).
byte[]	getSSLCertStore() The name of the certificate store for the client certificate.
java.lang.String	getSSLCertStorePassword() The password for the certificate store (if any).
int	getSSLCertStoreType() The type of certificate store for the client certificate.
java.lang.String	getSSLCertSubject() The subject of the certificate used for client authentication.
byte[]	getSSLServerCert() The server certificate for the last established connection.
java.lang.String	getSSLServerCertStatus() The verification status of the server certificate for the last established connection.
int	getSSLStartMode() Determines how the bean starts the SSL negotiation.
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.
int	getUserInfoCount() This is the current number of named registration fields.
java.lang.String	getUserInfoFields(int fieldIndex) This is a list of the names of necessary registration fields.
java.lang.String	getUserInfoValues(int fieldIndex) This is a list of values associated with registration fields.
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	removeXmppsEventListener(XmppsEventListener l)
void	retrieveRoster() This method will retrieve this entity's roster from the server.
void	sendCommand(java.lang.String command) This method sends a command to the server.
void	sendMessage(java.lang.String jabberId) This method will send a message to the specified user.
void	setBuddyGroup(int buddyIndex, java.lang.String buddyGroup) This is a comma-separated list of each buddy's associated group names.
void	setFirewallHost(java.lang.String firewallHost) Name or IP address of firewall (optional).
void	setFirewallPassword(java.lang.String firewallPassword) A password if authentication is to be used when connecting through the firewall.
void	setFirewallPort(int firewallPort) Port of the firewall to connect to.
void	setFirewallType(int firewallType) Determines the type of firewall to connect through.
void	setFirewallUser(java.lang.String firewallUser) A user name if authentication is to be used connecting through a firewall.
void	setIMPort(int IMPort) The server port for secure XMPP (default 5223).
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	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	setOtherData(java.lang.String otherData) This properties contains extra data elements for 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	setSSLAcceptServerCert(byte[] SSLAcceptServerCert) Instructs the bean to unconditionally accept the server certificate that matches the supplied certificate.
void	setSSLCertEncoded(byte[] SSLCertEncoded) The SSL certificate (PEM/base64 encoded).
void	setSSLCertStore(byte[] SSLCertStore) The name of the certificate store for the client certificate.
void	setSSLCertStorePassword(java.lang.String SSLCertStorePassword) The password for the certificate store (if any).
void	setSSLCertStoreType(int SSLCertStoreType) The type of certificate store for the client certificate.
void	setSSLCertSubject(java.lang.String SSLCertSubject) The subject of the certificate used for client authentication.
void	setSSLStartMode(int SSLStartMode) Determines how the bean starts the SSL negotiation.
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	setUserInfoCount(int userInfoCount) This is the current number 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	setUserInfoFields(int fieldIndex, java.lang.String userInfoFields) This is a list of the names of necessary registration fields.
void	setUserInfoValues(int fieldIndex, java.lang.String userInfoValues) This is a list of values associated with registration fields.
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 will cancel a subscription to another entity's presence.

Methods inherited from class java.lang.Object

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

Field Detail

stNone

public static final int stNone

See Also:

Constant Field Values

stTo

public static final int stTo

See Also:

Constant Field Values

stFrom

public static final int stFrom

See Also:

Constant Field Values

stBoth

public static final int stBoth

See Also:

Constant Field Values

stRemove

public static final int stRemove

See Also:

Constant Field Values

fwNone

public static final int fwNone

See Also:

Constant Field Values

fwTunnel

public static final int fwTunnel

See Also:

Constant Field Values

fwSOCKS4

public static final int fwSOCKS4

See Also:

Constant Field Values

fwSOCKS5

public static final int fwSOCKS5

See Also:

Constant Field Values

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

sstUser

public static final int sstUser

See Also:

Constant Field Values

sstMachine

public static final int sstMachine

See Also:

Constant Field Values

sstPFXFile

public static final int sstPFXFile

See Also:

Constant Field Values

sstPFXBlob

public static final int sstPFXBlob

See Also:

Constant Field Values

sstPEMKey

public static final int sstPEMKey

See Also:

Constant Field Values

sslAutomatic

public static final int sslAutomatic

See Also:

Constant Field Values

sslImplicit

public static final int sslImplicit

See Also:

Constant Field Values

sslExplicit

public static final int sslExplicit

See Also:

Constant Field Values

sslNone

public static final int sslNone

See Also:

Constant Field Values

Constructor Detail

Xmpps

public Xmpps()

Method Detail

getBuddyCount

public int getBuddyCount()

This is the number of buddies in the buddy list.

After a Sync event is fired, this property will contain the number of entries in the buddy list. Each time a change is made to the size of the list, this property will be updated.

getBuddyGroup

public java.lang.String getBuddyGroup(int buddyIndex)
                               throws IPWorksSSLException

This is a comma-separated list of each buddy's associated group names.

After the Sync event has fired, this property will contain a comma- separated list of groups for the associated BuddyId . This is the only buddy list property that can be modified. Changing this value will cause the buddy's group association to change. Setting it to the empty string ("") will cause the buddy to be completely dissociated from a particular group.

IPWorksSSLException

setBuddyGroup

public void setBuddyGroup(int buddyIndex,
                          java.lang.String buddyGroup)
                   throws IPWorksSSLException

This is a comma-separated list of each buddy's associated group names.

After the Sync event has fired, this property will contain a comma- separated list of groups for the associated BuddyId . This is the only buddy list property that can be modified. Changing this value will cause the buddy's group association to change. Setting it to the empty string ("") will cause the buddy to be completely dissociated from a particular group.

IPWorksSSLException

getBuddyId

public java.lang.String getBuddyId(int buddyIndex)
                            throws IPWorksSSLException

This is a list of the jabber ids in the buddy list.

After a Sync event is fired, this property will contain all of the user ids associated with each entry in the buddy list. If a buddy has multiple entries (e.g., if the buddy is listed in several groups) more than one entry will be the same.

IPWorksSSLException

getBuddySubscription

public int getBuddySubscription(int buddyIndex)
                         throws IPWorksSSLException

This is a list of the subscription status for each buddy.

After a Sync event is fired, this property will contain all of the types of subscriptions for each buddy. They are defined as follows:

stNone (0)

no subscription

stTo (1)

the buddy has a subscription to this entity.

stFrom (2)

this entity has a subscription to the buddy

stBoth (3)

subscription is both to and from

stRemove (4)

the item is to be removed from the list

IPWorksSSLException

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.

getFirewallHost

public java.lang.String getFirewallHost()

Name or IP address of firewall (optional).

If a FirewallHost is given, requested connections will be authenticated through the specified firewall when connecting.

If the FirewallHost property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the FirewallHost property is set to the corresponding address. If the search is not successful, an error is returned.

setFirewallHost

public void setFirewallHost(java.lang.String firewallHost)
                     throws IPWorksSSLException

Name or IP address of firewall (optional).

If a FirewallHost is given, requested connections will be authenticated through the specified firewall when connecting.

If the FirewallHost property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the FirewallHost property is set to the corresponding address. If the search is not successful, an error is returned.

IPWorksSSLException

getFirewallPassword

public java.lang.String getFirewallPassword()

A password if authentication is to be used when connecting through the firewall.

if FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.

setFirewallPassword

public void setFirewallPassword(java.lang.String firewallPassword)
                         throws IPWorksSSLException

A password if authentication is to be used when connecting through the firewall.

if FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.

IPWorksSSLException

getFirewallPort

public int getFirewallPort()

Port of the firewall to connect to.

The TCP port for the FirewallHost . See the description of the FirewallHost property for details.

Note that the FirewallPort is set automatically when FirewallType is set to a valid value. See the description of the FirewallType property for details.

setFirewallPort

public void setFirewallPort(int firewallPort)
                     throws IPWorksSSLException

Port of the firewall to connect to.

The TCP port for the FirewallHost . See the description of the FirewallHost property for details.

Note that the FirewallPort is set automatically when FirewallType is set to a valid value. See the description of the FirewallType property for details.

IPWorksSSLException

getFirewallType

public int getFirewallType()

Determines the type of firewall to connect through.

The applicable values are the following:

fwNone (0)

No firewall (default setting).

fwTunnel (1)

Connect through a tunneling proxy. FirewallPort is set to 80.

fwSOCKS4 (2)

Connect through a SOCKS4 Proxy. FirewallPort is set to 1080.

fwSOCKS5 (3)

Connect through a SOCKS5 Proxy. FirewallPort is set to 1080.

setFirewallType

public void setFirewallType(int firewallType)
                     throws IPWorksSSLException

Determines the type of firewall to connect through.

The applicable values are the following:

fwNone (0)

No firewall (default setting).

fwTunnel (1)

Connect through a tunneling proxy. FirewallPort is set to 80.

fwSOCKS4 (2)

Connect through a SOCKS4 Proxy. FirewallPort is set to 1080.

fwSOCKS5 (3)

Connect through a SOCKS5 Proxy. FirewallPort is set to 1080.

IPWorksSSLException

getFirewallUser

public java.lang.String getFirewallUser()

A user name if authentication is to be used connecting through a firewall.

if FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.

setFirewallUser

public void setFirewallUser(java.lang.String firewallUser)
                     throws IPWorksSSLException

A user name if authentication is to be used connecting through a firewall.

if FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.

IPWorksSSLException

getIMPort

public int getIMPort()

The server port for secure XMPP (default 5223).

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 IPWorksSSLException

The server port for secure XMPP (default 5223).

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.

IPWorksSSLException

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 IPWorksSSLException

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.

IPWorksSSLException

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 IPWorksSSLException

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.

IPWorksSSLException

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 IPWorksSSLException

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

IPWorksSSLException

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 IPWorksSSLException

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.

IPWorksSSLException

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 useful for tracking messages of type "chat" or "groupchat".

setMessageThread

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

This is the thread name of the current message.

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

IPWorksSSLException

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 IPWorksSSLException

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.

IPWorksSSLException

getOtherData

public java.lang.String getOtherData()

This properties contains extra data elements for the current message.

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

setOtherData

public void setOtherData(java.lang.String otherData)
                  throws IPWorksSSLException

This properties contains extra data elements for the current message.

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

IPWorksSSLException

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 IPWorksSSLException

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.

IPWorksSSLException

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:

offline (0)

JabberId is offline.

chat (1)

JabberId is online.

away (2)

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

xa (3)

JabberId is online, but the user is away from their computer for an extended period of time.

dnd (4)

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

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 IPWorksSSLException

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:

offline (0)

JabberId is offline.

chat (1)

JabberId is online.

away (2)

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

xa (3)

JabberId is online, but the user is away from their computer for an extended period of time.

dnd (4)

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

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.

IPWorksSSLException

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 IPWorksSSLException

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.

IPWorksSSLException

getSSLAcceptServerCert

public byte[] getSSLAcceptServerCert()

Instructs the bean to unconditionally accept the server certificate that matches the supplied certificate.

If it finds any issues with the certificate presented by the server, the bean will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert . If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, these property will create a security breach. Use it at your own risk.

setSSLAcceptServerCert

public void setSSLAcceptServerCert(byte[] SSLAcceptServerCert)
                            throws IPWorksSSLException

Instructs the bean to unconditionally accept the server certificate that matches the supplied certificate.

If it finds any issues with the certificate presented by the server, the bean will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert . If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, these property will create a security breach. Use it at your own risk.

IPWorksSSLException

getSSLCertEncoded

public byte[] getSSLCertEncoded()

The SSL certificate (PEM/base64 encoded).

This property is used to assign a specific certificate for SSL client authentication (SSL server authentication in the case of the IPDaemonS bean). The SSLCertStore and SSLCertSubject properties may also be used to specify a certificate.

When SSLCertEncoded is set, a search is initiated in the current SSLCertStore for the private key of the certificate. If the key is found, SSLCertSubject is updated to reflect the full subject of the selected certificate, otherwise SSLCertSubject is set to empty string.

setSSLCertEncoded

public void setSSLCertEncoded(byte[] SSLCertEncoded)
                       throws IPWorksSSLException

The SSL certificate (PEM/base64 encoded).

This property is used to assign a specific certificate for SSL client authentication (SSL server authentication in the case of the IPDaemonS bean). The SSLCertStore and SSLCertSubject properties may also be used to specify a certificate.

When SSLCertEncoded is set, a search is initiated in the current SSLCertStore for the private key of the certificate. If the key is found, SSLCertSubject is updated to reflect the full subject of the selected certificate, otherwise SSLCertSubject is set to empty string.

IPWorksSSLException

getSSLCertStore

public byte[] getSSLCertStore()

The name of the certificate store for the client certificate.

The SSLCertStoreType property specifies the type of the certificate store specified by SSLCertStore . If the store is password protected, specify the password in SSLCertStorePassword .

SSLCertStore is used in conjunction with the SSLCertSubject property in order to specify client certificates. If SSLCertStore has a value, and SSLCertSubject or SSLCertEncoded is set, a search for a certificate is initiated. Please refer to the SSLCertSubject property for details.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

MY

A certificate store holding personal certificates with their associated private keys.

CA

Certifying authority certificates.

ROOT

Root certificates.

SPC

Software publisher certificates.

In Java, the certificate store normally is a file containing certificates and optional private keys.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

If the provider is OpenSSL, the certificate store is a file containing a certificate and a private key. This property must be set to the name of the file.

setSSLCertStore

public void setSSLCertStore(byte[] SSLCertStore)
                     throws IPWorksSSLException

The name of the certificate store for the client certificate.

The SSLCertStoreType property specifies the type of the certificate store specified by SSLCertStore . If the store is password protected, specify the password in SSLCertStorePassword .

SSLCertStore is used in conjunction with the SSLCertSubject property in order to specify client certificates. If SSLCertStore has a value, and SSLCertSubject or SSLCertEncoded is set, a search for a certificate is initiated. Please refer to the SSLCertSubject property for details.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

MY

A certificate store holding personal certificates with their associated private keys.

CA

Certifying authority certificates.

ROOT

Root certificates.

SPC

Software publisher certificates.

In Java, the certificate store normally is a file containing certificates and optional private keys.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

If the provider is OpenSSL, the certificate store is a file containing a certificate and a private key. This property must be set to the name of the file.

IPWorksSSLException

getSSLCertStorePassword

public java.lang.String getSSLCertStorePassword()

The password for the certificate store (if any).

If the certificate store is of a type that requires a password, the value of this property is used to open the certificate store.

setSSLCertStorePassword

public void setSSLCertStorePassword(java.lang.String SSLCertStorePassword)
                             throws IPWorksSSLException

The password for the certificate store (if any).

If the certificate store is of a type that requires a password, the value of this property is used to open the certificate store.

IPWorksSSLException

getSSLCertStoreType

public int getSSLCertStoreType()

The type of certificate store for the client certificate.

This property can take one of the following values:

0 (sstUser - default)

For Windows, this specifies that the certificate store is a certificate store owned by the current user. For Java, this specifies that the certificate store is the name of a JKS (Java Key Store) file. If the provider is OpenSSL, this specifies that the certificate store is a file that contains PEM encoded certificate and private key.

1 (sstMachine)

The certificate store is a machine store (not available in Java and when provider is OpenSSL).

2 (sstPFXFile)

The certificate store is the name of a PFX (PKCS12) file containing certificates. If the provider is OpenSSL, the file may contain only one certificate and private key.

3 (sstPFXBlob)

The certificate store is a string (binary or base64 encoded) representing a certificate store in PFX (PKCS12) format.This setting is currently not supported when the provider is OpenSSL.

4 (sstPEMKey)

The certificate store is a string or filename that contains a PEM encoded certificate and private key.This store type is currently not supported in Java.

setSSLCertStoreType

public void setSSLCertStoreType(int SSLCertStoreType)
                         throws IPWorksSSLException

The type of certificate store for the client certificate.

This property can take one of the following values:

0 (sstUser - default)

For Windows, this specifies that the certificate store is a certificate store owned by the current user. For Java, this specifies that the certificate store is the name of a JKS (Java Key Store) file. If the provider is OpenSSL, this specifies that the certificate store is a file that contains PEM encoded certificate and private key.

1 (sstMachine)

The certificate store is a machine store (not available in Java and when provider is OpenSSL).

2 (sstPFXFile)

The certificate store is the name of a PFX (PKCS12) file containing certificates. If the provider is OpenSSL, the file may contain only one certificate and private key.

3 (sstPFXBlob)

The certificate store is a string (binary or base64 encoded) representing a certificate store in PFX (PKCS12) format.This setting is currently not supported when the provider is OpenSSL.

4 (sstPEMKey)

The certificate store is a string or filename that contains a PEM encoded certificate and private key.This store type is currently not supported in Java.

IPWorksSSLException

getSSLCertSubject

public java.lang.String getSSLCertSubject()

The subject of the certificate used for client authentication.

When this property is set, a search is performed in the current certificate store certificate with matching subject.

If an exact match is not found, the store is searched for subjects containing the value of the property.

When setting the property to a partial subject, CN= should be omitted. For example, the following code would find the certificate with subject CN=Test Certificate, OU=People, C=US

Example (Searching with partial subject)

 Control.CertSubject = "Test" 

If a match is not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

If a matching certificate is found, the SSLCertSubject property is set to the full subject of the matching certificate.

setSSLCertSubject

public void setSSLCertSubject(java.lang.String SSLCertSubject)
                       throws IPWorksSSLException

The subject of the certificate used for client authentication.

When this property is set, a search is performed in the current certificate store certificate with matching subject.

If an exact match is not found, the store is searched for subjects containing the value of the property.

When setting the property to a partial subject, CN= should be omitted. For example, the following code would find the certificate with subject CN=Test Certificate, OU=People, C=US

Example (Searching with partial subject)

 Control.CertSubject = "Test" 

If a match is not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

If a matching certificate is found, the SSLCertSubject property is set to the full subject of the matching certificate.

IPWorksSSLException

getSSLServerCert

public byte[] getSSLServerCert()

The server certificate for the last established connection.

SSLServerCert contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

getSSLServerCertStatus

public java.lang.String getSSLServerCertStatus()

The verification status of the server certificate for the last established connection.

When the verification fails, SSLServerCertStatus contains a string that indicates the reason(s) why, otherwise, it contains the string "OK".

Please note that the value of SSLServerCertStatus must be considered as only a suggestion as to the validity of the certificate. Application software must use its own logic to determine whether to accept the certificate or not, by using the SSLServerCert to access other certificate properties, or other application-specific information.

SSLServerCertStatus is reset an empty string every time a new connection is attempted.

getSSLStartMode

public int getSSLStartMode()

Determines how the bean starts the SSL negotiation.

The SSLStartMode property may have one of the following values:

0 (sslAutomatic - default)

If the remote port is set to the standard plaintext port of the protocol (where applicable), the bean will behave the same as if SSLStartMode is set to sslExplicit . In all other cases, SSL negotiation will be implicit ( sslImplicit ).

1 (sslImplicit)

The SSL negotiation will start immediately after the connection is established.

2 (sslExplicit)

The bean will first connect in plaintext, and then explicitly start SSL negotiation through a protocol command such as STARTTLS.

3 (sslNone)

No SSL negotiation, no SSL security. All communication will be in plaintext mode.

setSSLStartMode

public void setSSLStartMode(int SSLStartMode)
                     throws IPWorksSSLException

Determines how the bean starts the SSL negotiation.

The SSLStartMode property may have one of the following values:

0 (sslAutomatic - default)

If the remote port is set to the standard plaintext port of the protocol (where applicable), the bean will behave the same as if SSLStartMode is set to sslExplicit . In all other cases, SSL negotiation will be implicit ( sslImplicit ).

1 (sslImplicit)

The SSL negotiation will start immediately after the connection is established.

2 (sslExplicit)

The bean will first connect in plaintext, and then explicitly start SSL negotiation through a protocol command such as STARTTLS.

3 (sslNone)

No SSL negotiation, no SSL security. All communication will be in plaintext mode.

IPWorksSSLException

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:

offline (0)

JabberId is offline.

chat (1)

JabberId is online.

away (2)

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

xa (3)

JabberId is online, but the user is away from their computer for an extended period of time.

dnd (4)

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

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 IPWorksSSLException

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:

offline (0)

JabberId is offline.

chat (1)

JabberId is online.

away (2)

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

xa (3)

JabberId is online, but the user is away from their computer for an extended period of time.

dnd (4)

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

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.

IPWorksSSLException

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 behavior 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 IPWorksSSLException

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 behavior 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).

IPWorksSSLException

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 IPWorksSSLException

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

IPWorksSSLException

getUserInfoCount

public int getUserInfoCount()

This is the current number 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 UserInfoFields and UserInfoCount properties accordingly. After a successful query, all entries in UserInfoValues will be the empty string, "".

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 UserInfoValues , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

This method does not require a connection to be made to the server. If the bean is disconnected when this method is called, it will connect, poll the registration fields, and then disconnect.

setUserInfoCount

public void setUserInfoCount(int userInfoCount)
                      throws IPWorksSSLException

This is the current number 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 UserInfoFields and UserInfoCount properties accordingly. After a successful query, all entries in UserInfoValues will be the empty string, "".

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 UserInfoValues , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

This method does not require a connection to be made to the server. If the bean is disconnected when this method is called, it will connect, poll the registration fields, and then disconnect.

IPWorksSSLException

getUserInfoFields

public java.lang.String getUserInfoFields(int fieldIndex)
                                   throws IPWorksSSLException

This is a list of the names of 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 UserInfoFields and UserInfoCount properties accordingly. After a successful query, all entries in UserInfoValues will be the empty string, "".

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 UserInfoValues , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

This method does not require a connection to be made to the server. If the bean is disconnected when this method is called, it will connect, poll the registration fields, and then disconnect.

IPWorksSSLException

setUserInfoFields

public void setUserInfoFields(int fieldIndex,
                              java.lang.String userInfoFields)
                       throws IPWorksSSLException

This is a list of the names of 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 UserInfoFields and UserInfoCount properties accordingly. After a successful query, all entries in UserInfoValues will be the empty string, "".

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 UserInfoValues , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

This method does not require a connection to be made to the server. If the bean is disconnected when this method is called, it will connect, poll the registration fields, and then disconnect.

IPWorksSSLException

getUserInfoValues

public java.lang.String getUserInfoValues(int fieldIndex)
                                   throws IPWorksSSLException

This is a list of values associated with 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 UserInfoFields and UserInfoCount properties accordingly. After a successful query, all entries in UserInfoValues will be the empty string, "".

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 UserInfoValues , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

This method does not require a connection to be made to the server. If the bean is disconnected when this method is called, it will connect, poll the registration fields, and then disconnect.

IPWorksSSLException

setUserInfoValues

public void setUserInfoValues(int fieldIndex,
                              java.lang.String userInfoValues)
                       throws IPWorksSSLException

This is a list of values associated with 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 UserInfoFields and UserInfoCount properties accordingly. After a successful query, all entries in UserInfoValues will be the empty string, "".

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 UserInfoValues , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

This method does not require a connection to be made to the server. If the bean is disconnected when this method is called, it will connect, poll the registration fields, and then disconnect.

IPWorksSSLException

config

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

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.

IPWorksSSLException

add

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

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 sending 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 BuddyGroup 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.

IPWorksSSLException

cancel

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

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.

IPWorksSSLException

changePresence

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

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

PresenceCode should correspond the possible values of the Presence property:

offline (0)

JabberId is offline.

chat (1)

JabberId is online.

away (2)

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

xa (3)

JabberId is online, but the user is away from their computer for an extended period of time.

dnd (4)

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

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

IPWorksSSLException

connect

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

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.

IPWorksSSLException

disconnect

public void disconnect()
                throws IPWorksSSLException

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.

IPWorksSSLException

doEvents

public void doEvents()
              throws IPWorksSSLException

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.

IPWorksSSLException

probePresence

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

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.

IPWorksSSLException

queryRegister

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

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 UserInfoFields and UserInfoCount properties accordingly. After a successful query, all entries in UserInfoValues will be the empty string, "".

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 UserInfoValues , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

This method does not require a connection to be made to the server. If the bean is disconnected when this method is called, it will connect, poll the registration fields, and then disconnect.

IPWorksSSLException

register

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

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 UserInfoFields and UserInfoCount properties accordingly. After a successful query, all entries in UserInfoValues will be the empty string, "".

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 UserInfoValues , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

This method does not require a connection to be made to the server. If the bean is disconnected 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.

IPWorksSSLException

remove

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

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

IPWorksSSLException

retrieveRoster

public void retrieveRoster()
                    throws IPWorksSSLException

This method will retrieve 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 this event once per item. This event may also fire for each entity added to or removed from the roster.

IPWorksSSLException

sendCommand

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

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

IPWorksSSLException

sendMessage

public void sendMessage(java.lang.String jabberId)
                 throws IPWorksSSLException

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

OtherData

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

IPWorksSSLException

setUserInfoField

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

This method will add a user information field for registration.

This method will search through UserInfoFields for the index of the field name in Field and set the corresponding value in UserInfoValues with Value . If the field was not previously contained in UserInfoFields , it will be added and UserInfoCount will be updated accordingly.

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 UserInfoFields and UserInfoCount properties accordingly. After a successful query, all entries in UserInfoValues will be the empty string, "".

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 UserInfoValues , and added any extra fields they may wish to include in their registration, the application should make a call to Register .

This method does not require a connection to be made to the server. If the bean is disconnected when this method is called, it will connect, poll the registration fields, and then disconnect.

IPWorksSSLException

subscribeTo

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

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.

IPWorksSSLException

unregister

public void unregister()
                throws IPWorksSSLException

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.

IPWorksSSLException

unsubscribeTo

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

This method will cancel a subscription to another entity's presence.

This method will inform the server of the cancellation of subscription to JabberId 's presence. After a successful call the subscription type of the associated buddy list item will be updated.

IPWorksSSLException

addXmppsEventListener

public void addXmppsEventListener(XmppsEventListener l)
                           throws java.util.TooManyListenersException

java.util.TooManyListenersException

removeXmppsEventListener

public void removeXmppsEventListener(XmppsEventListener l)