text: #import <Foundation/Foundation.h>
  #import "RT-XMPP.h"
  
  #define _XMPP_TIME_H
  
  @class XMPPIDTracker;
  @protocol XMPPTimeDelegate;
  
  
  @interface XMPPTime : XMPPModule
  {
  	BOOL respondsToQueries;
  	XMPPIDTracker *queryTracker;
  }
  
  /**
   * Whether or not the module should respond to incoming time queries.
   * It you create multiple instances of this module, only one instance should respond to queries.
   * 
   * It is recommended you set this (if needed) before you activate the module.
   * The default value is YES.
  **/
  @property (readwrite) BOOL respondsToQueries;
  
  /**
   * Send query to the server or a specific JID.
   * The disco module may be used to detect if the target supports this XEP.
   * 
   * The returned string is the queryID (the elementID of the query that was sent).
   * In other words:
   * 
   * SEND: <iq id="<returned_string>" type="get" .../>
   * RECV: <iq id="<returned_string>" type="result" .../>
   * 
   * This may be helpful if you are sending multiple simultaneous queries to the same target.
  **/
  - (NSString *)sendQueryToServer;
  - (NSString *)sendQueryToServerWithTimeout:(NSTimeInterval)timeout;
  - (NSString *)sendQueryToJID:(XMPPJID *)jid;
  - (NSString *)sendQueryToJID:(XMPPJID *)jid withTimeout:(NSTimeInterval)timeout;
  
  /**
   * Extracts the utc date from the given response/time element,
   * and returns an NSDate representation of the time in the local time zone.
   * Since the returned date is in the local time zone, it is suitable for presentation.
  **/
  + (NSDate *)dateFromResponse:(XMPPIQ *)iq;
  
  /**
   * Extracts the time zone offset from the given response/time element.
  **/
  + (NSTimeZone *)timeZoneOffsetFromResponse:(XMPPIQ *)iq;
  
  /**
   * Given the returned time response from a remote party, and the approximate round trip time,
   * calculates the difference between our clock and the remote party's clock.
   * 
   * This is NOT a reference to the difference in time zones.
   * Time zone differences generally shouldn't matter as xmpp standards mandate the use of UTC.
   * 
   * Rather this is the difference between our UTC time, and the remote party's UTC time.
   * If the two clocks are not synchronized, then the result represents the approximate difference.
   * 
   * If our clock is earlier than the remote clock, then the result will be negative.
   * If our clock is ahead of the remote clock, then the result will be positive.
   * 
   * If you later receive a timestamp from the remote party, you could add the diff.
   * For example:
   * 
   * myTime = [givenTimeFromRemoteParty dateByAddingTimeInterval:diff];
  **/
  + (NSTimeInterval)approximateTimeDifferenceFromResponse:(XMPPIQ *)iq andRTT:(NSTimeInterval)rtt;
  
  /**
   * Creates and returns a time element.
  **/
  + (NSXMLElement *)timeElement;
  + (NSXMLElement *)timeElementFromDate:(NSDate *)date;
  
  @end
  
  @protocol XMPPTimeDelegate
  @optional
  
  - (void)xmppTime:(XMPPTime *)sender didReceiveResponse:(XMPPIQ *)iq withRTT:(NSTimeInterval)rtt;
  - (void)xmppTime:(XMPPTime *)sender didNotReceiveResponse:(NSString *)queryID dueToTimeout:(NSTimeInterval)timeout;
  
  // Note: If the xmpp stream is disconnected, no delegate methods will be called, and outstanding queries are forgotten.
  
  @end
  