Class

GKSession

A GKSession object provides the ability to discover and connect to nearby iOS devices using Bluetooth or Wi-fi.

Declaration

@interface GKSession : NSObject

Overview

Sessions primarily work with peers. A peer is any iOS device made visible by creating and configuring a GKSession object. Each peer is identified by a unique identifier, called a peer id (peerID) string. Your application can use a peerID string to obtain a user-readable name for a remote peer and to attempt to connect to that peer. Similarly, your session’s peer ID is visible to other nearby peers. After a connection is established, your application uses the remote peer’s ID to address data packets that it wants to send.

Peers discover other peers by using a unique string to identify the service they implement, called a session ID (sessionID). Sessions can be configured to broadcast a session ID (as a server), to search for other peers advertising with that session ID (as a client), or to act as both a server and a client simultaneously (as a peer.

Your application controls the behavior of a session through a delegate that implements the GKSessionDelegate protocol. The delegate is called when remote peers are discovered, when those peers attempt to connect to the session, and when the state of a remote peer changes. Your application also provides a data handler to the session so that the session can forward data it receives from remote peers. The data handler can be a separate object or the same object as the delegate.

When Bluetooth is turned on, Wi-Fi download speeds drastically decrease while the device is searching for other Bluetooth enabled devices. After the Bluetooth discovery time has completed, Wi-Fi speeds return to normal.

GKSession methods are thread-safe and may be called from any thread. However, the session always calls its delegate on the main thread.

Topics

Creating a Session

- initWithSessionID:displayName:sessionMode:

Initializes and returns a newly allocated session.

Setting and Getting the Delegate

delegate

The delegate of the session object.

Searching for Other Peers

available

A Boolean value that determines whether or not the session wants to connect to new peers.

Obtaining Information About Other Peers

- peersWithConnectionState:

Returns a list of peers in the specified connection state.

- displayNameForPeer:

Returns a user-readable name for a peer.

Connecting to a Remote Peer

- connectToPeer:withTimeout:

Creates a connection to another iOS device.

- cancelConnectToPeer:

Cancels a pending request to connect to another iOS device.

Receiving Connections from a Remote Peer

- acceptConnectionFromPeer:error:

Called by the delegate to accept a connection request received from a remote peer.

- denyConnectionFromPeer:

Called by the delegate to reject a connection request received from a remote peer.

Working with Connected Peers

- setDataReceiveHandler:withContext:

Sets the object that handles data received from other peers connected to the session.

- sendData:toPeers:withDataMode:error:

Transmits a collection of bytes to a list of connected peers.

- sendDataToAllPeers:withDataMode:error:

Transmits a collection of bytes to all connected peers.

disconnectTimeout

A time interval that expresses how long the session waits before it disconnects a nonresponsive peer.

- disconnectFromAllPeers

Disconnects the session from all connected peers.

- disconnectPeerFromAllPeers:

Disconnects a connected peer from all peers connected to the session.

Information about the Session

displayName

The name of the user.

peerID

A string that identifies your session to other peers.

sessionID

A string used to filter the list of peers who are allowed to see your session.

sessionMode

The mode the session uses to find other peers.

Constants

GKSendDataMode

The mechanism used to transmit data to other peers.

GKSessionMode

Modes that determine how a session interacts with other peers.

GKPeerConnectionState

The state of a peer known to the session.

The Session Error Domain

The GKSession error domain.

GKSessionError

Error codes for the GKSession error domain.

Relationships

Inherits From

See Also

Sessions

GKSessionDelegate

An object implements the GKSessionDelegate protocol to control the behavior of a GKSession object. The delegate is called when other visible peers change their state relative to the session. It is also called to determine whether another peer is allowed to connect to the session.

Deprecated

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software