Skip to main content
Version: 5.5

Group audio call

This page provides a code example for implementing a group audio call.

Prerequisites​

Before you begin, you must do the following:

Considerations for implementing a group audio call​

After calling JoinConference(), you must check the bSuccess field of the returned SStartResult first and then reason field if the call failed.

  • If bSuccess is true, it means success.
  • Otherwise, it means failure and you must take an appropriate action based on the reason.

Implement event listeners​

Implement the event listeners to be used on the call.

  • IConferenceEvent is an abstract class that provides an interface to handle status change events of a group call. Create a class that extends IConferenceEvent and override the functions.
  • IMyMediaStatusEvent is used to handle the local user's media status change events. You can update the local user's UI based on these events, such as when the mic becomes muted or unmuted, or when the audio description is updated. Create a class that extends IMyMediaStatusEvent and override the functions.
class ConferenceEventListener : public PlanetKit::IConferenceEvent {
public:
    // This is called when the call is connected.
    // Write your own code in function.
    void OnConnected(PlanetKit::PlanetKitConferencePtr pPlanetKitConference, PlanetKit::ConferenceConnectedParamPtr pParam) override;

    // This is called when the call is disconnected.
    // Write your own code in function.
    void OnDisconnected(PlanetKit::PlanetKitConferencePtr pPlanetKitConference, PlanetKit::ConferenceDisconnectedParamPtr pParam) override;

    // This is called when the list of peers is updated.
    // Write your own code in function.
    void OnPeerListUpdate(PlanetKit::PlanetKitConferencePtr pPlanetKitConference, PlanetKit::ConferencePeerUpdateParamPtr pParam) override;

    ...

    //
    // Also, you should implement other override functions.
    //
};

class MyMediaStatusListener : public PlanetKit::IMyMediaStatusEvent {
public :
    // This is called when the local user's audio is muted.
    // Write your own code in function.
    void OnMuted(PlanetKit::MyMediaStatusPtr pMyStatus) override;

    // This is called when the local user's audio is unmuted.
    // Write your own code in function.
    void OnUnmuted(PlanetKit::MyMediaStatusPtr pMyStatus) override;

    // This is called when the local user's audio description is updated.
    // Write your own code in function.
    void OnMyAudioDescriptionUpdated(PlanetKit::MyMediaStatusPtr pMyStatus, const PlanetKit::MyAudioDescription& sMyAudioDescription) override;

    ...

    //
    // Also, you should implement other override functions.
    //
};

Join a group call​

To join a group call, call JoinConference() with a proper ConferenceParamPtr.

class YourApplication {
private :
    // Prepare PlanetKitConference instance.
    PlanetKit::PlanetKitConferencePtr m_pConference;

    // Prepare call event listener instance.
    ConferenceEventListener m_cConferenceEventListener;

    // Prepare member variables to manage MyMediaStatusPtr and MyMediaStatusListener instances
    PlanetKit::MyMediaStatusPtr m_pMyMediaStatus;
    MyMediaStatusListener m_cMyMediaStatusListener;
};

void YourApplication::JoinConferenceExample(const std::wstring strRoomId, const std::wstring strAccessToken) {
    // Prepare local user's ID.
    std::wstring strUserId = "local user's user id";
    std::wstring strServiceId = "local user's service id";

    // Create the UserId object.
    PlanetKit::UserIdPtr pUserId = PlanetKit::UserId::Create(strUserId.c_str(), strServiceId.c_str());

    // Create ConferenceParam with Create API.
    PlanetKit::ConferenceParamPtr pConferenceParam = PlanetKit::ConferenceParam::CreateWithAccessToken(
            pUserId,
            strRoomId.c_str(),
            strServiceId.c_str(),
            strAccessToken.c_str()
        );

    // Set required parameter.
    pConferenceParam->SetConferenceEvent(&m_cConferenceEventListener);

    // Now you have to create a PlanetKit::PlanetKitConference type object
    // through the PlanetKit::PlanetKitManager::JoinConference() function.
    // Please note that the PlanetKit::PlanetKitConference type object is the main call instance
    // that controls call-related functions after the call setup completion.
    PlanetKit::PlanetKitManagerPtr pPlanetKitManager = PlanetKit::PlanetKitManager::GetInstance();

    PlanetKit::SStartResult sStartResult = pPlanetKitManager->JoinConference(pConferenceParam, &m_pConference);
    if (sStartResult.bSuccess == false) {
        // Handle an error by referring to sStartResult.reason
    }
}

Set the media status listener for the local user​

Once the call is connected, add the media status listener for the local user.

void YourApplication::SetMyMediaStatusListenerExample() {
    PlanetKit::MyMediaStatusPtr pMyMediaStatus = m_pConference->GetMyMediaStatus();

    // Keep the local user's media status instance
    this->m_pMyMediaStatus = pMyMediaStatus;

    // Register the event listener
    this->m_pMyMediaStatus->Register(&m_cMyMediaStatusListener);
}

Create peer control for each peer​

When the peer list is updated, create PeerControl for newly added peers and register a event listener that implements IPeerControlEvent. You can handle the status change of each peer using the the event listener.

// Prepare event listener class for getting peer's media change events.
class PeerControlContainer;
class PeerControlEventListener : public PlanetKit::IPeerControlEvent {
public:
    PeerControlEventListener(PeerControlContainer* pParentContainer) { m_pParentContainer = pParentContainer; }
    void OnInitialized(PlanetKit::PeerControlPtr pPeerControl, bool bResult) override;
    void OnMuted(PlanetKit::PeerControlPtr pPeerControl) override;
    void OnUnmuted(PlanetKit::PeerControlPtr pPeerControl) override;

    void OnDisconnected(PlanetKit::PeerControlPtr pPeerControl) override {
        pPeerControl->Unregister();
    }

    ...

private:
    PeerControlContainer* m_pParentContainer = nullptr;
};

// Prepare PeerControlContainer for using PlanetKit::PeerControl
class PeerControlContainer {
public:
     PeerControlContainer(PlanetKit::PeerControlPtr pPeerControl) {
        // Keep instance of PeerControl.
        m_pPeerControl = pPeerControl;
        // Register my event listener to instance of PeerControl.
        m_pPeerControl->Register(&m_cPeerControlEventListener);
     };

private:
    PlanetKit::PeerControlPtr m_pPeerControl;

    // Event listener for getting PeerControl's event.
    PeerControlEventListener m_cPeerControlEventListener{ this };
};

// You can handle added or removed peers in PlanetKit::IConferenceEvent::OnPeerListUpdate()
void  ConferenceEventListener::OnPeerListUpdate(PlanetKit::PlanetKitConferencePtr pPlanetKitConference, PlanetKit::ConferencePeerUpdateParamPtr pParam) {
    // Get the list of added peers.
    auto const& arrAdded = pParam->GetAddedPeer();

    for(int nIdx = 0; nIdx < arrAdded.Size(); ++nIdx) {
        // Create PeerControlContainer instance.
        PeerControlContainer* pPeerControlContainer = new PeerControlContainer(arrAdded.At(nIdx)->CreatePeerControl());

        // Keep instance of PeerControlContainer as you want to.
        ...
    }
}

Leave a group call​

To leave a group call, call LeaveConference().

void YourApplication::LeaveConferenceExample() {
    // Unregister the event listener
    this->m_pMyMediaStatus->Unregister();

    m_pConference->LeaveConference();
}