AmbientC

Introduction

AmbientC provides an Objective-C implementation of the ambient-oriented programming principles. The goal of this framework around Bonjour and socket communication is to provide developers with an easy way to develop ambient-oriented applications for mobile devices, like the iPhone and iPod Touch. The framework has similar characteristics to AmbientTalk [1].

The framework provides a way to connect devices running one or more services within a manet. For example, when creating a distributed audio player, one device can export his speaker as a service, while the other is the playlist (exporting as a playlist). When a device sends a message to a kind of service, all connected services running that service will receive that message. One of the main goals of the framework is providing an easy way to send messages to devices running inside a mobile ad-hoc network (manet). This means that there is no knowing when a device will be connected or not. The framework provides this abstraction: messages will only be sent to connected services. The developer does not have to check wether a specific device is connected or not, the framework provides this abstraction.

Features

No specific network setup (no server needed, only basic TCP/IP)
Especially suited for mobile devices (iPhone, iPod Touch)
Desktop OS compatible (Leopard, Tiger)
Multiple service exporting
Asynchronous, non-blocking communication
Trouble-free disconnections
Fast communication, low overhead (socket-based)

Examples

Setup: Basic service exporting and discovering

Here we are creating an AmbientC object and using it to export a service and start discovering services within the "iPiano" identifier.

 aC = [[AmbientC ambientCExportDiscoverServicesWithIdentifier:@"iPiano" withServiceType:@"speaker"] retain]; 
 [aC setDebugInfo:YES];
 [aC setDelegate:self];

Setting the delegate is important, because this is the only way in which you can receive notifications about service (dis)connections. This is normally set to self, but this could be any other class. Also remark that debugging information was on for testing.

Sending messages

Sending messages is very simple. There are three posibilities of sending messages:

To a specified service:
```
 [aC sendMessageToServices:@"yourmessage" ofServiceType:@"speaker"]; 
```
All devices running this service will receive the message.
To a specific service:
```
 [aC sendMessageToService:@"yourmessage" ofServiceId:@"theserviceidentifieroftheservice"]; 
```
Remember that the service identifier is a unique identifier for a specific service. This method can also be used to send to a specific device. The service identifier is obtained by storing the identifier received from the delegate from a discovered service.
And finally, to all connected services (within the Ambient-C identifier):
```
 [aC sendMessageToAllConnectedServices:@"yourmessage"]; 
```
Please remark that a device running multiple services will received this message for every service.

Also remark that for all methods that send messages, the sending will only happen to connected services within the Ambient-C identifier. Services running outside this identifier are not discovered.

Exporting a service

Exporting a service is possible after setup of the initial AmbientC object. For example, with the following code a keyboard service is exported:

 [aC exportService:@"keyboard"];

This returns a BOOL value whether this was succesfull or not (network error or service with that name already exported)

Removing exported service

Removing an exported service is also possible. For example, removing the previously exported "keyboard" service, is accomplished with the following method:

[aC removeServer:@"keyboard"];

This also returns a BOOL value telling the removal succeeded or not.

Registering the delegates

For registering the events important to Ambient-C, it is necessary to register the delegate. In most of the times, this is registered to the own class, self. E.g.:

 [aC setDelegate:self];

After that, the delegates are registered and can be used within the defined class. There are three available delegate methods, but not all of them have to be used. Here are the three methods with basic documentation:

Service discovered
```
 -(void)serviceDiscovered:(NSString *)serviceType withDeviceName:(NSString *)devName withServiceId:(NSString *)servId
```
This method provides the type of service that has been discovered, the name of the device running that service and the unique service identifier.
Service disconnected
```
- (void)serviceDisconnected:(NSString *)serviceType withServiceId:(NSString *)servId
```
This method informs about the disconnection of a service, providing the type of service that disconnected and the unique identifier.
Message received
```
 - (void)messageReceived:(NSString *)receivedMessage fromServiceId:(NSString *)servId
```
This method informs about a received message, providing the message and the unique service identifier.

Requirements

The following class files should be included:

AmbientC (Header and code files)
NetSocket (Header and code files)
NSDataSocketInformation (Header and code files)

The following framework has to be included:

CFNetwork

Intented usage

The framework is designed to run on iPod Touch devices running operating system version 2.2.1. It is tested on the simulator running under Leopard. It should also work for applications running under Leopard, but this is untested.

References

[1] AmbientTalk, PROG, Vrije Universiteit Brussel, More information at prog.vub.ac./amop Accessed 5 april 2009.