Commit: 79c2467b9f4ffdde60ba411813a52db75bdcd157 - CDEvents (git)

An Objective-C wrapper for Mac OS X’s FSEvents C API.

Commit MetaInfo

• Révision: 79c2467b9f4ffdde60ba411813a52db75bdcd157 (tree)
• l'heure: 2010-04-10 23:29:31
• Auteur: Aron Cedercrantz <aron@cede...>
• Commiter: Aron Cedercrantz

Message de Log

Merge branch 'release/1.1.0'

Change Summary

• modified: CDEvent.h
• modified: CDEvent.m
• modified: CDEvents.h
• modified: CDEvents.m
• modified: CDEvents.xcodeproj/project.pbxproj
• modified: Info.plist

Modification

--- a/CDEvent.h
+++ b/CDEvent.h
@@ -119,6 +119,238 @@ typedef FSEventStreamEventFlags CDEventFlags;
  */
 @property (readonly) CDEventFlags				flags;
 
+#pragma mark Specific flag properties
+/**
+ * Wheter there was some change in the directory at the specific path supplied in this event.
+ *
+ * @return <code>YES</code> if there was some change in the directory, otherwise <code>NO</code>
+ *
+ * @see kFSEventStreamEventFlagNone
+ * @see flags
+ * @see mustRescanSubDirectories
+ * @see isUserDropped
+ * @see isKernelDropped
+ * @see isEventIdsWrapped
+ * @see isHistoryDone
+ * @see isRootChanged
+ * @see didVolumeMount
+ * @see didVolumeUnmount
+ *
+ * @since 1.1.0
+ */
+@property (readonly) BOOL						isGenericChange;
+
+/**
+ * Wheter you must rescan the whole URL including its children.
+ *
+ * Wheter your application must rescan not just the URL given in the event, but
+ * all its children, recursively. This can happen if there was a problem whereby
+ * events were coalesced hierarchically. For example, an event in
+ * <code>/Users/jsmith/Music</code> and an event in
+ * <code>/Users/jsmith/Pictures</code> might be coalesced into an event with
+ * this flag set and <i>URL</i><code>=/Users/jsmith</code>. If this flag is set
+ * you may be able to get an idea of whether the bottleneck happened in the
+ * kernel (less likely) or in your client (more likely) by checking if
+ * flagUserDropped or flagKernelDropped returns <code>YES</code>.
+ *
+ * @return <code>YES</code> if you must rescan the whole directory including its children, otherwise <code>NO</code>
+ *
+ * @see kFSEventStreamEventFlagMustScanSubDirs
+ * @see flags
+ * @see isGenericChange
+ * @see isUserDropped
+ * @see isKernelDropped
+ * @see isEventIdsWrapped
+ * @see isHistoryDone
+ * @see isRootChanged
+ * @see didVolumeMount
+ * @see didVolumeUnmount
+ *
+ * @since 1.1.0
+ */
+@property (readonly) BOOL						mustRescanSubDirectories;
+
+/**
+ * Provides some information as to what might have caused the need to rescan the URL including its children.
+ *
+ * @return <code>YES</code> if mustRescanSubDirectories returns <code>YES</code> and the cause were in userland, otherwise <code>NO</code>
+ *
+ * @see kFSEventStreamEventFlagUserDropped
+ * @see flags
+ * @see isGenericChange
+ * @see mustRescanSubDirectories
+ * @see isKernelDropped
+ * @see isEventIdsWrapped
+ * @see isHistoryDone
+ * @see isRootChanged
+ * @see didVolumeMount
+ * @see didVolumeUnmount
+ *
+ * @since 1.1.0
+ */
+@property (readonly) BOOL						isUserDropped;
+
+/**
+ * Provides some information as to what might have caused the need to rescan the URL including its children.
+ *
+ * @return <code>YES</code> if mustRescanSubDirectories returns <code>YES</code> and the cause were in kernelspace, otherwise <code>NO</code>
+ *
+ * @see kFSEventStreamEventFlagKernelDropped
+ * @see flags
+ * @see isGenericChange
+ * @see mustRescanSubDirectories
+ * @see isUserDropped
+ * @see isEventIdsWrapped
+ * @see isHistoryDone
+ * @see isRootChanged
+ * @see didVolumeMount
+ * @see didVolumeUnmount
+ *
+ * @since 1.1.0
+ */
+@property (readonly) BOOL						isKernelDropped;
+
+/**
+ * Wheter the 64-bit event identifier counter has wrapped around.
+ *
+ * Wheter the 64-bit event identifier counter has wrapped around. As a result,
+ * previously-issued event identifiers are no longer valid arguments for the
+ * sinceEventIdentifier parameter of the CDEvents init methods.
+ *
+ * @return <code>YES</code> if the 64-bit event identifier counter has wrapped around, otherwise <code>NO</code>
+ *
+ * @see kFSEventStreamEventFlagEventIdsWrapped
+ * @see flags
+ * @see isGenericChange
+ * @see mustRescanSubDirectories
+ * @see isUserDropped
+ * @see isKernelDropped
+ * @see isHistoryDone
+ * @see isRootChanged
+ * @see didVolumeMount
+ * @see didVolumeUnmount
+ *
+ * @since 1.1.0
+ */
+@property (readonly) BOOL						isEventIdentifiersWrapped;
+
+/**
+ * Denotes a sentinel event sent to mark the end of the "historical" events sent.
+ *
+ * Denotes a sentinel event sent to mark the end of the "historical" events sent
+ * as a result of specifying a <i>sinceEventIdentifier</i> argument other than
+ * kCDEventsSinceEventNow with the CDEvents init methods.
+ *
+ * @return <code>YES</code> if if the event is sent to mark the end of the "historical" events sent, otherwise <code>NO</code>
+ *
+ * @see kFSEventStreamEventFlagHistoryDone
+ * @see flags
+ * @see isGenericChange
+ * @see mustRescanSubDirectories
+ * @see isUserDropped
+ * @see isKernelDropped
+ * @see isEventIdsWrapped
+ * @see isRootChanged
+ * @see didVolumeMount
+ * @see didVolumeUnmount
+ * @see kCDEventsSinceEventNow
+ * @see CDEvents
+ *
+ * @since 1.1.0
+ */
+@property (readonly) BOOL						isHistoryDone;
+
+/**
+ * Denotes a special event sent when there is a change to one of the URLs you asked to watch.
+ *
+ * Denotes a special event sent when there is a change to one of the URLs you
+ * asked to watch. When this method returns <code>YES</code>, the event
+ * identifier is zero and the <code>URL</code> corresponds to one of the URLs
+ * you asked to watch (specifically, the one that changed). The URL may no
+ * longer exist because it or one of its parents was deleted or renamed. Events
+ * with this flag set will only be sent if you passed the flag
+ * <code>kFSEventStreamCreateFlagWatchRoot</code> to the CDEvents.
+ *
+ * @return <code>YES</code> if there is a change to one of the URLs you asked to watch, otherwise <code>NO</code>
+ *
+ * @see kFSEventStreamEventFlagRootChanged
+ * @see flags
+ * @see isGenericChange
+ * @see mustRescanSubDirectories
+ * @see isUserDropped
+ * @see isKernelDropped
+ * @see isEventIdsWrapped
+ * @see isHistoryDone
+ * @see didVolumeMount
+ * @see didVolumeUnmount
+ * @see CDEvents
+ * @see kCDEventsDefaultEventStreamFlags
+ *
+ * @since 1.1.0
+ */
+@property (readonly) BOOL						isRootChanged;
+
+/**
+ * Denotes a special event sent when a volume is mounted underneath one of the URLs being watched.
+ *
+ * Denotes a special event sent when a volume is mounted underneath one of the
+ * URLs being watched. The URL in the event is the URL to the newly-mounted
+ * volume. You will receive one of these notifications for every volume mount
+ * event inside the kernel (independent of DiskArbitration). Beware that a
+ * newly-mounted volume could contain an arbitrarily large directory hierarchy.
+ * Avoid pitfalls like triggering a recursive scan of a non-local filesystem,
+ * which you can detect by checking for the absence of the
+ * <code>MNT_LOCAL</code> flag in the <code>f_flags</code> returned by statfs().
+ * Also be aware of the <code>MNT_DONTBROWSE</code> flag that is set for volumes
+ * which should not be displayed by user interface elements.
+ *
+ * @return <code>YES</code> if a volumen is mounted underneath one of the URLs being watched, otherwise <code>NO</code>
+ *
+ * @see kFSEventStreamEventFlagMount
+ * @see flags
+ * @see isGenericChange
+ * @see mustRescanSubDirectories
+ * @see isUserDropped
+ * @see isKernelDropped
+ * @see isEventIdsWrapped
+ * @see isHistoryDone
+ * @see isRootChanged
+ * @see didVolumeUnmount
+ *
+ * @since 1.1.0
+ */
+@property (readonly) BOOL						didVolumeMount;
+
+/**
+ * Denotes a special event sent when a volume is unmounted underneath one of the URLs being watched.
+ *
+ * Denotes a special event sent when a volume is unmounted underneath one of the
+ * URLs being watched. The URL in the event is the URL to the directory from
+ * which the volume was unmounted. You will receive one of these notifications
+ * for every volume unmount event inside the kernel. This is not a substitute
+ * for the notifications provided by the DiskArbitration framework; you only get
+ * notified after the unmount has occurred. Beware that unmounting a volume
+ * could uncover an arbitrarily large directory hierarchy, although Mac OS X
+ * never does that.
+ *
+ * @return <code>YES</code> if a volume is unmounted underneath one of the URLs being watched, otherwise <code>NO</code>
+ *
+ * @see kFSEventStreamEventFlagUnmount
+ * @see flags
+ * @see isGenericChange
+ * @see mustRescanSubDirectories
+ * @see isUserDropped
+ * @see isKernelDropped
+ * @see isEventIdsWrapped
+ * @see isHistoryDone
+ * @see isRootChanged
+ * @see didVolumeMount
+ *
+ * @since 1.1.0
+ */
+@property (readonly) BOOL						didVolumeUnmount;
+
+
 #pragma mark Class object creators
 
 /**

--- a/CDEvent.m
+++ b/CDEvent.m
@@ -53,7 +53,6 @@
 
 
 #pragma mark Init/dealloc methods
-
 - (void)dealloc
 {
 	[_date release];
@@ -79,7 +78,6 @@
 
 
 #pragma mark NSCoding methods
-
 - (void)encodeWithCoder:(NSCoder *)aCoder
 {
 	[aCoder encodeObject:[NSNumber numberWithUnsignedInteger:[self identifier]] forKey:@"identifier"];
@@ -98,16 +96,62 @@
 	return self;
 }
 
-#pragma mark NSCopying methods
 
+#pragma mark NSCopying methods
 - (id)copyWithZone:(NSZone *)zone
 {
 	// We can do this since we are immutable.
 	return [self retain];
 }
 
-#pragma mark Public API
 
+#pragma mark Specific flag properties 
+- (BOOL)isGenericChange
+{
+	return (kFSEventStreamEventFlagNone == _flags);
+}
+
+- (BOOL)mustRescanSubDirectories
+{
+	return (_flags & kFSEventStreamEventFlagMustScanSubDirs);
+}
+
+- (BOOL)isUserDropped
+{
+	return (_flags & kFSEventStreamEventFlagUserDropped);
+}
+
+- (BOOL)isKernelDropped
+{
+	return (_flags & kFSEventStreamEventFlagKernelDropped);
+}
+
+- (BOOL)isEventIdentifiersWrapped
+{
+	return (_flags & kFSEventStreamEventFlagEventIdsWrapped);
+}
+
+- (BOOL)isHistoryDone
+{
+	return (_flags & kFSEventStreamEventFlagHistoryDone);
+}
+
+- (BOOL)isRootChanged
+{
+	return (_flags & kFSEventStreamEventFlagRootChanged);
+}
+
+- (BOOL)didVolumeMount
+{
+	return (_flags & kFSEventStreamEventFlagMount);
+}
+
+- (BOOL)didVolumeUnmount
+{
+	return (_flags & kFSEventStreamEventFlagUnmount);
+}
+
+#pragma mark Misc
 - (NSString *)description
 {
 	return [NSString stringWithFormat:@"<%@: %p { identifier = %ld, URL = %@, flags = %ld, date = %@ }>",

--- a/CDEvents.h
+++ b/CDEvents.h
@@ -84,10 +84,17 @@ extern NSString *const CDEventsEventStreamCreationFailureException;
  *
  * @since 1.0.0
  */
