utils.c

CD_高级PALM编程

/********************************************************************
* FILE:				Utils.c
*
* DESCRIPTION:	A code module with a collection of generic utility functions.
*
* VERSION:		1.0
**********************************************************************/

//#include <PalmOS.h>
//#include	<PalmCompatibility.h>

#include "Utils.h"
#include "UtilsRsc.h"


/***********************************************************************
 * FUNCTION:    	OpenSharedLibrary
 *
 * DESCRIPTION: 	Open a shared library.
 *
 * RETURNED:    	Error code or zero if the library is succssfully opened.
 *					A reference # to the shared library if successful.
 ***********************************************************************/
 
Err OpenSharedLibrary ( 		// (out) error code or zero
	CharPtr	shLibNameP,		// (in) Library name
	DWord	shLibCreator,	// (in) Library creator ID
	UIntPtr	ioshLibRefP		// (out) Library reference number
)
{
	Err		error = 0;
	
	error = SysLibFind ( shLibNameP, ioshLibRefP );
	if ( error != 0 )
		error = SysLibLoad ( LibType, shLibCreator, ioshLibRefP );
	if ( error != 0 )
		FrmCustomAlert ( SharedLibOpenAlert, shLibNameP, " ", " " );
	return ( error );
}


/***********************************************************************
 * FUNCTION:    	CloseSharedLibrary
 *
 * DESCRIPTION: 	Close a shared library.
 *
 * RETURNED:    	An error code or zero if the library is successfully closed.
 ***********************************************************************/
 
Err CloseSharedLibrary		// (out) error code or zero
(
	UInt		ioshLibRef	// (in) The library reference number
)
{
	Err		error = 0;
	error = SysLibRemove ( ioshLibRef ); 
	if ( error )
		FrmAlert ( SharedLibCloseAlert );
	return ( error );
}


/***********************************************************************
 * FUNCTION:    	RomVersionCompatible
 *
 * DESCRIPTION: 	This routine checks for a minimum ROM version.
 *
 * RETURNED:    	error code or zero if ROM is compatible
 ***********************************************************************/
 
Err RomVersionCompatible		// (out) error code or zero
( 
	UInt32		requiredVersion, 	// (in) Minimum ROM version required
	UInt16		launchFlags			// (in) App launch flags to check for UI available
)
{
	UInt32 	romVersion;
	Err			error = 0;
	Char 		romVerStr1 [ 4 ];
	Char 		romVerStr2 [ 4 ];
	
//	Get the device's ROM version and check it.
	
	FtrGet ( sysFtrCreator, sysFtrNumROMVersion, &romVersion );
	if ( romVersion < requiredVersion )
	{

//	Invalid ROM version, tell the user if the UI is available.
		
		error = sysErrRomIncompatible;
		if (( launchFlags & ( sysAppLaunchFlagNewGlobals | sysAppLaunchFlagUIApp )) ==
			( sysAppLaunchFlagNewGlobals | sysAppLaunchFlagUIApp ))
		{
		
// Get the ROM version number strings for the alert and display the error alert.

			GetROMString ( requiredVersion, romVerStr1 );
			GetROMString ( romVersion, romVerStr2 );	
			FrmCustomAlert ( RomIncompatibleAlert, romVerStr1, romVerStr2, " " );
		
//	Palm OS 1.0 will continuously relaunch this app unless we switch to another safe one.
			
			if ( romVersion < sysMakeROMVersion ( 2, 0, 0, sysROMStageRelease, 0 ))
			{
				AppLaunchWithCommand ( sysFileCDefaultApp, sysAppLaunchCmdNormalLaunch, NULL );
			}
		}
	}
	return error;
}


