基於 Agora SDK 實現 Windows 端的一對一視頻通話

前提條件

• Microsoft Visual Studio 2017 或以上版本

• 支持 Windows 7 或以上版本的 Windows 設備

• 有效的 Agora 賬戶（免費註冊）

注：如果你的網絡環境部署了防火牆，請根據聲網文檔中心的「應用企業防火牆限制」打開相關端口。

設置開發環境

本節介紹如何創建項目，並將 Agora SDK 集成至你的項目中。

創建 Windows 項目

參考以下步驟創建一個 Windows 項目。若已有 Windows 項目，直接查看集成 SDK。

創建 Windows 項目

1. 打開 Microsoft Visual Studio 並點擊新建項目。

2. 進入新建項目窗口，選擇項目類型爲 MFC 應用程序，輸入項目名稱，選擇項目存儲路徑，並點擊確認。

3. 進入MFC 應用程序窗口，選擇應用程序類型爲基於對話框，並點擊完成。

集成 SDK

參考以下步驟將 Agora SDK 集成到你的項目中。

1. 配置項目文件

• 根據應用場景，從 官網獲取最新 SDK，解壓並打開。

• 將下載包中的 sdk 文件夾複製到你的項目文件夾下。

2. 配置項目屬性

在解決方案資源管理器窗口中，右擊項目名稱並點擊屬性進行以下配置，配置完成後點擊確定。

• 進入 C/C++ > 常規 > 附加包含目錄菜單，點擊編輯，並在彈出窗口中輸入 $(SolutionDir)include。

• 進入鏈接器 > 常規 > 附加庫目錄菜單，點擊編輯，並在彈出窗口中輸入 $(SolutionDir)。

• 進入鏈接器 > 輸入 > 附加依賴項菜單，點擊編輯，並在彈出窗口中輸入 agora_rtc_sdk.lib。

實現音視頻通話

本節介紹如何實現音視頻通話。視頻通話的 API 調用時序見下圖：

1. 創建用戶界面

根據場景需要，爲你的項目創建音視頻通話的用戶界面。若已有用戶界面，可以直接初始化 IRtcEngine。

如果你想實現一個視頻通話，我們推薦你添加如下 UI 元素：

• 本地視頻窗口

• 遠端視頻窗口

• 結束通話按鈕

當你使用示例項目中的 UI 設計時，你將會看到如下界面：

2. 初始化 IRtcEngine

在調用其他 Agora API 前，需要創建並初始化 IRtcEngine 對象。

你需要在該步驟中填入項目的 App ID。請參考如下步驟在控制檯（console.agora.io）創建 Agora 項目並獲取 App ID：

1. 登錄控制檯，點擊左側導航欄的項目管理圖標 。

2. 點擊創建，按照屏幕提示設置項目名，選擇一種鑑權機制，然後點擊提交。

3. 在項目管理頁面，你可以獲取該項目的 App ID。

調用 createAgoraRtcEngine 和 initialize 方法，傳入獲取到的 App ID，即可初始化 IRtcEngine。

你還可以根據場景需要，在初始化時註冊想要監聽的回調事件，如本地用戶加入頻道，及解碼遠端用戶視頻首幀等。

CAgoraObject *CAgoraObject::GetAgoraObject(LPCTSTR lpAppId)
{    if (m_lpAgoraObject == NULL)
        m_lpAgoraObject = new CAgoraObject();    if (m_lpAgoraEngine == NULL)        // 創建實例。
        m_lpAgoraEngine = (IRtcEngine *)createAgoraRtcEngine();    if (lpAppId == NULL)        return m_lpAgoraObject;
    RtcEngineContext ctx;    // 添加註冊回調和事件。
    ctx.eventHandler = &m_EngineEventHandler;#ifdef UNICODE
    char szAppId[128];
    ::WideCharToMultiByte(CP_ACP, 0, lpAppId, -1, szAppId, 128, NULL, NULL);    // 輸入你的 App ID。
    ctx.appId = szAppId;#else
    ctx.appId = lpAppId;#endif

    // 初始化 IRtcEngine。
    m_lpAgoraEngine->initialize(ctx);    return m_lpAgoraObject;
}

// 繼承 IRtcEngineEventHandler 類中的回調與事件。class CAGEngineEventHandler :
    public IRtcEngineEventHandler
{public:
    CAGEngineEventHandler(void);
    ~CAGEngineEventHandler(void);    void SetMsgReceiver(HWND hWnd = NULL);    HWND GetMsgReceiver() {return m_hMainWnd;};    // 註冊 onJoinChannelSuccess 回調。
    // 本地用戶成功加入頻道時，會觸發該回調。
    virtual void onJoinChannelSuccess(const char* channel, uid_t uid, int elapsed);    // 註冊 onLeaveChannel 回調。
    // 本地用戶成功離開頻道時，會觸發該回調。
    virtual void onLeaveChannel(const RtcStats& stat);    // 註冊 onFirstRemoteVideoDecoded 回調。
    // SDK 接收到第一幀遠端視頻併成功解碼時，會觸發該回調。
    // 可以在該回調中調用 setupRemoteVideo 方法設置遠端視圖。
    virtual void onFirstRemoteVideoDecoded(uid_t uid, int width, int height, int elapsed);    // 註冊 onUserOffline 回調。
    // 遠端用戶離開頻道或掉線時，會觸發該回調。
    virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason);private:
    HWND        m_hMainWnd;
};

3. 設置本地視圖

如果你想實現一個語音通話，可以直接跳過這一步，查看下一步「加入頻道」。