-const NSUInteger kCDEventsDefaultEventStreamFlags =
+const CDEventsEventStreamCreationFlags kCDEventsDefaultEventStreamFlags =
 	(kFSEventStreamCreateFlagUseCFTypes |
 	 kFSEventStreamCreateFlagWatchRoot);
 
+/**
+ * Use this to get all event since now when initializing a CDEvents object.
+ *
+ * @since 1.1.0
+ */
+const CDEventIdentifier kCDEventsSinceEventNow = kFSEventStreamEventIdSinceNow;
+
 
 #pragma mark -
 #pragma mark CDEvents interface
@@ -198,19 +205,6 @@ const NSUInteger kCDEventsDefaultEventStreamFlags =
  */
 + (CDEventIdentifier)currentEventIdentifier;
 
-/**
- * The last event identifier for the given device that was returned before the given date and time
- *
- * @param URL The URL of the item the event identifier is sought for, used to find the device.
- * @param time The date and time.
- * @return The last event identifier for the given URL that was returned before the given time
- *
- * @see FSEventsGetLastEventIdForDeviceBeforeTime(dev_t, CFAbsoluteTime)
- *
- * @since 1.1.0
- */
-+ (CDEventIdentifier)lastEventIdentifierForURL:(NSURL *)URL time:(NSDate *)time;
-
 
 #pragma mark Init methods
 /**
@@ -226,10 +220,11 @@ const NSUInteger kCDEventsDefaultEventStreamFlags =
  * @see initWithURLs:delegate:onRunLoop:
  * @see initWithURLs:delegate:onRunLoop:notificationLantency:ignoreEventsFromSubDirs:excludeURLs:streamCreationFlags:
  * @see kCDEventsDefaultEventStreamFlags
+ * @see kCDEventsSinceEventNow
  *
  * @discussion Calls startWatchingURLs:onRunLoop:notificationLantency:ignoreEventsFromSubDirs:excludeURLs:streamCreationFlags:
- * with <em>sinceEventIdentifier</em> with the current event identifier,
- * <em>notificationLatency</em> set to 3.0 seconds,
+ * with <em>sinceEventIdentifier</em> with the event identifier for "event since
+ * now", <em>notificationLatency</em> set to 3.0 seconds,
  * <em>ignoreEventsFromSubDirectories</em> set to <code>NO</code>,
  * <em>excludedURLs</em> to no URLs, the event stream creation flags will be set
  * to <code>kCDEventsDefaultEventStreamFlags</code> and schedueled on the
@@ -253,13 +248,14 @@ const NSUInteger kCDEventsDefaultEventStreamFlags =
  * @see initWithURLs:
  * @see initWithURLs:onRunLoop:notificationLantency:ignoreEventsFromSubDirs:excludeURLs:streamCreationFlags:
  * @see kCDEventsDefaultEventStreamFlags
+ * @see kCDEventsSinceEventNow
  *
  * @discussion Calls startWatchingURLs:onRunLoop:notificationLantency:ignoreEventsFromSubDirs:excludeURLs:streamCreationFlags:
  * with <em>runLoop</em> set to the current run loop, <em>sinceEventIdentifier</em>
- * with the current event identifier, <em>notificationLatency</em> set to 3.0
- * seconds, <em>ignoreEventsFromSubDirectories</em> set to <code>NO</code>, 
- * <em>excludedURLs</em> to no URLs and the event stream creation flags will be
- * set to <code>kCDEventsDefaultEventStreamFlags</code>.
+ * with the event identifier for "event since now", <em>notificationLatency</em>
+ * set to 3.0 seconds, <em>ignoreEventsFromSubDirectories</em> set to
+ * <code>NO</code>, <em>excludedURLs</em> to no URLs and the event stream
+ * creation flags will be set to <code>kCDEventsDefaultEventStreamFlags</code>.
  *
  * @since 1.0.0
  */

