For my application, I needed a much more accurate filtering capability, so I started to dig around to see what I could find. I found an excellent starting blog post followed up by another more advanced post that gave me some really good background information.

These two blog posts also sowed the seed that inspired this post.

Back To Coding

As far as I know, you cannot add time support to your NSPredicateEditor rows using Interface Builder in Xcode4. You need to drop back into code… come on in, the water is fine

As outlined in the previously referenced posts, each NSPredicateEditorRowTemplate is responsible for providing the individual controls by overriding the templateView method. As you can see from the above screenshot, this method normally returns an array containing the following controls: NSPopupButton, NSPopupButton and NSDatePicker respectively.

In order to facilitate time support, we are going to create a subclass of NSPredicateEditorRowTemplate and modify the third element to change the date components that are displayed.

Creating our subclass

#import <Cocoa/Cocoa.h>
 
@interface BDTimestampRowTemplate : NSPredicateEditorRowTemplate
 
-(id)initWithLeftExpressions:(NSArray *)leftExpressions;
 
@end

#import "BDTimestampRowTemplate.h"
 
@implementation BDTimestampRowTemplate
 
-(id)initWithLeftExpressions:(NSArray *)leftExpressions {
	NSAttributeType rightType = NSDateAttributeType;
	NSComparisonPredicateModifier modifier = NSDirectPredicateModifier;
	NSArray *operators = [NSArray arrayWithObjects:
	                       [NSNumber numberWithUnsignedInteger:NSLessThanPredicateOperatorType],
	                       [NSNumber numberWithUnsignedInteger:NSLessThanOrEqualToPredicateOperatorType],
	                       [NSNumber numberWithUnsignedInteger:NSGreaterThanPredicateOperatorType],
	                       [NSNumber numberWithUnsignedInteger:NSGreaterThanOrEqualToPredicateOperatorType],
	                       [NSNumber numberWithUnsignedInteger:NSEqualToPredicateOperatorType],
	                       [NSNumber numberWithUnsignedInteger:NSNotEqualToPredicateOperatorType],
	                       nil];
	NSUInteger options = 0;
	return [super initWithLeftExpressions:leftExpressions rightExpressionAttributeType:rightType modifier:modifier operators:operators options:options];
}
 
-(NSArray *)templateViews {
	// get the list of views in the template 
	NSArray *views = [super templateViews];
	// get out the date picker control
	NSDatePicker *datePicker = [views objectAtIndex:2];
	// change the flags so that it displays date AND time
	NSDatePickerElementFlags flags = NSYearMonthDayDatePickerElementFlag | NSHourMinuteSecondDatePickerElementFlag;
	// apply the flags
	[datePicker setDatePickerElements:flags];
	return views;
}
 
@end

Note that I have hard-coded (in this class) the supported operators. This is because a timestamp field really can only meaningfully support this subset. It makes the initWithLeftExpressions method just a little cleaner.

Using the techniques described in Dave’s excellent blog post, you can then use this new class to modify your timestamp row template.

It will result in a template row that looks like:

You will notice that it still doesn’t show seconds. Through some trial and error, I have found that the time-only flag will use seconds, but if you use date and time flags, you can’t get seconds.

Preparing the Workspace

Create 2 new folders in your eclipse workspace – jni and libs

Download the Zbar source tarball from SourceForge – http://zbar.sourceforge.net/download.html

Now open the tarball and locate the zbar folder.

Extract the contents of the zbar folder into the jni folder in your Eclipse workspace. You will also need to extract the zbar.h file from the include folder to the jni folder in your Eclipse workspace. Then download the ZBarAndroidPatch and unzip into the jni folder. The directory structure should look something like this:

You now need to code the JNI wrapper class that will be used to call the ZBar library. The following is an example of the source code for this class:

Generate JNI header

After the Eclipse workspace is setup you are ready to generate the JNI header for your wrapper class. To do this, you need to use the Java Header File Generator javah which can be found in the Java JDK. Go to the classes directory and run javah against your wrapper class:

This will generate a C header file. Copy this header file into the jni directory and edit the android_zbar.c source file to align with the newly generated JNI header:

