Change Role

Role is a powerful concept that takes a lot of complexity away in handling permissions and supporting features like breakout rooms. Learn more about roles here.

Each HMSPeer instance has a role property which returns an HMSRole instance. You can use this property to do following:

1. Check what this role is allowed to publish. i.e can it send video (and at what resolution)? can it send audio? can it share screen? Who can this role subscribe to? (For example student can only see the teacher's video) This is can be discovered by checking publishSettings and subscribeSettings properties.
2. Check what actions this role can perform. i.e can it change someone else current role, end meeting, remove someone from the room. This is can be discovered by checking the permissions property.

In certain scenarios you may want to change someone's role. Imagine an audio room with 2 roles "speaker" and "listener." Only someone with a "speaker" role can publish audio to the room while "listener" can only subscribe. Now at some point "speaker" may decide to nominate some "listener" to become a "speaker." This is where the changeRoleOfPeer API comes in.

You may choose to either:

1. Single Peer Role Change: Change the role of a single peer to a specified one.
2. Bulk Role Change: Change the role of all peers with a certain role, to a specified one.

Single Peer Role Change

To invoke the API you will need 4 parameters.

• peer: An instance of HMSPeer of the peer who's role you want to change.
• toRole: The HMSRole instance for the target role.
• force: Whether you want to change their role without asking them or give them a chance to accept/reject.
• hmsActionResultListener: The HMSActionResultListener that will get a success or failure callback depending on the result of the request. Note: success doesn't mean that the role was changed, just that the server accepted the request as valid.

All the peers that are in the current room are accessible via getPeers method of HMSSDK instance after a successful room join.

A list of all available roles in the current room can be accessed via the getRoles method of HMSSDK.

Once you have all you can invoke:

fun changeRoleOfPeer(forPeer: HMSPeer, toRole: HMSRole, force: Boolean)
    hmsSDK.changeRoleOfPeer(peer, toRole, force, object : HMSActionResultListener {
        override fun onSuccess() {
            // The request was sent successfully
        }

        override fun onError(error: HMSException) {
            // There was an error.
        }
    })
}

public void changeRoleOfPeer(HMSPeer peer, HMSRole toRole, Boolean force) {
    hmsSDK.changeRoleOfPeer(peer, toRole, force, new HMSActionResultListener() {
        @Override
        public void onSuccess() {
            // The request was sent successfully
        }

        @Override
        public void onError(@NonNull HMSException e) {
            // There was an error
        }
    });
}

If the peer accepted the request and their role changed, you will get an update in the HMSUpdateListener:

fun onPeerUpdate(type: HMSPeerUpdate, peer: HMSPeer)

with the the same peer you passed as targetPeer and a ROLE_CHANGED update type.

The force parameter in changeRole, when false, is basically a polite request: "Would you like to change you role from listener to speaker?" which can be ignored by the other party. The way it works is the other party will first receive a

fun onRoleChangeRequest(request: HMSRoleChangeRequest)

callback in HMSUpdateListener. At which point the app can choose to show a prompt to the user asking for permission. If the user accepts, app should call

hmsSDK.acceptChangeRole(hmsRoleChangeRequest)

with the same request which it received in onRoleChangeRequest which completes the changeRole loop. Both parties will receive a roleUpdated callback so that they both can do necessary UI updates. Now the user actually becomes a speaker and the audio publishing will start automatically.

Now lets imagine the newly nominated speaker is not behaving nicely and we want to move him back to listener without a prompt. This is where the force parameter comes in. When it is set to true the other party will not receive a confirmation roleChangeRequest but instead will straight away receive a new set of updated permissions and stop publishing. roleUpdated callback will still be fired so that the app can update the user's UI state.

Bulk Role Change

Bulk role change is used when you want to convert all roles from a list of roles, to another role.

For example if peers join a room with a waiting role and you want to change them all to viewers then you'd use this API.

It takes fewer parameters than for a single peer. Here is the method signature.

fun changeRoleOfPeersWithRoles(ofRoles: List<HMSRole>,
                                toRole: HMSRole,
                                hmsActionResultListener: HMSActionResultListener)

1. ofRoles is a list of HMSRole whose role should be changed.
2. toRole is the HMSRole they should be changed to.
3. hmsActionResultListener has onSuccess and onError callbacks for the result of the operation.

Note that if an empty list is sent to ofRoles, no roles will be changed. This is to avoid accidentally changing roles you may not have intended such as the bots that provide recording and streaming with the roles beam.

Also bulk role changes are always forced, no dialog will be given for the peer to accept it, they will just be changed immediately.

Here's how the method could be called to change all guest and waiting roles to host:

fun changeRoles(hmsSdk: HMSSDK) {
        val rolesToChange : List<HMSRole> = hmsSdk.getRoles()
            .filter {
                it.name == "guest" || it.name == "waiting"
            }
        val toRole : HMSRole = hmsSdk.getRoles().find { it.name == "host" }!!

        hmsSdk.changeRoleOfPeersWithRoles(rolesToChange, toRole, object : HMSActionResultListener {
            override fun onError(error: HMSException) {
                // Error
            }

            override fun onSuccess() {
                // Roles changed successfully
            }

        })
    }

public void changeRoles(HMSSDK hmsSdk) {
        List<HMSRole> rolesToChange = new ArrayList<>();
        HMSRole toRole = null;
        for (HMSRole role : hmsSdk.getRoles()) {
            if(role.getName().equals("guest") || role.getName().equals("waiting")) {
                rolesToChange.add(role);
            }
            if(role.getName().equals("host")) {
                toRole = role;
            }
        }
        hmsSdk.changeRoleOfPeersWithRoles(rolesToChange, toRole, new HMSActionResultListener() {
            @Override
            public void onSuccess() {
                // Role changed
            }

            @Override
            public void onError(@NonNull HMSException e) {
                // Error occurred
            }
        });
    }

Bulk Role Change Errors

You may get the following errors for bulk role change: