July 29, 2014
Hot Topics:
RSS RSS feed Download our iPhone app

Palm OS Communications Primer: Net Library

  • August 11, 2004
  • By Alex Gusev
  • Send Email »
  • More Articles »

The previous article told about Serial Manager. Now, we'll discuss how to develop network applications in a Palm OS environment. Obviously, we won't cover all available API calls, but will try to highlight the most common flow.

Net Library Architecture: Distant Glance

The Network Library can be naturally divided into two parts: the API itself and the protocol stack. This is a standard division for such kind of arcitectures. Your application as a client invokes API methods to get desired functionality. API translates all this calls into correspondend requests. These requests are then placed into some intermediate part—mailbox queue—and protocol stack layer reads requests from this queue and interacts with network. All responses are put back to mailbox queue, and finally and API returns answers back to client applications. Thats's the principal working flow of Palm OS Network Library.

If you want to map this schema against the OSI network model, we may state that the protocol stack provides transport, network, and data link services. TCP and UDP are transport-layer protocols, IP is a network-layer protocol, and PPP and SLIP are data link-layer protocols. Your program is responsible for providing the application, presentation, and session services of the OSI model. Thus the Net Library API plays a similar role as Berkeley sockets or the Winsock API.

If you have some experience in Unix network programming, here is the good news. As a matter of fact, you may develop your network application under a Unix environment and then (with a bit of glue here and there, of course) compile it for Palm OS. Changes will be really minor.

Stepping Into the Library

Net Lib is a system library, so it's usually preloaded at your application's runtime. Nevetheless, the standard and correct manner is first to find "Net.lib" and to load this library if necessary:

  // Find the network library
   UInt16 libRefnum = 0;
   Err error = errNone;

   error = SysLibFind("Net.lib", &libRefnum);
   if (error)
   {
      // Handle it
      return;
   }

   // Open the network library
   UInt16 netIFErrs = 0;
   error = NetLibOpen(libRefnum, &netIFErrs);
   if (netIFErrs || (error && error != netErrAlreadyOpen))
   {
       // Errors during opening Net Lib or bringing up the
       // network interface
       // Handle it somehow
   }

During above calls you're getting libRefnum—the reference number of the library. You will use it for all future calls to the rest of the network API. Please notice that when you receive netErrAlreadyOpen as an error, it means just that Net Lib is open. In this case, libRefnum is simply incremented.

Default values of interfaces to attach, IP addresses, and so forth are taken from the preference panel settings unless you want to open specific configuration by calling the following:

Err NetLibOpenConfig (UInt16 refNum,UInt16 configIndex,
                      UInt32 openFlags, UInt16 *netIFErrP);

When Net Library is no longer needed, you should release it:

error = NetLibClose(libRefnum, false);

The last parameter of this function (UInt16 immediate) controls the shutdown algorithm. If libRefnum is greater than 1, the function decreases the reference counter and returns netErrStillOpen. Otherwise, it behaves as follows:

  • If immediate is true, everything shuts down immediately. In other words, all network inrefaces, network protocol stack, and so forth are brought down, all memory is freed, and so forth.
  • If immediate is false, the OS creates a timer to wait during some period, but NetLibClose returns immediately. Net Lib is left in a "close-wait" state. If the timer expires, the Palm OS shuts libray down. If another call to NetLibOpen occurs before expiration time, the library remains open.

This brilliant solution significally increases performance because it allows you to launch another network application within a short period of time without any reinitialization.





Page 1 of 4



Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Sitemap | Contact Us

Rocket Fuel