Network Save Card

About Network Save Card

The OpenFeint Network Save Card service provides a simple API that enables an application to save a blob of data to the server and retrieve it later. Each blob is associated with a specific application, a specific user, and a key name chosen by the application. An application can only access blobs that it has created and only those that are associated with the current user. OpenFeint Network Save Card can be thought of as simple flat file system that follows a user account around the network and restores application specific data to a game even if the account shows up on a different device.

Network Save Card is a new service available as of version 2.4 of the OpenFeint SDK. The service is only available when OpenFeint is in the online state. An application is allowed to consume up to 256K of cloud storage per OpenFeint user account. Warning: accounts exceeding the limit may find that excess blocks are initially granted then mysteriously disappear from the server a week later. If your particular game has a good reason to consume more storage, please send us a support request explaining your needs and we'll see what we can do to increase your limits so that you do not experience disappearing data.

Use Case: Save Game State

One typical use case for the Network Save Card is to save the current player's game state. For games that allow a branched path through through the game, it is possible to save multiple game states under one OpenFeint identity provided that particular user's overall storage limit for that game is not exceeded.

Data Blob Access Methods

The API consists of two simple methods: one for uploading and one for downloading. Each blob is distinguished by a key name unique within the context of the current application and user. The blob of data itself is passed through the API as an NSData object consisting of whatever binary data the application may store. The prototypes of the two methods are:

 
+ (void)uploadBlob:(NSData*) blob withKey:(NSString*) keyStr
    onSuccess:(const OFDelegate&)onSuccess onFailure:(const OFDelegate&)onFailure;
+ (void)downloadBlobWithKey:(NSString*) keyStr
    onSuccess:(const OFDelegate&)onSuccess onFailure:(const OFDelegate&)onFailure; 

The key string is case sensitive alphanumeric text that must begin with an alphabetic character. The dash and underscore characters may also be used in this string. Key strings may be up to 32 characters long. The result of using a longer string is undefined. The last two parameters of each method accept application defined OFDelegate style callbacks to be executed upon success or failure of each API method.

Using Network Save Card

The sample app included with the API gives a simple demonstration of cloud storage in use. Try running the sample app and confirm that you can send and receive a couple of test blobs with different key strings. Take a look at the source code for this sample in the files "CloudStorageDemoController.mm" and "CloudStorageDemoController.xib".

The first thing to do in your own code is to include the appropriate header:

 
#import "OFCloudStorageService.h" 

Next, make sure you can send a blob of data and see that your success delegate is called.

 
- (IBAction)onBlobSend:(id)sender{
    NSData      *payloadData =
        [blobPayloadTextBox.text dataUsingEncoding: NSUTF8StringEncoding];
    OFDelegate   successDelegate(self, @selector(blobSend_SuccessDelegate));
    OFDelegate   failureDelegate(self, @selector(blobSend_FailureDelegate));
 
    [OFCloudStorageService uploadBlob: payloadData
        withKey: blobNameTextBox.text
        onSuccess: successDelegate
        onFailure: failureDelegate
    ];
} 

You can define the success and failure delegates very simply to start out. They don't have to do anything yet. You just need them as a place to intercept a breakpoint or spit out an NSLog string to see when they get called. Each should have a void return value and no parameters. The blob you send can be a simple chunk of text for now but you will be able to substitute this later with any binary data you like.

Next, try fetching a previously submitted blob using the key values you created them with.

 
- (IBAction)onBlobFetch:(id)sender{
    OFDelegate successDelegate(self, @selector(blobFetch_SuccessDelegate:));
    OFDelegate failureDelegate(self, @selector(blobFetch_FailureDelegate));
 
    [OFCloudStorageService downloadBlobWithKey: blobNameTextBox.text
        onSuccess: successDelegate
        onFailure: failureDelegate
    ];
} 

Note the colon at the end of the success delegate name in this case. This delegate receives one parameter containing the data fetched from the server. The failure delegate has no parameters or return value just like the result delegates used when sending a blob. See the following example and note that you could intercept a breakpoint to confirm that receivedString has the content you were expecting.

 
- (void)blobFetch_SuccessDelegate:(NSData*)blob{
    NSString        *receivedString = nil;
    NSUInteger   blobLen    = [blob length];
 
    if (blobLen <= 0){
        receivedString = @"";
    }else{
        receivedString =
            [[NSString alloc] initWithData: blob encoding: NSUTF8StringEncoding];
        [receivedString autorelease];
    }
} 

Once this sample is clear there should be no trouble extrapolating this service to handle whatever type of data you need to store provided that it meets the storage limitations.