/***********************************************************************
 * FUNCTION:    	GetROMString
 *
 * DESCRIPTION: 	Extract the ROM version components from a version #.
 *
 * RETURNED:    	Stores the components into a char arrary in the calling routine.
 ***********************************************************************/
 
 void	GetROMString
 ( 
 	UInt32		ROMVersion,		// (in) the ROM version #
 	char * 	outROMStr		// (out) the string versin #
 )
 {
 	outROMStr [ 0 ] = ( char ) ( sysGetROMVerMajor ( ROMVersion ) + 48 );
	outROMStr [ 1 ] = '.';
	outROMStr [ 2 ] =  ( char ) ( sysGetROMVerMinor ( ROMVersion ) + 48 );
	outROMStr [ 3 ] = NULL;
}

 
/***********************************************************************
 * FUNCTION:    	GetObjectPtr
 *
 * DESCRIPTION: 	Return a pointer to an object in the current form.
 *
 * RETURNED:    	void *
 ***********************************************************************/
 
void * GetObjectPtr			// (out) pointer to the object
(
	UInt16 	objectID		// ID of the object you want the pointer fo
)
{
	FormPtr frmP;

	frmP = FrmGetActiveForm();
	return ( FrmGetObjectPtr ( frmP, FrmGetObjectIndex ( frmP, objectID )));
}


/***********************************************************************
 * FUNCTION:    	QuadToString
 *
 * DESCRIPTION: 	This routine converts a four-byte quad to a string.
 *
 * RETURNED:    	nothing
 ***********************************************************************/
void QuadToString
(
	UInt32	quad,		// (in) quad to convert
	Char *	out		// (in/out) string to contain results
)
{
	struct converter { char a, b, c, d; } *c;
	
	c = (struct converter *)&quad;
	
	out[0] = c->a;
	out[1] = c->b;
	out[2] = c->c;
	out[3] = c->d;
	out[4] = '\000';

	return;
}

/***********************************************************************
 * FUNCTION:    	SetTextFieldWithString
 *
 * DESCRIPTION: 	Sets the text field's value to the given string.
 *
 * RETURNED:    	An error or 0 if no error occured.
 ***********************************************************************/
//
Err SetTextFieldWithString	//	(out)	result code
(	
	UInt16		textFldID,		//	(in)	the ID of the text field to set
	char *		string,			//	(in)	C-string to set
	Boolean	drawIt		//	(in)	true to draw the text right away
)		
{
	Err				anErr = noErr;
	MemHandle	textH;

// Create the field text handle
	
	textH = MemHandleNew ( StrLen ( string) + 1 );
	if ( textH != NULL )
	{
	
// Copy the source string to the handle

		StrCopy ( MemHandleLock ( textH ), string );
		MemHandleUnlock ( textH );
		
// Draw the field on the form

		SetTextFieldWithHandle ( textFldID, textH, drawIt );
	}
	else
	{
		anErr = memErrNotEnoughSpace;
	}
	return anErr;
}


/***********************************************************************
 * FUNCTION:    	SetTextFieldWithHandle
 *
 * DESCRIPTION: 	Sets the text field's value to a handle's value.
 *
 * RETURNED:    	An error or 0 if no error occured.
 ***********************************************************************/
void SetTextFieldWithHandle
(
	UInt16			textFldID,		// (in) the ID of the text field to set
	MemHandle	textHdl,		// (in) handle containing a C-string
	Boolean		drawIt)		// (in) true to draw the text right away
{
	FieldPtr		textFldP = GetObjectPtr ( textFldID );
	MemHandle	oldTextHdl;
	
// Get the field's current text handle
	
	oldTextHdl = FldGetTextHandle(textFldP);
	
// Set the field with the new text

	FldSetTextHandle ( textFldP, textHdl );
	if ( drawIt )
	{
		FldDrawField ( textFldP );
	}
	
// Free the old text handle

	if ( oldTextHdl != NULL )
	{
		MemHandleFree ( oldTextHdl );
	}
} 


/***********************************************************************
 * FUNCTION:    	OpenDatabase
 *
 * DESCRIPTION: 	Open a database. If unsuccessful, display a dialog.
 *
 * RETURNED:    	zero or an error code, plus the db reference.
 ***********************************************************************/
