Dolphin I/O iOS SDK Closed alpha testing release documentation 22/9/2013.

gistfile1.txt

# Dolphin I/O iOS SDK
###### Closed Alpha Release 22/9/2013

---

Thank you for trying Dolphin I/O. This release is the **closed alpha** release, meaning things will probably break and implementation of the **DolphinSDK** will change in the very near future.

The purpose of this release is for interested developers to try out how Dolphin I/O will work for their application.

If you run into any problem or bugs, we'd love to help. Please feel free to contact Max, <max@socialhappen.com>. 

---
### Getting Started

To get started, we recommend you to be using **Xcode 5** to avoid setup complications.

#### Xcode 4.6
TODO: Provide Xcode 4.6 setup instructions.

#### Xcode 5

Unzip `DolphinSDK-CAT-22092013.zip`. Drag and drop the `DolphinSDK` folder inside your project.

Import `DolphinSDK.h`.

  #import "DolphinSDK.h"
	
Try this to if the library is working properly.

    [[DolphinSDK defaultInstance] startSendingAudibleData:@"test"];

If a sound is played when you run the line above, you have successfully setup the library.

---

### DolphinSDK's Default Instance

DolphinSDK's library is setup as a singleton class. You should only use the library through the `[DolphinSDK defaultInstance]` call **only**.

DolphinSDK can only function in 1 of 2 modes at the same time, it is either **sending** or **listening**.

** Future implementation will allow you to send while listening (disabling listening momentary).*

### Sending Codes

It is very easy to send codes with DolphinSDK. There are **2 types** of codes, **Audible** and **Inaudible**. To method to receive these 2 types of codes are the same, through calling `startListening`.

### Sending Audible Code

DolphinSDK can send **Lowercase Alphabhet and Numbers**, that is 0-9 and a-z. An audible code can look like this: `h3llow0rld`.

To send **Audible Code**, call

    [[DolphinSDK defaultInstance] startSendingAudibleData:@"h3llow0rld"];
    
Where `h3llow0rld` is the string you would like to send.

**The recommended number of characters is less than 20 characters.**

### Sending Inaudible Code

Inaudible codes can send **0-9 and a-i**. An Inaudible code can look like this: `aj89726`.

To send **Audible Code**, call

    [[DolphinSDK defaultInstance] startSendingAudibleData:@"aj89726"];
    
Where `aj89726` is the string you would like to send.

**The recommended number of characters is less than 20 characters.**

### Finished Sending Event

DolphinSDK provides a notification through NSNotificationCenter to tell you that it has finished sending. A common use case for this event is to start listening again once it has finished sending.

The notification to subscribe to is `kDolphinSDKEventFinishedSending`. The code to subscribe would like something like this:

    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(dolphinSDKFinishedSending) name:kDolphinSDKEventFinishedSending object:nil];

### State Change Event

DolphinSDK provides a notification to let you know that it has changed state, betwenn `OFF`, `LISTENING` and `SENDING`.

Here's an example of the implementation:

    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(dolphinSDKStateChanged) name:kDolphinSDKEventChangedState object:nil];
    
And here's an example method to check which state DolphinSDK is in:

	- (void)dolphinSDKStateChanged {
	    NSString *newState;
	    switch ([[DolphinSDK defaultInstance] currentState]) {
	        case kDolphinSDKOff:
	            newState = @"OFF";
	            break;
	            
	        case kDolphinSDKListening:
	            newState = @"LISTENING";
	            break;
	            
	        case kDolphinSDKSending:
	            newState = @"SENDING";
	            break;
	    }
    
	    NSLog(@"DolphinSDK State Changed: %@", newState);
	}


### Listening for Codes

To start listening for codes, you would call

	[[DolphinSDK defaultInstance] startListening];

After calling this, DolphinSDK will turn on the microphone and start to listen for incoming audio.

There are 3 notifications related to listening. 

`kDolphinSDKEventBeganReceivingData`, when DolphinSDK detects incoming data.
`kDolphinSDKEventReceivedDataSuccess`, when data is received successfully.
`kDolphinSDKEventReceivedDataFailed`, when data receiving fails.

Example implementation of subscribing to these notifications:

    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(dolphinSDKReceivedData:) name:kDolphinSDKEventReceivedDataSuccess object:nil];

    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(dolphinSDKReceivedData:) name:kDolphinSDKEventReceivedDataFailed object:nil];

    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(dolphinSDKBeganReceiving) name:kDolphinSDKEventBeganReceivingData object:nil];

`kDolphinSDKEventReceivedDataSuccess` provides you with the data in the `userInfo` property of the `NSNotification` object.

`userInfo` is a dictionary with two keys, `type` and `data`.

`type` will have the value of either `audible` or `inaudible`, tell you whether it has received data as an audible code or inaudible code.

Here's an example implementation of getting the received codes.

	- (void)dolphinSDKReceivedData:(NSNotification *)notification {
	    dispatch_async(dispatch_get_main_queue(), ^{
	        [self.receivedDataIndicator stopAnimating];
	        
	        if ([notification.name isEqualToString:kDolphinSDKEventReceivedDataSuccess]) {

	            self.receivedDataLabel.text = [notification.userInfo objectForKey:@"data"];

	            self.receivedDataLabel.textColor = [UIColor whiteColor];
	            NSLog(@"Received (%@) data: %@", [notification.userInfo objectForKey:@"type"], [notification.userInfo objectForKey:@"data"]);
	        } else {

	            self.receivedDataLabel.text = [notification.userInfo objectForKey:@"data"];

	            self.receivedDataLabel.textColor = [UIColor carrotColor];
	            NSLog(@"Received data failed...");
	        }
	        
	        self.receivedDataLabel.hidden = NO;
	    });
	}

**Important Note!**

The thread DolphinSDK is running on is not the main thread, so if you want to make changes to the UI of your app when a code is received, you will need to do that in the main thread. The example above uses GCD call to do that, note `dispatch_async(dispatch_get_main_queue(), ^{})`.