Build the Library

You are now ready to NDK build the ZBar library. In the jni directory run the ndk-build command:

All going well, this should build the libzbar.so library:

Copy ZBar Library Into Workspace

The last step is to copy the ZBar library back into your eclipse workspace. Copy the armeabi directory (including the libzbar.so file) into the libs directory of your workspace:

Using the Library

To use the native ZBar library, simply call the method on your JNI wrapper class:

Third-party libraries that are hosted on github, bitbucket, etc typically offer varying degrees of documentation as to how they should be linked in but, in general, they all follow the same basic sequence of steps.

This post describes the approach that I have been using to link third-party libraries that I have cloned from git.

Overview

I tend to make good use of the new workspace functionality of Xcode4. For me, it allows me to group my related projects while still retaining the logical separation of each of the projects.

This post describes creating a new workspace and adding an out-of-the-box project from one of the Xcode4 templates. It then clones an arbitrary project from github and links it into our application.

Sounds fairly easy… let’s get into it.

Setting Up the Workspace

Create a new workspace:

And add a project from the list of Xcode4-supplied iPhone templates:

Now, you should be able to compile and run this project. Nothing very exciting yet.

Cloning Third-Party Project

For this example, I chose to clone a JSON library (for no other reason than it was the first one to appear in google).

Open the Git Repositories view by using the File/Source Control/Repositories… menu item and add a new cloned repository:

and enter the URL for your remote library:

and the local name for it (I usually try to use the same name as the remote repository):

and clone:

Note that cloning does not add the project to your workspace. You have to manually add it. After cloning you will be presented with the following dialog – choose Show in Finder and we will drag the project into our workspace.

Drag the xcodeproj file into your Xcode4 workspace. Be careful here… you want to drag the project so that it is a peer of your TestApp project, not a subordinate.

Your workspace should now look like the following:

If it looks like the following, delete it and drag it a little further left before dropping:

Verifying Cloned Library

Now that we have successfully cloned the third-party library into our workspace, we should firstly make sure it compiles by itself.

Switch schemes to the newly added project and confirm that the library compiles OK (note that very occasionally Xcode4 doesn’t add the new schemes into the list – I have no idea why, but usually just closing Xcode4 and starting again seems to fix it.)

Adding Third-Party Library as a Dependency

We have the third-party library in our workspace, but the TestApp project still doesn’t know about it yet. Fortunately, Xcode4 supports the notion of dependent projects, which is what we are going to use next.

Drag the blue heading bar of the third-party library onto the blue heading bar of the TestApp application:

and create a group for the added project:

Your workspace should now look like:

You’ve added a project dependency within the workspace, but we still haven’t told your target that it is dependent on the third-party library. Click on your app’s target, select the Build Phases tab, and add a Target Dependency:

While you’re on this tab, add an entry to the Link Binary With Libraries section to make sure the library is linked in at build-time:

The nice thing about this dependency being set up is that if you make any changes to the sub-project, Xcode4 is smart enough to recompile the library and re-link it into your app.

Using the Library

Switch back to the TestApp scheme and perform a build. You should find that everything compiles OK at this point. Now it is time to add some code that uses the third-party library.

In this case, we are just going to add a single line of code (with an import). Open up the AppDelegate.m file and add the following statement:

#import <SBJson/SBJson.h>

Now, add a line at the start of the application:didFinishLaunchingWithOptions: method:

NSLog(@"JSON Test: %@", [[NSDictionary dictionary] JSONRepresentation]);

If everything has been set up correctly, you should find that Xcode4’s content assist should be able to offer assistance for the library’s methods.

Compile and run.

Uh-oh… What will likely happen is that it will start up, but bomb out with an error message like:

2012-02-27 15:31:19.108 TestApp[95762:f803] -[__NSCFDictionary JSONRepresentation]: unrecognized selector sent to instance 0x6841c70
2012-02-27 15:31:19.132 TestApp[95762:f803] *** Terminating app due to uncaught exception 'NSInvalidArgumentException', reason: '-[__NSCFDictionary JSONRepresentation]: unrecognized selector sent to instance 0x6841c70'

