Palm OS Network Programming: Writing Connected Applications for the Palm

Palm OS Network Programming: Writing Connected Applications for the Palm

by Greg Winton, Troy Mott

The wireless revolution has touched off a huge demand for Palm OS network applications. But information on how to connect a Palm is fragmented across dry function listings in the SDK documentation, a couple of book chapters, some sample code, and a few articles on the Palm web site (each of which assumes prior knowledge of network applications).Palm OS Network

…  See more details below


The wireless revolution has touched off a huge demand for Palm OS network applications. But information on how to connect a Palm is fragmented across dry function listings in the SDK documentation, a couple of book chapters, some sample code, and a few articles on the Palm web site (each of which assumes prior knowledge of network applications).Palm OS Network Programming pulls all the necessary elements together in the first complete guide to developing network applications for the Palm Computing Platform. The author assumes knowledge of Palm programming in C, but no network experience is required. You'll learn Palm network concepts such as transport protocols and client-server applications from the ground up, clearly illustrated with examples using Metrowerks CodeWarrior development environment.The Palm Net Library, essential to any network application development, gets the detailed treatment it deserves, with sample network applications demonstrating how to make the best use of this powerful system library.Palm OS Network Programming is the first complete developer's resource to building creative—and connected—applications for the fastest-growing platform of the 21st century.

Read More

Editorial Reviews

