* @param contactIdentifier the identifier of the contact whose status we're * interested in. * @return PresenceStatus the PresenceStatus of the specified * contact * * @throws OperationFailedException with code NETWORK_FAILURE if retrieving * the status fails due to errors experienced during network communication * @throws IllegalArgumentException if contact is not a contact * known to the underlying protocol provider * @throws IllegalStateException if the underlying protocol provider is not * registered/signed on a public service. */ public PresenceStatus queryContactStatus(String contactIdentifier) throws IllegalArgumentException, IllegalStateException, OperationFailedException; /** * Adds a subscription for the presence status of the contact corresponding * to the specified contactIdentifier. Note that apart from an exception in * the case of an immediate failure, the method won't return any indication * of success or failure. That would happen later on through a * SubscriptionEvent generated by one of the methods of the * SubscriptionListener. *
* This subscription is not going to be persistent (as opposed to * subscriptions added from the OperationSetPersistentPresence.subscribe() * method) * @param contactIdentifier the identifier of the contact whose status * updates we are subscribing for. *
* @throws OperationFailedException with code NETWORK_FAILURE if subscribing * fails due to errors experienced during network communication * @throws IllegalArgumentException if contact is not a contact * known to the underlying protocol provider * @throws IllegalStateException if the underlying protocol provider is not * registered/signed on a public service. */ public void subscribe(String contactIdentifier) throws IllegalArgumentException, IllegalStateException, OperationFailedException; /** * Removes a subscription for the presence status of the specified contact. * @param contact the contact whose status updates we are unsubscribing from. * * @throws OperationFailedException with code NETWORK_FAILURE if unsubscribing * fails due to errors experienced during network communication * @throws IllegalArgumentException if contact is not a contact * known to the underlying protocol provider * @throws IllegalStateException if the underlying protocol provider is not * registered/signed on a public service. */ public void unsubscribe(Contact contact) throws IllegalArgumentException, IllegalStateException, OperationFailedException; /** * Returns a reference to the contact with the specified ID in case we have * a subscription for it and null otherwise/ * @param contactID a String identifier of the contact which we're seeking a * reference of. * @return a reference to the Contact with the specified * contactID or null if we don't have a subscription for the * that identifier. */ public Contact findContactByID(String contactID); /** * Returns the protocol specific contact instance representing the local * user. In the case of SIP this would be your local sip address or in the * case of an IM protocol such as ICQ - your own uin. No set method should * be provided in implementations of this class. The getLocalContact() * method is only used for giving information to the user on their currently * used addressed a different service (ConfigurationService) should be used * for changing that kind of settings. * @return the Contact (address, phone number, or uin) that the Provider * implementation is communicating on behalf of. */ public Contact getLocalContact(); /** * Handler for incoming authorization requests. An authorization request * notifies the user that someone is trying to add her to their contact list * and requires her to approve or reject authorization for that action. * @param handler an instance of an AuthorizationHandler for authorization * requests coming from other users requesting permission add us to their * contact list. */ public void setAuthorizationHandler(AuthorizationHandler handler); /** * Adds a listener that would receive events upon changes of the provider * presence status. * @param listener the listener to register for changes in our PresenceStatus. */ public void addProviderPresenceStatusListener( ProviderPresenceStatusListener listener); /** * Unregisters the specified listener so that it does not receive further * events upon changes in local presence status. * @param listener ProviderPresenceStatusListener */ public void removeProviderPresenceStatusListener( ProviderPresenceStatusListener listener); /** * Registers a listener that would receive a presence status change event * every time a contact, whose status we're subscribed for, changes her * status. * Note that, for reasons of simplicity and ease of implementation, there * is only a means of registering such "global" listeners that would receive * updates for status changes for any contact and it is not currently * possible to register such contacts for a single contact or a subset of * contacts. * * @param listener the listener that would received presence status * updates for contacts. */ public void addContactPresenceStatusListener( ContactPresenceStatusListener listener); /** * Removes the specified listener so that it won't receive any further * updates on contact presence status changes * @param listener the listener to remove. */ public void removeContactPresenceStatusListener( ContactPresenceStatusListener listener); /** * Registers a listener that would get notifications any time a new * subscription was succesfully added, has failed or was removed. * @param listener the SubscriptionListener to register */ public void addSubscriptionListener(SubscriptionListener listener); /** * Removes the specified subscription listener. * @param listener the listener to remove. */ public void removeSubscriptionListener(SubscriptionListener listener); /** * Returns the status message that was confirmed by the serfver * @return the last status message that we have requested and the aim server * has confirmed. */ public String getCurrentStatusMessage(); /** * Creates and returns a unresolved contact from the specified * address and persistentData. The method will not try * to establish a network connection and resolve the newly created Contact * against the server. The protocol provider may will later try and resolve * the contact. When this happens the corresponding event would notify * interested subscription listeners. * * @param address an identifier of the contact that we'll be creating. * @param persistentData a String returned Contact's getPersistentData() * method during a previous run and that has been persistently stored * locally. * * @return the unresolved Contact created from the specified * address and persistentData */ public Contact createUnresolvedContact( String address, String persistentData); }