The reason for this is that we need to include one more linker setting to tell the compiler to pick up the newly added objective-c methods. Apple has written an article that describes the reasoning behind this. To resolve, open up the Build Settings for the TestApp target, search for Other Linker Flags and add the following values:

Compile and run again, and you should see output like:

2012-02-27 15:37:47.226 TestApp[96063:f803] JSON Test: {}

And that is it! We’re done.

Footnote: Header File Management

You may be wondering how Xcode4 found the SBJson.h file that we imported. I don’t claim to be an expert here, but my research (and some trial/error) indicates that there are several factors at play here:

• When using an Xcode4 workspace, the build artefacts all get built into a ‘Derived Data’ directory. This physical location for this directory is defined in the Location panel of the Xcode4 settings dialog. On my machine, this is ~/Library/Developer/Xcode/DerivedData. Underneath this directory, each workspace gets its own unique directory. In my case, it is LinkingThirdPartiesExample-bvzijybaagkayohgfmjlxcaezgck
• Within this directory, there is a Build directory that contains the build-time artefacts for the various platforms (iPhone simulator, iPhone device, Mac, et al).
• Xcode4 is pre-defined to look in the include directory for header files. If they are there, they will automatically be picked up.
• Any .h in your workspace that are marked as Public are published underneath the Build directory.

• Well-structured libraries (such as SBJson) mark their headers as public and use the Public Headers Folder Path build setting in such a way so that consumers of their library don’t have to modify their include paths.

  

• Not-so-well-structured libraries may not mark their headers as public, or have non-standard entries for their Public Headers Folder Path, which will force you to modify your app’s build path to include those files explicitly.

• BDCommon – A shared library that contains logic that is common across all applications
• MyMacApp – A Lion-based Mac application that depends on the BDCommon project
• MyPhoneApp – A universal iOS application that depends on the BDCommon project

As you probably know, when it comes to linking libraries, iOS apps can only link static libraries and the preferred approach for Mac OS X apps is to use a framework. So, I decided to create a single project that has two targets:

• BDCommon.framework (used when linking from a Mac OS X app)
• libBDCommon.a (used when linking from an iOS app)

This post describes the steps I performed in Xcode4 to achieve this.

Create Common Project

What you are about to do is create a new MAC OS X Framework project called BDCommon. This will be the containing shell for both targets.

Create new Mac OS X Framework

Create a new Mac OS X Framework:

Set the product name and company identifier:

And save the project:

Configure BDCommon Project

Now we need to configure our newly create BDCommon project to support having two targets (one for the framework and one for the static library). The default behaviour of Xcode4 is to use the target’s name as the product name. This is OK if you only have one target, but because we want to build two products that have the same “name” (ie. BDCommon.framework and libBDCommon.a) we have to have two targets, both with different names. Hence, we need to decouple the product’s name from the target’s name.

In build settings for the BDCommon target, change the Packaging/Product Name from $(TARGET_NAME) to BDCommon:

We will now rename the name of the target itself to BDCommon.framework so that we can easily recognise it in the list of targets:

