Original URL: http://www.theregister.co.uk/2009/09/24/mac_secrets/

Fun with CoreGraphics, Part II

Split personality framework

By Dave Jewell

Posted in Developer, 24th September 2009 10:12 GMT

Mac Secrets This month, we continue our exploration of Apple’s mysterious CoreGraphics framework, beginning with an anatomical overview. Then, I show you how to exploit the notification mechanism built into the framework.

You’d be forgiven for thinking that the CoreGraphics library is only about graphics. It actually does a lot of event-related stuff too. For example, as I’ve described in previous articles, OS X employs an undocumented symbolic hot-key mechanism which is used by many parts of the system. The actual guts of the implementation is handled inside the CoreGraphics framework.

This framework is one of the most interesting components of OS X, partly because of its split personality. As well as exporting a large number of (mostly undocumented) routines for use by client applications, CoreGraphics.framework is also the home of the window server itself. This is the WindowServer process which you can see from Activity Monitor.

When OS X starts running, launched executes the stub executable WindowServer (look at the resources inside CoreGraphics the library, itself contained inside ApplicationServices.framework). This stub, in turn, simply calls the CGXServer entry point in the framework, which starts the server. As long as the window server is running, the CGXServer call does not return.

On the client side, many of the undocumented library routines are simply wrappers around lower-level stuff - e.g. CGSSetWindowAutofillColor validates the supplied connection ID and window identifier before calling another routine, _CGSSetWindowAutofillColor, which packages up the client-supplied parameters into a Mach call, thus switching context into the server itself.

Let’s Get Notified

OK, enough with the anatomy lesson. This month, I want to show how to use the CoreGraphics notification handler. This is used quite extensively by Apple’s system-level software and internally within CoreGraphics itself.

As an example, Activity Monitor can display a list of currently running processes, including any processes which appear to have hung. In order to do this, it needs to be notified when a process becomes unresponsive, or when an unresponsive process becomes responsive again. (Yes, even Microsoft Office apps do occasionally return from the Land of Nod). To make this work, Activity Monitor calls a special CoreGraphics routine, CGSRegisterNotifyProc, specifying which notifications it wants to receive. If you think about it, this makes perfect sense: As already mentioned, CoreGraphics is responsible for event handling, so it’s well placed to know when an application has hung up.

As another example, consider the loginwindow process. Despite the name, it has a number of ongoing responsibilities after a user session has started. Amongst other things, it manages the "Force Quit" dialog (reached via the Apple menu), monitors the system for low memory and displays a warning dialog in such situations, and also implements the screen zoom facility that’s part of the Universal Access pane in System Preferences. All this works courtesy of CoreGraphics notifications.

Force Quit

The ‘Force Quit’ dialog (part of the loginwindow process) is an example of code which registers itself with the windows server in order to receive notification of when an application is launched, terminated, or hangs up

The function prototype for CGSRegisterNotifyProc looks like this:

extern CGError CGSRegisterNotifyProc (CGSNotifyProcPtr proc,

CGSNotificationType type,

void * userData);

This prototype is due to prior investigations done by Joe Ranieri of Alacatia labs. Basically, it takes three parameters. First, there's a pointer to the notification procedure (supplied by you) that’s called from CoreGraphics when a notification is received. This parameter cannot be nil. The type parameter refers to an enumerated type (or simple integer if you prefer) which indicates what specific notification you want.

If you wish to receive, say, three different notifications, then you must call CGSRegisterNotifyProc once for each of them.

The final parameter, userData, is passed to the notification procedure so that you can re-establish the calling context. You can pass nil here, but typically, you’d pass self as this parameter, so that you can then make method calls on your class from within the notification procedure.

Cross-application notifications

Different applications can register for the same notifications (e.g., loginwindow and Activity Monitor are both interested in when new processes start running or existing processes die), and you can even register for the same notification more than once from different classes within the same program. In this specific case, though, you really would have to make use of the userData parameter to determine which object is interested in the notification - if you see what I mean.

To unregister a notification procedure (typically you’d do this in your object’s dealloc method), use the CGSRemoveNotifyProc call. This routine has the exact same function prototype as CGSRegisterNotifyProc - just pass the same three parameters.

The notification procedure type looks like this:

typedef void (* CGSNotifyProcPtr)(CGSNotificationType type, void * data, NSUInteger dataLength, void *userData);

In other words, the first parameter is the notification type, corresponding to the second parameter to CGSRegisterNotifyProc. The last parameter, userData, will be whatever you passed as the third parameter to CGSRegisterNotifyProc.

You’ll probably want to use the same notification procedure for several different notifications, in which case you can check the first parameter to see what notification you’re dealing with. Obviously, if you’ve only registered one notification for each notification procedure, the check is superfluous.

The "meat" of the notification is in the data and dataLength parameters. The significance of these parameters varies depending upon the notification type that’s being received. More on that next time. The bad news is that I’ve said so much, I’m out of space. There’s no sample project this time, but next month I’ll provide source for an app which receives CoreGraphics notifications, and I’ll delineate some of the notification types available. I’ll also wrap up this mini-series on CoreGraphics by pointing you to some of the other goodies contained therein. ®