成功初始化 IRtcEngine 對象後，需要在加入頻道前設置本地視圖，以便在通話中看到本地圖像。參考以下步驟設置本地視圖：

• 調用 enableVideo 方法啓用視頻模塊。

• 調用 setupLocalVideo 方法設置本地視圖。

// 啓用視頻模塊。m_lpAgoraObject->GetEngine()->enableVideo();// 設置本地視圖。VideoCanvas vc;
vc.uid = 0;
vc.view = m_wndLocal.GetSafeHwnd();
vc.renderMode = RENDER_MODE_FIT;
m_lpAgoraObject->GetEngine()->setupLocalVideo(vc);

4. 加入頻道

完成初始化和設置本地視圖後（視頻通話場景），你就可以調用 joinChannel 方法加入頻道。你需要在該方法中傳入如下參數：

• channelName: 傳入能標識頻道的頻道 ID。輸入頻道 ID 相同的用戶會進入同一個頻道。

• token：傳入能標識用戶角色和權限的 Token。可設爲如下一個值：

注：若項目已啓用 App 證書，請使用 Token。

• NULL

• 臨時 Token。臨時 Token 服務有效期爲 24 小時。你可以在控制檯裏生成一個臨時 Token，詳情請在文檔中心搜索「獲取臨時 Token」。

• 在你的服務器端生成的 Token。在安全要求高的場景下，我們推薦你使用此種方式生成的 Token。

• uid: 本地用戶的 ID。數據類型爲整型，且頻道內每個用戶的 uid 必須是唯一的。若將 uid 設爲 0，則 SDK 會自動分配一個 uid，並在 onJoinChannelSuccess 回調中報告。

更多的參數設置注意事項請參考聲網文檔中心 joinChannel 接口中的參數描述。

// 加入頻道。BOOL CAgoraObject::JoinChannel(LPCTSTR lpChannelName, UINT nUID,LPCTSTR lpToken)
{    int nRet = 0;#ifdef UNICODE
    CHAR szChannelName[128];
    ::WideCharToMultiByte(CP_UTF8, 0, lpChannelName, -1, szChannelName, 128, NULL, NULL);    char szToken[128];
    ::WideCharToMultiByte(CP_UTF8, 0, lpToken, -1, szToken, 128, NULL, NULL);    if(0 == _tcslen(lpToken))
        nRet = m_lpAgoraEngine->joinChannel(NULL, szChannelName, NULL, nUID);    else
        nRet = m_lpAgoraEngine->joinChannel(szToken, szChannelName, NULL, nUID);#else
    if(0 == _tcslen(lpToken))
        nRet = m_lpAgoraEngine->joinChannel(NULL, lpChannelName, NULL, nUID);    else
        nRet = m_lpAgoraEngine->joinChannel(lpToken, lpChannelName, NULL, nUID);#endif
    if (nRet == 0)
        m_strChannelName = lpChannelName;    return nRet == 0 ? TRUE : FALSE;
}

5. 設置遠端視圖

視頻通話中，通常你也需要看到其他用戶。在加入頻道後，可通過調用setupRemoteVideo 方法設置遠端用戶的視圖。

遠端用戶成功加入頻道後，SDK 會觸發 onFirstRemoteVideoDecoded 回調，該回調中會包含這個遠端用戶的 uid 信息。在該回調中調用 setupRemoteVideo 方法，傳入獲取到的 uid，設置遠端用戶的視圖。

// SDK 接收到第一幀遠端視頻併成功解碼時，會觸發該回調。// 在該回調中調用 setupRemoteVideo 方法設置遠端視圖。LRESULT CAgoraTutorialDlg::OnFirstRemoteVideoDecoded(WPARAM wParam, LPARAM lParam)
{
    LPAGE_FIRST_REMOTE_VIDEO_DECODED lpData = (LPAGE_FIRST_REMOTE_VIDEO_DECODED)wParam;
    VideoCanvas vc;
    vc.renderMode = RENDER_MODE_FIT;
    vc.uid = lpData->uid;
    vc.view = m_wndRemote.GetSafeHwnd();    // 設置遠端視圖。
    m_lpAgoraObject->GetEngine()->setupRemoteVideo(vc);    delete lpData;    return 0;
}

6. 離開頻道

根據場景需要，如結束通話、關閉 App 或 App 切換至後臺時，調用 leaveChannel 離開當前通話頻道。

BOOL CAgoraObject::LeaveChannel()
{
    m_lpAgoraEngine->stopPreview();    // 離開頻道。
    int nRet = m_lpAgoraEngine->leaveChannel();    return nRet == 0 ? TRUE : FALSE;
} void CAgoraObject::CloseAgoraObject()
{    if(m_lpAgoraEngine != NULL)        // 釋放 IRtcEngine 對象。
        m_lpAgoraEngine->release();    if(m_lpAgoraObject != NULL)        delete m_lpAgoraObject;
    m_lpAgoraEngine = NULL;
    m_lpAgoraObject = NULL;
}

示例代碼

你可以在 Agora-Windows-Tutorial-1to1 示例項目的 AgoraTutorialDlg.cpp 文件中查看完整的源碼和代碼邏輯。

Github ：https://github.com/AgoraIO/Basic-Video-Call/tree/master/One-to-One-Video/Agora-Windows-Tutorial-1to1

運行項目

你可以在 Windows 設備中運行此項目。當你成功開始視頻通話時，你可以同時看到本地和遠端的視圖。

如開發中遇到問題，可訪問 RTC 開發者社區發帖提問