Err OpenDatabase	// (out) error code or zero
(
	UInt32				dbType,		// (in) database type
	UInt32				dbCreator,	// (in) database creator
	UInt16				dbMode,		// (in) open mode
	DmOpenRef*		dbRef			// (out) database reference
)
{

// Open the database

	Err				result = 0;
	DmOpenRef 	dbP = DmOpenDatabaseByTypeCreator ( dbType, dbCreator, dbMode );	
	if ( ! dbP )
	{
	
// Problem, display the dialog

		Char	creatorStr [ 5 ], typeStr [ 5 ];
		QuadToString ( dbType, typeStr );
		QuadToString ( dbCreator, creatorStr );
		FrmCustomAlert ( DBOpenAlert, typeStr, creatorStr, " " );
		result = dmErrDatabaseOpen;
	}
	
// No problem, return the DB reference for future use

	else
	{
		* dbRef = dbP;
	}	
	return ( result );
}


/***********************************************************************
 * FUNCTION:    	GetRecordData
 *
 * DESCRIPTION: 	Retrieve the contents of a record and put it in buffer.
 *
 * RETURNED:    	The record contents are copied to a destination location.
 ***********************************************************************/
void GetRecordData
 (
	DmOpenRef	dbRef,			// (in) database to get the record from
	UInt16			itemNum,		// (in) record # to fetch
	Char *			dataStr		// (out) place to put the record data
 )
 {	
	MemHandle 	recH;
	MemPtr		dataP;

// Look for the record
	
	recH = DmQueryRecord ( dbRef, itemNum );
	if ( recH )
	{
	
// Found it. Lock itt.

		dataP = MemHandleLock ( recH );
		if ( dataP )
		{
		
// Locked. Move the data to the destination buffer.

			Int32 recSize = ( Int32 ) MemPtrSize ( dataP );
			MemMove ( dataStr, dataP, recSize );
		}
		MemHandleUnlock ( recH );
	}
}

/***********************************************************************
 * FUNCTION:    	CheckAppInfo
 *
 * DESCRIPTION: 	Get a pointer to the AppInfo block so it can be examined
 *					in the debugger.
 *
 * RETURNED:    	An error code if there is an error.
 **********************************************************************/

Err  CheckAppInfo
(
	DmOpenRef	dbRef		// (in) database to check the appInfo for
)
{
	UInt16			cardNo;
	LocalID		dbID;
	LocalID		appInfoID;
	AppInfoPtr	appInfoP;

// Open the database info
	
	if ( DmOpenDatabaseInfo ( dbRef, &dbID, NULL, NULL, &cardNo, NULL ))
		return dmErrInvalidParam;
		
// Get the appinfo ID

	if ( DmDatabaseInfo ( cardNo, dbID, NULL, NULL, NULL, NULL, NULL, NULL, 
		 NULL, &appInfoID, NULL, NULL, NULL))
		return dmErrInvalidParam;

// If there is one, lock the pointer so you can look at it.

	if ( appInfoID )
	{	
		appInfoP = MemLocalIDToLockedPtr ( appInfoID, cardNo );
		if ( appInfoP )
			MemPtrUnlock ( appInfoP );
	}
	return ( 0 );
}


/***********************************************************************
 * FUNCTION:    	CheckDatabaseMode
 *
 * DESCRIPTION: 	Check to see if an database is in a certain mode.
 *
 * RETURNED:    	True if it is, false otherwise.
 ***********************************************************************/
 
Boolean  CheckDatabaseMode	// (out) database is set to input mode
(
	DmOpenRef	dbRef,				// (in) the database to get the mode of
	UInt16			modeToCheck	// (in) the mode to check
)
{
	Boolean 	result = false;
	Err			error;
	UInt16 	mode;

	if ( dbRef )
	{
	
// Get the database info

		error = DmOpenDatabaseInfo ( dbRef, NULL, NULL, &mode, NULL, NULL );
		if ( ! error ) 
		{
		
// Tell the caller the truth
		
			if ( mode == modeToCheck )
				result = true;
		}
	}	
	return ( result );
}

/***********************************************************************
 * FUNCTION:    	DebugMessage
 *
 * DESCRIPTION: 	Displays a debugging alert.
 *
 * RETURNED:    	nothing
 ***********************************************************************/
void DebugMessage
(
		Char *m	// (in) Message for debugging...
)
{
		FrmCustomAlert ( DebugAlert, m, "", " " );
	
}