Hacking OS X: How to write a plugin for Safari

There is no official plugin API for Safari (or many other OS X applications), so we need to find our own way in:

1. Get Safari to load our code bundle
2. Work out which methods in Safari should trigger our code
3. Replace the relevant methods with our own

Input Managers

• Part of the text input system
• Loaded by all Cocoa applications
• Allows a Cocoa bundle to be loaded into apps at run time

Writing an Input Manager

• Two components:

  Property list file

  XML containing various settings

  Cocoa bundle

  The standard way of packaging code on OS X (a .app is a special kind of bundle)

• Both live in /Library/InputManagers/YourInputManager/

The property list

• The property list file should be called Info

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" 
	"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>BundleName</key>
	<string>MySafariPlugin.bundle</string>
	<key>LoadBundleOnLaunch</key>
	<string>YES</string>
	<key>LocalizedNames</key>
	<dict>
		<key>English</key>
		<string>MySafariPlugin</string>
	</dict>
	<key>NoMenuEntry</key>
	<string>YES</string>
</dict>
</plist>

The bundle

• The bundle's principle class should respond to +(void)load
• Use [NSBundle mainBundle] to get information about the host application
  • [[NSBundle mainBundle] bundleIdentifier] e.g. com.apple.Safari
  • [[NSBundle mainBundle] infoDictionary] for other information

Example bundle code

+ (void)load
{
	NSBundle *hostApp = [NSBundle mainBundle];

	// Check the host app is Safari
	NSString *bundleID = [hostApp bundleIdentifier];
	if(![bundleID isEqualToString:@"com.apple.Safari"])
		return;
	
	// Check this version of Safari is supported
	NSDictionary *infoDict = [hostApp infoDictionary];
	float v = [[infoDict 
		valueForKey:@"CFBundleVersion"] floatValue];
	if(v < 5528.16)
	{
		//TODO: Tell the user why the plugin hasn't loaded
		return;
	}
	
	// Initialise your plugin here...
}

SIMBL (Smart InputManager Bundle Loader)

• SIMBL is an input manager
• It loads different Bundles based on the bundle identifier (e.g. com.apple.Safari) and version of the running app
• Disadvantage: Users need to have SIMBL installed
• Advantage: Slightly easier to write your plugins
• Available from http://www.culater.net/software/SIMBL/SIMBL.php

Our code is loaded into Safari, but we want to add or modify certain behaviours.

• What classes make up Safari?
• What methods do those classes have?
• Which method(s) should our plugin replace?

Class-dump

• A command line tool that generates header files from a compiled executable.
• Available from http://www.codethecode.com/projects/class-dump/
• Example usage: class-dump -H /Applications/Safari.app/Contents/MacOS/Safari
  • The -H switch generates header files
  • Pass the path of an executable, not a .app bundle

F-Script Anywhere

• Adds an F-Script interpretter and simple GUI to any running Cocoa application
• Available from http://www.fscript.org/
• Useful for identifying specific GUI elements, delegates etc.

Other tools

Various UNIX command line tools can also be helpful:

nm

Displays the symbol table for an executable

strings

Displays any printable strings contained within a binary file

gdb

The GNU debugger

Two methods for replacing a built in Safari method with your own:

• Posing
• Method “swizzling”

Posing

• Make a subclass pose as its parent class: [[ClassB class] poseAsClass:[ClassA class]] (where ClassB is a subclass of ClassA)
• Only applies to instances created after calling poseAsClass
• Subclass cannot add any new instance variables

Method swizzling

• Use a category to add a new method to the class
• Use Objective-C's underlying C functions and structures to replace the target method with your new method

Example code

#import <objc/objc-class.h>

@implementation Swizzler

+ (BOOL)renameSelector:(SEL)oldSelector 
                    to:(SEL)newSelector 
               onClass:(Class)class
{
	Method method = class_getInstanceMethod(class, oldSelector);
	if(method == nil)
		return FALSE;

	method->method_name = newSelector;
	return TRUE;
}

@end

Usage:

[Swizzler 
	renameSelector:@selector(doSomething) 
	to:@selector(myplugin_old_doSomething) 
	onClass:[MyClass class]];
	
[Swizzler 
	renameSelector:@selector(myplugin_new_doSomething) 
	to:@selector(doSomething) 
	onClass:[MyClass class]];

• Multiple plugins can swizzle the same methods but must use unique names
• Use your plugin name as a prefix to prevent conflicts

Linker settings

• Safari's internal classes aren't defined anywhere in your bundle
• Need to convince the linker the headers are enough, it doesn't need implementations
• Add -undefined dynamic_lookup to Other Linker Flags

Source code for a demonstration plugin is available on GitHub: github.com/georgebrock/bcl6-safari-plugin-demo

The demo code is released under a Creative Commons attribution license, so you can do almost anything you want with it.