One last thing is to rename the Scheme to BDCommon.Framework (like renaming the Target, this is mostly a cosmetic act that helps us distinguish between the framework’s scheme and the static library’s scheme:

Perform a build. Confirm that the BDCommon.framework gets created:

Now would probably be a good time to commit your changes to git.

Adding the libBDCommon.a Static Library Target

So, we now have a project that contains a target that will build a framework for our Mac OS X apps. Next, we want to add an additional target to build a static library for our iOS apps.

Choose the File/New/New Target… menu option and add a Cocoa Touch Static Library:

Set the name to BDCommon and add it to the BDCommon project:

Again, because we want to be able to rename the target, we need to decouple the product’s name by hard-coding it to BDCommon:

Let’s rename the target to libBDCommon.a so that it is more obvious which target is which:

And lastly, let’s rename the scheme to libBDCommon.a to match the target name (again, to make it easier to distinguish between the two targets’ schemes):

Perform a build for both schemes (BDCommon.framework and libBDCommon.a). Here is where you will notice what I believe is a bug in Xcode4:

Despite Xcode4 reporting that the build was successful, libBDCommon.a is depicted in red (indicating that it hasn’t built successfully). If you choose Open in Finder for both products, you will notice that it can find where it built BDCommon.framework, but not where it built libBDCommon.a.

It turns that it has actually built libBDCommon.a – it just displays it in the wrong colour. Using Finder, you can navigate manually to the common build directory and see that they do indeed get built successfully:

Almost done now. If you have a look at the files in your Project Navigator, you will notice that the BDCommon group is duplicated. This is due to Xcode4 being “helpful” and generating code when you added the second target. Note that it hasn’t actually generated two copies of the physical files… it has just created several references to the existing files. If you expand both BDCommon groups, you can delete the one with the fewer entries:

Make sure, though, that you choose Remove References Only though, otherwise, it will actually physically delete the files.

When you deleted the references in the step above, you also would have removed the membership of those references for the physical files from the two targets. You need to make sure that both BDCommon.h is in the membership list of both framework and static library targets.

The convention for shared libraries (whether they be a static library or a framework) is to have a single monolithic header file (in our case, that will be BDCommon.h) that imports all the other .h files. At the moment, we don’t have any other .h files to include, so go ahead and remove all content from BDCommon.h so that it is an empty file.

Make sure that BDCommon.h is declared as a public header for both targets:

You can safely remove BDCommon.m now, as it no longer serves any really purpose. Note that this time, you will really delete the file (not just the reference).

Perform another build for both schemes and make sure your products get rebuilt correctly.

Again, this would be a good time to check your code into git.

Adding Some Behaviour to the Common Project

Over time, I expect that my common project will evolve to contain many different classes. To illustrate the process for the purpose of this article, we’ll add a simple class called BDLog that has a single method that outputs Hello world. Clearly, this is a contrived example, but it should give an indication on how to add new functionality to your common library.

Add a new Objective-C class:

Set the class name to be BDLog:

And save to your BDCommon group. Make sure you included it in both the BDCommon.framework and the libBDCommon.a targets:

Add a static method definition called log to BDLog.h:

+(void)log;

And a corresponding implementation in BDLog.m:

+(void)log {
	NSLog(@"Hello world!");
}

Now you need to declare it as a public header for both your targets so that it is accessible from the application projects:

Modify BDCommon.h to add the following line:

#import <BDCommon/BDLog.h>

When building your libraries, Xcode4 copies the public headers for your static library into a directory like .../DerivedData-dflasdfiouknclskjdchvlawioiewhsk/Build/Products/Debug-iphonesimulator/usr/local/include. This is fine, but it means that you need to change the header search path for every project that wants to include it, which is a pain in the ass. What we can do to make this easier is to rely on a little bit of knowledge about the list of directories that Xcode automatically uses when building. As it turns out, it always adds a directory called include to the header search path. To take advantage of this, we will change the Packaging/Public Headers Folder Path from /usr/local/include to include/BDCommon (per the screenshot below, you can also use $(PRODUCT_NAME) which will automatically substitute BDCommon). Using this path, allows us to import our headers with a statement like #import <BDCommon/BDCommon.h>. This step is only required for the libBDCommon.a target.

Perform a build and check that both the framework and static libraries still build correctly.

Creating a Mac OS X Application

Alright, we are now at the moment of truth. We need to see whether all the hard work above (which should be a once-off setup) allows us to share common code. To do this, we’re first going to create a Mac OS X application and link to our framework.

Create a new Mac OS X app:

Set the name to MyMacApp – although it doesn’t really matter… we are just verifying that the framework will link OK:

And save the application:

Open the Build Phases tab for your application, and expand the Link Binary with Libraries section:

Click on the +, and with a bit of luck, our newly created framework should appear in the list of frameworks in the workspace. Select it, and choose Add:

Open up your App Delegate class implementation and add the following statement at the top of the file:

#import <BDCommon/BDCommon.h>

Now add the following code to the applicationDidFinishLaunching: method (if all goes well, Xcode4 will even auto-complete the class and method names for you):

[BDLog log];

Build and run. If everything goes to plan, you will see Hello world! appear in the console output.

Creating an iPhone Application

One down, one to go. Same basic deal as before – we are going to create an iPhone application, but this time we will link in the static library, instead of the framework.

Create a new iPhone app:

Set the name to MyPhoneApp:

And save the application:

Open the Build Phases tab for your application, and expand the Link Binary with Libraries section:

Click on the +, and our newly created static library should appear in the list of libraries in the workspace. Select it, and choose Add:

Open up your App Delegate class implementation and add the following statement at the top of the file:

#import <BDCommon/BDCommon.h>

Now add the following code to the application:didFinishLaunchingWithOptions: method (if all goes well, Xcode4 will even auto-complete the class and method names for you):

[BDLog log];

Build and run. If everything goes to plan, you will see Hello world! appear in the console output.

Linking Static Libraries That Contain Categories

If you use Objective-C categories in your common library, you will likely get an error when you link your static library against the iOS app. Apple has written an [article](http://developer.apple.com/library/mac/#qa/qa1490/_index.html “Building Objective-C static libraries with categories”) that describes the process to resolve this problem. In a nutshell, though, you can modify the *Other Linker Flags* in your iOS app to include the -ObjC and -all_load options:

Wrapping Up

There are a few things that I haven’t yet touched on that I may include in a future post:

• Bundling your library for distribution to other developers
• Private header files

As this was my first foray into this topic, I would be very interested in hearing feedback from you. In particular, if there are pieces of the above that are incorrect or misleading, please let me know and I will correct ASAP.

Drop me a line at craig (at) blackdogfoundry (dot) com

This service is designed to assist you in keeping your application reference (or operational) data up-to-date. For example, consider the case where you have developed an application that stores train timetable information in an sqlite database on your iphone. This information would be correct at the time of application publication, however, over time it would quickly become out of date. The replication service that BlackDog offers is to store a copy of the “master” data on the BlackDog server (which you can update at any time), and the devices connect to the BlackDog server and replicate down only the changed records.

Many developers write their own data replication behaviour, but it is complex and error-prone. The BlackDog Replication service allows you to concentrate on developing your application’s behaviour and core functionality, not dealing with challenges like replication.

This tutorial describes the steps you will need to perform in order to integrate the sqlite replication behaviour into your application. It assumes that you are have previously used XCode to develop iphone applications.

The overriding premise of the BlackDog replication behaviour is that you, as the application developer, can develop your application with only a small amount of consideration to the replication that occurs under the covers. This means that you should be able to develop your application reading from the database with no BlackDog functionality, and then add in the BlackDog replication once your application is working.

Looking at a typical iphone development project, it would normally involve the following high-level sequence of steps:

• Create initial sqlite database that contains some data
• Copy that database into your project’s resource folder
• Build your application that reads from that database using sqlite APIs
• Finalise the contents of the sqlite database
• Perform final testing
• Ship the application to Apple for approval

Contrast that to the workflow when using the BlackDog replication libraries (new steps in bold):

• Create initial sqlite database that contains some data
• Copy that database into your project’s resource folder
• Build your application that reads from that database using sqlite APIs
• Finalise the contents of the sqlite database
• Upload the contents of the sqlite database to the BlackDog server
• Add a few lines of code to invoke the BlackDog replication service
• Perform final testing
• Ship the application to Apple for approval

Downloading BlackDog Libraries

The first thing you will need to download is the latest BlackDog replication libraries. The BlackDog libraries come in a ZIP file that contains a number of libraries, but the two that you will need to use the replication functionality are:

• bdcommon
• bdrepl

When you unzip that file, you will find the following file hierarchy:

You will note that there are libraries provided for both Release and Debug compilation options, as well as the device and simulator runtime engines. The Headers directory contains the Objective-C header files that define the BlackDog functionality. Unzip this file into a directory of your choosing. For the purposes of this tutorial, I assume that the zip file was unzipped into /Users/xxxx/BlackDog

Setting up your XCode Environment

As all developers like to manage their development environment settings, there is no single canonical way to set up your environment. However, there are several key objectives that must be achieved to link in the BlackDog replication libraries.

• Include the Headers directory
• Link the replication libraries
• Add some pre-requisite frameworks

One possible way of achieving each of these is described below.

Include the Headers directory

Right-click on your Target, and choose Get Info. On the Build tab, type “header search” in the filter field and enter /Users/xxxx/BlackDog/Headers into the “Header Search Paths” setting.

Link the replication libraries

In the Target Info Build tab, filter for “other linker flags” and enter -all_load -lbdcommon -lbdrepl in the “Other Linker Flags” setting.

In the Target Info Build tab, filter for “library search” and add /Users/xxxx/BlackDog/$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME) in the “Library Search Paths” setting.

Note that the use of the $(CONFIGURATION) and $(EFFECTIVE_PLATFORM_NAME) variables are a clever technique that allows for dynamically picking up the correct BlackDog runtime library depending on whether you are running on the device or simulator, or in Debug/Release mode.

Add some pre-requisite frameworks

In the Target Info General tab, add the following frameworks/dynamic libraries:

• CFNetwork.framework
• libxml2.dylib
• libsqlite3.0.dylib

Calling the Libraries

Once your XCode environment has been setup correctly, you can now start calling the Replication libraries. The functionality that is available is defined in the BlackDogReplication.h file in the Headers folder. The API is very simple:

@interface BlackDogReplication : NSObject {	
}
 
/**
 * Launches a synchronous replication.  If you require an asynchronous
 * invocation, use a separate background thread to run this function.
 * 
 * Parameters:
 *   delegate - The delegate that provides the input parameters and responds
 *              to the callback functions as replication occurs
 *   fullReplication - Should we get a full replication, or a delta.  In nearly
 *                     all cases, this value will be false as you would normally
 *                     only want to replicate changes since your last update.
 *                     However, there may be cases where you want to completely
 *                     refresh the contents of the table.  In those rare cases,
 *                     pass true in this parameter.
 */
+(void)replicate:(id<BlackDogReplicationDelegate>)delegate fullReplication:(BOOL)fullReplication;
@end

There is a single static method defined on the BlackDogReplication class that takes your delegate and a boolean indicating whether you want a full replication, or an incremental replication. You will nearly always want an incremental so you should pass NO as the parameter. You will need to define a delegate class that can be used, and it will need to implement the methods that are defined in the BlackDogReplicationDelegate class and its parent class (BlackDogDelegate). The simplest example of a delegate class looks like:

@implementation DemoDelegate
 
-(NSString *)appKey {
	return @"cd79fbe3ae6d41ba9daad1acf45b5bff";
}
-(NSString *)secretKey {
	return @"3a1248037bc74fd2aa512f4e8feabf90";
}
-(NSString *)sqliteDatabasePath {
	NSString *docDirectory = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0];
	return [docDirectory stringByAppendingPathComponent:@"database.sqlite"];
}
-(NSString *)tableName {
	return @"mytable";
}
-(int)initialChangeId {
	return 1;
}
@end

