TweetFollow Us on Twitter

Updating Navigation

Volume Number: 16 (2000)
Issue Number: 6
Column Tag: Navigation Services

Updating Navigation Services Sample Code

by Thurman Gillespy III, M.D.

On the Road to Carbon Compliance

Introduction

A recent project gave me an excuse to delve seriously into the Navigation Services (NavServices) SDK for the first time. The SDK includes three example projects (Sampler, StExample, and SimpleText) that illustrate the NavServices API. During routine debugging of my code, however, I discovered multiple "write-to-nil" bugs that had originated in the example projects. This article describes the steps you need to fix those errors and to update the projects to work with CodeWarrior Pro 5 and Universal Headers 3.3. For a pointer to the NavServices SDK, see the References section at the end of this article.

Sampler

Sampler is a small C program that demonstrates to use the NavServices API in a document-based application. It uses NavServices functions to elicit files from the user, save files, and prompt the user to save or discard changes to a document. It also shows how to use NavServices functions to let the user choose a folder, volume, or file-system object. Sampler is a very good place to start learning how to use NavServices. So let's make Sampler usable!

Update Access Paths

In the Access Paths panel of the Sampler.PPC Settings dialog box, remove the 'Shared Libraries' and 'Cincludes' paths from the User Paths list. They are not needed. Then change the System Paths to:

{Compiler}:MacOS Support:
{Compiler}:MSL:

Save the changes to this panel by clicking the Save button.

Implied Int No Longer Allowed

In Templates.c, there is an implied return value of type int to the main function that is no longer legal in C++. Change:

main()

to:

int main(void)

Runtime Library Changes

Change the MWCRuntime.lib library (which is no longer present) to MSL RuntimePPC.Lib.

Add a Header File

Universal Headers 3.3 include the new header file ControlDefinitions.h, which contains some constants previously defined in the file Controls.h. So add the following lines to the file Common.h:

#ifndef __CONTROLDEFINITIONS__
#include <ControlDefinitions.h>
#endif

NavCBRec Field Change

Somewhere between "then and now", the fields in the NavCBRec structure changed. In file.c and menu.c, there are a total of 10 NavCBRecPtr variables to update. Change:

callBackParms->eventData.event

to:

callBackParms->eventData.eventDataParms.event

Duplicate cfrg Resource

A 'cfrg' resource is defined in TemplatePPC.r. This definition is no longer needed because the CodeWarrior IDE now generates the correct resource. I simply commented out the definition in TemplatePPC.r.

/*
resource 'cfrg' (0) {
	{
	kPowerPC,
	kFullLib,
	kNoVersionNum,kNoVersionNum,
	0,0,
	kIsApp,kOnDiskFlat,kZeroOffset,kWholeFork,
	"Template"
	}
};
*/

AEGetDescData Write-to-nil Errors

AEGetDescData (defined in Common.c) is a utility function that extracts a DescType of type typeCode from the AEDesc. In Sampler, it is used to extract an FSSpec from the AEDesc. Listing 1 shows the original function.

Listing 1: Getting data from an AEDesc structure (before)

AEGetDescData

OSErr AEGetDescData(const AEDesc *desc, DescType *typeCode,
				void *dataBuffer, ByteCount maximumSize,
				ByteCount *actualSize)
{
	*typeCode = desc->descriptorType;
	Handle h = (Handle)desc->dataHandle;
	ByteCount dataSize = GetHandleSize(h);
	if (dataSize > maximumSize)
		*actualSize = maximumSize;
	else
		*actualSize = dataSize;
	BlockMoveData(*h, dataBuffer, *actualSize);
	return noErr;
}

The function is acceptable, except for a complete lack of any error checking (a common practice in developer example code). However, AEGetDescData is called 10 times with two NULL pointers (menus.c).

if ((theErr = AEGetDescData ( &resultDesc, NULL,
		&finalFSSpec, sizeof ( FSSpec ), NULL )) == noErr)...

