nSync Plugin Developers' Reference

nSync plugins are implemented as Cocoa bundles. Your plugin's primary class will subclass nSync's SyncPlugin class. Below is a description of the nSync classes your plugin will interact with.

Newton.h

These are the methods in the Newton class that are relevant to plugin development.

- (void)setCurrentSoup:(NSString *)theSoup;

Invoke this method to request access to a given soup. theSoup should be the name of the soup you want to access. The Newt will respond by invoking the plugin's currentSoupChanged method

- (void)executeScript:(NSString *)theScript;

Use this method to execute a snippet of NewtonScript code on the Newt. The Newt will respond by invoking the plugin's receivedScriptResults method.

theScript should not be longer than 500 characters

- (void)executeScripts:(NSArray *)theScripts;

Similar to executeScript. theScripts should be an array of NSString objects. The scripts will be executed in order. The Newt will respond by invoking the plugin's receivedScriptResults method with the results of the last script.

- (void)getRecordCount;

Call this method after you have called setCurrentSoup. The Newt will respond by calling the plugin's receivedRecordCount method.

- (void)getNextRecord;

Request the next record from the Newt. The Newt will respond by calling the plugin's receivedNextRecord method.

- (void)getRecordsDeletedFromCache:(NSArray *)cache;

// calls receivedDeletedRecordsList:(NSArray *)deletedRecords with deleted records

- (void)deleteRecords:(NSArray *)recordUIDs;

// deletes the specified UIDs and calls deletedNewtonRecords when done

- (void)getCurrentTime;

// calls gotTime:(int)theTime when done

- (void)logEntry:(NSString *)theEntry;

// writes theEntry to the log file

SyncWinController.h

plugins can manipulate the nSync UI to a imited extent via the SyncWinController class. These are the methods in the SyncWinController class that are relevant to plugin development.

- (void)setNumRecords:(int)numRecords;

Use this method to initialize your plugin's progress bar. numRecords should be the total number of items you intend to sync.

- (void)advanceProgressBar;

Invoke this method each time you complete the sync of an item. It will advance your plugin's progress bar one step.

- (void)handleNextPlugin;

Call this method only once, when your plugin is completely finished. Invoking this method will cause nSync to proceed on to the next plugin.

MyPlugin.h

Your plugin will be a subclass of nSync's SyncPlugin class. There are two methods that you must override for your plugin to be useful. The header file for a very minimal plugin might look like this...

#import "SyncPlugin.h"

@interface SyncAddressBook : SyncPlugin
{
  int state;
  int numNeedingSync;
  int numSynced;
}

- (void)synchronizeWithNewton;
- (BOOL)willRunFirst;

@end

MyPlugin.m

Plugins are most effectively written as state machines due to the callback nature of the API. Here is an example of the basic steps most plugins go through to do their job. This is a simple example and therefore not necessarily a state machine, but for illustative purposes, basic state code is included.

#import "MyPlugin.h"
#import "SyncConnectWinController.h"
#import "Newton.h"

@implementation SyncAddressBook

+ (void)initialize
{
  // here you can setup any user defaults your plugin makes use of
}

- (id)init
{
  if (self = [super init]) 
  {
    // initialize your plugin's instance variables
  }
  return self;
}

- (void)awakeFromNib
{
  // here you should set up your plugin's settings GUI
}

//
//  this method should always return NO
//
- (BOOL)willRunFirst
{
  return NO;
}

- (void)synchronizeWithNewton
{
  // nSync will call this method to invoke your plugin
  // begin your sync procedure here

  numNeedingSync = 0;
  numSynced = 0;

  state = kSettingSoupState;

  // this call will cause the Newt to invoke currentSoupChanged
  [[self myNewton] setCurrentSoup:@"aSoupName"];
}

- (void)currentSoupChanged
{
  // this call will cause the Newt to invoke receivedRecordCount
  [[self myNewton] getRecordCount];
}

- (void)receivedRecordCount:(int)count
{
  numNeedingSync = count;
  [[self myConnectWinController] setNumRecords: count];

  // this call will cause the Newt to invoke receivedNextRecord
  [[self myNewton] getNextRecord];
}

- (void)receivedNextRecord:(id)record
{
  // do some processing on the record

  state = kSyncingNewtRecordState;

  // this call will cause the Newt to invoke receivedScriptResults
  [[self myNewton] executeScript: @"a NS snippet"];
}

- (void)receivedScriptResults:(NSString *)theResults
{
  if( state == kSyncingNewtRecordState )
  {
    numSynced++;
    [[self myConnectWinController] advanceProgressBar];

    if( numSynced == numNeedingSync )
      [[self myConnectWinController] handleNextPlugin];
    else
      // this call will cause the Newt to invoke receivedNextRecord
      [[self myNewton] getNextRecord];
  }
  else
  {
    . . .
  }
}

@end