Magic Internet Kit Programmer's Guide

Automated package creation

The typical first step in creating a Magic Cap application is cloning an existing package. The Magic Internet Kit takes this much farther, though, and allows you to customize your new communicating application's features with an easy-to-use dialog box.

Additionally, MIK provides several template packages to start from, so you can pick the perfect starting point for your own development. These templates start at the most basic "empty" communications package and go up to a dumb terminal package with complete user interface.

---

Note: If you are already familiar with developing Magic Cap applications, you are probably familiar with the Clone Package feature of the Magic Developer environment. You do not want to use this script when cloning a MIK template; use the New Comms App feature instead. The template make files that come with the Magic Internet Kit are designed to be modified by the new menu item's script, so it's best not to mess with them directly.

---

The New Comms App helper tool

MIK's New Comms App dialog is accessed from the Magic -> NewCommsApp menu in your Macintosh Programmer's Workshop (MPW) environment. From here you can click on the checkboxes for the types of features you want in your new application.

Figure 2 NewCommsApp script dialog

---

Note: If you are familiar with MPW, you'll notice that this dialog box is really a Commando interface to a MPW script.

---

Connection types and hardware support

The first part of New Comms App to look at is the Connection Types section. There are two options in here: Serial and TCP/IP. Serial means direct serial communications; for example using the serial port to read and write raw bytes of data. The TCP/IP connection type uses Transmission Control Protocol/Internet Protocol to communicate with remote hosts, for example a web server.

The next section to look at, Hardware Support, deals with what physical means that you'll use for communicating. These options are dependent on what connection types you have set up, for example you cannot use the Xircom Netwave PC Card for a direct serial connection. Don't worry if you're not familiar with all of the hardware or connection types; these will all be discussed shortly. The following tables illustrate how the hardware and connection types are interrelated:

Hardware	Serial Connection
Built-in Modem	Serial modem
Serial port	Direct serial via MagicBus port
MagicBus Modem	Serial via external modem on MagicBus port
Xircom Netwave	(not available)

Hardware	TCP/IP Connection
Built-in Modem	PPP via built-in modem
Serial port	(not available)
MagicBus Modem	PPP via external modem on MagicBus port
Xircom Netwave	Wireless Ethernet via Xircom Netwave card

In the above table, the Built-in modem refers to the internal modem that is present in all Magic Cap communicators. The serial port refers to using a communicator's MagicBus port as a passive serial port. The next two options, MagicBus modem and Xircom Netwave, use custom drivers that are included with the Magic Internet Kit. These drivers are provided as source code so that you can learn from and modify them if you so desire. The MagicBus modem driver lets you use an external modem connected to the MagicBus port via the same APIs as the internal modem. For example, you can use this driver to provide native support for Metricom's Ricochet wireless modem. The Xircom Netwave driver allows you to use these PC Cards as a data link server for MIK's TCP/IP stack. These two drivers will be discussed in much greater detail in later chapters.

The third part of New Comms App to consider is the section for TCP Options. This section only contains one checkbox for the DNS resolver. As you might imagine, this option only applies to TCP/IP connections; if you don't use TCP/IP, this box will be grayed out. If you are using TCP/IP, DNS will allow you to specify symbolic host names as the destination for a TCP stream instead of needing IP numbers. For example, "www.genmagic.com" could be used as a valid destination name instead of it's IP address, which is currently 192.216.22.142.

The final section of New Comms App is used to select the template to use when creating the new package. The following section explains the features of each template.

Magic Internet Kit templates

Now that you know how you're going to communicate, it's handy to start with some work already done for you, and that's exactly what MIK's application templates are for. Say you want to brew up an application, and you want to let the user set up various options for the connection. You could then find a template with an interface that's close to what you want, and use this as the starting point for your new application.

This section will discuss the templates that are included with the Magic Internet Kit so you can decided which ones you want to use for your own projects.

Terminal (a.k.a. CujoTerm)

This is the classic TTY terminal package. When you use CujoTerm as your template, you get a simple terminal that you can connect to a remote host over whatever connections means you set up in the New Comms App dialog. This is a good template to use for testing out code or investigating protocols. For example, if you wanted to write a package that knew how to send email via SMTP, you could use CujoTerm to make sure that the commands you are sending to the server are actually doing the right thing. Additionally, since CujoTerm works "out of the box," you can use it as a good sample package to learn from.

CujoTerm comes with a user interface for setting up connections, and you may find these components useful in your own application. The UI for setting up the connection is totally independent of the terminal code, so you can tear up the other parts of CujoTerm and the setup scene will still work.

Another key component of CujoTerm is its architecture; this terminal, while basic in user-level features, has an advanced multi-threaded structure behind it that can even support multiple simultaneous TCP/IP connections. The two key classes that implement this functionality are the CommsActor and CommsManager. The code that executes on its own thread is part of the CommsActor, and the CommsManager is used to easily create and destroy CommsActors. Both of these classes will be discussed in much greater detail in the Multithreaded Communications chapter of this document.

EmptyWithFrills

The EmptyWithFrills package is similar to the Empty template discussed below, but it also contains some user interface and multithreading frills from CujoTerm. The UI in EmptyWithFrills is the same as CujoTerm's setup scene. This allows you to easily create or prototype applications without worrying about setting up the connection options. Additionally, EmptyWithFrills includes the CommsActor and CommsManager classes from CujoTerm, but the terminal-specific code is removed so that you can easily add in your own functionality.

Empty

As you might imagine, the Empty template is pretty sparse. This package is the same as Magic Developer's EmptyPackage template, except that this version has its MPW make file already set up to communicate using the means that were selected in the New Comms App dialog box.

Where to go from here

Now that you're all set up with a clone of your preferred template, it's time to make it do some real work. The next chapter, Connecting to the World, shows you how to connect to a remote host, use the connection, and then destroy it when you're done.