Dolphin I/O iOS SDK - Partner Release 01/04/2014

gistfile1.txt

# Dolphin I/O iOS SDK
###### Partner Release 01/04/2014

---

Thank you for trying Dolphin I/O. This release is the **partner** release. The SDK is compiled and will only work with the application ids you have provided.

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 the zip file you have received via email. Drag and drop the `DolphinIO` folder inside your project.

Import `DolphinIO.h`.

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

	[[DolphinIO defaultInstance] startWithListening:YES];
	
	DolphinIOData *data = [[DolphinIOData alloc] initWithValue:@"test"];
	[[DolphinIO defaultInstance] sendData:data isAudible:YES];

Turn up your volume and run the app. If the sound plays, you have successfully setup the library.

---

### DolphinIO's Default Instance

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

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

### Starting DolphinIO

To use DolphinIO, you will need to start it up using either the **start** or **startWithListening** methods.

To start and enable listening for incoming data by default, use **start** like this:
	
	[[DolphinIO defaultInstance] start]; 

*Alias for [[DolphinIO defaultInstance] startWithListening:YES]*
	
To start and disable listening, use **startWithListening** like this:

	[[DolphinIO defaultInstance] startWithListening:NO];

Starting DolphinIO is required only once for each launch, unless you call the **stop** method.

### Stopping DolphinIO

In the case that you would like to stop DolphinIO, you may call the **stop** method like so:

	[[DolphinIO defaultInstance] stop];


### Sending Codes

It is very easy to send codes with DolphinIO. There are **2 types** of codes, **Audible** and **Inaudible**. DolphinIO provides you with the **DolphinIOData** class. To send codes, you will create a DolphinIOData object and send that through the **sendData: isAudible:** method.

### Sending Data Code

For **Audible** data, DolphinIO can send **Lowercase Alphabhet, Uppercase Alphabhet, and Numbers**, that is 0-9, a-z, A-Z.

For **Inaudible** data, DolphinIO can send **a-i (lowercase) and 0-9**.

To create a DolphinIOData object:

	DolphinIOData *data = [[DolphinIOData alloc] initWithValue:@"HelloWorld"]
    
To send the code as **Audible**, call:

	[[DolphinIO defaultInstance] sendData:data isAudible:YES];
	
To send the code as **Inaudible**, call:

	[[DolphinIO defaultInstance] sendData:data isAudible:NO];

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

### Finished Sending Event

DolphinIO provides a notification through NSNotificationCenter to tell you that it has finished sending.

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

    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(dolphinIOFinishedSending) name:kDolphinIOEventFinishedSending object:nil];

### State Change Event

DolphinIO 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(dolphinIOStateChanged) name:kDolphinIOEventChangedState object:nil];
    
And here's an example method to check which state DolphinIO is in:

	- (void)DolphinIOStateChanged {
	    NSString *newState;
	    switch ([[DolphinIO defaultInstance] currentState]) {
	        case kDolphinIOOff:
            newStateName = @"OFF";
            
	        case kDolphinIOListening:
	            newStateName = @"LISTENING";
	            break;
	        
	        case kDolphinIOReceivingAudible:
	            newStateName = @"RECEIVING AUDIBLE";
	            break;
	        
	        case kDolphinIOReceivingInaudible:
	            newStateName = @"RECEIVING INAUDIBLE";
	            break;
	        
	        case kDolphinIOSending:
	            newStateName = @"SENDING";
	            break;
	        
	        case kDolphinIOIdle:
	            newStateName = @"IDLE";
	            break;
	            
	        default:
	            newStateName = @"UNKNOWN";
	            break;
	    }
	    
	    NSLog(@"DolphinIO State Changed: %@", newState);
	}


### Listening for Codes

There are 3 notifications related to listening. 

`kDolphinIOEventBeganReceivingData`, when DolphinIO detects incoming data.
`kDolphinIOEventReceivedDataSuccess`, when data is received successfully.
`kDolphinIOEventReceivedDataFailed`, when data receiving fails.

Example implementation of subscribing to these notifications:

    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(DolphinIOReceivedData:) name:kDolphinIOEventReceivedDataSuccess object:nil];

    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(DolphinIOReceivedData:) name:kDolphinIOEventReceivedDataFailed object:nil];

    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(DolphinIOBeganReceiving) name:kDolphinIOEventBeganReceivingData object:nil];

`kDolphinIOEventReceivedDataSuccess` 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.

The `data` object is a `DolphinIOData` object, which you can directly access the value property.

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

	- (void)DolphinIOReceivedData:(NSNotification *)notification {
	    dispatch_async(dispatch_get_main_queue(), ^{
	    	DolphinIOData *data = [notification.userInfo objectForKey:@"data"];
	    	
	        if ([notification.name isEqualToString:kDolphinIOEventReceivedDataSuccess]) {

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

### DolphinIO's Thread
**Important Note!**

The thread DolphinIO 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(), ^{})`.