This book shows how to develop network applications for the Palm Computing platform, detailing all major concepts needed and providing examples of the two major development environments, Metrowerks CodeWarrior and GCC. The book examines the Palm Net Library and offers sample networking applications to illustrate how to make the best use of it. Though no network experience is assumed, the book will be most valuable to developers who have written Palm applications in C. Annotation c. Book News, Inc., Portland, OR (

Product Details

O'Reilly Media, Incorporated
Publication date:
Edition description:
Product dimensions:
7.14(w) x 9.20(h) x 0.90(d)

Read an Excerpt

Chapter 5: A Brief Tour of the Net Library

There are two layers to the Net Library: the network protocol stack and the application programming interface. The protocol stack is on the bottom, handling the nitty gritty details of network services. The programming interface sits on top, providing a way for your application to take advantage of these services. This architecture, and the details of its implementation, are the result of years of research and development on a wide variety of platforms. As a developer, you benefit from all this work. Understanding this work and the reasons behind the design decisions will help you write more efficient and stable network code.

In this chapter, we explore the Net Library from a distance. Don't worry, we dive into the details of Palm Network Programming in Chapter 6. If you're already an expert (or just really impatient), feel free to jump on ahead. We'll catch up. But if you persevere through this chapter, you'll be rewarded with a view of the architectural and functional beauty of the Net Library.

The Design of the Net Library

The Net Library provides networking services for the Palm OS. The standard implementation supports TCP and UDP over an IP network. In this section, we explore the architecture and design of the external interface presented to the networking applications, as well as the internal system that provides the networking functionality.


The Network Library can be divided into two parts: the API and the protocol stack. The API is the set of functions that an application invokes to access the Net Library's functionality. The protocol stack handles all communication with the network: connecting, sending, and receiving. These components are connected by a mailbox queue. Figure 5-1 illustrates these relationships.

In this diagram, we see the client application invoking functions in the API. The API translates these into requests that are placed into the mailbox queue. The protocol stack reads the requests and talks to the network. The protocol stack then places a response into the mailbox queue. The API reads the mailbox queue and returns a result to the client application.

This is a fairly standard division of labor in network architectures. Mapped against the OSI network model, 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 application needs to provide the application, presentation, and session services of the OSI model.

The Net Library API provides the interface between these layers. This is the same role that is played by the Berkeley sockets API on Unix platforms and the Winsock API on Microsoft Windows platforms. The mailbox queue is an operating system construct that allows the user interface task, under which the API is running, to communicate with the protocol stack's task.

The Protocol Stack

The Palm OS protocol stack runs as a task, separate from the UI task under which all applications run. As it turns out, the Net Library API is mostly responsible for packaging up requests for the protocol stack and putting them in the mailbox queue, and then taking responses off the mailbox queue and translating them into return values that the application expects. The protocol stack contains the meat of the network handling code. The mailbox queue sits between these two modules.

When an API call is made, it packages the relevant information into a request and adds it to the end of the mailbox queue. The protocol stack reads requests from the queue, processes them, and then adds responses to the mailbox queue. The API call waits until it receives this response to be returned by the protocol stack.

Avoiding Network Traffic Jams

Networks, as a rule, operate much more slowly than the devices they connect. In the case of a nonmultitasking environment, such as DOS or Windows 3.1, this means that everything comes to a stop for the duration of any network call. This is bad.

So TCP/IP protocol stacks provide asynchronous operation. The network call is made (packets are sent and received) but the application doesn't have to wait for the answer. Every so often, it peeks to see if there is data to send or receive

Also, modern operating systems provide multitasking. So you can create a subtask that patiently sits and waits for the network to respond. The rest of the application goes along, occasionally checking for signs that the network has replied. When the network does respond, the subtask signals that it is ready for the next network function. On the Protocol Stack side, different tasks can be connecting, reading, and writing, all at the same time. And this is even better.

On the Palm, things are a little different. Today's PC's are computing powerhouses running sophisticated operating systems on hundreds of megabytes of memory and gigabytes of disk space, all made possible by the wire that connects them to the electrical outlet. Palms run on batteries, and small ones at that. Once you switch to batteries, well, your priorities just change a little. Efficiency is really important. So is simplicity.

So the Palm Engineers simplified. They provided multitasking internally to the protocol stack. The protocol stack runs as a separate task in the operating system. This allows tremendous efficiencies in the networking code. These tasks run separate from the single application task. This simplifies things for the application developer.

Figure 5-2 illustrates the addition of task boundaries to our architectural diagram.

The application calls functions from the Net Library API. These functions are performed in the application task; the API writes to and reads from the queue, and at the same time, the protocol stack tasks reads from and writes to the queue, and talks to the network.

Avoiding Lengthy Redials

When your application exits, it should be a good Palm citizen and shut down its resources, including the network. But what if you are surfing the Net and want to look up the URL of a best friend's adventure travel web site? Press the address book button. The first thing that happens is the web browser has to stop. And when the web browser stops, it closes down the Net Library, which closes down the Net protocol stack. So you copy the URL of a best friend's adventure travel web site and switch back to your browser. Paste the URL into the browser, and wait while the browser loads the protocol stack.

I used to do this with my email. Every 15 minutes or so, Eudora would wake up, dial my ISP, check for mail, and hang up. Whenever I really needed something, I'd dial up the network, launch a browser, and hit the Web. I had to really need it though, to go through all that work. Nowadays I stay connected to the Internet all day and all night. I find that because the connection is up, I'm much more likely to check things out on the Web. A constant connection encourages me to use my browser application.

You want to encourage your users to use your network application. But, if every time your user switches away to look up the URL of his best friend's adventure travel web site, he loses the network connection and then has to wait while your application reconnects to the Internet before he can find out about exciting trips, well, let's just say your application will not be popular.

Fortunately, the Palm engineers have already solved this. When an application closes down the Net Library, it can select to have the protocol stack live a little before shutting itself down. So now I can switch to address book, find the URL I need, switch back to my browser, paste the URL, and find about exciting trips all without dropping my connection. I just have to be really fast.

You might ask, "Why doesn't my web browser just leave the protocol stack running when I switch to another application?" Well it could, but how would it know that you intend to switch back again? If you never switch back again, then your web browser never gets the chance to unload the protocol stack. The protocol stack would run forever (or until your Palm shutdown), consuming resources and tying up the processor with all those protocol stack tasks.

Calling the Net Library

The API functions act as if they are directly linked into the application. They execute in the applications task, and if there is not a lot of overhead in the function calls, they share the same memory with the application. But they are not directly linked into the application. If they were, their code would repeat in every network-aware application. This overhead applies even if the application never actually accessed the network.

So the Palm engineers simplified. The Net Library API is packaged as a system library. The client application attempts to load this library. If it cannot, the application can continue safely without networking, or it can exit. In short, it can handle this failure gracefully. On the other hand, if it is successful, then the client application has gained entrance to the wonderful world of the Net Library.

Using the Net Library

This is all very well and good, but what does the application do in this wonderful world of the Net Library? Let's take a look.

Before we dive into the functions themselves, let's talk briefly about system libraries. When your compiler comes to normal function calls, it embeds the symbolic function name into your code. Then the linker comes along and resolves this symbolic name to the actual address of the function's implementation. If the linker can't find the implementation of the function, then it generates a linker error.

Palm OS System Libraries work differently. They operate according to something known as the 68K Trap Dispatch mechanism. 68K refers to the series of processors from Motorola that run the Palm, the MAC, and a bunch of other devices. What we care about, though, is the Trap Dispatch Mechanism. When your compiler comes across a call to a function in a system library, instead of inserting a symbolic name, it puts in assembly instructions that generate an exception that is caught by the Palm OS's system trap dispatcher. The system trap dispatcher uses the first parameter to select the correct system library to invoke a function from. As a result, every call to the NetLib API takes a reference number as its first parameter (well, actually there are a few byte-ordering functions that don't, but they turn out to be macros).

