基於 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。可設爲以下一個值：

  • 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 ：github.com/AgoraIO/Bas…

若是在開發過程當中，遇到問題，能夠訪問「RTC 開發者社區」發帖提問，聲網工程師會在線幫助解答。