Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
An Objective-C wrapper for Mac OS X’s FSEvents C API.
Objective-C Shell Ruby
Pull request Compare This branch is 55 commits behind develop.

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
CDEvents.xcodeproj
English.lproj
TestApp
.gitattributes
.gitignore
CDEvent.h
CDEvent.m
CDEvents.h
CDEvents.m
CDEventsDelegate.h
CDEventsTestApp-Info.plist
CDEvents_Prefix.pch
Info.plist
README.mdown
api.doxygen
compat.h
version.plist

README.mdown

CDEvents Project status

Note: Experimental ARC branch

What is this?

It's an Objective-C wrapper for Mac OS X's FSEvents C API. Inspired and based upon the (MIT-licensed) open source project SCEvents created by Stuart Connolly.

Requirements

Requires Mac OS X 10.6 (Snow Leopard) and an Intel 64-bit CPU. The requirements stems from that automatic reference counting (ARC) is supported from 10.6 and up as long as the modern (i.e. 64-bit) Objective-C runtime is used. (ARC requires the non-fragile ABI.) Although the built product should work on 10.6 and up it must be built on a machine running 10.7 (Lion) using Xcode 4.2 and the 10.7 SDK as the 10.6 SDK does not include ARC. Supports both manual memory management and automatic reference counting.

If you need to support older versions of OS X please see the non-ARC branch, currently develop and master. Though which branch is the non-ARC will probably change in the future.

Usage

  1. Add CDEvents to your project,
    • either by compiling the project and dragging the CDEvents.framework into your project or
    • by dragging the entire CDEvents project into your project as a sub-project.
  2. Import the CDEvents.h header where you need it.
  3. Import the CDEventsDelegate.h header where you need it (i.e. in the file which declares your delegate).
  4. See the test app (TestApp) for details on how to use the framework. Essentially it boils down to,
    1. Implement the delegate method -URLWatcher:eventOccurred:.
    2. Set up your CDEvents instance.

self.events = [[CDEvents alloc] initWithURLs:<NSArray of URLs to watch>
                                    delegate:<Your delegate>
                                   onRunLoop:[NSRunLoop currentRunLoop]
                        sinceEventIdentifier:kCDEventsSinceEventNow
                        notificationLantency:CD_EVENTS_DEFAULT_NOTIFICATION_LATENCY
                     ignoreEventsFromSubDirs:CD_EVENTS_DEFAULT_IGNORE_EVENT_FROM_SUB_DIRS
                                 excludeURLs:<NSArray of URLs to exlude>
                         streamCreationFlags:kCDEventsDefaultEventStreamFlags];

Important: Since we have 10.6 set as the deployment target automatic zeroing of weak references is not available and as such you must set the delegate of CDEvents to nil when you no longer want to receive events. That is, at least in your -dealloc method. This is also required when using 10.7 and up!

For more details please refer to the documentation in the header files and the section "API documentation" below.

What differentiates CDEvents from SCEvents then?

Not all that much but a few things differentiate the two. The (event data wrapper) class CDEvent is immutable in contrast to SCEvent which is mutable. The next difference, which were the initial reason why I decided to rewrite SCEvents is that the class SCEvents' is a singleton class, where's CDEvents is a "normal" class. I couldn't find a good reason as to why SCEvents had been designed that way and for my project a "normal" non-singleton class would be and is better.

Another difference between CDEvents and SCEvents is that CDEvents is available for both manual memory management and environments using garbage collection.

So I've written some of the code from scratch and "borrowed" some from SCEvents.

API documentation

You can generate API documentation with the help of Doxygen. In Doxygen open the file api.doxygen, click the Run tab and then the Run doxygen button. When it's done you should have a directory (ignored by git) in the root of the project named api with a sub-directory html in which you will find index.html double-click and enjoy.

Authors

  • Aron Cedercrantz

License

The code is released under the MIT-license.

If you want, even though you really don't have to, I would love hearing what you use CDEvents for! Send me an email (first name @ last name dot se) or a message via GitHub.

Something went wrong with that request. Please try again.