--- a/CDEvents.m
+++ b/CDEvents.m
@@ -94,7 +94,7 @@ static void CDEventsCallback(
 	return [self initWithURLs:URLs
 					 delegate:delegate
 					onRunLoop:runLoop
-		 sinceEventIdentifier:[CDEvents currentEventIdentifier]
+		 sinceEventIdentifier:kCDEventsSinceEventNow
 		 notificationLantency:CD_EVENTS_DEFAULT_NOTIFICATION_LATENCY
 	  ignoreEventsFromSubDirs:CD_EVENTS_DEFAULT_IGNORE_EVENT_FROM_SUB_DIRS
 				  excludeURLs:nil

--- a/CDEvents.xcodeproj/project.pbxproj
+++ b/CDEvents.xcodeproj/project.pbxproj
@@ -325,6 +325,7 @@
 				GCC_OPTIMIZATION_LEVEL = 0;
 				GCC_PRECOMPILE_PREFIX_HEADER = YES;
 				GCC_PREFIX_HEADER = CDEvents_Prefix.pch;
+				GCC_PREPROCESSOR_DEFINITIONS = NS_BUILD_32_LIKE_64;
 				GCC_VERSION = "";
 				INFOPLIST_FILE = Info.plist;
 				INSTALL_PATH = "@loader_path/../Frameworks";
@@ -345,6 +346,7 @@
 				GCC_MODEL_TUNING = G5;
 				GCC_PRECOMPILE_PREFIX_HEADER = YES;
 				GCC_PREFIX_HEADER = CDEvents_Prefix.pch;
+				GCC_PREPROCESSOR_DEFINITIONS = NS_BUILD_32_LIKE_64;
 				GCC_VERSION = "";
 				INFOPLIST_FILE = Info.plist;
 				INSTALL_PATH = "@loader_path/../Frameworks";
@@ -401,6 +403,7 @@
 				GCC_OPTIMIZATION_LEVEL = 0;
 				GCC_PRECOMPILE_PREFIX_HEADER = YES;
 				GCC_PREFIX_HEADER = "$(SYSTEM_LIBRARY_DIR)/Frameworks/AppKit.framework/Headers/AppKit.h";
+				GCC_PREPROCESSOR_DEFINITIONS = NS_BUILD_32_LIKE_64;
 				INFOPLIST_FILE = "CDEventsTestApp-Info.plist";
 				INSTALL_PATH = "$(HOME)/Applications";
 				OTHER_LDFLAGS = (
@@ -425,6 +428,7 @@
 				GCC_MODEL_TUNING = G5;
 				GCC_PRECOMPILE_PREFIX_HEADER = YES;
 				GCC_PREFIX_HEADER = "$(SYSTEM_LIBRARY_DIR)/Frameworks/AppKit.framework/Headers/AppKit.h";
+				GCC_PREPROCESSOR_DEFINITIONS = NS_BUILD_32_LIKE_64;
 				INFOPLIST_FILE = "CDEventsTestApp-Info.plist";
 				INSTALL_PATH = "$(HOME)/Applications";
 				OTHER_LDFLAGS = (

--- a/Info.plist
+++ b/Info.plist
@@ -21,7 +21,7 @@
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleVersion</key>
-	<string>1.0.3</string>
+	<string>1.1.0</string>
 	<key>NSPrincipalClass</key>
 	<string></string>
 </dict>