This code fragment results in two writes to nil (typeCode and actualSize) and one read from nil (BlockMoveData). Bad form, indeed. For a fix, I simply check for the NULL parameters; I also added a few other error checks for good measure, as shown in Listing 2.

Listing 1: Getting data from an AEDesc structure (after)

AEGetDescData
OSErr AEGetDescData(const AEDesc *desc, DescType *typeCode,
				void *dataBuffer, ByteCount maximumSize,
				ByteCount *actualSize)
{
	Handle		h = NULL;
	ByteCount	dataSize = 0,
						bytesToCopy = 0;
	OSErr			err = -1;
	
	// check for invalid NULL handles or pointers
	if (desc == NULL || desc->dataHandle == NULL ||
			dataBuffer == NULL)
		return nilHandleErr;
	
	// get the size of the object, check for errors
	h = (Handle)desc->dataHandle;
	dataSize = GetHandleSize(h);
	err = MemError();
	if (err != noErr)
		return err;
	
	// determine how many bytes to copy
	if (dataSize > maximumSize)
		bytesToCopy = maximumSize;
	else
		bytesToCopy = dataSize;

	// copy object from the handle to the buffer
	BlockMoveData(*h, dataBuffer, bytesToCopy);

	// return type code and number of bytes copied,
	// if pointers are not NULL
	if (typeCode != NULL)
		*typeCode = desc->descriptorType;
	if (actualSize != NULL)
		*actualSize = bytesToCopy;
	
	return noErr;
}

AEGetNthDesc Write-to-nil Errors

In Sampler, AEGetNthDesc writes to nil 11 times (files.c, menus.c) because the fourth parameter, a pointer to an AEKeyword structure, is set to NULL.

AEGetNthDesc(&(theReply.selection), index, typeFSS, NULL,
						&resultDesc)

To correct this error, simply add an appropriate AEKeyword parameter.

AEKeyword  aekw; // not used
AEGetNthDesc(&(theReply.selection), index, typeFSS, &aekw,
						&resultDesc)

Sampler CFM68k

For the Sampler.68kCFM project, make the same changes to the access paths, then update the obsolete libraries to the correct versions.

MathLibCFM68k(4i/8d).Lib			==>		MathLibCFM68k (4i_8d).Lib
MSL C.CFM68kFar(4i/8d).Lib		==>		MSL C.CFM68kFa(4i_8d).Lib
MWCFM68kRuntime.Lib					==>		MSL MWCFM68kRuntime.Lib

StExample

The StExample project is a C++ example of using NavServices that is less complete than Sampler. The StExample project is also easier to update.

  • Update the User Paths as you did for Sampler.
  • Update the Navigation library to NavigationLib.
  • In HelloWorld.cp, the last parameter to StNavGetFile must be changed from long to (void *). Change:
StNavGetFile gf1( &err, &specs, &numspecs, &rdopen,
							&navreply, false, true, &rdevt, nil,
							nil, tlh, 0xaabbccdd);

to

UInt32	usrDat = 0xaabbccdd;
StNavGetFile  gf1( &err, &specs, &numspecs, &rdopen,
								&navreply, false, true, &rdevt, nil,
								nil, tlh, (void *)&usrDat );
  • There are two write-to-nil errors, both in StNavServices.cp. Change the NULL fourth parameter in the call to AEGetNthDesc to a valid AEKeyword pointer.

SimpleText

The SimpleText project uses the obsolete QuickDrawGX, and a dated MacIncludes.h header. I decided it wasn't worth the effort to update the project.

Checking the Result

To see the write-to-nil errors, drop into Macsbug and invoke the EBBE (Even Better Bus Error) dcmd.

