Tuesday, November 29, 2011

use protobuf on iphone app

This post is a step by step tutorial showing how to use protobuf in iphone application. It shows how to:
  • Create a reusable static library
  • Create a executable project
  • Mix C++ code with object C code
1. Start terminal, cd to root folder of protobuf and run ./configure here to generate config.h header file and makefile.

2. Start XCode and create a new project. Select iOS - Library - Cocoa Touch Static Library project template.

3. Right click Other Sources and select add Existing Files.

4. Select the src/google directory, and add the directory recursively.

5. In the previous step, we add too much source files than actually needed. The sources files for the protoc compiler and unittest are included too. They're not needed to run ios application. To filter out unnecessary files, we can refer to the libprotobuf_lite_la_SOURCES and libprotobuf_la_SOURCES variables in src/Makefile, which list source files needed for protobuf library.

6. Now we need to add header file search path. Click Edit Project Settings under Project menu item.

7. Double click Header Search Paths.

8. Add protobuf and protobuf/src directory.

9. Now build the project.

10. In the terminal, run "make install" command to build protoc compiler and install it to default location(/usr/local/bin/protoc).

11. Go to examples directory and run "protoc addressbook.proto --cpp_out=./" to generate addressbook.pb.cc and addressbook.pb.h files.

12. Create a Window-Based Application.

13. Add reference to the static library we built. Right click Frameworks and select Add Existing Frameworks.

14. Click Add Other button.

15. Select the libprotobuf_ios.a file and click add button. Also, we need to add protobuf/src and protobuf/examples directory to Header Search Paths for this project.

16. Rename add_personAppDelegate.m to add_personAppDelegate.mm so that it'll be compiled as object C++.

17. The basic logic of add_personAppDelegate.mm is first create the addressbook.dat file in iphone's document directory. Then create a new AddressBook instance and add a person to it. Finally serialize the addressbook to the file we created. The full source is :

#import "add_personAppDelegate.h"


#include "addressbook.pb.h"
#include <fstream>

using namespace std;

@implementation add_personAppDelegate

@synthesize window;



#pragma mark -
#pragma mark Application lifecycle

(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {  
    GOOGLE_PROTOBUF_VERIFY_VERSION;   

    NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
    NSString *documentDirectory = [paths objectAtIndex:0];
    NSString *filename = [NSString stringWithFormat:@"%@/addressbook.dat", documentDirectory];   

    ifstream input([filename UTF8String], ios::in | ios::binary);   

    tutorial::AddressBook address_book;  
    address_book.ParseFromIstream(&input);
    int count = address_book.person_size();  
    tutorial::Person *person = address_book.add_person();
    person->set_id(42);
    person->set_name("raymond");
    person->set_email("raymond@gmail.com");   

    tutorial::Person_PhoneNumber *pn = person->add_phone();

    pn->set_type(tutorial::Person_PhoneType_WORK);
    pn->set_number("12345678");   

    fstream output([filename UTF8String], ios::out | ios::trunc | ios::binary);
    person->SerializeToOstream(&output);   

    NSHomeDirectory();
    // Override point for customization after application launch.   

    [self.window makeKeyAndVisible]; 

    return YES;
}


(void)applicationWillResignActive:(UIApplication *)application {
    /*
     Sent when the application is about to move from active to inactive state. This can occur for certain types of temporary interruptions (such as an incoming phone call or SMS message) or when the user quits the application and it begins the transition to the background state.
     Use this method to pause ongoing tasks, disable timers, and throttle down OpenGL ES frame rates. Games should use this method to pause the game.
     */
}


(void)applicationDidEnterBackground:(UIApplication *)application {
    /*
     Use this method to release shared resources, save user data, invalidate timers, and store enough application state information to restore your application to its current state in case it is terminated later.
     If your application supports background execution, called instead of applicationWillTerminate: when the user quits.
     */
}


(void)applicationWillEnterForeground:(UIApplication *)application {
    /*
     Called as part of  transition from the background to the inactive state: here you can undo many of the changes made on entering the background.
     */
}

(void)applicationDidBecomeActive:(UIApplication *)application {
    /*
     Restart any tasks that were paused (or not yet started) while the application was inactive. If the application was previously in the background, optionally refresh the user interface.
     */
}


(void)applicationWillTerminate:(UIApplication *)application {
    /*
     Called when the application is about to terminate.
     See also applicationDidEnterBackground:.
     */
}

#pragma mark -
#pragma mark Memory management


(void)applicationDidReceiveMemoryWarning:(UIApplication *)application {
    /*
     Free up as much memory as possible by purging cached data objects that can be recreated (or reloaded from disk) later.
     */
}

(void)dealloc {
    [window release];
    [super dealloc];
}

@end



18. After build and run the application in iphone emulator, we get generated addressbook.dat file in /Users/user_name/Library/
Application Support/iPhone Simulator/4.3/Applications/9AF109CF-1B33-49DA-BE73-603CC798408F/Documents/addressbook.dat

Thursday, November 24, 2011

port protobuf-lite to wince

protobuf is a wonderful project that helps us implement communication protocol. There are a lot of benefits to use it in practical project, including:
  1. It has an efficient binary serialization algorithm
  2. It runs cross platforms
  3. It support mainstream programming languages, c++, python and java. there are also lots of porting out there for other popular languages.
  4. It's designed to make protocols both backward and forward compatible.
  5. It enables developers to focus on protocol design.
 Currently, there is no official windows CE version for protobuf. It's not an easy task to port protobuf full version to windows CE. But the lite version, which supports less feature than full version (check the explanation for optimize_for option in this page for what's the difference), is easier to port. Here is how I port it:

  1. Create a Win32 Smart Device Project library project, name it protobuf-lite-ce
  2. Copy all source files from protobuf-lite project to protobuf-lite-ce project in Solution Explorer
  3. Create a ce_port folder in the project's directory, and copy the errno.h header file from (Visual_Studio_Root)/VC/include into the folder. This is because Windows CE doesn't have this file, so we need to provide one. Actually, this errno.h can be a pure empty file.
  4. Add "../src;.;./ce_port" to the project's Additional Include Directories.
  5. The windef.h header file already defines OPTIONAL macro, it conflicts with Cardinality::OPTIONAL enum. So the extension_set.cc fails to compile, to solve this, add following code before enum Cardinality definition to undefine OPTIONAL:

#if defined(OPTIONAL)
#if defined(_MSC_VER)
#pragma message ("Unexpected OPTIONAL macro definition, #undefine OPTIONAL")
#else
#warning  "Unexpected OPTIONAL macro definition, #undefine OPTIONAL"
#endif
#undef OPTIONAL
#endif
namespace {

enum Cardinality {
  REPEATED,
  OPTIONAL
};

}  // namespace


Now the protobuf-lite-ce project should compiles fine.
Here is the project file for downloading. Just get everything there and place them in protobuf/vsprojects/ directory.