GKVoiceChatService Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/GameKit.framework
Availability
Available in iOS 3.0 and later.
Deprecated in iOS 7.0.
Companion guide
Declared in
GKPublicConstants.h
GKVoiceChatService.h

Overview

The GKVoiceChatService class allows your application to connect two iOS devices into a voice chat.

Before you can use voice chat, your application must configure an audio session that allows for both play and recording (kAudioSessionCategory_PlayAndRecord). For more information on audio sessions, see Audio Session Programming Guide.

The voice chat service uses a client implemented by your application to find and connect to other participants. Each participant in the chat is identified by a unique participant identifier string. The client provides a participant identifier for the local user and translates other participant identifiers into connections to other users. The format and mechanism used to translate participant identifiers into network connections is defined by the client. See Game Center Programming Guide for a more complete discussion.

Your application can configure the voice chat service to control the volume level of both local and remote participants and to detect when someone is speaking.

To use the voice chat service, your application retrieves the default service and attaches a client to it, then either connects to another participant or waits for them to start a connection.

Tasks

Determining Whether Voice Chat Is Available

Getting the Shared Voice Chat Service

Setting the Client

Establishing a Voice Chat

Adjusting Audio Properties

Monitoring the Audio Level

Ending a Voice Chat

Methods Called by the Client

Properties

client

An object that the voice chat service uses to communicate with remote participants.

@property(assign) id<GKVoiceChatClient> client
Discussion

The client’s chief responsibility is to provide a network connection that the voice chat service can use to connect to another participant.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

inputMeteringEnabled

A Boolean value that indicates whether the microphone’s sound level is being monitored.

@property(nonatomic, getter=isInputMeteringEnabled) BOOL inputMeteringEnabled
Discussion

If YES, your application can read the inputMeterLevel property to monitor the sound level of the microphone. If NO, the value of the inputMeterLevel property is undefined. Default is NO. When your application doesn’t need to monitor the microphone, it should set this property to NO to improve performance.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

inputMeterLevel

The volume, in decibels (db), being received by the microphone. (read-only)

@property(readonly) float inputMeterLevel
Discussion

The value of this property is undefined if inputMeteringEnabled is set to NO.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

microphoneMuted

A Boolean value that determines whether the user’s microphone is muted.

@property(nonatomic, getter=isMicrophoneMuted) BOOL microphoneMuted
Discussion

YES if the user’s microphone is turned off; NO if the user’s speech is being transmitted to remote participants. The default is NO.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

outputMeteringEnabled

A Boolean value that indicates whether the voice level of remote participants is monitored.

@property(nonatomic, getter=isOutputMeteringEnabled) BOOL outputMeteringEnabled
Discussion

If YES, your application can read the outputMeterLevel property to monitor sound level of remote participants. If NO, the value of the outputMeterLevel property is undefined. Default is NO. When your application doesn’t need to monitor remote participants, it should set this property to NO to improve performance.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

outputMeterLevel

The volume, in decibels (db), being received from all other participants. (read-only)

@property(readonly) float outputMeterLevel
Discussion

The value of this property is undefined if outputMeteringEnabled is set to NO.

The volume level is the aggregate volume of all remote participants, modified by the remoteParticipantVolume property.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

remoteParticipantVolume

A float that scales the volume of all remote participants.

@property(nonatomic) float remoteParticipantVolume
Discussion

The value should be between 0.0 (muted) and 1.0 (full volume). The default is 1.0.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

Class Methods

defaultVoiceChatService

Retrieves the singleton chat service.

+ (GKVoiceChatService *)defaultVoiceChatService
Return Value

The chat service.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

isVoIPAllowed

Returns whether voice chat is allowed to be used on the device.

+ (BOOL)isVoIPAllowed
Return Value

YES if voice chat is available to the application.

Discussion

Some countries or phone carriers may restrict the availability of voice over IP services. Before retrieving the shared voice chat service object, your application should check to see whether voice chat is available.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKVoiceChatService.h

Instance Methods

acceptCallID:error:

Accepts a request from a remote user to establish a voice chat.

- (BOOL)acceptCallID:(NSInteger)callID error:(NSError **)error
Parameters
callID

An integer that identifies the connection request.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Return Value

YES if the connection was established; otherwise NO.

Discussion

When a remote user requests a voice chat, the voice chat service calls the client’s voiceChatService:didReceiveInvitationFromParticipantID:callID: method. The client calls this method to accept the request or denyCallID: to reject it.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

denyCallID:

Rejects a request to establish a voice chat.

- (void)denyCallID:(NSInteger)callID
Parameters
callID

An integer that identifies the connection request.

Discussion

When a remote user requests a voice chat, the voice chat service calls the client’s voiceChatService:didReceiveInvitationFromParticipantID:callID: method. The client calls this method to reject the request or acceptCallID:error: to accept it.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

receivedData:fromParticipantID:

Called by the client to deliver new data received from a remote participant.

