This is mainly a synchronous library, just like Java, so always bear in mind to make any remote calls in a separate thread so not to block the UI thread. You may download the project file here, build the framework and include it in your projects.

Documentation

The documentation of the Object-C library can be found here.

Examples

Just like the Java library, the Objective-C library resides on the same three main classes: the TourismClientFactory, TourismClient stub and the DataReader.

Making a TourismClient Stub

To generate a TourismClient stub, one uses the TourismClientFactory by passing the home URL. If the URL is a CitySDK-powered tourism server then the factory class will generate a TourismClient stub. Such URL is visited only once and further calls on the factory with the same URL will just generate another (equal) stub without calling the URL again. If a different URL is passed then the mentioned procedure is repeated. An example of using the TourismClientFactory class is shown below:

#import <CitySDK/TourismClientFactory.h>
 
- (TourismClient *) getClientWithUrl:(NSString *) url 
{
    NSError* err;
    // get a factory instance
    TourismClientFactory* factory = [TourismClientFactory getInstance];
 
    // create a client stub
    TourismClient* client = [factory getClient:url :&err];
 
    // handle any error that might occur
    if(err)
        NSLog(@"$@", [err description]);
 
    return client;
}

Using the TourismClient Stub

The TourismClient stub allows to call and instantiate the POI objects (like POIs, Events, Routes, Categories and Tags) and its listings. Some examples are shown below:

Getting a List of POI-based Objects

A list of POI-based objects is requested through the use of a parameter list which contains the query parameters to make a given request. An example of getting a list of POIs is shown below:

#import <CitySDK/TourismClientFactory.h>
 
- (ListEvent *) getListOfEventsFromUrl:(NSString *) url withParams:(ParameterList *) list
{
    NSError* err;
    ListEvent* eventList = nil;
 
    // get a factory instance
    TourismClientFactory* factory = [TourismClientFactory getInstance];
 
    // create a client stub
    TourismClient* client = [factory getClient:url :&err];
 
    // handle any error that might occur
    if(err)
        NSLog(@"$@", [err description]);
    else {
        // get a list of events
        eventList = [client getEvents:list :&err];
 
        // handle any error that might occur
        if(err) {
            NSLog(@"$@", [err description]);
        }
    }
     
    return eventList;
}
 
...
ParameterList* list = [[ParameterList alloc] init];
[list add:[[Parameter alloc] initWithName:[ParameterTerms getTerm:CATEGORY] 
    andValue:@"Music" :&err]];
[list add:[[Parameter alloc] initWithName:[ParameterTerms getTerm:EVENT] 
    andValue:@"Steve Vai" :&err]];
ListEvent* events = [self getListOfEventsFromUrl:@"http://some-url.pt" withParams:list];
...

Getting a list of Categories or Tags

A list of Categories can be requested by specifying which list is needed (POIs, Events or Routes). Getting a list of Tags will be similar.
An example is shown below:

#import <CitySDK/TourismClientFactory.h>
 
- (ListEvent *) getCategoriesFromUrl:(NSString *) url withList:(ParameterList *) list
{
    NSError* err;
    Category* categories = nil;
     
    // get a factory instance
    TourismClientFactory* factory = [TourismClientFactory getInstance];
     
    // create a client stub
    TourismClient* client = [factory getClient:url :&err];
     
    // handle any error that might occur
    if(err)
        NSLog(@"$@", [err description]);
    else {
        // get categories
        categories = [client getCategories:list :&err];
 
        // handle any error that might occur
        if(err) {
            NSLog(@"$@", [err description]);
        }
    }
 
    return categories;
}
 
...
ParameterList* list = [[ParameterList alloc] init];
[list add:[[Parameter alloc] initWithName:[ParameterTerms getTerm:LIST] 
    andValue:@"poi" :&err]];
Category* categories = [self getCategoriesFromUrl:@"http://some-url.pt"
    withList:list];
...

Getting a Single POI-based Object

Getting a single POI-based object (like POIs, Events or Routes) can be made by using the base and the id of such object like shown below:

#import <CitySDK/TourismClientFactory.h>
 
- (PointOfInterest *) getPoiFromUrl:(NSString *) url withBase:(NSString *) base 
    andId:(NSString *) baseID
{
    NSError* err;
    PointOfInterest* poi = nil;
     
    // get a factory instance
    TourismClientFactory* factory = [TourismClientFactory getInstance];
     
    // create a client stub
    TourismClient* client = [factory getClient:url :&err];
     
    // handle any error that might occur
    if(err)
        NSLog(@"$@", [err description]);
    else {
        // get complete description of the poi
        poi = [client getPoi:base withId:baseID :&err];
 
        // handle any error that might occur
        if(err) {
            NSLog(@"$@", [err description]);
        }
    }
 
    return poi;
}
 
...
ListPointOfInterest* list = ...; // previously got poi list
PointOfInterest* poi = [list getPoi: 0];
poi = [self getPoiFromUrl:@"http://some-uri.com" withBase:poi.base andId:poi.baseID];
...

Using the DataReader on returned data

The DataReader is used to parse the objects returned by the methods of TourismClient stub. This class allows to parse any type of SINGLE POI-based object and return the desired value. Some examples are shown next.

#import <CitySDK/TourismClientFactory.h>
#import <CitySDK/DataReader.h>
 
- (void) parseItems:(ListEvent *) list 
{  
    // define the default language to be used, in case the wanted language
    // does not exist. The default language - if this method is not called - is en_GB.
    [DataReader setDefaultLocale: [[NSLocale alloc] initWithLocaleIdentifier:@"en_GB"]];
 
    // get the default locale
    NSLocale* locale = [[NSLocale alloc] initWithLocaleIdentifier:@"pt_PT"];
    for(int i = 0; i < [list getNumEvents]; i++) {
        Event* event = [list getEvent:i];
         
        NSLog(@"Label: %@", [DataReader getLabel:event withTerm:LABEL_TERM_PRIMARY
            andLocale:locale]);
        NSLog(@"Description: %@", [DataReader getDescription:event withLocale:locale]);
        NSLog(@"Contacts: %@", [DataReader getContacts:poi]);
        NSLog(@"Calendar: %@", [DataReader getCalendar:poi withTerm:TIME_TERM_OPEN]);
        NSLog(@"Link: %@", [DataReader getLink:poi withTerm:LINK_TERM_ALTERNATE]);
    }
}
 
...
ListEvent* list = ...; // get a list of events
[self parseItems: list]; // parse its items
...