iOS Developer Library

Developer

GameKit Framework Reference GKTurnBasedExchange Class Reference

Options
Deployment Target:

On This Page
Language:

GKTurnBasedExchange

Inherits From


Conforms To


Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


Available in iOS 7.0 and later

A GKTurnBasedExchange object provides developers with a way to expand how turn based matches are currently played by allowing players to send information even when they are not the current player.

All exchanges must include the current turn holder, as only the current turn holder is allowed to update the game status. Exchanges have the following workflow:

  • A player specifies a timeout and passes a small amount of data.

  • The receiving player(s) get a push notification and receive the exchange the next time they launch the game.

  • Depending on the type of exchange, the receiver may reply to the exchange and send a small amount of data back to the sender.

  • The sender gets a push notification after all receivers have responded or timed-out and gets the reply the next time they launch the game.

  • The exchange is complete and the turn holder is notified. The turn holder then applies the results of the exchange to the match data and marks it as resolved.

  • Cancels an exchange.

    Declaration

    Swift

    func cancelWithLocalizableMessageKey(_ key: String!, arguments arguments: [AnyObject]!, completionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    - (void)cancelWithLocalizableMessageKey:(NSString *)key arguments:(NSArray *)arguments completionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    key

    A string in the Localizable.strings file for the current localization.

    arguments

    An array of objects to be substituted using the format string.

    completionHandler

    A block to be called after the cancel event has been sent.

    The block receives the following parameters:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    Discussion

    When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

    It is possible to cancel both active and complete exchanges. When an exchange is cancelled, a push notification is sent to each participant using the localizable message. An error is returned if the exchange has previously been cancelled.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • The date when the exchange was completed. (read-only)

    Declaration

    Swift

    var completionDate: NSDate! { get }

    Objective-C

    @property(readonly, nonatomic) NSDate *completionDate

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • data data Property

    Data that is sent with the exchange. (read-only)

    Declaration

    Swift

    var data: NSData! { get }

    Objective-C

    @property(readonly, nonatomic) NSData *data

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • A persistent identifier that is used when referring to this exchange. (read-only)

    Declaration

    Swift

    var exchangeID: String! { get }

    Objective-C

    @property(readonly, nonatomic) NSString *exchangeID

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • message message Property

    The localized message that is pushed to all of the recipients of the exchange. (read-only)

    Declaration

    Swift

    var message: String! { get }

    Objective-C

    @property(readonly, nonatomic) NSString *message

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • The players to receive the exchange. (read-only)

    Declaration

    Swift

    var recipients: [AnyObject]! { get }

    Objective-C

    @property(readonly, nonatomic) NSArray *recipients

    Discussion

    An array of GKTurnBasedParticipant objects denoting the players the exchange was sent to.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • replies replies Property

    List of exchange replies. (read-only)

    Declaration

    Swift

    var replies: [AnyObject]! { get }

    Objective-C

    @property(readonly, nonatomic) NSArray *replies

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • Replies to an exchange.

    Declaration

    Swift

    func replyWithLocalizableMessageKey(_ key: String!, arguments arguments: [AnyObject]!, data data: NSData!, completionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    - (void)replyWithLocalizableMessageKey:(NSString *)key arguments:(NSArray *)arguments data:(NSData *)data completionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    key

    A string in the Localizable.strings file for the current localization.

    arguments

    An array of objects to be substituted using the format string.

    data

    The data associated with the exchange.

    completionHandler

    A block to be called after the reply has been sent.

    The block receives the following parameters:

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

    Discussion

    When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • sendDate sendDate Property

    The date that the exchange was sent out. (read-only)

    Declaration

    Swift

    var sendDate: NSDate! { get }

    Objective-C

    @property(readonly, nonatomic) NSDate *sendDate

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • sender sender Property

    The participant who sent the exchange. (read-only)

    Declaration

    Swift

    var sender: GKTurnBasedParticipant! { get }

    Objective-C

    @property(readonly, nonatomic) GKTurnBasedParticipant *sender

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • status status Property

    The current status of the exchange. (read-only)

    Declaration

    Swift

    var status: GKTurnBasedExchangeStatus { get }

    Objective-C

    @property(assign, readonly, nonatomic) GKTurnBasedExchangeStatus status

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • The amount of time the exchange is to stay active before timing out. (read-only)

    Declaration

    Swift

    var timeoutDate: NSDate! { get }

    Objective-C

    @property(readonly, nonatomic) NSDate *timeoutDate

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • The status of an exchange or reply.

    Declaration

    Swift

    typealias GKTurnBasedExchangeStatus = _GKTurnBasedExchangeStatus

    Objective-C

    typedef enum _GKTurnBasedExchangeStatus : int8_t { GKTurnBasedExchangeStatusUnknown = 0, GKTurnBasedExchangeStatusActive = 1, GKTurnBasedExchangeStatusComplete = 2, GKTurnBasedExchangeStatusResolved = 3, GKTurnBasedExchangeStatusCanceled = 4 } GKTurnBasedExchangeStatus;

    Constants

    • GKTurnBasedExchangeStatusUnknown

      GKTurnBasedExchangeStatusUnknown

      The state of the exchange or reply is not currently known.

      Available in iOS 7.0 and later

    • GKTurnBasedExchangeStatusActive

      GKTurnBasedExchangeStatusActive

      The exchange or reply is currently active.

      Available in iOS 7.0 and later

    • GKTurnBasedExchangeStatusComplete

      GKTurnBasedExchangeStatusComplete

      The exchange or reply has been completed.

      Available in iOS 7.0 and later

    • GKTurnBasedExchangeStatusResolved

      GKTurnBasedExchangeStatusResolved

      The exchange or reply has been resolved.

      Available in iOS 7.0 and later

    • GKTurnBasedExchangeStatusCanceled

      GKTurnBasedExchangeStatusCanceled

      The exchange or reply has been cancelled.

      Available in iOS 7.0 and later

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • The amount of time that passes before an exchange time outs.

    Declaration

    Swift

    var GKExchangeTimeoutDefault: NSTimeInterval var GKExchangeTimeoutNone: NSTimeInterval

    Objective-C

    extern NSTimeInterval GKExchangeTimeoutDefault; extern NSTimeInterval GKExchangeTimeoutNone;

    Constants

    • GKExchangeTimeoutDefault

      GKExchangeTimeoutDefault

      The exchange will timeout after one day if no reply is received.

      Available in iOS 7.0 and later

    • GKExchangeTimeoutNone

      GKExchangeTimeoutNone

      The exchange will not timeout.

      Available in iOS 7.0 and later