- (void)receivedData:(NSData *)arbitraryData fromParticipantID:(NSString *)participantID
Parameters
arbitraryData

The data received from a participant.

participantID

A string that uniquely identifies the participant who sent the data.

Discussion

The voice chat service uses a network connection provided by the client to exchange information between the participants. When the client receives information intended for the voice chat service, it should call this method to transfer it.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

receivedRealTimeData:fromParticipantID:

Called by the client to deliver voice data received from a remote participant..

- (void)receivedRealTimeData:(NSData *)audio fromParticipantID:(NSString *)participantID
Parameters
audio

The audio data that was received from the other participant.

participantID

A string that uniquely identifies the speaking participant.

Discussion

The voice chat service uses a network connection provided by the client to exchange information between the participants. When the client receives information intended for the voice chat service, it should call this method to transfer it.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

startVoiceChatWithParticipantID:error:

Sends a request to another participant to join the voice chat.

- (BOOL)startVoiceChatWithParticipantID:(NSString *)participantID error:(NSError **)error
Parameters
participantID

A string that uniquely identifies the participant to connect to.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Return Value

YES if the connection was successfully created.

Discussion

The voice chat service calls the client’s voiceChatService:sendData:toParticipantID: method to send the connection request to the remote participant.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

stopVoiceChatWithParticipantID:

Ends a previously established voice chat.

- (void)stopVoiceChatWithParticipantID:(NSString *)participantID
Parameters
participantID

A string that uniquely identifies the participant in the chat.

Discussion

When this method is called, the client’s voiceChatService:didStopWithParticipantID:error: method is called.

Availability
  • Available in iOS 3.0 and later.
Declared In
GKVoiceChatService.h

Constants

Voice Chat Service Error Domain

The GKVoiceChatService error domain.

NSString * const GKVoiceChatServiceErrorDomain;
Constants
GKVoiceChatServiceErrorDomain

An error occurred in GKVoiceChatService.

Available in iOS 3.0 and later.

Declared in GKVoiceChatService.h.

Voice Chat Service Errors

Error codes for the GKVoiceChatService error domain.

typedef enum {
   GKVoiceChatServiceInternalError = 32000,
   GKVoiceChatServiceNoRemotePacketsError = 32001,
   GKVoiceChatServiceUnableToConnectError = 32002,
   GKVoiceChatServiceRemoteParticipantHangupError = 32003,
   GKVoiceChatServiceInvalidCallIDError = 32004,
   GKVoiceChatServiceAudioUnavailableError = 32005,
   GKVoiceChatServiceUninitializedClientError = 32006,
   GKVoiceChatServiceClientMissingRequiredMethodsError = 32007,
   GKVoiceChatServiceRemoteParticipantBusyError = 32008,
   GKVoiceChatServiceRemoteParticipantCancelledError = 32009,
   GKVoiceChatServiceRemoteParticipantResponseInvalidError = 32010,
   GKVoiceChatServiceRemoteParticipantDeclinedInviteError = 32011,
   GKVoiceChatServiceMethodCurrentlyInvalidError = 32012,
   GKVoiceChatServiceNetworkConfigurationError = 32013,
   GKVoiceChatServiceUnsupportedRemoteVersionError = 32014,
   GKVoiceChatServiceOutOfMemoryError = 32015,
   GKVoiceChatServiceInvalidParameterError = 32016
} GKVoiceChatServiceError;
Constants
GKVoiceChatServiceInternalError

A serious error occurred inside the voice chat service.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceNoRemotePacketsError

The voice chat service stopped receiving packets from the remote participant.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceUnableToConnectError

The voice chat service was unable to establish a connection with another user.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceRemoteParticipantHangupError

The remote participant in a voice chat stopped the chat.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceInvalidCallIDError

The voice chat service didn’t recognize the call identifier.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceAudioUnavailableError

The audio hardware is unavailable to the voice chat service.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceUninitializedClientError

The application did not set a client before calling voice chat service methods.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceClientMissingRequiredMethodsError

The voice chat service did not find an expected method defined by the client.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceRemoteParticipantBusyError

The remote participant is already connected to a voice chat.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceRemoteParticipantCancelledError

A remote participant attempted to start a voice chat, then canceled.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceRemoteParticipantResponseInvalidError

Invalid data was received from a remote participant.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceRemoteParticipantDeclinedInviteError

A remote participant declined an invitation.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceMethodCurrentlyInvalidError

A method on the voice chat service was called when it was not allowed to be called (for example, attempting to connect when the voice chat service was already connected).

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceNetworkConfigurationError

The voice chat service had problems accessing the network.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceUnsupportedRemoteVersionError

The other participant is running a different version of the voice chat service.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceOutOfMemoryError

The voice chat service was unable to allocate memory required to operate.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.

GKVoiceChatServiceInvalidParameterError

A parameter had an unrecognized value.

Available in iOS 3.0 and later.

Declared in GKPublicConstants.h.