An example invocation of the API looks like:

DemoDelegate *delegate = [[DemoDelegate alloc] init];
[BlackDogReplication replicate:delegate fullReplication:NO];
[delegate release];

The above code connects to the BlackDog server and replicates any changes since your device last replicated data from the master server.

Updating your data

There are two ways to update your master data:

1. Uploading a complete sqlite database via the BlackDog website (non-incremental)
2. Invoking a web service (XML-based) APIs to send incremental updates to the BlackDog server

Some important notes

• When you initially upload an sqlite database to the BlackDog website, it performs a number of validations, and creates a snapshot of the data with a changeID of 1.
• Every time changes get made to the table and uploaded to the BlackDog website, the changed records (including deletions) are flagged with the next ChangeID.
• The client libraries know what the latest ChangeID is for the data on the device, so when it performs a replication, it only fetches the rows that have been changed since that ChangeID.
• If your replicated tables do not make use of a primary key column, the BlackDog replication service is unable to provide incremental replication. That is, the whole table will be replicated even if only one row has changed.
• If you delete a replicated table from the BlackDog server, the data is gone forever. You can upload a fresh copy of the table, but it will be given a ChangeID of 1 and your devices are very likely to have a ChangeID of, say, 23. In this case the client will download a complete set of the data again.

Caveats for uploading complete sqlite databases

