Package org.jivesoftware.smackx.carbons

Class CarbonManager

java.lang.Object

org.jivesoftware.smack.Manager

org.jivesoftware.smackx.carbons.CarbonManager

public final class CarbonManager
extends Manager

Manager for XEP-0280: Message Carbons. This class implements the manager for registering CarbonExtension support, enabling and disabling message carbons, and for CarbonCopyReceivedListener.

Note that it is important to match the 'from' attribute of the message wrapping a carbon copy, as otherwise it would may be possible for others to impersonate users. Smack's CarbonManager takes care of that in CarbonCopyReceivedListeners which were registered with addCarbonCopyReceivedListener(CarbonCopyReceivedListener).

You should call enableCarbons() before sending your first undirected presence (aka. the "initial presence").

Method Summary

Modifier and Type	Method	Description
boolean	addCarbonCopyReceivedListener(CarbonCopyReceivedListener listener)	Add a carbon copy received listener.
void	disableCarbons()	Helper method to disable carbons.
static void	disableCarbons(Message msg)	Deprecated. use CarbonExtension.Private.addTo(Message)
void	disableCarbonsAsync(ExceptionCallback<Exception> exceptionCallback)	Disable carbons asynchronously.
void	enableCarbons()	Helper method to enable carbons.
void	enableCarbonsAsync(ExceptionCallback<Exception> exceptionCallback)	Enable carbons asynchronously.
boolean	getCarbonsEnabled()	Check if carbons are enabled on this connection.
static CarbonManager	getInstanceFor(XMPPConnection connection)	Obtain the CarbonManager responsible for a connection.
boolean	isSupportedByServer()	Returns true if XMPP Carbons are supported by the server.
boolean	removeCarbonCopyReceivedListener(CarbonCopyReceivedListener listener)	Remove a carbon copy received listener.
void	sendCarbonsEnabled(boolean new_state)	Deprecated. use enableCarbonsAsync(ExceptionCallback) or disableCarbonsAsync(ExceptionCallback) instead.
void	setCarbonsEnabled(boolean new_state)	Notify server to change the carbons state.
static void	setEnabledByDefault(boolean enabledByDefault)	Should Carbons be automatically be enabled once the connection is authenticated? Default: false

Methods inherited from class org.jivesoftware.smack.Manager

connection, getAuthenticatedConnectionOrThrow, schedule, schedule, scheduleBlocking

Methods inherited from class java.lang.Object

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

Method Detail

setEnabledByDefault

public static void setEnabledByDefault(boolean enabledByDefault)

Should Carbons be automatically be enabled once the connection is authenticated? Default: false

Parameters:

enabledByDefault - new default value

getInstanceFor

public static CarbonManager getInstanceFor(XMPPConnection connection)

Obtain the CarbonManager responsible for a connection.

Parameters:

connection - the connection object.

Returns:

a CarbonManager instance

addCarbonCopyReceivedListener

public boolean addCarbonCopyReceivedListener(CarbonCopyReceivedListener listener)

Add a carbon copy received listener.

Parameters:

listener - the listener to register.

Returns:

true if the filter was not already registered.

Since:

4.2

removeCarbonCopyReceivedListener

public boolean removeCarbonCopyReceivedListener(CarbonCopyReceivedListener listener)

Remove a carbon copy received listener.

Parameters:

listener - the listener to register.

Returns:

true if the filter was registered.

Since:

4.2

isSupportedByServer

public boolean isSupportedByServer()
                            throws SmackException.NoResponseException,
                                   XMPPException.XMPPErrorException,
                                   SmackException.NotConnectedException,
                                   InterruptedException

Returns true if XMPP Carbons are supported by the server.

Returns:

true if supported

Throws:

SmackException.NotConnectedException - if the XMPP connection is not connected.

XMPPException.XMPPErrorException - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the remote entity.

InterruptedException - if the calling thread was interrupted.

sendCarbonsEnabled

@Deprecated
public void sendCarbonsEnabled(boolean new_state)

Deprecated.

use enableCarbonsAsync(ExceptionCallback) or disableCarbonsAsync(ExceptionCallback) instead.

Notify server to change the carbons state. This method returns immediately and changes the variable when the reply arrives. You should first check for support using isSupportedByServer().

Parameters:

new_state - whether carbons should be enabled or disabled

enableCarbonsAsync

public void enableCarbonsAsync(ExceptionCallback<Exception> exceptionCallback)

Enable carbons asynchronously. If an error occurs as result of the attempt to enable carbons, the optional exceptionCallback will be invoked.

Note that although this method is asynchronous, it may block if the outgoing stream element queue is full (e.g. because of a slow network connection). Thus, if the thread performing this operation is interrupted while the queue is full, an InterruptedException is thrown.

Parameters:

exceptionCallback - the optional exception callback.

Since:

4.2

disableCarbonsAsync

public void disableCarbonsAsync(ExceptionCallback<Exception> exceptionCallback)

Disable carbons asynchronously. If an error occurs as result of the attempt to disable carbons, the optional exceptionCallback will be invoked.

Note that although this method is asynchronous, it may block if the outgoing stream element queue is full (e.g. because of a slow network connection). Thus, if the thread performing this operation is interrupted while the queue is full, an InterruptedException is thrown.

Parameters:

exceptionCallback - the optional exception callback.

Since:

4.2

setCarbonsEnabled

public void setCarbonsEnabled(boolean new_state)
                       throws SmackException.NoResponseException,
                              XMPPException.XMPPErrorException,
                              SmackException.NotConnectedException,
                              InterruptedException

Notify server to change the carbons state. This method blocks some time until the server replies to the IQ and returns true on success. You should first check for support using isSupportedByServer().

Parameters:

new_state - whether carbons should be enabled or disabled

Throws:

XMPPException.XMPPErrorException - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

InterruptedException - if the calling thread was interrupted.

enableCarbons

public void enableCarbons()
                   throws XMPPException,
                          SmackException,
                          InterruptedException

Helper method to enable carbons.

Throws:

XMPPException - if an XMPP protocol error was received.

SmackException - if there was no response from the server.

InterruptedException - if the calling thread was interrupted.

disableCarbons

public void disableCarbons()
                    throws XMPPException,
                           SmackException,
                           InterruptedException

Helper method to disable carbons.

Throws:

XMPPException - if an XMPP protocol error was received.

SmackException - if there was no response from the server.

InterruptedException - if the calling thread was interrupted.

getCarbonsEnabled

public boolean getCarbonsEnabled()

Check if carbons are enabled on this connection.

Returns:

true if carbons are enabled, else false.

disableCarbons

@Deprecated
public static void disableCarbons(Message msg)

Deprecated.

use CarbonExtension.Private.addTo(Message)

Mark a message as "private", so it will not be carbon-copied.

Parameters:

msg - Message object to mark private