net.java.sip.communicator.service.protocol
Interface AuthorizationHandler

All Known Implementing Classes:

AuthorizationHandlerImpl

public interface AuthorizationHandler

Instances of this interface are used by the protocol provider in order to make the user act upon requests coming from contacts that would like to add us to their contact list or simply track oour presence status, or whenever a subscription request has failed for a particular contact because we need to first generate an authorization request demanding permission to subscibe.

The AuthorizationHandler is to be implmented by the User Interface as all its methods would require user intervention.

Note that some protocols do not support authorizations or allow them to be turned off. In such cases the methods from this interface will never be called.

Author:

Emil Ivov

Method Summary

AuthorizationRequest	createAuthorizationRequest(Contact contact) Called by the protocol provider, this method should be implemented by the user interface.
AuthorizationResponse	processAuthorisationRequest(AuthorizationRequest req, Contact sourceContact) Called by the protocol provider whenever someone would like to add us to their contact list.
void	processAuthorizationResponse(AuthorizationResponse response, Contact sourceContact) Called by the protocol provider, this method should be implemented by the user interface.

Method Detail

processAuthorisationRequest

AuthorizationResponse processAuthorisationRequest(AuthorizationRequest req,
                                                  Contact sourceContact)

Called by the protocol provider whenever someone would like to add us to their contact list.

The returned AuthorizationResponse object is to be created by the implementation of this interface, and it should contain a reason phrase (especially in the case of a negative response) that will be sent to the remote user.

Note that some protocols do not support authorizations or allow them to be turned off. In such cases the method will never be called.

Parameters:

req - the authorization request that we should act upon.

sourceContact - a reference to the Contact demanding authorization

Returns:

a new authorization response instance indicating whether or not the request has been accepted and (if applicable) a reason for turning it down.

createAuthorizationRequest

AuthorizationRequest createAuthorizationRequest(Contact contact)

Called by the protocol provider, this method should be implemented by the user interface. The method will be called any time when the user has tried to add a contact to the contact list and this contact requires authorization. The returned AuthorizationRequest object is to be created by the implementation of this interface, and it should also contain a reason phrase that will be sent to the remote user as well as an inidication of whether the specified contact should on its turn be authorized to add us to their contact list. In case the user would prefer to cancel the whole process, this method is to return null (this will be interpreted the same way as a response withe an IGNORED response code). This would subsequently lead to a SubscriptionFailedEvent.

Note that some protocols do not support authorizations or allow them to be turned off. In such cases the method will never be called.

Parameters:

contact - the Contact whose authorization we'll be requesting.

Returns:

the AuthorizationRequest instance that the user interface has created, and which contains a reason phrase and/or a pre-request authorization grant.

processAuthorizationResponse

void processAuthorizationResponse(AuthorizationResponse response,
                                  Contact sourceContact)

Called by the protocol provider, this method should be implemented by the user interface. The method will be called any whenever someone acts upone an authorization request that we have previously sent.

Parameters:

response - the AuthorizationResponse that we have received.

sourceContact - a reference to the Contact demanding authorization