• If you upload a complete sqlite database via the website, it is treated as non-incremental. That is, when devices replicate they will receive a complete data refresh. If you need incremental changes to be incremented, you need to use the BlackDog web services which will be described in a later tutorial.
• If the uploaded sqlite database contains multiple tables, all tables will be registered for replication (if there are tables in the database that you do not need for replication, you can delete the reference to them on the BlackDog website.) Tables that already exist on the BlackDog server will be updated with a new ChangeID; new tables will be initialised with a ChangeID of 1.

In order to use the BlackDog services, you first need to register for an account. To do this, you will need to select an account name, password and provide your email address.

Once you have entered the required details, you will be sent a confirmation email with a URL for you to click on to confirm your account.

Applications

Within your BlackDog account, you have the ability to define an application. The application name can be whatever you like (it is purely informational to help you manage your applications within BlackDog), and would typically align to an application that you submit to the Apple Store/Android Marketplace. If you have an application that runs on multiple devices (but still has the same underlying behaviour), you would only create one application in BlackDog.

Once you’ve created the application, it will be assigned an application key and a secret key. These values are used on the mobile devices to create secure sessions with the BlackDog server.

You can define multiple applications that all have completely separate functionality and settings.

Using APIs

The primary purpose of BlackDog is for you to take advantage of the iPhone and Android libraries and embed them in your mobile applications. Currently, the following libraries are provided:

