实时捕捉以太网原始数据包(PacketRawEthernetMonitor)----Kithara RTS工程源代码解析

// Used Modules:     Kernel Module, Packet Module//使用到的模块
//                                                                                                 
// Descript.:        Sample application showing how to implement a raw
//                   ethernet monitor application  //形成一个以太网监视应用程序
// Purpose:
//
// This example shows how to program a raw ethernet monitoring application.
//该例子展示了如何编制一个基本的以太网监视程序
// First, the program opens the driver and the Ethernet adapter.//首先，打开驱动及网卡适配器
// We install the receiver callback.安装接收器回调函数
// A receive thread is displaying the mac header, which is submitted by a pipe. 接收线程通过管道显示mac头
// Finally we release all used resources and close the driver.最后清理资源
//
// Attention! It is nessary that there is no switch between our adapter and the adapter we want to trace!不能对适配器进行切换
// Otherwise, only broadcast messages will be monitored!  否则只能监视反馈回来的信息
//
// ATTENTION! Network cards can only be used here, when the driver of the card has been switched to Kithara!
// It is not possible to use the original driver for real-time! Please refer to the manual, chapter 16
// "Packet Module" for further instructions on switching the driver to Kithara!


#include "..\_KitharaSmp\_KitharaSmp.h"


const char* pCustomerNumber = "DEMO";


//--------------------------------------------------------------------------------------------------------------
// This is a user defined argument structure to the callback routine.用户定义回调函数结构体
// You are free to define your own arguments in any record/class.
//--------------------------------------------------------------------------------------------------------------

//------ CallBackData ------
struct CallBackData {   //回调数据的结构体，
  Handle hAdapter_;     //适配器句柄
  Handle hCallBack_;    //回调函数句柄
  Handle hEvent_;       //事件句柄
  Handle hPipe_;        //管道句柄
  bool finished_;       //标志位
};

//当接收到数据包时，将数据包地址存在管道中
//--------------------------------------------------------------------------------------------------------------
// These are user defined callback routines. They are called every time a packet is received.一下定义回调函数，当有数据包接收到的时候调用
// We put the data in a pipe and set the receive event. 将数据放入管道中，设置接收数据的事件
//--------------------------------------------------------------------------------------------------------------

//------ _callBack ------回调函数的定义
static Error __stdcall _callBack(void* pArgs, void* pContext) {
  CallBackData* pData = (CallBackData*)pArgs;
  PacketUserContext* pUserContext = (PacketUserContext*)pContext;

  Error ksError;

  ksError = KS_putPipe(                                 // 将数据包地址放入管道中
              pData->hPipe_,                            // Pipe handle，管道对应的句柄
              &pUserContext->pPacketApp,                // Address of pointer to packet，待存入管道中的数据内存地址，这里是接收的数据包地址
              1,                                        // Item count，数量
              NULL,                                     // Number of bytes transmitted ，Number of bytes transmitted so far.
              0);                                       // Flags, here none
  if (ksError != KS_OK)
    return ksError;

  ksError = KS_setEvent(                                // 设置事件，触发线程继续运行
              pData->hEvent_);                          // Event handle事件句柄
  if (ksError != KS_OK)
    return ksError;

  return KS_OK;
}


//--------------------------------------------------------------------------------------------------------------
// This is the user defined thread function. It contains a loop in which the thread waits for the event
// signalization whenever a packet is received.线程，等待事件信号，然后将管道中的数据取出并显示数据包头，最后释放数据包的内存对象
// After displaying the packet header, the packet must be released with KS_releasePacket.
//--------------------------------------------------------------------------------------------------------------

