Moderation — iOS

When you connect to a session with a token that includes moderator privileges, you can force other clients to disconnect from a session or mute their audio:

Checking for moderation privileges

Once you have connected to a session, you can check if the client can moderate. Check the value of the capabilities.canForceDisconnect or the capabilities.canForceMute property of the OTSession object. If it is set to YES, the client can moderate:

if (session.capabilities.canForceDisconnect) {
    // The client can force disconnect. See the next section.
} else {
    // The client cannot force disconnect.
}

if (session.capabilities.canForceMute) {
  // The client can force mute. See the next section.
} else {
  // The client cannot force mute.
}

Forcing a client to disconnect

Moderators can force any client to disconnect from the session. To force a client to disconnect, call the [OTSession forceDisconnect:connection error:error] method of the Session object, passing in the Connection object for the client you want to disconnect:

OTError* error = nil;
[session forceDisconnect:connection error:&error];
if (error) {
  NSLog(@"connect failed with error: (%@)", error);
}

You can get references to OTStream objects when the -session:connectionCreated: message is sent. See Detecting when other clients have connected and disconnected. You can also get an OTConnection object from the connection property of an OTStream object.

When the call fails, the error parameter is set to an OTError object. For example, if the client does not have moderation privileges, the error parameter is set to an OTError object with the code property set to OTSessionUnableToForceDisconnect. In this context, success indicates that the options passed into the method are valid and the request to disconnect the connection was sent. It does not guarantee that the request was successfully acted upon.

Muting the audio of streams in a session

Moderators can force all clients or a publisher of a specific stream to mute their published audio.

To force a publisher of a specific stream to mute its audio, call the [OTSession forceMuteStream:options:error:] method, passing in the OTStream object corresponding to the stream to be muted:

OTError* error = nil;
[session forceMuteStream:stream error:&error];
if (error) {
  NSLog(@"forceMuteStream failed with error: (%@)", error);
}

When the call fails, the error parameter is set to an OTError object. For example, if the client does not have moderation privileges, the error parameter is set to an OTError object with the code property set to OTSessionUnableToForceMute. In this context, success indicates that the options passed into the method are valid and the request to mute the stream was sent. It does not guarantee that the request was successfully acted upon.

Moderators can also force all streams (except for an optional array of streams) in a session to mute published audio. Call the [OTSession forceMuteAll:excludedStreams:error:] method, passing in an array of OTStream objects corresponding to the streams you want to exclude from muting:

OTError* error = nil;
[session forceMuteAll:excludedStreams error:&error];
if (error) {
  NSLog(@"forceMuteAll failed with error: (%@)", error);
}

A stream published by the moderator calling the [OTSession forceMuteAll:excludedStreams:error:] method is muted along with other streams in the session, unless you add the moderator's stream (or streams) to the excluded streams array.

If you set the excludedStreams parameter to nil, all streams in the session (including those of the moderator) will stop publishing audio:

OTError* error = nil;
[session forceMuteAll:nil error:&error];
if (error) {
  NSLog(@"forceMuteAll failed with error: (%@)", error);
}

Any streams that are published after the call to the [OTSession forceMuteAll:excludedStreams:error:] method are published with audio muted. You can remove the mute state of a session by calling the [OTSession disableForceMute:error:] method:

OTError* error = nil;
[session disableForceMute: error:&error];
if (error) {
  NSLog(@"forceMuteAll failed with error: (%@)", error);
}

After you call the [OTSession disableForceMute:error:] method, new streams published to the session will no longer have audio muted.

You can get references to OTStream objects when the [OTSessionDelegate:session:streamCreated:] message is sent. See Detecting streams in a session. You can also get an OTStream object from the stream property of an OTPublisher or OTSubscriber object.

When the stream is muted as a result of one of these methods (or from a force mute stream call in another client SDK), the [OTPublisherKitDelegate publisher:muteForced:] message is sent in each client publishing a muted stream.

Similarly, in response to a call to the [OTSession forceMuteAll:excludedStreams:error:] method (or to a force mute all call in another client SDK), [OTSessionDelegate session:muteForced:info] message is sent in each client connected to the session, and the active property of the OTMuteForcedInfo object passed in as the info parameter is set to YES.

And in response to a call to the [OTSession disableForceMute:error:] method (or to a disable force mute call in another client SDK), the [OTSessionDelegate session:muteForced:info] message is sent in each client connected to the session, and the active property of the OTMuteForcedInfo object passed in as the info parameter is set to NO.