Remove Peer

Someone's overstayed their welcome and now you need to remove a peer from the video call room. Just call hmsSdk.removePeerRequest.

Permissions

Can't let just anyone remove others from the video call room. First you need to create a role with the permissions to remove others.

In the SDK, the permission to remove others from the room is within PermissionsParams removeOthers and you should check for that within the HMSRole of the peer to see if they have it.

Here's how to check whether the local peer has the permission to end the room:

fun isAllowedToRemovePeer(): Boolean {
    return hmsSDK.getLocalPeer()!!
                .hmsRole.permission?
                .removeOthers == true
}

private boolean isAllowedToRemovePeer() {
    return Optional.ofNullable(hmsSdk.getLocalPeer())
            .map(HMSPeer::getHmsRole)
            .map(HMSRole::getPermission)
            .map(PermissionsParams::getRemoveOthers)
            .orElse(false);
}

private boolean isAllowedToRemovePeer() {
    HMSLocalPeer peer = hmsSdk.getLocalPeer();
    if(peer != null) {
        HMSRole role = peer.getHmsRole();
        if(role != null) {
            PermissionsParams permissions = role.getPermission();
            if(permissions != null) {
                return permissions.getRemoveOthers();
            }
        }
    }
    return false;
}

hmsSdk.getLocalPeer() will not return null as long as you're in a preview or in a meeting. Since you likely won't need to check for permissions if you're not in one it would be ok.

Removing a peer

Once the permissions are checked to ensure the caller has the permission to remove a peer, remove them by calling hmsSdk.removePeerRequest.

The parameters are:

peer: is the HMSRemotePeer that you'd like to be removed from the video call room.

reason: is the string that should be conveyed to them as the reason for being removed.

hmsActionResultListener: is the listener that will convey the success or error of the server accepting the request.

fun requestPeerLeave(peer: HMSRemotePeer, reason: String) {
    hmsSDK.removePeerRequest(peer, reason,
         object : HMSActionResultListener{
            override fun onError(error: HMSException) {
            }

            override fun onSuccess() {
            }
    })
  }

public void requestPeerLeave(HMSRemotePeer peer, String reason) {
    hmsSdk.removePeerRequest(peer, reason, new HMSActionResultListener() {
        @Override
        public void onSuccess() {

        }

        @Override
        public void onError(@NonNull HMSException e) {

        }
    });
}

Handling the remove peer callback

The target of the removePeerRequest will receive a call in HMSUpdateListener of onRemovedFromRoom(notification : HMSRemovedFromRoom).

The HMSRemovedFromRoom object which is passed into the callback has the structure:

data class HMSRemovedFromRoom(
    val reason : String,
    val peerWhoRemoved : HMSRemotePeer?,
    val roomWasEnded : Boolean
)

reason: Is the string that the caller of removePeerRequest sent as the reason they were being removed from the room.

peerWhoRemoved: Is an HMSRemotePeer instance containing the details of the person who called removePeerRequest. This can be used to show the name of the person who removed them.

roomWasEnded: This will be false if the peer was removed. If true, it indicates that the peer was not removed, but the entire room was ended. See End Room for details.

When this callback is received, the UI should be cleaned up from the client side. The video call room would be ended from the SDK once this callback is sent.