Palm OS Communications Primer: Net Library, Page 4

Debugging Network Applications

Net Library contains a NetLibMaster function, which provides the network statistics, interface statistics, and the contents of the trace buffer. The last feature is quite useful for debugging purposes. NetLibMaster, together with NetLibTracePrintF and NetLibTracePutS, gives you a powerful mechanism to debug either your application or network configuration issues. To get an access to the tracing capability, you can call either NetLibSettingSet for the Net Library in general or NetLibIFSettingSet for specific a network interface, passing netSettingTraceBits as target setting. The netTracingAppMsgs bit should be raised to get the above functions doing something. The default value is (netTracingErrors | netTracingAppMsgs), but if you don't see any output, take care about setting everything properly. The next code snippet illustrates all this dry theory:

///////////////////////////////////////////////////////////////////
// Enable tracing
///////////////////////////////////////////////////////////////////
void SetupTracing()
{
   Err   err;
   DWord value;
   Word  settingSize;
   Word  index;
   Byte  traceRoll;

   value = 0x0800;
   settingSize = sizeof(value);
   err = NetLibSettingSet(libRefnum, netSettingTraceSize, &value,
                          settingSize);
   if (err)
   {
      // Handle error
      return;
   }

   // Set tracing bits
   value = netTracingErrors | netTracingMsgs | netTracingAppMsgs;

   // Set trace level for stack
   NetLibSettingSet(libRefnum, netSettingTraceBits, &value,
                    settingSize);

   // Set rollover to none
   traceRoll = false;
   NetLibSettingSet(libRefnum, netSettingTraceRoll, &traceRoll,
                    sizeof(traceRoll));

   // Set trace bits also for all attached interfaces
   for (index = 0; 1; index++)
   {
      DWord ifCreator;
      Word  ifInstance;

      err = NetLibIFGet(libRefnum, index, &ifCreator, &ifInstance);
      if (err)
      {
         err = 0;
         break;
      }

      NetLibIFSettingSet(libRefnum, ifCreator, ifInstance,
                         netIFSettingTraceBits, &value, settingSize);
   }
}

...
///////////////////////////////////////////////////////////////////
// Do actual traces
///////////////////////////////////////////////////////////////////
NetLibTracePrintF(libRefNum, "Error occured is %x\n", error);
...

///////////////////////////////////////////////////////////////////
// Extract tracing data
///////////////////////////////////////////////////////////////////

void ShowTracing()
{
   NetMasterPBType pb;
   Err             err;
   Char            text[100];
   DWord           oldTrace;
   Int             i;
   DWord           value;
   Word            settingSize;
   Boolean         setTraceBits = false;
   Word            index;
   Byte            traceRoll;
   CharPtr         cmdP;

   // Temporarily disable tracing
   settingSize = sizeof(oldTrace);
   NetLibSettingGet(libRefnum, netSettingTraceBits, &oldTrace,
                    &settingSize);
   value = 0;
   err = NetLibSettingSet(libRefnum, netSettingTraceBits, &value,
                          settingSize);

   if (oldTrace == 0)
      StdPutS("Tracing not on\n");
   else {
      StdPutS("From oldest to newest...");
      StdPutS("\nTICKS EVENT  ROUTINE\n");
   }

   // See what the oldest entry is
   for (i=0; 1; i++) {
      pb.param.traceEventGet.index = i;
      pb.param.traceEventGet.textP = text;
      err = NetLibMaster(libRefnum, netMasterTraceEventGet, &pb,
                         AppNetTimeout);
      if (err) {
         printf("Error: %s\n", appErrString(err));
         break;
      }
   }

   // Print them in oldest to newest order
   for (i=i-1; i>=0 ; i--)
   {
      pb.param.traceEventGet.index = i;
      pb.param.traceEventGet.textP = text;
      err = NetLibMaster(libRefnum, netMasterTraceEventGet, &pb,
                         AppNetTimeout);
      if (err) break;
      // User 'text' buffer as you want to
      ...
   }

   // Restore tracing level
   err = NetLibSettingSet(libRefnum, netSettingTraceBits, &oldTrace,
                          settingSize);
}

Download

You may download the sample project here.

About the Author

Alex Gusev started to play with mainframes at the end of the 1980s, using Pascal and REXX, but soon switched to C/C++ and Java on different platforms. When mobile PDAs seriously rose their heads in the IT market, Alex did it too. Now, he works at an international retail software company as a team leader of the Mobile R department, making programmers' lives in the mobile jungles a little bit simpler.