iOS Components and Frameworks: Understanding the Advanced Features of the iOS SDK (2014)

---

Sending Data

Connecting to a new peer is only the first step in implementing a functional peer-to-peer networking app. After connecting to a new peer, you will want to send that peer some data. Sending data using Game Kit is extremely easy. Take a look at the following code snippet:

[mySession sendDataToAllPeers:messageData withDataMode:GKSendDataReliable error:&error];

The first part of this method is a pointer to the session that was returned as part of connecting to a new peer. In the preceding example the data is being sent to all connected peers. There is an alternative method, sendData:toPeers:withDataMode:error:, if you wanted to send data to only a specific peer. The next part of the code snippet is an argument called messageData. This needs to be of the NSData type. You also have to specify a data mode, which is covered later in this section. (The example uses GKSendDataReliable.) Finally, there is a reference to an error to catch anything that goes wrong.

Data Modes

When data is sent using Game Kit, there are two possible valuables for the dataMode argument: GKSendDataReliable and GKSendDataUnreliable. It is important to understand the distinction between these methods:

GKSendDataReliable tells Game Kit that this data is required to be received by the peer; if it is not received, it will be resent until it is received. In addition to continually retrying to send the data, GKSendDataReliable ensures that data packets are received in the same order in which they are sent. This method is used in the sample app since we want text messages to never get lost in the network and we want them to appear in the order in which they are sent.

GKSendDataUnreliable, on the other hand, means that the data is not resent if it is not received; each packet is sent only once. This means that the networking is faster since the originating peer does not have to wait for confirmation that the packet has arrived. In addition, packets might not arrive in the order in which they were sent. GKSendDataUnreliable is very useful for fast networking and keeping two clients in sync when the data isn’t entirely crucial to the app. For example, if you have a racing game, you will want to send the position of your car to the other player. However, if a packet doesn’t reach its destination, it is better to skip it and sync up with the next packet; otherwise, the data you receive will be old and out-of-date. Each client would slowly fall further out of sync with the other.

There is a general rule of thumb for helping you decide which data mode you should use for your app. Use GKSendDataReliable when the data and order are more important than the time it takes to arrive. Use GKSendDataUnreliable when the speed at which the data is received is more important than the order and the data itself.

Sending Data in the Sample App

Take a look at how sending data is implemented in the sample app; everything is handled directly in the sendMessage: method. Because the app will need to send more data than just the message string, a new dictionary is created to also store information about who the message came from. For the purposes of the sample app, there is a mutable array that will hold onto all the incoming and outgoing data called chatObjectArray. Because we are sending a message, a local copy is inserted into that array.

Earlier, you learned that you can send only NSData. However, you do not want to send the dictionary since the sender key is set to "myself"; when the other peer receives a message, the sender should not be set to "myself". A new NSData object is created with just the message string, and a dictionary object can be created after the message has been received.

Now that the message has been translated into an NSData object and a new NSError has been created, the session that was created when the app connected to a peer can call sendDataToAllPeers:withDataMode:error: with the newly created information. You will want to make sure that no errors were returned; if an error is returned, it is logged to the console in the sample app.

- (IBAction)sendMessage:(id)sender
{
NSDictionary *messageDictionary = [[NSDictionary alloc] initWithObjectsAndKeys:[inputTextField text], @"message", @"myself", @"sender", nil];

[chatObjectArray addObject: messageDictionary];
[messageDictionary release];

NSData *messageData = [inputTextField.text dataUsingEncoding:NSUTF8StringEncoding];

NSError *error = nil;

[self.currentSession sendDataToAllPeers:messageData withDataMode:GKSendDataReliable error:&error];

if(error != nil)
{
NSLog(@"An error occurred: %@", [error localizedDescription]);
}


[inputTextField setText: @""];

[sendButton setEnabled: NO];

[chatTableView reloadData];

//scroll to the last row
NSIndexPath* indexPathForLastRow = [NSIndexPath indexPathForRow:[chatObjectArray count]-1 inSection:0];

[chatTableView scrollToRowAtIndexPath:indexPathForLastRow atScrollPosition:UITableViewScrollPositionTop animated:YES];
}

The sample app has some additional cleanup that needs to be performed whenever a message is sent, such as clearing the text field and setting the Send button back to disabled. In addition, the chatTableView is reloaded and scrolled to the bottom to reflect the new outgoing message. In the next section you will learn how to receive the data that was just sent.

Receiving Data

Sending data is pointless if the receiving peer is not set up to handle that data. The first thing that needs to be done when preparing your app to receive data is letting the GKSession know which class will handle the incoming messages by setting the dataReceiveHandler. An example is shown in the following code snippet:

[self.currentSession setDataReceiveHandler:self withContext:nil];

A data handler needs to be set for each session and is session-specific. You can define a context as part of the setDataReceiveHandler: and this context will be passed along as part of any incoming data calls.

Every time your session receives data, your data handler will call receiveData:fromPeer:inSession:context. The following example prints the received NSData to the log:

- (void) receiveData:(NSData *)data fromPeer:(NSString *)peer inSession: (GKSession *)session context:(void *)context
{
NSLog(@"Data Received: %@", data);
}

Receiving Data in the Sample App