• bdrepl
• bdnotify

The above libraries also depend on the bdcommon library for some base functionality. For example, if you are using the Replication API, you will need to include both bdcommon and bdrepl libraries.

The key input that you, as a developer, need to provide is defined by either the BlackDogReplicationDelegate or BlackDogNotificationDelegate protocol/interface. Both of these interfaces extend from a parent interface called BlackDogDelegate that defines some common behaviour.

iPhone

/**
 * The BlackDogDelegate protocol is designed to represent a common set of functions
 * across all BlackDog Foundry services.  In particular, by abstracting the application 
 * key and secret key into this protocol, it gives the developers the freedom to share
 * an implementation of this protocol across multiple BlackDog services (such as 
 * replication and analytics), without having to duplicate information.
 *
 * As a stand-alone protocol, this isn't a particularly useful class.  Delegates should
 * not implement this protocol directly, but rather implement one or more specific
 * protocols such as BlackDogReplicatorDelegate.
 */
@protocol BlackDogDelegate <NSObject>
 
/**
 * Returns a string containing your application's 32-character application key.  
 * eg. "2119cafdaa37402c9c0af77e8f701f58"
 */
-(NSString *)appKey;
 
/**
 * Returns a string containing your application's 32-character secret key.  
 * eg. "f333759829f74d4faf07496aeac23604"
 */
-(NSString *)secretKey;
 
@optional
 
/**
 * Called by the BlackDog libraries if a session with the BlackDog server is unable
 * to be established.   During typical operations, this should never be called, with 
 * the possible exception of when the BlackDog server is down (or for some reason 
 * temporarily not servicing requests), in which case, the code parameter will be 
 * STATUS_TEMPORARILY_UNAVAIL.  In this case, it may be meaningful to let end-users
 * know that there is a temporarily problem with replication (depending on how much
 * visibility the end-users have of replication).  In all other cases, though, the
 * code and reason parameters will be of little meaning to end-users - they are aimed
 * at the developer of the application.
 * 
 * Parameters:
 *   code   - Contains a integer code that gives a hint of what the problem may have been.   
 *   reason - Contains a (possibly) human-readable string with a little more info.
 */
-(void)didFailToEstablishSession:(int)code reason:(NSString *)reason;
 
