onps棧使用說明（2）——ping、域名解析等網路工具測試

1. ping測試

協定棧提供ping工具，其標頭檔案為「net_tools/ping.h」，將其include進你的目標系統中即可使用這個工具。

……
#include "onps.h"
#include "net_tools/ping.h"

//* 回撥函數，收到目標地址的應答報文後ping工具會呼叫這個函數完成使用者的特定處理邏輯
//* 針對這個測試，在這裡就是簡單地列印出了應答報文的內容以及ping的響應時間
static void  ping_recv_handler(USHORT usIdentifier,   //* ping的標識id，響應報文與探測報文這個id應該一致
                               in_addr_t unFromAddr,  //* 響應報文的源地址
                               USHORT usSeqNum,       //* 響應報文序號，其與探測報文一致
                               UCHAR *pubEchoData,    //* 響應報文攜帶的響應資料，其與探測報文一致
                               UCHAR ubEchoDataLen,   //* 響應報文攜帶的資料長度
                               UCHAR ubTTL,           //* ttl值
                               UCHAR ubElapsedMSecs)  //* 響應時長，單位：秒，從傳送探測報文開始計時到收到響應報文結束計時
{
    CHAR szSrcAddr[20];
    struct in_addr stInAddr; 
    stInAddr.s_addr = unFromAddr; 
    printf("<Fr>%s, recv %d bytes, ID=%d, Sequence=%d, Data='%s', TTL=%d, time=%dms\r\n", 
           inet_ntoa_safe(stInAddr, szSrcAddr), //* 這是一個執行緒安全的ip地址轉ascii字串函數
           (UINT)ubEchoDataLen, 
           usIdentifier, 
           usSeqNum, 
           pubEchoData, 
           (UINT)ubTTL, 
           (UINT)ubElapsedMSecs);
}

int main(void)
{
    if(open_npstack_load(&enErr))
    {    
        printf("The open source network protocol stack (ver %s) is loaded successfully. \r\n", ONPS_VER);
        
        //* 協定棧載入成功，在這裡初始化ethernet網路卡或等待ppp鏈路就緒
    #if 0
        emac_init(); //* ethernet網路卡初始化函數，並註冊網路卡到協定棧
    #else
        while(!netif_is_ready("ppp0")) //* 等待ppp鏈路建立成功
            os_sleep_secs(1); 
    #endif
    }
    else
    {
        printf("The open source network protocol stack failed to load, %s\r\n", onps_error(enErr));
        return -1; 
    }
    
    //* 啟動ping測試
    USHORT usSeqNum = 0;
    UINT unErrCount = 0; 
    INT nPing = ping_start(&enErr); 
    if(nPing < 0)
    {
        //* 啟動失敗，輸出一條紀錄檔資訊
        printf("ping_start() failed, %s\r\n", onps_error(enErr));
        return -1; 
    }
    
    while(TRUE && usSeqNum < 100)
    {
        //* ping目標地址
        INT nRtnVal = ping(nPing, inet_addr("192.168.0.2"), usSeqNum++, 64, GetElapsedMSecs, ping_recv_handler, 3, &enErr);
        if(nRtnVal <= 0) //* ping返回一個錯誤
        {
            //* 累計ping錯誤數
            unErrCount++; 

            //* 控制檯列印當前錯誤數        
            printf("no reply received, the current number of errors is %d, current error: %s\r\n", unErrCount, nRtnVal ? onps_error(enErr) : "recv timeout"); 
        }
        os_sleep_secs(1); 
    }    
    
    //* 結束ping測試
    ping_end(nPing);
    
    return 0; 
}

上述範例程式碼呼叫了ping測試工具提供的幾個api函數。ping_start()函數的呼叫非常簡單，其功能就是開啟ping測試。結束ping測試需要呼叫ping_end()函數，否則ping測試會一直佔用協定棧資源。這幾個函數的說明如下：

函數原型

INT ping_start(EN_ONPSERR *penErr);

功能

啟動ping測試。注意，啟動後你可以隨時更換目標地址，不必拘泥於一個固定的目標地址。

引數

penErr：如果啟動失敗，該引數用於接收具體的錯誤碼

返回值

成功，返回當前啟動的ping測試任務的控制程式碼；失敗，返回值小於0，具體錯誤資訊參看pennErr儲存的錯誤碼。

函數原型

void ping_end(INT nPing);

功能

結束ping測試，釋放佔用的協定棧資源。

引數

nPing：ping_start()函數返回的ping測試控制程式碼

返回值

無

函數原型

INT ping(INT nPing,

in_addr_t unDstAddr,

USHORT usSeqNum,

UCHAR ubTTL,

UINT(*pfunGetCurMSecs)(void),

void(*pfunRcvHandler)(USHORT usIdentifier,

in_addr_t unFromAddr,

USHORT usSeqNum,

UCHAR *pubEchoData,

UCHAR ubEchoDataLen,

UCHAR ubTTL,

UCHAR ubElapsedMSecs),

UCHAR ubWaitSecs,

EN_ONPSERR *penErr);