The previous examples are really the simplest form of receiving data. Most of the time, you need to convert the NSData back into whatever format you want to work with, such as an NSString or a UIImage. In addition, you will probably want to do something with that newly received data beyond logging it. Take a look at the receiveData:fromPeer:inSession:context: method in the sample app, shown in the following code snippet. Because the sample app is working with a string, the first thing that needs to be done is retrieve the value back out of theNSData. After you have the NSString, you need to store it into the expected data format of an NSDictionary. This is the same approach taken in the sending data methods, except that the "sender" key "peer" is set instead of "myself". This allows it to be displayed correctly in the table view. After the new dictionary is inserted into the chatObjectArray, the chatTableView is refreshed and scrolled to the bottom to make the newest message visible.

- (void) receiveData:(NSData *)data fromPeer:(NSString *)peer inSession: (GKSession *)session context:(void *)context
{
NSString *messageString = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];

NSDictionary *messageDictionary = [[NSDictionary alloc] initWithObjectsAndKeys:messageString, @"message", @"peer", @"sender", nil];

[chatObjectArray addObject: messageDictionary];

[messageString release];
[messageDictionary release];

[chatTableView reloadData];

//scroll to the last row
NSIndexPath* indexPathForLastRow = [NSIndexPath indexPathForRow:[chatObjectArray count]-1 inSection:0];

[chatTableView scrollToRowAtIndexPath:indexPathForLastRow atScrollPosition:UITableViewScrollPositionTop animated:YES];

}

State Changes

When working with remote peers, it is important to know the state of the remote device because networks and connectivity can unexpectedly drop. You will want to inform your user and perform appropriate error-recovery behavior in these events. To monitor state changes, you must first declare a class as the delegate, make sure that your class conforms to GKSessionDelegate, and then set the delegate for the session in a manner similar to the following example. Note that this is different from the dataReceiveHandler, which can be set to a different class.

[self.currentSession setDelegate: self];

Your newly set delegate will now receive calls to session:peer:didChangeState:. This code snippet is from the sample app, in which a disconnected peer is caught and we present the user with an alert informing them of such. See Table 10.1 for a complete list of possible states.

- (void)session:(GKSession *)session peer:(NSString *)peerID didChangeState:(GKPeerConnectionState)state
{
if(state == GKPeerStateDisconnected)
{
UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Alert!" message:@"The peer has disconnected" delegate:nil cancelButtonTitle: @"Dismiss" otherButtonTitles: nil];

[alert show];
[alert release];

[self.currentSession disconnectFromAllPeers];

[[self navigationController] popViewControllerAnimated: YES];
}
}

Table 10.1 Possible State Changes and Their Definitions

Advanced Features

In previous sections, you learned how to create a new basic connection using the Peer Picker and sending and receiving data from that peer. Game Kit’s Bluetooth networking has several advanced features, some of which are covered in this section.

Peer Display Name

It is often useful to display the name of the peer you are connected to. Referring to Figure 10.1, the navigation bar contains a title that references the connected user; this is done using the following code snippet:

NSString *peerDisplayName = [self.currentSession displayNameForPeer: self.peerID];

[[self navigationItem] setTitle: [NSString stringWithFormat:@"Chat with %@", peerDisplayName]];

Connecting Without the Peer Picker

There are times when you might want to connect using Game Kit but without displaying the Peer Picker. Although this is a slightly more difficult approach, it is still entirely possible. First, you need to create a new session, as shown in the following example:

currentSession = [[GKSession alloc] initWithSessionID:nil displayName:nil sessionMode:GKSessionModePeer];

currentSession.delegate = self;
currentSession.available = YES;
currentSession.disconnectTimeout = 15;

[currentSession setDataReceiveHandler:self withContext:nil];

There are some key differences in the preceding example from implementing a connection using the Peer Picker. First, you need to create the GKSession instead of the Peer Picker returning one during the connection callback. The sessionID argument can be used to define matching peers to connect to. If the session IDs do not match, the devices will not see each other. In the following section you will learn more about the sessionMode argument. You will also need to set the available property to YES, which is an important step for other devices to see the device as ready for a connection. A disconnectTimeout is also set for 15 seconds.

When you set a device to available, it will inform any other devices looking for peers that it has become available for connections. Because there is a state change from unavailable to available, the GKSession delegate will receive a callback to session:peer:didChangeState:. In the following example, when the app detects that a new device has become available, it immediately tries to connect. In real-world implementations, you might want to present your user a list of IDs before they pick one to connect to.

- (void)session:(GKSession *)session peer:(NSString *)peerID didChangeState:(GKPeerConnectionState)state
{
if(state == GKPeerStateAvailable)
{
[session connectToPeer:peerID withTimeout:15];
}
}

When a device attempts to connect to your device, you receive a call to didReceiveConnectionRequestFromPeer:, which must be handled similarly to the next code snippet:

- (void)session:(GKSession*) session didReceiveConnectionRequestFromPeer:(NSString*) peerID
{
[session acceptConnectionFromPeer:peerID error:nil];
}

After you have called acceptConnectionFromPeer:, your delegate will receive another call to session:peerID:didChangeState: with a GKPeerStateConnected state. From here, you can continue with your app as if you had connected using the Peer Picker.