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

Dash 3.0.2 - Instant search and offline...
Dash is an API Documentation Browser and Code Snippet Manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
FontExplorer X Pro 5.0 - Font management...
FontExplorer X Pro is optimized for professional use; it's the solution that gives you the power you need to manage all your fonts. Now you can more easily manage, activate and organize your... Read more
Typinator 6.6 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
Arq 4.12.1 - Online backup to Google Dri...
Arq is super-easy online backup for the Mac. Back up to your own Google Drive storage (15GB free storage), your own Amazon Glacier ($.01/GB per month storage) or S3, or any SFTP server. Arq backs up... Read more
Gutenprint 5.2.11-pre1 - Quality drivers...
Gutenprint is a suite of printer drivers that may be used with most common UNIX print spooling systems, including CUPS, lpr, LPRng, or others. Gutenprint currently supports over 2000 printer models.... Read more
Dropbox 3.6.8 - Cloud backup and synchro...
Dropbox is an application that creates a special Finder folder that automatically syncs online and between your computers. It allows you to both backup files and keep them up-to-date between systems... Read more
Evernote 6.0.15 - Create searchable note...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
MacUpdate Desktop 6.0.7 - Search and ins...
MacUpdate Desktop 6 brings seamless 1-click installs and version updates to your Mac. With a free MacUpdate account and MacUpdate Desktop 6, Mac users can now install almost any Mac app on macupdate.... Read more
Freeway Pro 7.0.4 - Drag-and-drop Web de...
Freeway Pro lets you design and build sophisticated responsive websites code free. With its user-oriented drag-and-drop interface, Freeway Pro helps you piece together the website of your dreams. Add... Read more
VueScan 9.5.18 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more

This Week at 148Apps:June 22-26, 2015
June's Summer Journey Continues With 148Apps How do you know what apps are worth your time and money? Just look to the review team at 148Apps. We sort through the chaos and find the apps you're looking for. The ones we love become Editor’s Choice,... | Read more »
LEGO® Minifigures Online (Games)
LEGO® Minifigures Online 1.0.1 Device: iOS iPhone Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: | Read more »
World of Tanks Blitz celebrates its firs...
Today marks the first anniversary of the launch of World of Tanks Blitz, the mobile version of the PC tank battler, World of Tanks. World of Tanks Blitz launched on iOS and Android on June 26th last year and to celebrate, Wargaming is giving all... | Read more »
Heroes and Castles 2 Has its Own Standal...
Heroes and Castles 2 is a third-person castle defense game from the same team behind Block Fortress and Bug Heroes. It's cool, it's fun, and now it has its very own free version. [Read more] | Read more »
Formula Cartoon All-Stars Lets You Race...
Ever want to pit your favorite characters from shows like Steven Universe, Adventure Time, and Regular Show against each other in a not quite death race? Well once upon a time you could, but Formula All Stars Touch N' Go doesn't exist anymore. Hope... | Read more »
Retype - Typography Photo Editor (Photo...
Retype - Typography Photo Editor 1.0 Device: iOS Universal Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Retype is built out of passion for great typography and it's all about adding text to photo with style... | Read more »
Hungry Shark Evolution Celebrates Shark...
Shark Week is almost here, as is Independence Day, so naturally Hungry Shark Evolution is going to get in on the action. Yes, even the fireworks. [Read more] | Read more »
The New Trivia Crack Will Feature a Musi...
It's official: iHeartMedia (you may know them from iHeartRadio) will be in charge of providing music-related questions for Trivia Crack's upcoming sequel. Also Trivia Crack is getting a sequel. [Read more] | Read more »
Toca Life: City (Education)
Toca Life: City 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: Welcome to Toca Life: City, a metropolis filled with everyday fun! Customize characters, explore exciting locations and... | Read more »
Ironkill's Big New Update is Big an...
The other popular robot fighting game on the App Store, Ironkill, has received a pretty substantial update today. We're talking new bots, new rewards, graphical tweaks; the works. [Read more] | Read more »

Price Scanner via MacPrices.net

MacBook Airs on sale for up to $75 off MSRP
Save up to $75 on the purchase of a new 2015 13″ or 11″ 1.6GHz MacBook Air at the following resellers. Shipping is free with each model: 11" 128GB MSRP $899 11" 256GB... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
Save up to $600 with Apple refurbished Mac Pr...
The Apple Store has Apple Certified Refurbished Mac Pros available 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
Mac Pros on sale for up to $260 off MSRP
B&H Photo has Mac Pros on sale for up to $260 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2799, $200 off MSRP - 3.5GHz 6-core Mac Pro: $3719.99... Read more
Save up to $400 on 2014 15-inch Retina MacBoo...
B&H Photo has previous-generation 2014 15″ Retina MacBook Pros on sale for up to $400 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro... Read more
15-inch Retina MacBook Pros on sale for up to...
B&H Photo has new 2015 15″ Retina MacBook Pros on sale for up to $125 off MSRP including free shipping plus NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1899.99 $100 off - 15″ 2.5GHz... Read more
College Student Deals: Additional $100 off Ma...
Take an additional $100 off all MacBooks and iMacs at Best Buy Online with their College Students Deals Savings, valid through July 11, 2015. Anyone with a valid .EDU email address can take advantage... Read more
Apple refurbished Time Capsules available for...
The Apple Store has certified refurbished Time Capsules available for $100 off MSRP. Apple’s one-year warranty is included with each Time Capsule, and shipping is free: - 2TB Time Capsule: $199, $100... Read more
Newsweek Launches iPhone App
The venerable weekly news magazine Newsweek, owned by IBT Media, has announced the launch of its first iPhone app. The new app is available through Apple’s App Store and will allow consumers to read... Read more
New Initiative Covering 80 Million Homes Will...
Today, Internet service providers, equipment suppliers and retail equipment manufacturers joined the Consumer Electronics Association (CEA) and the National Cable & Telecommunications Association... Read more

Jobs Board

Architect / Senior Software Engineer, *Apple...
**Job Summary** Apple Pay is already changing our pay-habit in a deeper and fundamental level. We are looking for a software engineer with a passion for large scale inte Read more
Project Manager, *Apple* Retail New Store O...
**Job Summary** An Apple Retail New Store Openings & Remodels Project Manager is responsible for successfully managing the openings, remodels, and small works of 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
Program Manger, WW *Apple* Direct Fulfillme...
**Job Summary** We are seeking a business analyst to work within our Worldwide Apple Direct Fulfillment Operations team. This role will work closely with related program Read more
Hardware Design Validation Engineer - *Apple...
**Job Summary** The Apple Watch team is looking for a Hardware Design Validation Engineer. This person will be part of the Apple Watch hardware team with Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.