Error __stdcall _recvThread(void* pArgs) {//也是一个回调函数，接收数据的线程

  Error ksError = KS_OK;
  CallBackData* pData = (CallBackData*)pArgs;

  while (!pData->finished_) {             //


    //----------------------------------------------------------------------------------------------------------
    // Wait for the event to be set.
    //----------------------------------------------------------------------------------------------------------

    ksError = KS_waitForEvent(                          // 等待接收数据
                pData->hEvent_,                         // Event handle在回调函数中定义的事件
                0,                                      // Flags
                0);                                     // Time-out, in 100-ns-units
    if (ksError != KS_OK)
      return ksError;

    KSMACHeader* pHeader;
    while (KS_getPipe(pData->hPipe_, &pHeader, 1, NULL, 0) == KS_OK) {
      outputTxt(" ", true);//读出管道中的数据，并显示出来
      for (int i = 0; i < 3; ++i)
        outputHex(KS_ntohs(*(ushort*)&pHeader->source[i * 2]), "", "", false);

      outputTxt(" -> ", false);

      for (int i = 0; i < 3; ++i)
        outputHex(KS_ntohs(*(ushort*)&pHeader->destination[i * 2]),
                  "", "", false);
      outputHex(KS_ntohs(pHeader->typeOrLength), " typeOrLength: ", "", false);

      //--------------------------------------------------------------------------------------------------------
      // Finally we release the packet.最后清空数据包
      //--------------------------------------------------------------------------------------------------------

      ksError = KS_releasePacket(//释放数据包
                  pData->hAdapter_,                     // Adapter handle，网卡句柄
                  pHeader,                              // Pointer to packet，指向数据包的指针
                  KSF_RAW_ETHERNET_PACKET);             // Flags，标志
      if (ksError != KS_OK)
        return ksError;
    }
  }

  outputTxt("Thread has been finished.");
  return ksError;
}


//--------------------------------------------------------------------------------------------------------------
// This is the main program 主函数
//--------------------------------------------------------------------------------------------------------------

