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

Apple Security Update 2016-003 Supplemen...
Apple Security Update is recommended for all users and improves the security of OS X. For detailed information about the security content of this update, please visit: http://support.apple.com/kb/... Read more
Apple macOS Sierra 10.12.3 - The latest...
With Apple macOS Sierra, Siri makes its debut on Mac, with new features designed just for the desktop. Your Mac works with iCloud and your Apple devices in smart new ways, and intelligent... Read more
BetterTouchTool 1.992 - Customize Multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
Viber 6.5.5 - Send messages and make cal...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device, so... Read more
Opera 42.0.2393.137 - High-performance W...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more
iClock Pro 3.4.7 - Customize your menuba...
iClock Pro is a menu bar replacement clock for Apple's default clock. iClock Pro is an update, total rewrite and improvement to the popular iClock. Have the day, date and time in different fonts and... Read more
PhotoDesk 4.1.5 - Instagram client for p...
PhotoDesk lets you view, like, comment, and download Instagram pictures/videos. (NO Uploads! / Image Posting! Instagram forbids that! AND you need an existing Instagram account). But you can do so... Read more
Capo 3.5.1 - Slow down and learn to play...
Capo lets you slow down your favorite songs so you can hear the notes and learn how they are played. With Capo, you can quickly tab out your songs atop a highly-detailed OpenCL-powered spectrogram... Read more
HandBrake 1.0.2 - Versatile video encode...
HandBrake is a tool for converting video from nearly any format to a selection of modern, widely supported codecs. Features Supported Sources VIDEO_TS folder, DVD image or real DVD (unencrypted... Read more
Sound Studio 4.8.6 - Robust audio record...
Sound Studio lets you easily record and professionally edit audio on your Mac. Easily rip vinyls and digitize cassette tapes, or record lectures and voice memos. Prepare for live shows with live... Read more

Collect pets and sling arrows in Arcane...
Mobile gaming is a crowded market, but regular updates are a good way to keep us attention-short players keen. The brand new content in Arcane Online is a prime example. Published by Japanese developer Gala, Arcane Online is a fantasy MMO that... | Read more »
Super Mario Run dashes onto Android in M...
Super Mario Run was one of the biggest mobile launches in 2016 before it was met with a lukewarm response by many. While the game itself plays a treat, it's pretty hard to swallow the steep price for the full game. With that said, Android users... | Read more »
WarFriends Beginner's Guide: How to...
Chillingo's new game, WarFriends, is finally available world wide, and so far it's a refreshing change from common mobile game trends. The game's a mix of tower defense, third person shooter, and collectible card game. There's a lot to unpack here... | Read more »
Super Gridland (Entertainment)
Super Gridland 1.0 Device: iOS Universal Category: Entertainment Price: $1.99, Version: 1.0 (iTunes) Description: Match. Build. Survive. "exquisitely tuned" - Rock Paper Shotgun No in-app purches, and no ads! | Read more »
Red's Kingdom (Games)
Red's Kingdom 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Mad King Mac has kidnapped your father and stolen your golden nut! Solve puzzles and battle goons as you explore and battle your... | Read more »
Turbo League Guide: How to tame the cont...
| Read more »
Fire Emblem: Heroes coming to Google Pla...
Nintendo gave us our first look at Fire Emblem: Heroes, the upcoming mobile Fire Emblem game the company hinted at last year. Revealed at the Fire Emblem Direct event held today, the game will condense the series' tactical RPG combat into bite-... | Read more »
ReSlice (Music)
ReSlice 1.0 Device: iOS Universal Category: Music Price: $9.99, Version: 1.0 (iTunes) Description: Audio Slice Machine Slice your audio samples with ReSlice and create flexible musical atoms which can be triggered by MIDI notes or... | Read more »
Stickman Surfer rides in with the tide t...
Stickson is back and this time he's taken up yet another extreme sport - surfing. Stickman Surfer is out this Thursday on both iOS and Android, so if you've been following the other Stickman adventures, you might be interested in picking this one... | Read more »
Z-Exemplar (Games)
Z-Exemplar 1.4 Device: iOS Universal Category: Games Price: $3.99, Version: 1.4 (iTunes) Description: | Read more »

Price Scanner via MacPrices.net

Roundup of 15-inch Touch Bar MacBook Pro sale...
B&H Photo has the new 2016 15″ Apple Touch Bar MacBook Pros in stock today and on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.7GHz Touch Bar... Read more
Apple refurbished iPad Pros available for up...
Apple has Certified Refurbished 9″ and 12″ Apple iPad Pros available for up to $160 off the cost of new iPads. An Apple one-year warranty is included with each model, and shipping is free: - 32GB 9″... Read more
16GB iPad Air 2, Apple refurbished, available...
Apple has Certified Refurbished 16GB iPad Air 2s available for $319 including free shipping. A standard Apple one-year is included. Their price is $60 off original MSRP for this model. Read more
Apple iMacs on sale for up to $120 off MSRP
B&H Photo has 21″ and 27″ Apple iMacs on sale for up to $120 off MSRP, each including free shipping plus NY sales tax only: - 27″ 3.3GHz iMac 5K: $2199 $100 off MSRP - 27″ 3.2GHz/1TB Fusion iMac... Read more
Apple refurbished Apple TVs available for up...
Apple has Certified Refurbished 32GB and 64GB Apple TVs available for up to $30 off the cost of new models. Apple’s standard one-year warranty is included with each model, and shipping is free: -... Read more
Save up to $350 with Apple Certified Refurbis...
Apple has Certified Refurbished 2015 21″ & 27″ iMacs available for up to $350 off MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: - 21″ 3.... Read more
2015 12-inch Retina MacBooks, Apple refurbish...
Apple has Certified Refurbished 2015 12″ Retina MacBooks available for up to $410 off original MSRP. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The... Read more
Apple offering Certified Refurbished Series 1...
Apple is now offering Certified Refurbished Series 1 and Series 2 Apple Watches for 14-16% off MSRP, starting at $229. An Apple one-year warranty is included with each watch. Shipping is free: Series... Read more
12-inch 1.2GHz Space Gray Retina MacBook on s...
Amazon has the 2016 12″ 1.2GHz/512GB Space Gray Retina MacBook (Apple model #MLH82LL/A) on sale for $1299.99 including free shipping. Their price is $300 off MSRP. Read more
Twelve South Releases RelaxedLeather Cases fo...
Inspired by the laid-back luxury of burnished leather boots and crafted in rich tones of taupe, herb and marsala, RelaxedLeather cases deliver smart, easy protection for the iPhone 7. Each genuine... Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Site Security Manager - Apple (Unite...
# Apple Site Security Manager Job Number: 54692472 Culver City, California, United States Posted: Jan. 19, 2017 Weekly Hours: 40.00 **Job Summary** The Apple Read more
*Apple* macOS Systems Integration Administra...
…most exceptional support available in the industry. SCI is seeking an Junior Apple macOS systems integration administrator that will be responsible for providing Read more
*Apple* Retail - Multiple Positions- Deer Pa...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.