功能

ping目標地址並等待接收對端的響應報文。其功能與通用的ping測試工具完全相同。

引數

nPing：ping_start()函數返回的ping測試控制程式碼
unDstAddr：目標地址
usSeqNum：報文序號，用於唯一的標識發出的探測報文
ubTTL：ttl值，探測報文到達目標地址之前的生存時間
pfunGetCurMSecs：函數指標，這個函數返回系統定時器自啟動以來的工作時長，單位：毫秒，其精度取決於os定時器粒度，其用於統計
ping的響應時間，必須提供這個函數，否則ping操作將無法完成
pfunRcvHandler：函數指標，收到響應報文後將呼叫這個函數完成使用者指定的操作，ping_recv_handler()就是它的實際實現
ubWaitSecs：響應報文的最長等待時間，單位：秒
penErr：如果ping失敗，該引數儲存具體的錯誤碼

返回值

大於0，ping成功；0，等待響應報文超時；小於0，失敗，具體的錯誤資訊參看pennErr儲存的錯誤碼。

2. dns測試

這個測試需要為網路卡設定好能夠存取網際網路的閘道器、DNS伺服器地址等設定資訊。當然如果採用dhcp動態地址申請的方式能夠得到這些資訊那就更省事了。dns查詢工具的標頭檔案為"net_tools/dns.h"。

……
#include "onps.h"
#include "net_tools/ping.h"
int main(void)
{
    if(open_npstack_load(&enErr))
    {    
        printf("The open source network protocol stack (ver %s) is loaded successfully. \r\n", ONPS_VER);
        
        //* 協定棧載入成功，在這裡初始化ethernet網路卡或等待ppp鏈路就緒
    #if 0
        emac_init(); //* ethernet網路卡初始化函數，並註冊網路卡到協定棧
    #else
        while(!netif_is_ready("ppp0")) //* 等待ppp鏈路建立成功
            os_sleep_secs(1); 
    #endif
    }
    else
    {
        printf("The open source network protocol stack failed to load, %s\r\n", onps_error(enErr));
        return -1; 
    }
    
    //* dns查詢測試
    in_addr_t unPrimaryDNS, unSecondaryDNS;
    INT nDnsClient = dns_client_start(&unPrimaryDNS, &unSecondaryDNS, 3, &enErr);
    if(nDnsClient < 0)
    {
        //* dns使用者端啟動失敗，輸出一條錯誤紀錄檔
        printf("%s\r\n", onps_error(enErr)); 
    }
    else
    {
        //* 傳送查詢請求並等待dns伺服器的應答
        in_addr_t unIp = dns_client_query(nDnsClient, unPrimaryDNS, unSecondaryDNS, "gitee.com", &enErr); 
        if(unIp) //* 查詢成功
        {
            CHAR szAddr[20];
            printf("The ip addr: %s\r\n", inet_ntoa_safe_ext(unIp, szAddr));
        }
        else
            printf("%s\r\n", onps_error(enErr)); //* 查詢失敗
        
        //* 結束dns查詢，釋放佔用的協定棧資源
        dns_client_end(nDnsClient);
    }
    
    return 0; 
}

與ping測試工具相同，dns查詢工具同樣提供了一組簡單的api函數用於實現域名查詢。這一組函數包括dns_client_start()、dns_client_end()以及dns_client_query()，其使用說明如下：

函數原型

INT dns_client_start(in_addr_t *punPrimaryDNS, in_addr_t *punSecondaryDNS, CHAR bRcvTimeout, EN_ONPSERR *penErr);

功能

啟動一個域名查詢使用者端。

引數

punPrimaryDNS：指標型別，用於接收主域名伺服器地址。協定棧會選擇預設路由繫結的網路卡，並得到網路卡攜帶的dns伺服器地址用於接下來的域名查詢，該引數即用於儲存主dns伺服器的地址
punSecondaryDNS：指標型別，與上同，用於接收次域名伺服器地址
bRcvTimeout：查詢超時時間，單位：秒
penErr：如果啟動失敗，該引數用於接收具體的錯誤碼

返回值

成功，返回當前啟動的dns使用者端的控制程式碼；失敗，返回值小於0，具體錯誤資訊參看pennErr儲存的錯誤碼。

函數原型

void dns_client_end(INT nClient);

功能

結束dns使用者端，釋放佔用的協定棧資源。

引數

nClient：dns_client_start()函數返回的dns使用者端控制程式碼

返回值

無

函數原型

in_addr_t dns_client_query(INT nClient, in_addr_t unPrimaryDNS, in_addr_t unSecondaryDNS, const CHAR *pszDomainName, EN_ONPSERR *penErr);

功能

傳送dns查詢請求，並等待伺服器的響應報文，功能與通用的dns使用者端完全相同。

引數

