Creating Packages

Unfortunately no. This is an area that we intend to address someday. For now, this represents an excellent third party opportunity.

I want to build an API in my package that other developers can use. What if they want to subclass one of my package's classes?

Interpackage operation technology does not allow for another package to subclass one of your packages classes. You'll need to define your API in such a way that this is not necessary.

How do I create an authority for my package?

It's easiest to just describe the steps:

1. Run Magic Cap on the Mac.
2. Create a new name card and personalize.
3. Inspect the personalized name card.
4. Tap the addressCard field.
5. Tap the assignedName field of the address card.
6. Tap the authority field of the Telename object.
7. Dump the OctetString.

Voila! A new authority for your company. You should use the same authority code for all your packages, changing the identity for each package.

This process is also described in the Citation chapter of the Magic Cap Class and Reference Manual.

How can I use Magic Xchange to download packages that I've built? In particular, I see two files with my package name that end in "RC" and "RAM". What's the secret?

The format that Magic Xchange uses is not the same as any of the files produced by Magic Developer, so it cannot be used to download them directly. However, there is an MPW tool called XchangeConvert that changes a package you build into a Magic Xchange file. This tool is located in the "Cool Stuff:Random Code and Tools" folder on the CodeWarrior Magic CD. To use it, simply type:

XchangeConvert packageName

on your MPW worksheet. This creates a Magic Xchange file named packageName.PKG in the same directory as your package.

There is also a Magic Cap package that runs on the Magic Cap simulator, called DownloadPackage that performs the same function. Simply launch the Magic Cap simulator with your package and DownloadPackage. Go to the download scene, choose your package and tap the download button. This creates a file that can be downloaded to the device with Magic Xchange.

OK, I'm tired of using the simulator to test my package. How do I download my package onto a communicator?

There are several ways of getting a package onto a device. In order of preference, they are:

1) Specify a device build target. You can choose either a "universal" device target, or a specific device target from the Magic menu. This builds a package that is meant to be used on a device. If the "autoRun" option is checked in the Magic menu, the package will be downloaded automatically to a PC card. This option requires that you have a Telebug enabled device (i.e., it's got a tail sticking out of the case).

2) Convert the device build of your package into Magic Xchange format, then use Magic Xchange to download the package onto the device. Magic Xchange uses a different file format to represent downloadable packages. There is an MPW tool called XchangeConvert that changes a package you build into a Magic Xchange file. This tool is located in the "Cool Stuff:Random Code and Tools" folder on the CodeWarrior Magic CD. To use it, simply type:

XchangeConvert packageName

on your MPW worksheet. This creates a Magic Xchange file named packageName.PKG in the same directory as your package.

3) There is also a Magic Cap package that runs on the Magic Cap simulator, called DownloadPackage that performs the same function. Simply launch the Magic Cap simulator with your package and DownloadPackage. Go to the download scene, choose your package and tap the download button. This creates a file that can be downloaded to the device with Magic Xchange.

This third solution can get a little tricky if your package uses hardware related classes. (The serial server is a great example of this.) If you convert and download a Mac build, it probably won't work on the device. You can open a device build from the simulator; these are the generated packages that end with the "RAM" suffix. The same caveat is true in this case, but in reverse: the device build of your package might have code that won't run on the simulator. This isn't as big a problem since you're just going to convert the package, not actually use it. This would only be a problem if you have device specific code in a Load(), Install() or InstallInto() method.

After downloading a RAM card, the screen goes blank for a few seconds and appears to have powered off. It actually is in the processes of rebooting. You're probably flipping the power switch at this point in an effort to turn the communicator on, but you are in fact, powering it off. The communicator finishes booting then dutifully powers off, as you had requested. When you flip the power switch a second time, the communicator powers on directly to the scene that was showing before being powered off. If this describes your experience, then yes this is normal.

I've noticed that after I have downloaded my package to my communicator several times, I start to get a lot of extra clocks and paintings on the wall of my hallway. I feel like I'm in an art gallery. What's causing this to happen?

Magic Cap tries to provide the user with a "sense of place" in the hallway by spacing drawers, clocks and paintings along the length of the hallway. (The theory is that the user can remember that the door leading to the game room is next to a Picasso, but the entrance to the library is further down the hallway, between a Monet and a clock.) What happens is that when you download a fresh image of your package onto the RAM card in your communicator, some header information on the PC card changes, causing Magic Cap to think that this is a different card than what was inserted in your communicator before. Magic Cap senses this change of state while it is booting after the download reset the communicator. In this situation, Magic Cap goes through all the objects in main memory and removes references to objects that were on the PC card. The entrance to your package is one such object that gets removed. Even though the entrance was removed, Magic Cap remembers that there used to be an entrance there, and will put the entrance to the "new" package to the right of where the old entrance was. This process repeats every time you download your package. Magic Cap will eventually decide it's time to furnish the hallway a little, to help users remember where they are in the hallway, and put a clock, painting, or drawer in.

The only way to remove furnishings is to cold reset your communicator. You can do this in Telebug, by typing "rb;g" to reboot the communicator. Keep in mind that this causes any data you have in the communicator's main memory to be lost.

If you want, you can force the communicator to cold reboot after every download, so you never see all the extra paintings. To do this, open the MagicSendRAMCard file inside the MagicDeveloper:Scripts: folder. Search for the line that contains:

set LocalDownloadOptions "-auto "

Add -cold 0xFFF84 inside the quotes. The next time you download your package, the communicator will reboot after the download completes. And losing any data in main memory, of course.

How can I create an update package that patches an existing version of a software package?

We don't recommend that this be done for packages. Patching in Magic Cap is designed to be used for patching the system and packages that are in the onboard ROM. It does not work well for patching RAM-resident packages. One of the more serious problems is that the patches can become disconnected from the package. They will never be garbage collected, and thus become a permanent memory leak.

You should use the Magic Cap simulator to create a Name Card for yourself, exactly the way you want to include it in your package. You can't put an AT&T label on your card using the simulator, but you can put an Internet e-mail label on it. If you prefer to require that your customers use AT&T PersonaLink, you can leave the "addresses" ObjectList empty (that is, an ObjectList with no entries), and Magic Cap will automatically do a directory lookup the first time your customer sends you mail. However, I don't think that solution works well for AOL subscribers; the best solution for all customers is to use an Internet address, or to include both AT&T and AOL addresses. Forcing a directory lookup is preferable to actually putting an a-number on your card since it allows you to change your a-number without invalidating the address cards your customers have.

Once you have your card set up just the way you want it, dump out all the objects in the AddressCard (you don't need the NameCard itself). Use the inspector to point to the AddressCard (it's a field in the NameCard), then select the "Dump Inspector Target Deep" menu item.

If you absolutely must have the PersonaLink number on your card, you can use your real communicator to get it. On the communicator, file a copy of your name card into a new data package and then use MagicXchange to upload the package to your Macintosh. From there, use DownloadPackage (in the "Cool Stuff:Random Code and Tools:Code:DownloadPackage:" folder) to get the card into the simulator. At that point, you can do a "Dump Inspector Target Deep."

If you include these objects in your Objects.Def file, and put a reference to the AddressCard object in the author and publisher fields of your SoftwarePackage, you'll be all set. The HelloWorld sample shows how to do that.

This behavior can happen if the contentSize of your entrance is not accurate. It should be the same size as the size of your Image. (Actually, I've found that it sometimes helps to make it one unit larger.) Setting the relativeOrigin to <0.0, 0.0> is usually the right thing to do, but some adjustment of the vertical coordinate may be necessary.