Permalink
Browse files

Adding XMPPAutoTime - Can be used to automatically keep track of the …

…difference between client and server's system clock.
  • Loading branch information...
robbiehanson committed Aug 10, 2011
1 parent e59b9e5 commit d560d0fbd318999936596380cfc78c85a058f8cb
@@ -0,0 +1,98 @@
+#import "XMPP.h"
+#import "XMPPTime.h"
+
+@class XMPPJID;
+
+/**
+ * The XMPPAutoTime module monitors the time difference between our machine and the target.
+ * The target may simply be the server, or a specific resource.
+ *
+ * The module works by sending time queries to the target, and tracking the responses.
+ * The module will automatically send multiple queuries, and take into account the average RTT.
+ * It will also automatically update itself on a customizable interval, and whenever the machine's clock changes.
+ *
+ * This module is helpful when you are using timestamps from the target.
+ * For example, you may be receiving offline messages from your server.
+ * However, all these offline messages are timestamped from the server's clock.
+ * And the current machine's clock may vary considerably from the server's clock.
+ * Timezone differences don't matter as UTC is always used in XMPP, but clocks can easily differ.
+ * This may cause the user some confusion as server timestamps may reflect a time in the future,
+ * or much longer ago than in reality.
+**/
+@interface XMPPAutoTime : XMPPModule
+{
+ NSTimeInterval recalibrationInterval;
+ XMPPJID *targetJID;
+ NSTimeInterval timeDifference;
+
+ dispatch_time_t lastCalibrationTime;
+ dispatch_source_t recalibrationTimer;
+
+ BOOL awaitingQueryResponse;
+ XMPPTime *xmppTime;
+
+ NSData *lastServerAddress;
+
+ NSDate *systemUptimeChecked;
+ NSTimeInterval systemUptime;
+}
+
+/**
+ * How often to recalibrate the time difference.
+ *
+ * The module will automatically calculate the time difference when it is activated,
+ * or when it first sees the xmppStream become authenticated (whichever occurs first).
+ * After that first calculation, it will update itself according to this interval.
+ *
+ * To temporarily disable recalibration, set the interval to zero.
+ *
+ * The default recalibrationInterval is 24 hours.
+**/
+@property (readwrite) NSTimeInterval recalibrationInterval;
+
+/**
+ * The target to query.
+ *
+ * If the targetJID is nil, this implies the target is the xmpp server we're connected to.
+ * If the targetJID is non-nil, it must be a full JID (user@domain.tld/rsrc).
+ *
+ * The default targetJID is nil.
+**/
+@property (readwrite, retain) XMPPJID *targetJID;
+
+/**
+ * Returns the calculated time difference between our machine and the target.
+ *
+ * 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 value will be negative.
+ * If our clock is ahead of the remote clock, then the value will be positive.
+ *
+ * If you later receive a timestamp from the remote party, you can simply add the diff.
+ * For example:
+ *
+ * myTime = [givenTimeFromRemoteParty dateByAddingTimeInterval:diff];
+**/
+@property (readonly) NSTimeInterval timeDifference;
+
+/**
+ * The last time we've completed a calibration.
+**/
+@property (readonly) dispatch_time_t lastCalibrationTime;
+
+@end
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+#pragma mark -
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+@protocol XMPPAutoTimeDelegate
+@optional
+
+- (void)xmppAutoTime:(XMPPAutoTime *)sender didUpdateTimeDifference:(NSTimeInterval)timeDifference;
+
+@end
Oops, something went wrong.

0 comments on commit d560d0f

Please sign in to comment.