void runSample() {
  outputTxt("***** Kithara example program ‘PacketRawEthernetMonitor‘ *****");

  Error ksError;

  ///////////////////////////////////////////////////////////////////////
  //////1.程序初始化
  ///////////////////////////////////////////////////////////////////////

  //------------------------------------------------------------------------------------------------------------
  // Opening the driver is always the first step! After that, we can use other functions. If the opening fails,
  // no other function can be called.
  //
  // This function takes your customer number with Kithara (or "DEMO" or "BETA" if applicable) as a parameter.
  //------------------------------------------------------------------------------------------------------------

  ksError = KS_openDriver(//第一步，打开驱动
              pCustomerNumber);                         // Customer number 已定义const char* pCustomerNumber = "DEMO";
  if (ksError) {
    outputErr(ksError, "KS_openDriver", "Maybe incorrect customer number?");
    return;
  }


  //------------------------------------------------------------------------------------------------------------
  // Allocation of Sharedmem分配共享内存
  //------------------------------------------------------------------------------------------------------------

  CallBackData* pAppPtr; //结构体指针
  CallBackData* pSysPtr;
  ksError = KS_createSharedMem(//创建共享内存
              (void**)&pAppPtr,                         // App Pointer
              (void**)&pSysPtr,                         // Sys Pointer
              "MyPacketRawEthernetMonitorMemory",       // Name
              sizeof(CallBackData),                     // Size大小为定义的结构体大小
              0);                                       // Flags
  if (ksError != KS_OK) {
    outputErr(ksError, "KS_createSharedMem",
      "Failed to allocate shared memory");
    KS_closeDriver();
    return;
  }

  //------------------------------------------------------------------------------------------------------------
  // First, the names of all network adapters are queried and displayed首先，查询并显示所有网络适配器
  //------------------------------------------------------------------------------------------------------------

  char pDeviceName[256];//定义一个大小为256的char型数组

  outputTxt(" ");
  outputTxt("Following network adapters found:");

  for (int i = 0; ; ++i) {


    //----------------------------------------------------------------------------------------------------------
    // The following function can be used to query the names of all network adapters assigned to the Kithara
    // Driver. The number ‘i‘ runs beginning from zero. 
    //枚举可用的网卡适配器，选择一个使用
    // ATTENTION! Network cards can only be used here, when the driver of the card has been switched to Kithara!
    // It is not possible to use the original driver for real-time! Please refer to the manual, chapter 16
    // "Packet Module" for  further instructions on switching the driver to Kithara!
    //----------------------------------------------------------------------------------------------------------

    ksError = KS_enumDevices(//枚举设备的函数
                "NET",                                  // Searches for network devices，专门寻找有关网络的设备
                i,                                      // Count, starting with zero计数
                pDeviceName,                            // Buffer for device name 设备名称
                0);                                     // Flags
    if (ksError != KS_OK) {
      if (KSERROR_CODE(ksError) != KSERROR_DEVICE_NOT_FOUND)
        outputErr(ksError, "KS_enumDevices",
          "Unable to query network device name!");

      if (KSERROR_CODE(ksError) == KSERROR_DEVICE_NOT_FOUND && !i) {
        outputTxt("No devices found");
        outputTxt(" ");
        outputTxt("Did you switch the network card driver to Kithara?");
        outputTxt("Please refer to the manual, chapter 16 \"Packet Module\"");
        outputTxt("for further instructions!");
        KS_closeDriver();
        return;
      }

      break;
    }

    outputDec(i, "", ": ", false);
    outputTxt(pDeviceName);
  }
  outputTxt(" ");


  //------------------------------------------------------------------------------------------------------------
  // Please enter the index of the adapter, which should be opened上一个函数时枚举，现在选择，index不同，选择好，打开网络适配器
  //------------------------------------------------------------------------------------------------------------

  int deviceIndex = inputDec("Device number: ", "");

  ksError = KS_enumDevices(
              "NET",                                    // Searches for network devices
              deviceIndex,                              // Index of device
              pDeviceName,                              // Buffer for device name
              0);                                       // Flags
  if (ksError != KS_OK) {
    outputErr(ksError, "KS_enumDevices",
      "Unable to query network device name!");
    KS_closeDriver();
    return;
  }

  outputTxt("Selected device: ", false);
  outputTxt(pDeviceName);


  //------------------------------------------------------------------------------------------------------------
  // Then we open the network adapter.
  //
  // Please enter a part of the hardware ID of your network controller.
  // e.g.
  // Intel: "VEN_8086"
  // Realtek: "PCI\\VEN_10EC&DEV_8139" or "DEV_8139"
  //------------------------------------------------------------------------------------------------------------
  //选择好之后，打开选择好的网卡适配器
  ksError = KS_openAdapter(
              &pAppPtr->hAdapter_,                      // Adapter handle
              pDeviceName,                              // Device name of the adapter
              100,                                      // Receive Pool Length
              0,                                        // Send Pool Length
              KSF_RAW_ETHERNET_PACKET |
              KSF_ACCEPT_ALL);                          // Flags
  if (ksError != KS_OK) {
    outputErr(ksError, "KS_openAdapter", "Failed to open adapter");
    KS_closeDriver();
    return;
  }


  //------------------------------------------------------------------------------------------------------------
  // Here we set a mac multicast address, cause we want to display all packets going to this address.设置一个mac地址，来显示经过此地址的数据包
  // It is necessary that there is no network switch between our adapter and the adapter we want to trace
  //注意：适配器跟要追溯的适配器不能切换
  //------------------------------------------------------------------------------------------------------------

  byte multi[6] = { 0xff, 0xff, 0xff, 0xff, 0xff, 0xff };
  ksError = KS_execAdapterCommand(//对网络适配器进行操作
              pAppPtr->hAdapter_,                       // Adapter handle
              KS_PACKET_SET_MAC_MULTICAST,              // Command， Adds a MAC multicast address to the reception filter.
              multi,                                    // Data 数据包存在这里面啦
              0);                                       // Flags
  if (ksError != KS_OK) {
    outputErr(ksError, "KS_execAdapterCommand", "Failed to execute command");
    KS_closeDriver();
    return;
  }


  //------------------------------------------------------------------------------------------------------------
  // For data transfer between the async callbacks and the receive thread we use a pipe.
  // 用一个管道来进行异步回调与接收线程之间数据传输
  //------------------------------------------------------------------------------------------------------------

  ksError = KS_createPipe(                              //创建管道
              &pAppPtr->hPipe_,                         // Pipe Handle
              "MyPacketRawEthernetMonitorPipe",         // Name管道名称
              sizeof(void*),                            // Item size, here pointer size
              100,                                      // Item count
              NULL,                                     // Object to signal
              0);                                       // Flags
  if (ksError != KS_OK) {
    outputErr(ksError, "KS_createPipe", "Unable to create pipe!");
    KS_closeDriver();
    return;
  }


  //------------------------------------------------------------------------------------------------------------
  // Create an event object, which will be signalled when a packet arrives. 创建一事件，当有数据包到达时，有相应信号
  //每当有数据接收到时 有相应信号
  //------------------------------------------------------------------------------------------------------------

  ksError = KS_createEvent(
              &pAppPtr->hEvent_,                        // Event handle
              "MyPacketRawEthernetMonitorEvent",        // Name of event
              0);                                       // Flags, here 0
  if (ksError != KS_OK) {
    outputErr(ksError, "KS_createEvent", "Unable to create finish event!");
    KS_closeDriver();
    return;
  }

  
  //------------------------------------------------------------------------------------------------------------
  // Now create the thread.创建线程
  //------------------------------------------------------------------------------------------------------------

  ksError = KS_createThread(                            //调用线程回调函数，当有信号（event产生），说明有数据，将数据从管道中读出
              _recvThread,                              // Thread function，调用回调函数，开始等待信号，有event信号，开始读出数据
              pAppPtr,                                  // Parameter to the thread
              NULL);                                    // Address of thread handle,
                                                        // not needed here
  if (ksError != KS_OK) {
    outputErr(ksError, "KS_createThread", "Unable to create the thread!");
    KS_closeDriver();
    return;
  }


  //------------------------------------------------------------------------------------------------------------
  // For signalization we use a callback 回调函数
  //------------------------------------------------------------------------------------------------------------

  ksError = KS_createCallBack(
              &pAppPtr->hCallBack_,                     // Address of callback handle 句柄地址
              _callBack,                                // Callback Routine 接收数据 将接收的数据放入管道中，并设置event，触发waitforevent，读出这里写入的数据
              pSysPtr,                                  // Reference parameter to the callback
              KSF_DIRECT_EXEC,                          // Flags, here kernel level in realtime context
              0);                                       // Priority
  if (ksError != KS_OK) {
    outputErr(ksError, "KS_createCallBack", "Failed to create callback");
    KS_closeDriver();
    return;
  }


  //------------------------------------------------------------------------------------------------------------
  // Finally we start the packet receiver with KS_recvPackets.程序中没有KS_recvPackets的，源码注释错误。
  // The signalization object must be a callback create with DIRECT_EXEC.
  // KS_installPacketHandler函数的作用是为网卡的某个事件（这里是收到数据包时触发的事件KS_PACKET_RECV）关联一个回调函数（pAppPrt->hCallBack）,在事件触发时该回调函数将会被执行
  //------------------------------------------------------------------------------------------------------------

  pAppPtr->finished_ = false;                          // false表示线程中开始接收数据

  ksError = KS_installPacketHandler(                    // 安装数据包处理函数
              pAppPtr->hAdapter_,                       // Adapter handle
              KS_PACKET_RECV,                           // Event code 安装好用该函数进行数据包的接收，开始接收数据包
              pAppPtr->hCallBack_,                      // Callback handle，调用回调函数，将采集到的数据包的地址放入管道中
              KSF_RAW_ETHERNET_PACKET);                 // Flags Enables the raw ethernet packet mode for the handle，处理的是原始数据包
  if (ksError != KS_OK) {
    outputErr(ksError, "KS_installPacketHandler", "Failed to install handler");
    KS_closeDriver();
    return;
  }

  inputTxt("Press <enter> to stop... ");
  outputTxt(" ");

/////以下为程序退出部分
  //------------------------------------------------------------------------------------------------------------
  // Set the event, so the thread can be finished. Before that, we set the variable ‘finished_‘ to true, so the
  // thread knows it should terminate.
  //------------------------------------------------------------------------------------------------------------

  pAppPtr->finished_ = true;                           //首先线程中接收到数据显示，然后线程关闭，以下是停止接收数据


  //------------------------------------------------------------------------------------------------------------
  // To stop the receiver, we set the Callback handle to NULL. 停止接收数据
  //------------------------------------------------------------------------------------------------------------

  ksError = KS_installPacketHandler(
              pAppPtr->hAdapter_,                       // Adapter handle
              KS_PACKET_RECV,                           // Event code
              NULL,                                     // Callback handle句柄为null，停止接收数据
              KSF_RAW_ETHERNET_PACKET);                 // Flags
  if (ksError != KS_OK) {
    outputErr(ksError, "KS_installPacketHandler", "Failed to uninstall handler");
    KS_closeDriver();
    return;
  }

  ksError = KS_setEvent(pAppPtr->hEvent_);
  if (ksError != KS_OK)
    outputErr(ksError, "KS_setEvent", "Setting event failed!");
  waitTime(500 * ms);


  //------------------------------------------------------------------------------------------------------------
  // Display the adapter state 以下是显示适配器信息
  //------------------------------------------------------------------------------------------------------------

  KSAdapterState state;
  state.structSize = sizeof(KSAdapterState);
  ksError = KS_getAdapterState(                         //获取适配器信息函数
              pAppPtr->hAdapter_,                       // Adapter handle
              &state,                                   // Pointer to Buffer
              0);                                       // Flags
  if (ksError != KS_OK)
    outputErr(ksError, "KS_getAdapterState",
      "Querying the adapter state failed!");
  else {
    outputTxt(" ");
    outputDec(state.numPacketsSendOk,         "Number of packets sent successfully:             ", "");
    outputDec(state.numPacketsSendError,      "Number of packets failed to send:                ", "");
    outputDec(state.numPacketsSendARPTimeout, "Number of packets failed because of ARP timeout: ", "");
    outputDec(state.numPacketsWaitingForARP,  "Number of packets waiting for ARP:               ", "");
    outputDec(state.numPacketsRecvOk,         "Number of packets received successfully:         ", "");
    outputDec(state.numPacketsRecvError,      "Number of packets failed to receive:             ", "");
    outputTxt(" ");
  }


  //------------------------------------------------------------------------------------------------------------
  // Close the Adapter.  
  //------------------------------------------------------------------------------------------------------------

  ksError = KS_closeAdapter(                            //关闭适配器
              pAppPtr->hAdapter_);                      // Adapter handle
  if (ksError != KS_OK)
    outputErr(ksError, "KS_closeAdapter", "Unable to close Adapter!");


  //------------------------------------------------------------------------------------------------------------
  // Remove callbacks.
  //------------------------------------------------------------------------------------------------------------

  ksError = KS_removeCallBack(
              pAppPtr->hCallBack_);                     // Callback handle
  if (ksError != KS_OK)
    outputErr(ksError, "KS_removeCallBack", "Unable to remove the callback!");


  //------------------------------------------------------------------------------------------------------------
  // Close the event object
  //------------------------------------------------------------------------------------------------------------

  ksError = KS_closeEvent(
              pAppPtr->hEvent_);                        // Event handle
  if (ksError != KS_OK)
    outputErr(ksError, "KS_closeEvent", "Unable to close event!");


  //------------------------------------------------------------------------------------------------------------
  // Remove the data pipe
  //------------------------------------------------------------------------------------------------------------

  ksError = KS_removePipe(
              pAppPtr->hPipe_);                         // Pipe handle
  if (ksError != KS_OK)
    outputErr(ksError, "KS_removePipe", "Unable to remove the pipe!");


  //------------------------------------------------------------------------------------------------------------
  // Remove the shared memory
  //------------------------------------------------------------------------------------------------------------

  ksError = KS_freeSharedMem(
              pAppPtr);                                 // Application pointer
  if (ksError != KS_OK)
    outputErr(ksError, "KS_freeSharedMem", "Unable to remove shared memory!");


  //------------------------------------------------------------------------------------------------------------
  // At last we have to close the driver to free any allocated resources.
  //------------------------------------------------------------------------------------------------------------

  ksError = KS_closeDriver();
  if (ksError != KS_OK)
    outputErr(ksError, "KS_closeDriver", "Unable to close the driver!");

  waitTime(500 * ms);
  outputTxt("End of program ‘PacketRawEthernetMonitor‘.");
  outputTxt("Press <enter> to close.");
}