/**
 * Called by the BlackDog libraries if a a particular API call was not successful.
 * Usually this would occur if the call to the remote service was technically sucessful
 * (ie. the remote service was invoked), but suffered an error during execution.  This
 * might be due to you passing invalid data, or perhaps due to a BlackDog server error
 * condition.  There is also a chance that the client-side BlackDog libraries had some
 * problems performing an action (for example, if errors were experienced opening a local
 * sqlite database.  The code and reason parameters will almost certainly contain no 
 * meaningful information that would be able to be displayed to end-users - they are 
 * aimed at the developer of the application.
 * 
 * Parameters:
 *   code   - Contains a integer code that gives a hint of what the problem may have been.   
 *   reason - Contains a (possibly) human-readable string with a little more info.
 */
-(void)didFailToInvokeRemoteService:(int)code reason:(NSString *)reason;
 
@end

If you are developing an application for the iPhone that is using the BlackDog replication services, you would define your delegate class like so (note that extremely minimal error handling methods have been implemented):

#import "DemoDelegate.h"
 
@implementation DemoDelegate
 
-(NSString *)appKey {
	return @"cd79fbe3ae6d41ba9daad1acf45b5bff";
}
-(NSString *)secretKey {
	return @"3a1248037bc74fd2aa512f4e8feabf90";
}
-(NSString *)sqliteDatabasePath {
	NSString *docDirectory = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0];
	return [docDirectory stringByAppendingPathComponent:@"database.sqlite"];
}
-(NSString *)tableName {
	return @"mytable";
}
-(int)initialChangeId {
	return 1;
}
-(void)didFailToFetchChanges:(int)code reason:(NSString *)reason {
	NSLog(@"%@", reason);
}
-(void)didFailToEstablishSession:(int)code reason:(NSString *)reason {
	NSLog(@"%@", reason);
}
-(void)didFailToInvokeRemoteService:(int)code reason:(NSString *)reason {
	NSLog(@"%@", reason);
}
@end

If you were using both replication and notification, you have three choices:

1. Define a single delegate class that implements both BlackDogReplicationDelegate and BlackDogNotificationDelegate.
2. Define two separate delegate classes – one that implements BlackDogReplicationDelegate and one that implements BlackDogNotificationDelegate
3. Define three delegate classes – one that implements BlackDogDelegate (eg. MyDelegate) and provides the common details (application and secret key), and two others that subclass MyDelegate that respectively implement the replication and notification delegates.

Reports

BlackDog offers a number of reports that help you understand the usage of the BlackDog services.

Device Type Report

This report displays a pie chart with the percentage breakdown of the various device types. The high level report displays a breakdown of the device types (iPhone, Android, etc), but the Include Sub-Types checkbox allows you to drill down into more specifics on the actual types (eg. iPhone 3GS, HTC Magic, etc).

The start and end dates filter the time period that you would like the report over; for this report, the referenced date is date on which the device irst connected to the BlackDog services). You can optionally run the report across all your applications, or just for a single application. By default, the data in the BlackDog database is stored in UTC format, however, you can override this choose an offset to run the report for.

Device Installation Report

This report displays a line chart that shows the number of devices that connect to the BlackDog service for the first time during that period. You can group the data points of report on an hourly, daily, monthly and yearly basis.

The start and end dates filter the time period that you would like the report over; for this report, the referenced date is the date on which the device first connected to the BlackDog services). You can optionally run the report across all your applications, or just for a single application. By default, the data in the BlackDog database is stored in UTC format, however, you can override this choose an offset to run the report for.

API Usage Counts Report

This report displays a line chart indicating the volume of the various BlackDog API calls. This report will give you an excellent view of the way that your application interacts with the BlackDog services.

The start and end dates filter the time period that you would like the report over. You can optionally run the report across all your applications, or just for a single application. By default, the data in the BlackDog database is stored in UTC format, however, you can override this choose an offset to run the report for.

Active Devices Report

This report displays the list of active devices during the given period (where “active” is defined as having some interaction with the BlackDog services).

The start and end dates filter the time period that you would like the report over. You can optionally run the report across all your applications, or just for a single application. By default, the data in the BlackDog database is stored in UTC format, however, you can override this choose an offset to run the report for.