그룹 음성 통화

그룹 음성 통화를 구현하는 예제 코드입니다.

필수 조건

시작하기 전에 다음 작업을 수행해야 합니다.

• PlanetKit을 초기화하세요.
• 적절한 액세스 토큰을 획득하세요.
• 그룹 통화 흐름에서 전반적인 API 사용 과정을 확인하세요.

그룹 음성 통화 구현 시 고려 사항

JoinConference()를 호출한 다음에는 반환된 SStartResult의 bSuccess 필드로 성공 여부를 확인하고 실패한 경우 reason 필드도 확인해야 합니다.

• bSuccess가 true인 경우 성공을 의미합니다.
• 그렇지 않으면 실패를 의미하며 reason에 따라 적절한 조치를 취해야 합니다.

이벤트 리스너 구현

다음처럼 통화에서 사용될 이벤트 리스너를 구현하세요.

• IConferenceEvent는 그룹 통화의 상태 변경 이벤트 처리용 인터페이스를 제공하는 추상 클래스입니다. IConferenceEvent를 상속한 클래스를 만들고, 함수를 오버라이드하세요.
• IMyMediaStatusEvent는 로컬 사용자의 미디어 상태 변경 이벤트 처리용 인터페이스를 제공하는 추상 클래스입니다. 마이크가 음 소거되거나 음 소거 해제되는 경우 또는 오디오 설명이 업데이트되는 경우 등 이벤트를 기반으로 로컬 사용자의 UI를 업데이트할 수 있습니다. IMyMediaStatusEvent를 상속한 클래스를 만들고, 함수를 오버라이드하세요.

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.
    //
};

그룹 통화 입장

그룹 통화에 입장하려면 적절한 ConferenceParamPtr 인자와 함께 JoinConference()를 호출하세요.

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

    // Prepare call event listener instance.
    PlanetKit::SharedPtr<ConferenceEventListener> m_pConferenceEventListener = PlanetKit::MakeAutoPtr<ConferenceEventListener>();

    // Prepare member variables to manage MyMediaStatusPtr and MyMediaStatusListener instances
    PlanetKit::MyMediaStatusPtr m_pMyMediaStatus;
    PlanetKit::SharedPtr<MyMediaStatusListener> m_pMyMediaStatusListener = PlanetKit::MakeAutoPtr<MyMediaStatusListener>();
};

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_pConferenceEventListener);

    // 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();

    // The currently used microphone device must be passed to JoinConference() as an argument.
    // If the microphone in use has not been set, set it using the ChangeMic() of AudioManager.
    // If the microphone is not set, PlanetKit::NullOptional will be retrieved by GetCurrentMic().
    // Passing PlanetKit::NullOptional to JoinConference() will start the conference without a microphone device.
    auto pMic = pPlanetKitManager->GetAudioManager()->GetCurrentMic();

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

로컬 사용자에 대한 미디어 상태 리스너 설정

통화가 연결되면 로컬 사용자에 대한 미디어 상태 리스너를 설정하세요.

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_pMyMediaStatusListener);
}

각 피어에 대한 피어 컨트롤 생성

피어 목록이 업데이트되면 새로 추가된 피어에 대해 PeerControl을 생성하고 IPeerControlEvent를 구현하는 이벤트 리스너를 등록하세요. 이벤트 리스너를 사용하여 각 피어의 상태 변경을 처리할 수 있습니다.

// 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_peerControlEventListener);
     };

private:
    PlanetKit::PeerControlPtr m_pPeerControl;

    // Event listener for getting PeerControl's event.
    PlanetKit::SharedPtr<PeerControlEventListener> m_peerControlEventListener = PlanetKit::MakeAutoPtr<PeerControlEventListener>( 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.
        ...
    }
}

그룹 통화 퇴장

그룹 통화에서 퇴장하려면 LeaveConference()를 호출하세요.

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

    m_pConference->LeaveConference();
}

관련 예제 코드

• PlanetKit 초기화 및 로그 설정
• 그룹 영상 통화

관련 문서

• 액세스 토큰
• 그룹 통화 흐름
• 앱 서버의 역할