Finding the Net Library

The very first thing you must do is to find the Net Library. This is a three-step process. First, ask the operating system for its version. The Net Library appeared for the first time with the PalmPilot Professional, and it simply cannot be used on any device that is not running Palm OS Version 2 or above. The version of the OS is stored in the sysFtrNumROMVersion feature. If you don't know how to retrieve features, don't panic. We describe this in Chapter 6, when we discuss how to load, initialize, and open the Net Library.

Once you determine that you're running the right OS, you need to check if the Net Library is in fact there. Remember, system libraries such as the Net Library are not required for a Palm Device. Even though it has been included with every device since the PalmPilot Professional, there are no guarantees that it will always be available. The easiest way to check if the Net Library is installed is to try to get its version number. The version of the Net Library is stored in the netFtrNumVersion feature. If the Net Library is not installed, you get an error when you try to retrieve this feature.

Now, if you've gotten this far, it's time to initialize the Net Library. System libraries are always loaded, you just have to find them. Call SysLibFind and it returns the reference to the Net Library. This is the reference number that you'll need to pass to all subsequent Net Library API calls, so keep it handy. Once you have the Net Library's reference number, you're ready to go. The process for finding the Net Library is shown in Figure 5-3.

Configuring the Net Library

It's a fact of life that network interfaces need to be configured. Thankfully, configuration is an infrequent occurrence. Rather than have each network application bear the responsibility of supporting network interface configuration, the Palm engineers provided an application in which all preferences should be set. The network panel of the Preferences application allows the user to configure one or more services. Services describe how the device operates on the network: connection types, baud rates, flow control, and all sorts of settings that I usually only set when I have a tech support person near at hand.

There might be a time when you find yourself needing to adjust the configuration for your application. For this, the Palm engineers also provided a programmatic API for setting these configurations. In fact, they used this same API in implementing the Network Preferences Panel. The Net Library setup and configuration functions allow you to configure the protocol stack from your application. This is not recommended except in extreme circumstances. We do not cover the setup and configuration protocol in this book.

Opening the Net Library

Once you have finished configuring the Net Library, it's time to use it. Remember, the Palm engineers set up the Net Library so that the protocol stack could be loaded only when needed. Your application must therefore tell the Net Library when you want to use the protocol stack and when you are done. The process for opening the Net Library is illustrated in Figure 5-4.

Initializing the protocol stack

To open the Net Library and initialize the protocol stack, call NetLibOpen. Be sure you've completed any setup and configuration required. NetLibOpen reads the current configuration from the Network Preferences database. Once the Net Library is open, most of these configurations cannot be changed. Also, be careful about calling any nonconfiguration functions before calling NetLibOpen; they mostly return the error netErrNotOpen.

The first thing NetLibOpen does is check if the protocol stack has already been loaded. If so, NetLibOpen simply increments the open count and returns. Why would the protocol stack have already been loaded? The most common reason is that an application has closed the Net Library, but specified that the protocol stack should hang out for a while in case it's needed again soon. This could happen in the case described earlier, in which you want to switch from your web browser to your address book to get a URL and switch back again. Or, you might switch from your web browser to your email reader.

If the protocol stack is not already loaded, NetLibOpen creates a new task and loads the protocol stack on this task. The protocol stack then allocates memory for internal use, and brings up the network connection. At this point, the configuration settings are read and applied. From now on, any configuration changes are only reflected if the Net Library is shut down and reopened......

Read More

Meet the Author

Greg Winton has been a professional software developer for thirteen years. As director of software development for Bachmann Software and Services, he transformed a respected Windows software development company into the premier Palm solutions provider.

Customer Reviews

Average Review:

Write a Review

and post it to your social network


Most Helpful Customer Reviews

See all customer reviews >