nClient：dns_client_start()函數返回的dns使用者端控制程式碼
punPrimaryDNS：主域名伺服器地址，其值為dns_client_start()函數得到的主域名伺服器地址
punSecondaryDNS：次域名伺服器地址，其值為dns_client_start()函數得到的次域名伺服器地址
pszDomainName：指標型別，指向要查詢的域名
penErr：如果查詢失敗，該引數用於接收具體的錯誤碼

返回值

成功，返回域名對應的ip地址；失敗，返回值為0，具體錯誤資訊參看pennErr儲存的錯誤碼。

3. sntp網路校時測試

與dns的測試要求一樣，要進行這個測試依然要確保你的開發板在物理層能夠存取網際網路，同時你的開發板支援rtc，並提供一組rtc操作函數，包括讀取、設定系統當前時間等api。這裡假設你的測試環境已經具備上述測試條件。sntp網路校時工具的標頭檔案為"net_tools/sntp.h"。

……
#include "onps.h"
#include "net_tools/sntp.h"
int main(void)
{
    if(open_npstack_load(&enErr))
    {    
        printf("The open source network protocol stack (ver %s) is loaded successfully. \r\n", ONPS_VER);
        
        //* 協定棧載入成功，在這裡初始化ethernet網路卡或等待ppp鏈路就緒
    #if 0
        emac_init(); //* ethernet網路卡初始化函數，並註冊網路卡到協定棧
    #else
        while(!netif_is_ready("ppp0")) //* 等待ppp鏈路建立成功
            os_sleep_secs(1); 
    #endif
    }
    else
    {
        printf("The open source network protocol stack failed to load, %s\r\n", onps_error(enErr));
        return -1; 
    }
    
    //* 先設定個不合理的時間，以測試網路校時功能是否正常,由rtc驅動提供，負責修改系統當前時間
    //* RTC字首的函數為目標系統應提供的rtc時鐘操作函數
    RTCSetSysTime(22, 9, 5, 17, 42, 30); 
    
    //* 開啟網路校時，sntp_update_by_ip()與sntp_update_by_dns()均可使用
    ST_DATETIME stDateTime;     
#if 1    
    if(sntp_update_by_ip("52.231.114.183", NULL, RTCSetSystemUnixTimestamp, 8, &enErr)) //* ntp伺服器地址直接校時
#else
    if(sntp_update_by_dns("time.windows.com", Time, RTCSetSystemUnixTimestamp, 8, &enErr)) //* ntp伺服器域名方式校時
#endif      
    {
        //* 獲取系統時間，檢查校時結果
        RTCGetSysTime(&stDateTime);
        
        //* 控制檯輸出當前系統時間
        printf("The time is %d-%02d-%02d %02d:%02d:%02d\r\n", stDateTime.usYear, stDateTime.ubMonth, 
               stDateTime.ubDay, stDateTime.ubHour, stDateTime.ubMin, stDateTime.ubSec);
    }
    else
    {        
        printf("%s\r\n", onps_error(enErr)); 
        return -1; 
    }
    
    return 0; 
}

測試程式碼首先把時間設定在了2022年9月5日17點42分30秒，目的是為了驗證目標系統時間是否會被成功校正。測試程式碼用到了目標系統應提供的一組rtc時鐘操作函數。其中RTCSetSysTime()用於設定系統時間。RTCSetSystemUnixTimestamp()函數同樣也是設定系統時間，只不過是通過unix時間戳進行設定。RTCGetSysTime()函數用於讀取當前系統時間。相較於ping及dns工具，sntp網路校時工具只提供了一個介面函數sntp_update_by_xx()即可完成校時。我們可以通過ntp伺服器地址也可以通過ntp伺服器域名進行校時。該函數的詳細使用說明如下：

函數原型

BOOL sntp_update_by_ip(const CHAR *pszNtpSrvIp, time_t(*pfunTime)(void), void(*pfunSetSysTime)(time_t), CHAR bTimeZone, EN_ONPSERR *penErr);

功能

傳送一個校時請求到pszNtpSrvIp引數指定的ntp伺服器，並等待伺服器的響應報文，完成校時操作。

引數

pszNtpSrvIp：ntp伺服器ip地址
pfunTime：函數指標，與c庫函數time()功能及原型相同，返回自1970年1月1日0時0分0秒以來經過的秒數，可以為空
pfunSetSysTime：函數指標，通過unix時間戳設定系統當前時間，由sntp_update_by_xx()內部呼叫，收到正確的響應報文後呼叫該函數設定系統時間
bTimeZone：時區，例如東8區，其值為8；西8區其值為-8
penErr：如果校時失敗，該引數用於接收具體的錯誤碼

返回值

校時成功，返回TRUE；失敗，返回FALSE，具體錯誤資訊參看pennErr儲存的錯誤碼。

sntp_update_by_dns()函數與sntp_update_by_ip()函數除了第一個入口引數變成了域名外，其它完全相同，不再贅述。