Adium

Note: This article is taken from a cache of Toby Peterson's site. Now that the OpenDarwin project has shut down, his original article is no longer available. The original stylesheet and images have been lost.

The copyright contained Toby's direct email at opendarwin, and other locations. In the interest of not having him spammed to death, it has been removed.

Also note, Toby has not worked with the Adium project in years, and his guide is a few years old.

Creating an Adium Plugin

Introduction

Important note: Plugins use internal Adium APIs, which are in no way guaranteed to be stable. This means that plugins may need to be updated periodically to work with new Adium releases.

This tutorial assumes familiarity with Xcode and Objective-C. The instructions apply to Xcode 2.0, so there may be slight variations in earlier Xcode releases. Throughout the tutorial, the example plugin will be referred to as SampleAdiumPlugin, with a principal class of the same name.

Xcode Setup

Step 1: Compiling Adium

In order to start developing an Adium plugin, you'll need to compile Adium first. If you don't know how to do this, you aren't ready to write a plugin.

Step 2: Creating a Project

From the File menu, choose New Project... (⇧⌘N) and create a Cocoa Bundle.

From the Project menu, choose Edit Active Target 'SampleAdiumPlugin' (⌥⌘E).

Now, go to the Properties tab and set the principal class. We will create this class later.

Also, be sure to set the bundle identifier and the creator code. The creator code should be 'AdIM'.

Image of properties tab not available.

Now, go to the Build tab and make the following changes. $(ADIUM) is the location of your adium checkout, so this will vary depending upon your setup. Note: the double quotes are intentional, due to the spaces in the filenames.

Setting Value
Header Search Paths $(ADIUM)/Source
Framework Search Paths $(ADIUM)/build "$(ADIUM)/Frameworks/AIUtilities Framework/build"
Wrapper Extension AdiumPlugin
Installation Directory "$(HOME)/Library/Application Support/Adium 2.0/PlugIns/"

Image of build tab not available.

If your plugin does not need to work on Mac OS X 10.2:
Editors note: Adium no longer supports Mac OS X 10.2.

  • Add the following build settings:
Setting Value
Other Linker Flags -undefined dynamic_lookup
Mac OS X Deployment Target Mac OS X 10.3
  • Remove all frameworks from your project's 'Frameworks and Libraries' group.

If your plugin needs to work on Mac OS X 10.2:

  • Add Adium.framework and AIUtilities.framework to your project's 'Frameworks and Libraries' group.

Step 3: Creating an AIPlugin Subclass

Finally, you need to create the plugin's principal class, which must be a subclass of AIPlugin. You specified the name of this class in the Properties tab (see above). Here's the basic template:

/* SampleAdiumPlugin.h */

#import <Adium/AIPlugin.h>
/* #import <Adium/AISharedAdium.h>  -- not needed as of Adium 1.3.3 */

@interface SampleAdiumPlugin : AIPlugin 
{

}

@end
/* SampleAdiumPlugin.m */

#import "SampleAdiumPlugin.h"

@implementation SampleAdiumPlugin

- (void)installPlugin
{
    
}

- (void)uninstallPlugin
{
    
}

@end

Add these files to the project, and you'll be ready to start doing real work.

At this point you should be able to build your plugin in Xcode and try installing it (simply double click on SampleAdiumPlugin.AdiumPlugin which should have been created in the build directory of the SampleAdiumPlugin project directory).

If you get an error like this

"Could not load SampleAdiumPlugin. The SampleAdiumPlugin plugin is not compatible with Adium 1.3. Please check adiumxtras.com to see if an update is available."

then you need to add to the following to SampleAdiumPlugin's Info.plist:

<key>AIMinimumAdiumVersionRequirement</key> <string>1.3</string>

Adium Reference

Important Note

As I mentioned in the introduction, Adium's internal APIs are unstable and subject to change. Be prepared to update your plugin to work with new Adium releases. That said, read on.

Core Controllers

Adium has several so-called "core controllers" which offer functionality for plugins to use.

Here's a simple example of how to access a controller.

/* SampleAdiumPlugin.m */

#import "SampleAdiumPlugin.h"
#import "AISharedAdium.h" // Contains the 'adium' ivar.
#import "AIContentController.h"

@implementation SampleAdiumPlugin

- (void)installPlugin
{
    [[adium contentController] registerChatObserver:self];
}

// AIContentController will invoke this method when appropriate.
- (NSSet *)updateChat:(AIChat *)inChat keys:(NSSet *)inModifiedKeys silent:(BOOL)silent
{
    // Do stuff.
}

@end

Core Components

Adium also has core "components" which are essentially built-in plugins. These can be accessed via the core component loader.

Again, I will illustrate with a simple code example.

/* SampleAdiumPlugin.m */

#import "SampleAdiumPlugin.h"
#import "AISharedAdium.h" // Contains the 'adium' ivar.
#import "AICoreComponentLoader.h"

@implementation SampleAdiumPlugin

- (void)installPlugin
{
    logPath = [[[adium componentLoader] pluginWithClassName:@"AILoggerPlugin"] logBasePath];
    // Do something.
}

@end

Controller Reference

This section is incomplete. Feel free to email any additions to me.
Editors note: Please make your changes directly to this Wiki page.

Account Controller

Applescriptability Controller

Contact Alerts Controller

Contact Controller

Content Controller

Debug Controller

Dock Controller

Emoticon Controller

File Transfer Controller

Interface Controller

Login Controller

Preference Controller

Sound Controller

Status Controller

Toolbar Controller

Page last modified by dreeves, 8 years ago