Using Afaria to Provision Configuration Data

To use these APIs you must provide the application to the device through an Afaria application policy. When setting up such an application policy, the Afaria administration interface provides an option to add configuration data to the policy as text or binary.

The following is an an example of the Afaria administration screen for an application policy that provides an application named "CertsOnBoard" to an enrolled device. The "Configuration" tab shows the configuration data provided to the application.

In this case, the configuration information is added using the administration user interface, but it can also be provided as a text or binary file. The example shows plain text, but you can also provide the information as XML or JSON text for easier parsing by the application.

You can obtain configuration data for your application using Afaria by calling the following API from the SeedingAPISynchronous class (in Afaria's SeedingAPISynchronous.h header file:

+ (NSInteger)retrieveSeedData:(NSString *)urlScheme InFile:(NSMutableString *)seedFile withCredentials:(NSURLCredential *)credentials;

Or, call this asynchronous API from the SeedDataAPI class (in SeedDataAPI.h):

- (void)retrieveSeedData;

To access this data, the application provides an NSMutableString to the retrieveSeedData API. If the device is correctly enrolled to Afaria, the API returns kSeedDataAvailable and the NSMutableString contains the full path to a file in the application's sandbox with the seed data.

This example code retrieves the configuration data using the Afaria API, parses it using the native iOS APIs, and applies the appropriate settings using the Sybase Unwired Platform APIs (the SUPApplication and SUPConnectionProperties classes).

NSMutableString *seedFile = [NSMutableString string];
retCode = [SeedingAPISynchronous retrieveSeedData:@"certsonboard-seed" InFile:seedFile withCredentials:nil];
NSError *error = nil;
switch(retCode)
{
  case kSeedDataAvailable:  // Seed data is available, read the file
    NSLog(@"Seed file = %@",seedFile);
    NSLog(@"Seed data = %@",[NSString stringWithContentsOfFile:seedFile encoding:NSUTF8StringEncoding error:&error]);
    break;
  case kSeedDataUnavailable:
    NSLog(@"kSeedDataUnavailable"); // Error
    break;
  case kAfariaClientNotInstalled:
    NSLog(@"kAfariaClientNotInstalled");  // Error
    break;
  case kAfariaSettingsRequested:
    NSLog(@"kAfariaSettingsRequested");  // Error
    break;
}

// Read the text from the Afaria configuration file
NSString *configurationText = [NSString stringWithContentsOfFile:seedFile encoding:NSUTF8StringEncoding error:&error];
    
// Separate the text into lines
NSArray *configurationLines = [configurationText componentsSeparatedByString:@"\n"];
    
// Create a dictionary, and go through the lines to find name value pairs
NSMutableDictionary *settings = [NSMutableDictionary dictionary];
for(NSString *s in configurationLines)
{
  NSArray *nvpair = [s componentsSeparatedByString:@": "];
  if([nvpair count] == 2)
    [settings setValue:[nvpair objectAtIndex:1] forKey:[nvpair objectAtIndex:0]];
}
    
// Use the name value pairs from the configuration file to set the appropriate settings in the SUPApplication API
SUPApplication *app = [SUPApplication getInstance];
app.applicationIdentifier = @"myAppID";
    
SUPConnectionProperties *properties = app.connectionProperties;
    
properties.serverName = [settings valueForKey:@"Server"];
properties.portNumber = [[settings valueForKey:@"Port"] intValue];
properties.farmId = [settings valueForKey:@"Farm ID"];
properties.urlSuffix = [settings valueForKey:@"URL Suffix"];
 
NSLog(@"Server name is set to %@",properties.serverName);
NSLog(@"Port number is set to %d",properties.portNumber);
NSLog(@"Farm ID is set to %@",properties.farmId);
NSLog(@"URL suffix is set to %@",properties.urlSuffix);

Example output on the Xcode console:

2012-09-24 13:06:33.014 CertsOnboard[579:707] Seed file = /var/mobile/Applications/21935FE8-843A-418D-A2BF-EE415B5D4DF0/Documents/TEXT_FILE_
2012-09-24 13:06:33.016 CertsOnboard[579:707] Seed data = Server: relayserver.sybase.com

Port: 80
URL Suffix: /ias_relay_server/client/rs_client.dl
Farm ID: example.exampleMBS

For more information on the Afaria APIs and the meanings of return codes, see the Afaria documentation.