EBBE on
EBBE is ON (using the value $68F168F1 with a task rate of
	#17 milliseconds)

Then run the unaltered Sampler application as delivered in the SDK. You should see one or more write-to-nil errors in every call to NavServices. Both QC and Spotlight (Onyx Technology) will also catch the errors.

The EBBE dcmd has detected that location $0000
	has been overwritten

After making the corrections described here, run this test again on the compiled example applications and on any of your code based on the SDK sample code. The write-to-nil errors should be eliminated.

References

Navigation Services SDK
<http://developer.apple.com/sdk/index.html>
Onyx Technology
<http://www.onyx-tech.com/>


Thurman Gillespy III is a radiologist at the Veterans Administration Puget Sound Health Care System in Seattle, Washington. He can be reached at tg3@u.washington.edu

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Cyberduck 4.7 - FTP and SFTP browser. (F...
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more
Labels & Addresses 1.7 - Powerful la...
Labels & Addresses is a home and office tool for printing all sorts of labels, envelopes, inventory labels, and price tags. Merge-printing capability makes the program a great tool for holiday... Read more
teleport 1.2.1 - Use one mouse/keyboard...
teleport is a simple utility to let you use one single mouse and keyboard to control several of your Macs. Simply reach the edge of your screen, and your mouse teleports to your other Mac! The... Read more
Apple iMovie 10.0.8 - Edit personal vide...
With an all-new design, Apple iMovie lets you enjoy your videos like never before. Browse your clips more easily, instantly share your favorite moments, and create beautiful HD movies and Hollywood-... Read more
Box Sync 4.0.6233 - Online synchronizati...
Box Sync gives you a hard-drive in the Cloud for online storage. Note: You must first sign up to use Box. What if the files you need are on your laptop -- but you're on the road with your iPhone? No... Read more
Fantastical 2.0.3 - Create calendar even...
Fantastical 2 is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more
The Hit List 1.1.14 - Advanced reminder...
The Hit List manages the daily chaos of your modern life. It's easy to learn - it's as easy as making lists. And it's powerful enough to let you plan, then forget, then act when the time is right.... Read more
Path Finder 7.1.4 - Powerful, award-winn...
Become a master of file management with Path Finder. Take full control over your file system. Save your time: compare and synchronize folders, view hidden files, use Dual Pane and full keyboard... Read more
PhotoStyler 6.8.2 - Add a sense of reali...
PhotoStyler is the easiest way to style your digital photos with your Mac. This simple, fast and accurate native solution combines the powers of Apple's core technologies with the flexibility and... Read more
Astropad 1.1 - Turn your iPad into a gra...
Note: Requires iPad companion app. ($24.99) Astropad transforms your iPad into a professional graphics tablet for your Mac. Use your iPad to draw directly into Photoshop and any other Mac creative... Read more

SoundHound + LiveLyrics is Making its De...
SoundHound Inc. has announced that SoundHound + LiveLyrics, will be one of the first third-party apps to hit the Apple Watch. With  SoundHound you'll be able to tap on your watch and have the app recognize the music you are listening to, then have... | Read more »
Adobe Joins the Apple Watch Lineup With...
A whole tidal wave of apps are headed for the Apple Watch, and Adobe has joined in with 3 new ways to enhance your creativity and collaborate with others. The watch apps pair with iPad/iPhone apps to give you total control over your Adobe projects... | Read more »
Z Steel Soldiers, Sequel to Kavcom'...
Kavcom has released Z Steel Soldiers, which continues the story of the comedic RTS originally created by the Bitmap Brothers. [Read more] | Read more »
Seene Lets You Create 3D Images With You...
Seene, by Obvious Engineering, is a 3D capture app that's meant to allow you to create visually stunning 3D images with a tap of your finger, and then share them as a 3D photo, video or gif. [Read more] | Read more »
Lost Within - Tips, Tricks, and Strategi...
Have you just downloaded Lost Within and are you in need of a guiding hand? While it’s not the toughest of games out there you might still want some helpful tips to get you started. [Read more] | Read more »
Entertain Your Pet With Your Watch With...
The Petcube Camera is a device that lets you use live video to check in on your pet, talk to them, and play with them using a laser pointer - all while you're away. And the Petcube app is coming to the Apple Watch, so you'll be able to hang out with... | Read more »
Now You Can Manage Your Line2 Calls With...
You'll be able to get your Line2 cloud phone service on the Apple Watch very soon. The watch app can send and receive messages using hands-free voice dictation, or by selecting from a list of provided responses. [Read more] | Read more »
R.B.I. Baseball 15 (Games)
R.B.I. Baseball 15 1.01 Device: iOS Universal Category: Games Price: $4.99, Version: 1.01 (iTunes) Description: The legendary Major League Baseball franchise returns to the diamond. Make History. ** ALL iPOD Touch, the iPad 2 and the... | Read more »
Here's How You Can Tell if an App W...
The Apple Watch is pretty much here, and that means a whole lot of compatible apps and games are going to be updated or released onto the App Store. That's okay though, beacause Apple has quietly updated their app description pages to make things... | Read more »
Forgotten Memories : Alternate Realities...
Forgotten Memories : Alternate Realities 1.0.1 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: + REDUCED PRICE ONLY THE LAUNCHING WEEK + "The most exciting horror game of 2015." - AppSpy... | Read more »

Price Scanner via MacPrices.net

Heal to Launch First One-Touch House Call Doc...
Santa Monica, California based Heal, a pioneer in on-demand personal health care services — will offer the first one-touch, on-demand house call doctor app for the Apple Watch. Heal’s Watch app,... Read more
Mac Notebooks: Avoiding MagSafe Power Adapter...
Apple Support says proper usage, care, and maintenance of Your Mac notebook’s MagSafe power adapter can substantially increase the the adapter’s service life. Of course, MagSafe itself is an Apple... Read more
12″ Retina MacBook In Shootout With Air And P...
BareFeats’ rob-ART morgan has posted another comparison of the 12″ MacBook with other Mac laptops, noting that the general goodness of all Mac laptops can make which one to purchase a tough decision... Read more
FileMaker Go for iPad and iPhone: Over 1.5 Mi...
FileMaker has announced that its FileMaker Go for iPad and iPhone app has surpassed 1.5 million downloads from the iTunes App Store. The milestone confirms the continued popularity of the FileMaker... Read more
Sale! 13-inch 2.7GHz Retina MacBook Pro for $...
 Best Buy has the new 2015 13″ 2.7GHz/128GB Retina MacBook Pro on sale for $1099 – $200 off MSRP. Choose free shipping or free local store pickup (if available). Price for online orders only, in-... Read more
Minimalist MacBook Confirms Death of Steve Jo...
ReadWrite’s Adriana Lee has posted a eulogy for the “Digital Hub” concept Steve Jobs first proposed back in 2001, declaring the new 12-inch MacBook with its single, over-subscribed USB-C port to be... Read more
13-inch 2.7GHz Retina MacBook Pro for $1234 w...
Adorama has the 13″ 2.7GHz/128GB Retina MacBook Pro in stock for $1234.99 ($65 off MSRP) including free shipping plus a free LG external DVD/CD optical drive. Adorama charges sales tax in NY & NJ... Read more
13-inch 2.5GHz MacBook Pro available for $999...
 Adorama has the 13-inch 2.5GHz MacBook Pro on sale for $999 including free shipping plus NY & NJ sales tax only. Their price is $100 off MSRP. Read more
Save up to $600 with Apple refurbished Mac Pr...
The Apple Store is offering Apple Certified Refurbished Mac Pros for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The... Read more
Updated MacBook Price Trackers
We’ve updated our MacBook Price Trackers with the latest information on prices, bundles, and availability on 12″ MacBooks, MacBook Airs, and MacBook Pros from Apple’s authorized internet/catalog... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Program Manager, *Apple* Community Support...
**Job Summary** Apple Support Communities ( discussions. apple .com) helps customers get the most from their Apple products and services by providing access to Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
Event Director, *Apple* Retail Marketing -...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global engagement strategy and team. Delivering an overarching brand Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.