Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

29    Host Control

System Management

Exploring Palm OS®

This chapter describes the host control API, which you can use to call Emulator-defined functions while your application is running under the Palm OS® Emulator. For example, you can make function calls to start and stop profiling in the Emulator.

This chapter is organized as follows:

Host Control Structures and Types
Host Control Constants
Host Control Functions and Macros

The header file HostControl.h declares the API that this chapter describes.

The functions documented in this chapter are invoked by executing a trap/selector combination that is defined for use by the Emulator and other foreign host environments. Palm OS Emulator catches the calls intended for it that are made to this selector.


IMPORTANT: These functions are not for use on actual devices; they are only intended to be called from code running in a simulated environment such as Palm OS Emulator.

Host Control Structures and Types ^TOP^

HostBool Typedef ^TOP^

Purpose

An alias for HostBoolType.

Declared In

HostControl.h

Prototype

typedef HostBoolType HostBool

HostBoolType Typedef ^TOP^

Purpose

A Boolean value type, used to pass Boolean values to and receive Boolean values from various host control functions.

Declared In

HostControl.h

Prototype

typedef long HostBoolType

HostClockType Typedef ^TOP^

Purpose

A platform-independent representation of the standard C library clock_t type.

Declared In

HostControl.h

Prototype

typedef long HostClockType

HostControlSelectorType Typedef ^TOP^

Purpose

Contains a Host Control function selector value.

Declared In

HostControl.h

Prototype

typedef uint16_t HostControlSelectorType

Comments

See "Host Control Function Selectors" for a complete list of function selectors.

HostControlTrapNumber Typedef ^TOP^

Purpose

An alias for HostControlSelectorType.

Declared In

HostControl.h

Prototype

typedef HostControlSelectorType
   HostControlTrapNumber

HostDirEntType Struct ^TOP^

Purpose

A platform-specific type (usually just a null-terminated file name) that contains a directory name.

Declared In

HostControl.h

Prototype

struct HostDirEntType
{
   char d_name[HOST_NAME_MAX + 1];
};
typedef struct HostDirEntType HostDirEntType

Fields

d_name
The directory name.

Comments

This type is used by HostReadDir() to return a directory name.

HostDIRType Struct ^TOP^

Purpose

Type that represents an open directory whose contents can be read.

Declared In

HostControl.h

Prototype

struct HostDIRType
{
   long _field;
};
typedef struct HostDIRType HostDIRType

Fields

_field

Comments

Values of this type are returned by HostOpenDir(). The HostReadDir() and HostCloseDir() functions take values of this type.

HostErr Typedef ^TOP^

Purpose

An alias for HostErrType.

Declared In

HostControl.h

Prototype

typedef HostErrType HostErr

HostErrType Typedef ^TOP^

Purpose

A type that contains a host control error.

Declared In

HostControl.h

Prototype

typedef long HostErrType

HostFILE Typedef ^TOP^

Purpose

An alias for HostFILEType.

Declared In

HostControl.h

Prototype

typedef HostFILEType HostFILE

HostFILEType Struct ^TOP^

Purpose

Type that represents an open file whose contents can be manipulated.

Declared In

HostControl.h

Prototype

struct HostFILEType
{
   long _field;
};
typedef struct HostFILEType HostFILEType

Fields

_field

Comments

The host control API defines HostFILEType for the standard C library functions that take FILE* parameters. It is returned by HostFOpen() and used by other host control functions.

HostID Typedef ^TOP^

Purpose

An alias for HostIDType.

Declared In

HostControl.h

Prototype

typedef HostIDType HostID

HostIDType Typedef ^TOP^

Purpose

A host identifier.

Declared In

HostControl.h

Prototype

typedef long HostIDType

Comments

Retrieve a host's identifier with HostGetHostID(). See the "Host IDs" enum for the set of values that this type can assume.

HostPlatform Typedef ^TOP^

Purpose

An alias for HostPlatformType.

Declared In

HostControl.h

Prototype

typedef HostPlatformType HostPlatform

HostPlatformType Typedef ^TOP^

Purpose

A platform identifier.

Declared In

HostControl.h

Prototype

typedef long HostPlatformType

Comments

Retrieve a host's platform tyhpe with HostGetHostPlatform(). See the "Host Platforms" enum for the set of values that this type can assume.

HostSignal Typedef ^TOP^

Purpose

An alias for HostSignalType.

Declared In

HostControl.h

Prototype

typedef HostSignalType HostSignal

HostSignalType Typedef ^TOP^

Purpose

A host signal, used by functions such as HostSignalSend().

Declared In

HostControl.h

Prototype

typedef long HostSignalType

Comments

See the "Host Signals" enum for the set of values that this type can assume.

HostSizeType Typedef ^TOP^

Purpose

A platform-independent version of the standard C library size_t type.

Declared In

HostControl.h

Prototype

typedef long HostSizeType

HostStatType Struct ^TOP^

Purpose

Contains file status.

Declared In

HostControl.h

Prototype

struct HostStatType {
   unsigned long   st_dev_;
   unsigned long   st_ino_;
   unsigned long   st_mode_;
   unsigned long   st_nlink_;
   unsigned long   st_uid_;
   unsigned long   st_gid_;
   unsigned long   st_rdev_;
   HostTimeType    st_atime_;
   HostTimeType    st_mtime_;
   HostTimeType    st_ctime_;
   unsigned long   st_size_;
   unsigned long   st_blksize_;
   unsigned long   st_blocks_;
   unsigned long   st_flags_;
};
typedef struct HostStatType HostStatType

Fields

st_dev_
Drive number of the disk containing the file (the same as st_rdev_).
st_ino_
Number of the information node for the file (Unix-specific information).
st_mode_
Bit mask for file-mode information. The _S_IFDIR bit indicates if this is a directory; the _S_IFREG bit indicates an ordinary file or device. User read/write bits are set according to the file's permission mode; user execute bits are set according to the filename extension.
st_nlink_
Always 1 on non-NTFS file systems.
st_uid_
Numeric identifier of the user who owns the file (Unix-specific information).
st_gid_
Numeric identifier of the group who owns the file (Unix-specific information).
st_rdev_
Drive number of the disk containing the file (the same as st_dev_).
st_atime_
Time of the last access of the file.
st_mtime_
Time of the last modification of the file.
st_ctime_
Time of the creation of the file.
st_size_
Size of the file in bytes.
st_blksize_
Block size for the file.
st_blocks_
Number of blocks.
st_flags_
File flags.

Comments

Retrieve file status information with HostStat().

HostTimeType Typedef ^TOP^

Purpose

A platform-independent version of the standard C library time_t type.

Declared In

HostControl.h

Prototype

typedef long HostTimeType

Comments

This type is used in the HostStatType and HostUTimeType structures and by various time-related host control functions.

HostTmType Struct ^TOP^

Purpose

Contains a date and time; used by various host control time functions.

Declared In

HostControl.h

Prototype

struct HostTmType
{
   long tm_sec_;
   long tm_min_;
   long tm_hour_;
   long tm_mday_;
   long tm_mon_;
   long tm_year_;
   long tm_wday_;
   long tm_yday_;
   long tm_isdst_;
};
typedef struct HostTmType HostTmType

Fields

tm_sec_
Seconds after the minute: range from 0 to 59.
tm_min_
Minutes after the hour: range from 0 to 59.
tm_hour_
Hours since midnight: range from 0 to 23.
tm_mday_
Day of the month: range from 1 to 31.
tm_mon_
Months since January: range from 0 to 11.
tm_year_
Years since 1900.
tm_wday_
Days since Sunday: range from 0 to 6.
tm_yday_
Days since January 1: range from 0 to 365.
tm_isdst_
Daylight savings time flag.

HostUTimeType Struct ^TOP^

Purpose

Contains the creation, access, and modification times for a file.

Declared In

HostControl.h

Prototype

struct HostUTimeType
{
   HostTimeType crtime_;
   HostTimeType actime_;
   HostTimeType modtime_;
};
typedef struct HostUTimeType HostUTimeType

Fields

crtime_
asctime_
modtime_

Comments

This structure is used in conjunction with the HostUTime() function to alter the modification time for a file.

Host Control Constants ^TOP^

Host Control Function Selectors ^TOP^

Purpose

Host control functions are invoked by executing a trap/selector combination that is defined for use by the Emulator and other foreign host environments. Palm OS Emulator catches the calls intended for it that are made to one of these selectors.

Declared In

HostControl.h

Constants

#define hostSelectorAscTime 0x0370
#define hostSelectorBase 0x0100
#define hostSelectorClock 0x0371
#define hostSelectorCloseDir 0x0383
#define hostSelectorCTime 0x0372
#define hostSelectorEnteringApp 0x0C03
#define hostSelectorErrNo 0x0300
#define hostSelectorExgLibAccept 0x0586
#define hostSelectorExgLibClose 0x0581
#define hostSelectorExgLibConnect 0x0585
#define hostSelectorExgLibControl 0x058C
#define hostSelectorExgLibDisconnect 0x0587
#define hostSelectorExgLibGet 0x0589
#define hostSelectorExgLibHandleEvent 0x0584
#define hostSelectorExgLibOpen 0x0580
#define hostSelectorExgLibPut 0x0588
#define hostSelectorExgLibReceive 0x058B
#define hostSelectorExgLibRequest 0x058D
#define hostSelectorExgLibSend 0x058A
#define hostSelectorExgLibSleep 0x0582
#define hostSelectorExgLibWake 0x0583
#define hostSelectorExitedApp 0x0C04
#define hostSelectorExportFile 0x0501
#define hostSelectorFClose 0x0301
#define hostSelectorFEOF 0x0302
#define hostSelectorFError 0x0303
#define hostSelectorFFlush 0x0304
#define hostSelectorFGetC 0x0305
#define hostSelectorFGetPos 0x0306
#define hostSelectorFGetS 0x0307
#define hostSelectorFOpen 0x0308
#define hostSelectorFPrintF 0x0309
#define hostSelectorFPutC 0x030A
#define hostSelectorFPutS 0x030B
#define hostSelectorFRead 0x030C
#define hostSelectorFree 0x031A
#define hostSelectorFReopen 0x030F
#define hostSelectorFScanF 0x0310
#define hostSelectorFSeek 0x0311
#define hostSelectorFSetPos 0x0312
#define hostSelectorFTell 0x0313
#define hostSelectorFWrite 0x0314
#define hostSelectorGestalt 0x0104
#define hostSelectorGet68KDebuggerPort 0x0C05
#define hostSelectorGetChar 0x0C40
#define hostSelectorGetDirectory 0x0B02
#define hostSelectorGetEnv 0x0317
#define hostSelectorGetFile 0x0B00
#define hostSelectorGetFileAttr 0x03AF
#define hostSelectorGetFirstApp 0x0C43
#define hostSelectorGetHostID 0x0101
#define hostSelectorGetHostPlatform 0x0102
#define hostSelectorGetHostVersion 0x0100
#define hostSelectorGetPreference 0x0600
#define hostSelectorGMTime 0x0374
#define hostSelectorHostControl68K 0x0C08
#define hostSelectorImportFile 0x0500
#define hostSelectorIsCallingTrap 0x0105
#define hostSelectorIsSelectorImplemented 0x0103
#define hostSelectorLastTrapNumber 0x0CFF
#define hostSelectorLocalTime 0x0375
#define hostSelectorLogEvent 0x0C07
#define hostSelectorLogFile 0x0700
#define hostSelectorMalloc 0x0318
#define hostSelectorMkDir 0x03AA
#define hostSelectorMkTime 0x0376
#define hostSelectorOpenDir 0x0380
#define hostSelectorPrintF 0x0C41
#define hostSelectorProfileCleanup 0x0204
#define hostSelectorProfileDetailFn 0x0205
#define hostSelectorProfileDump 0x0203
#define hostSelectorProfileInit 0x0200
#define hostSelectorProfileStart 0x0201
#define hostSelectorProfileStop 0x0202
#define hostSelectorPutFile 0x0B01
#define hostSelectorReadDir 0x0381
#define hostSelectorRealloc 0x0319
#define hostSelectorRemove 0x030D
#define hostSelectorRename 0x030E
#define hostSelectorRmDir 0x0394
#define hostSelectorSessionClose 0x0802
#define hostSelectorSessionCreate 0x0800
#define hostSelectorSessionOpen 0x0801
#define hostSelectorSessionQuit 0x0803
#define hostSelectorSetErrorLevel 0x0C06
#define hostSelectorSetFileAttr 0x03B0
#define hostSelectorSetLogFileSize 0x0701
#define hostSelectorSetPreference 0x0601
#define hostSelectorSignalResume 0x0806
#define hostSelectorSignalSend 0x0804
#define hostSelectorSignalWait 0x0805
#define hostSelectorSlotHasCard 0x0A02
#define hostSelectorSlotMax 0x0A00
#define hostSelectorSlotRoot 0x0A01
#define hostSelectorStat 0x03AB
#define hostSelectorStrFTime 0x0377
#define hostSelectorTime 0x0378
#define hostSelectorTmpFile 0x0315
#define hostSelectorTmpNam 0x0316
#define hostSelectorTraceClose 0x0901
#define hostSelectorTraceInit 0x0900
#define hostSelectorTraceOutputB 0x0906
#define hostSelectorTraceOutputT 0x0902
#define hostSelectorTraceOutputTL 0x0903
#define hostSelectorTraceOutputVT 0x0904
#define hostSelectorTraceOutputVTL 0x0905
#define hostSelectorTruncate 0x03A7
#define hostSelectorUTime 0x03AE
#define hostSelectorVFPrintF 0x031B
#define hostSelectorVFScanF 0x031C
#define hostSelectorVPrintF 0x0C42

Comments

You can use the host function selector constants with the HostIsSelectorImplemented() function to determine if a certain function is implemented on your debugging host. Each constant is the name of a function, with the Host prefix replaced by hostSelector.

Host Control Error Codes Enum ^TOP^

Purpose

Error codes returned by the various host control functions.

Declared In

HostControl.h

Constants

#define hostErrorClass 0x1C00
The value upon which all host control errors are based.
hostErrNone = 0
No error.
hostErrBase = hostErrorClass
The value upon which all host control errors are based.
hostErrUnknownGestaltSelector
The specified Gestalt selector value is not valid.
hostErrDiskError
A disk error occurred. The standard C library error code EIO is mapped to this error constant.
hostErrOutOfMemory
There is not enough memory to complete the request. The standard C library error code ENOMEM is mapped to this error constant.
hostErrMemReadOutOfRange
An out of range error occurred during a memory read.
hostErrMemWriteOutOfRange
An out of range error occurred during a memory write.
hostErrMemInvalidPtr
The pointer is not valid.
hostErrInvalidParameter
A parameter to a function is not valid. The standard C library error codes EBADF, EFAULT, and EINVAL are mapped to this error constant.
hostErrTimeout
A timeout occurred.
hostErrInvalidDeviceType
The specified device type is not valid.
hostErrInvalidRAMSize
The specified RAM size value is not valid.
hostErrFileNotFound
The specified file could not be found. The standard C library error code ENOENT is mapped to this error constant.
hostErrRPCCall
A function that must be called remotely was called by an application. These functions include: HostSessionCreate(), HostSessionOpen(), HostSessionClose(), HostSessionQuit(), HostSignalWait(), and HostSignalResume().
hostErrSessionRunning
A session is already running and one of the following functions was called: HostSessionCreate(), HostSessionOpen(), or HostSessionQuit().
hostErrSessionNotRunning
No session is running and the HostSessionClose() function was called.
hostErrNoSignalWaiters
The HostSignalSend() function was called, but there are no external scripts waiting for a signal.
hostErrSessionNotPaused
The HostSignalResume() function was called, but the session has not been paused by a call to HostSignalSend().
hostErrPermissions
The standard C library error codes EACCES and EPERM are mapped to this error constant.
hostErrFileNameTooLong
The standard C library error code ENAMETOOLONG is mapped to this error constant.
hostErrNotADirectory
The standard C library error code ENOTDIR is mapped to this error constant.
hostErrTooManyFiles
The standard C library error codes EMFILE and ENFILE are mapped to this error constant.
hostErrFileTooBig
The standard C library error code EFBIG is mapped to this error constant.
hostErrReadOnlyFS
The standard C library error code EROFS is mapped to this error constant.
hostErrIsDirectory
The standard C library error code EISDIR is mapped to this error constant.
hostErrExists
The standard C library error code EEXIST is mapped to this error constant.
hostErrOpNotAvailable
The standard C library error codes ENOSYS and ENODEV are mapped to this error constant.
hostErrDirNotEmpty
The standard C library error code ENOTEMPTY is mapped to this error constant.
hostErrDiskFull
The standard C library error code ENOSPC is mapped to this error constant.
hostErrProfilingNotReady
The profiling system is not ready.
hostErrUnknownError
The standard C library error code values that are not mapped to any of the above error constants are mapped to this error constant.

Host IDs Enum ^TOP^

Purpose

The HostGetHostID() function uses a Host ID value to specify the debugging host type.

Declared In

HostControl.h

Constants

hostIDPalmOS
A Palm Powered™ device.
hostIDPalmOSEmulator
The Palm OS Emulator application.
hostIDPalmOSSimulator
Returned for both Palm OS Simulator and the Macintosh Palm Simulator application.

Host Platforms Enum ^TOP^

Purpose

The HostGetHostPlatform() function uses one of these values to specify operating system hosting the emulation.

Declared In

HostControl.h

Constants

hostPlatformPalmOS
The Palm OS platform.
hostPlatformWindows
The Windows operating system platform.
hostPlatformMacintosh
The Mac OS platform.
hostPlatformUnix
The Unix operating system platform.

Host Signals Enum ^TOP^

Purpose

This section describes the host signal values, which you can use with HostSignalSend().

Declared In

HostControl.h

Constants

hostSignalReserved
System-defined signals start here.
hostSignalIdle
Palm OS Emulator is about to go into an idle state.
hostSignalQuit
Palm OS Emulator is about to quit.
hostSignalUser = 0x40000000
User-defined signals start here.

File Attributes Enum ^TOP^

Purpose

File or directory attributes. Supply one of these values to HostGetFileAttr() to retrieve the corresponding setting for a specified file or directory.

Declared In

HostControl.h

Constants

hostFileAttrReadOnly = 1
The file is read-only.
hostFileAttrHidden = 2
The file is hidden.
hostFileAttrSystem = 4
The file is a system file.

Error Levels ^TOP^

Purpose

Error levels.

Declared In

HostControl.h

Constants

#define kErrorLevelFatal 2
Fatal error.
#define kErrorLevelNone 0
No error.
#define kErrorLevelWarning 1
Warning.

Miscellaneous Host Control Constants ^TOP^

Purpose

The Host Control APIs also include these constants.

Declared In

HostControl.h

Constants

#define HOST_NAME_MAX 255
The maximum length, not including the terminating null character, of a directory name as encapsulated in a HostDirEntType structure.
#define kPalmOSEmulatorFeatureCreator ('pose')
Creator ID of the Palm OS Emulator feature. Pass this value along with kPalmOSEmulatorFeatureNumber to FtrGet() to see if you are running under the Palm OS Emulator. If not, FtrGet() returns ftrErrNoSuchFeature.
#define kPalmOSEmulatorFeatureNumber (0)
Feature number of the Palm OS Emulator feature. Pass this value along with kPalmOSEmulatorFeatureCreator to FtrGet() to see if you are running under the Palm OS Emulator. If not, FtrGet() returns ftrErrNoSuchFeature.

Host Control Functions and Macros ^TOP^

HostAscTime Function ^TOP^

Purpose

Obtain a character string representation of a HostTmType structure.

Declared In

HostControl.h

Prototype

char *HostAscTime (
   const HostTmType *time
)

Parameters

time
The time for which a character string representation is desired.

Returns

The time as a character string.

See Also

HostCTime()

HostClock Function ^TOP^

Purpose

Obtain an elapsed time value.

Declared In

HostControl.h

Prototype

HostClockType HostClock (
   void
)

Parameters

None.

Returns

The elapsed time in terms of the operating system's clock function (usually the number clock ticks that have elapsed since the start of the process), or -1 if the function call was not successful.

HostCloseDir Function ^TOP^

Purpose

Close a directory.

Declared In

HostControl.h

Prototype

long HostCloseDir (
   HostDIRType *directory
)

Parameters

directory
The directory to be closed.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

HostControl Function ^TOP^

Purpose

Host control function dispatcher.

Declared In

HostControl.h

Prototype

uint32_t HostControl (
   HostControlTrapNumber selector,
   ...
)

Parameters

selector
The function selector of for the function to be called. One of the values listed under "Host Control Function Selectors."
...
Parameters for the function being called.

Returns

Returns the result of the function.

HostCTime Function ^TOP^

Purpose

Generate a text representation of a HostTimeType structure.

Declared In

HostControl.h

Prototype

char *HostCTime (
   const HostTimeType *timeOfDay
)

Parameters

timeOfDay
The time for which a text representation is desired.

Returns

A text representation of the specified time.

See Also

HostAscTime()

HostEnteringApp Function ^TOP^

Purpose

Record an application's name for later use in various logging messages.

Declared In

HostControl.h

Prototype

void HostEnteringApp (
   char *appName
)

Parameters

appName
The name of the application that is about to be entered.

Returns

Returns nothing.

See Also

HostSetErrorLevel()

HostErrNo Function ^TOP^

Purpose

Returns the value of errno, the standard C library variable that reflects the result of many standard C library functions. You can call this function after calling one of the host control functions that wraps the standard C library.

Declared In

HostControl.h

Prototype

long HostErrNo (
   void
)

Parameters

None.

Returns

The error number.

Comments

This function is only applicable to functions that wrap standard C library functions that affect errno. It is not applicable to all host control functions.

See Also

HostFError()

HostExgLibAccept Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

status_t HostExgLibAccept (
   uint16_t libRefNum,
   void *exgSocketP
)

HostExgLibClose Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

status_t HostExgLibClose (
   uint16_t libRefNum
)

HostExgLibConnect Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

status_t HostExgLibConnect (
   uint16_t libRefNum,
   void *exgSocketP
)

HostExgLibControl Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

status_t HostExgLibControl (
   uint16_t libRefNum,
   uint16_t op,
   void *valueP,
   uint16_t *valueLenP
)

HostExgLibDisconnect Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

status_t HostExgLibDisconnect (
   uint16_t libRefNum,
   void *exgSocketP,
   status_t error
)

HostExgLibGet Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

status_t HostExgLibGet (
   uint16_t libRefNum,
   void *exgSocketP
)

HostExgLibHandleEvent Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

Boolean HostExgLibHandleEvent (
   uint16_t libRefNum,
   void *eventP
)

HostExgLibOpen Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

status_t HostExgLibOpen (
   uint16_t libRefNum
)

HostExgLibPut Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

status_t HostExgLibPut (
   uint16_t libRefNum,
   void *exgSocketP
)

HostExgLibReceive Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

uint32_t HostExgLibReceive (
   uint16_t libRefNum,
   void *exgSocketP,
   void *bufP,
   const uint32_t bufSize,
   status_t *errP
)

HostExgLibRequest Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

status_t HostExgLibRequest (
   uint16_t libRefNum,
   void *exgSocketP
)

HostExgLibSend Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

uint32_t HostExgLibSend (
   uint16_t libRefNum,
   void *exgSocketP,
   const void *const bufP,
   const uint32_t bufLen,
   status_t *errP
)

HostExgLibSleep Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

status_t HostExgLibSleep (
   uint16_t libRefNum
)

HostExgLibWake Function ^TOP^

Purpose

Internal function intended for system use only. Applications should not call this function.

Declared In

HostControl.h

Prototype

status_t HostExgLibWake (
   uint16_t libRefNum
)

HostExitedApp Function ^TOP^

Purpose

Declared In

HostControl.h

Prototype

void HostExitedApp (
   char *,
   uint32_t
)

Parameters

uint32_t

Returns

Nothing.

HostExportFile Function ^TOP^

Purpose

Copies a database from the device to the desktop computer.

Declared In

HostControl.h

Prototype

HostErrType HostExportFile (
   const char *fileName,
   const char *dbName
)

Parameters

fileName
The filename to use on the desktop computer.
dbName
The name of the database on the device to be copied.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

See Also

HostImportFile()

HostFClose Function ^TOP^

Purpose

Close a file on the desktop computer.

Declared In

HostControl.h

Prototype

long HostFClose (
   HostFILEType *f
)

Parameters

f
The file to close.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

See Also

HostFOpen()

HostFEOF Function ^TOP^

Purpose

Determine the status of a specified file's end-of-file indicator.

Declared In

HostControl.h

Prototype

long HostFEOF (
   HostFILEType *f
)

Parameters

f
The file for which the end-of-file status is being checked.

Returns

Returns 0 if the specified file's end-of-file indicator is set, or a nonzero value otherwise.

HostFError Function ^TOP^

Purpose

Retrieve the error code from the most recent operation on the specified file.

Declared In

HostControl.h

Prototype

long HostFError (
   HostFILEType *f
)

Parameters

f
The file for which the error code is needed.

Returns

The error code from the most recent operation on the specified file. Returns errNone if no errors have occurred on the file.

See Also

HostErrNo()

HostFFlush Function ^TOP^

Purpose

Flush the buffer for the specified file.

Declared In

HostControl.h

Prototype

long HostFFlush (
   HostFILEType *f
)

Parameters

f
The file to flush.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

See Also

HostFPrintF(), HostFPutC(), HostFPutS(), HostFWrite()

HostFGetC Function ^TOP^

Purpose

Retrieve the character at the current position in the specified file.

Declared In

HostControl.h

Prototype

long HostFGetC (
   HostFILEType *f
)

Parameters

f
The file from which the character is to be read.

Returns

The character at the current position, or EOF if the current position is at the end of the file.

See Also

HostFGetS(), HostFPutC()

HostFGetPos Function ^TOP^

Purpose

Retrieve the current position in the specified file.

Declared In

HostControl.h

Prototype

long HostFGetPos (
   HostFILEType *f,
   long *posP
)

Parameters

f
The file.
posP
The current position in the file.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

See Also

HostFTell()

HostFGetS Function ^TOP^

Purpose

Retrieve a character string from the selected file.

Declared In

HostControl.h

Prototype

char *HostFGetS (
   char *s,
   long n,
   HostFILEType *f
)

Parameters

s
Pointer to the string buffer that will be filled with characters obtained from the specified file.
n
The number of characters to retrieve.
f
The file containing the string to be retrieved.

Returns

A pointer to the character string, or NULL if an error occurred.

See Also

HostFError(), HostFGetC()

HostFOpen Function ^TOP^

Purpose

Open a file on the desktop computer.

Declared In

HostControl.h

Prototype

HostFILEType *HostFOpen (
   const char *name,
   const char *mode
)

Parameters

name
The name of the file to open.
mode
The mode to use when opening the file. See the Comments section, below, for the format of this string.

Returns

A filestream pointer or NULL if an error occurred.

Comments

The mode argument points to a string beginning with one of the following sequences (additional characters may follow these sequences):

"r"
Open text file for reading. The stream is positioned at the beginning of the file.
"r+"
Open for reading and writing. The stream is positioned at the beginning of the file.
"w"
Truncate file to zero length or create text file for writing. The stream is positioned at the beginning of the file.
"w+"
Open for reading and writing. The file is created if it does not exist, otherwise it is truncated. The stream is positioned at the beginning of the file.
"a"
Open for writing. The file is created if it does not exist. The stream is positioned at the end of the file. Subsequent writes to the file will always end up at the then current end of file, irrespective of any intervening HostFSeek() or similar.
"a+"
Open for reading and writing. The file is created if it does not exist. The stream is positioned at the end of the file. Subsequent writes to the file will always end up at the then current end of file, irrespective of any intervening HostFSeek() or similar.

The mode string can also include the letter "f" to indicate that only plain files should be opened. It can also include the letter "b", but this is strictly for compatibility with ISO/IEC 9899:1990 ("ISO C89") and has no effect; the "b" is ignored.

See Also

HostFClose(), HostFError(), HostFReopen()

HostFPrintF Function ^TOP^

Purpose

Write a formatted string to a file.

Declared In

HostControl.h

Prototype

long HostFPrintF (
   HostFILEType *f,
   const char *fmt,
   ...
)

Parameters

f
The file to which the string is written.
fmt
The format specification.
...
String arguments.

Returns

The number of characters written to the file.

See Also

HostFPutC(), HostFPutS(), HostFScanF()

HostFPutC Function ^TOP^

Purpose

Write a character to the specified file.

Declared In

HostControl.h

Prototype

long HostFPutC (
   long c,
   HostFILEType *f
)

Parameters

c
The character to write.
f
The file to which the character is written.

Returns

The number of characters written, or EOF if an error occurred.

See Also

HostFError(), HostFGetC(), HostFPutS()

HostFPutS Function ^TOP^

Purpose

Write a string to the specified file.

Declared In

HostControl.h

Prototype

long HostFPutS (
   const char *s,
   HostFILEType *f
)

Parameters

s
The string to write.
f
The file to which the string is written.

Returns

The number of characters written, or EOF if an error occurred.

See Also

HostFError(), HostFGetS(), HostFPrintF(), HostFPutC()

HostFRead Function ^TOP^

Purpose

Read a number of items from a file into a buffer.

Declared In

HostControl.h

Prototype

long HostFRead (
   void *buffer,
   long size,
   long count,
   HostFILEType *f
)

Parameters

buffer
The buffer into which data is read.
size
The size of each item.
count
The number of items to read.
f
The file from which to read.

Returns

The number of items that were actually read.

See Also

HostFScanF(), HostFWrite()

HostFree Function ^TOP^

Purpose

Free memory on the desktop computer.

Declared In

HostControl.h

Prototype

void HostFree (
   void *p
)

Parameters

p
Pointer to the memory block to be freed.

Returns

Returns nothing.

See Also

HostMalloc(), HostRealloc()

HostFReopen Function ^TOP^

Purpose

Change the file with which a given file stream is associated. HostFReopen closes the file currently associated with the stream, then opens the new file and associates it with the same stream.

Declared In

HostControl.h

Prototype

HostFILEType *HostFReopen (
   const char *name,
   const char *mode,
   HostFILEType *f
)

Parameters

name
The name of the file to open.
mode
The mode to use when opening the file. See the Comments section under HostFOpen() for the format of this parameter.
f
The file stream to be reopened.

Returns

The file stream pointer, or NULL to indicate an error.

See Also

HostFClose(), HostFError(), HostFOpen()

HostFScanF Function ^TOP^

Purpose

Read formatted text from a file.

Declared In

HostControl.h

Prototype

long HostFScanF (
   HostFILEType *f,
   const char *fmt,
   ...
)

Parameters

f
The file from which to read.
fmt
A format string, as used in standard C-library calls such as scanf.
...
The list of variables into which scanned input is written.

Returns

The number of items that were read, or a negative value to indicate an error. Returns EOF if end of file was reached while scanning.

See Also

HostFGetS(), HostFPrintF()

HostFSeek Function ^TOP^

Purpose

Move the file pointer to a specified position.

Declared In

HostControl.h

Prototype

long HostFSeek (
   HostFILEType *f,
   long offset,
   long origin
)

Parameters

f
The file for which the current position is to be moved.
offset
The number of bytes to move from the initial position, which is specified in the origin parameter. Note that this is a signed value; offset can either be positive or negative.
origin
The initial position. Either SEEK_SET (offset is relative to the start of the file), SEEK_CUR (offset is relative to the current position), or SEEK_END (offset is relative to the end of the file).

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

See Also

HostFGetPos(), HostFSetPos(), HostFTell()

HostFSetPos Function ^TOP^

Purpose

Set the file's position indicator.

Declared In

HostControl.h

Prototype

long HostFSetPos (
   HostFILEType *f,
   long *pos
)

Parameters

f
The file for which the position indicator is to be set.
pos
The position within the file.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

See Also

HostFGetPos(), HostFSeek(), HostFTell()

HostFTell Function ^TOP^

Purpose

Retrieve the current position of the specified file.

Declared In

HostControl.h

Prototype

long HostFTell (
   HostFILEType *f
)

Parameters

f
The file.

Returns

Returns errNone if the operation was successful, or -1 if an error occurred.

See Also

HostFError(), HostFGetPos(), HostFSeek(), HostFSetPos()

HostFWrite Function ^TOP^

Purpose

Write data to a file.

Declared In

HostControl.h

Prototype

long HostFWrite (
   const void *buffer,
   long size,
   long count,
   HostFILEType *f
)

Parameters

buffer
The buffer that contains the data to be written.
size
The size of each item.
count
The number of items to write.
f
The file to which the data is written.

Returns

The number of items actually written.

See Also

HostFPutC(), HostFPutS(), HostFRead()

HostGestalt Function ^TOP^

Purpose

Currently does nothing except return an "invalid selector" error. In the future, this function will be used for queries about the runtime environment.

Declared In

HostControl.h

Prototype

HostErrType HostGestalt (
   long gestSel,
   long *response
)

Parameters

gestSel
A selector.
response
The response. This function currently does nothing with this parameter.

Returns

Returns hostErrUnknownGestaltSelector.

HostGetChar Function ^TOP^

Purpose

Get a character from the host user.

Declared In

HostControl.h

Prototype

long HostGetChar (
   void
)

Parameters

None.

Returns

The character.

HostGetDirectory Function ^TOP^

Purpose

Get a directory, in support of the operating system file chooser dialog box.

Declared In

HostControl.h

Prototype

const char *HostGetDirectory (
   const char *prompt,
   const char *defaultDir
)

Parameters

prompt
Text with which to prompt the user.
defaultDir
The default directory to get.

Returns

Returns the directory as a character string.

See Also

HostGetFile()

HostGetEnv Function ^TOP^

Purpose

Retrieve the value of an environment variable.

Declared In

HostControl.h

Prototype

char *HostGetEnv (
   const char *varName
)

Parameters

varName
The name of the environment variable that you want to retrieve.

Returns

The value of the named variable as a string, or NULL if the variable cannot be retrieved.

See Also

HostGetPreference()

HostGetFile Function ^TOP^

Purpose

Get a file, in support of the operating system file chooser dialog box.

Declared In

HostControl.h

Prototype

const char *HostGetFile (
   const char *prompt,
   const char *defaultDir
)

Parameters

prompt
Text with which to prompt the user.
defaultDir
The default directory to get.

Returns

Returns the file as a character string.

See Also

HostGetDirectory(), HostGetFileAttr(), HostPutFile()

HostGetFileAttr Function ^TOP^

Purpose

Get the attribute settings of a file or directory. This function can tell you whether the file is read-only, hidden, or a system file.

Declared In

HostControl.h

Prototype

long HostGetFileAttr (
   const char *fileOrPathName,
   long *attrFlag
)

Parameters

fileOrPathname
The file name or directory path for which you want to get the file attribute setting.
attrFlag
The setting to be retrieved. Supply one of the values listed under "File Attributes."

Returns

The value of the requested file attribute.

See Also

HostGetFile(), HostSetFileAttr()

HostGetFirstApp Function ^TOP^

Purpose

Declared In

HostControl.h

Prototype

uint32_t HostGetFirstApp (
   void
)

Parameters

None.

Returns

HostGetHostID Function ^TOP^

Purpose

Retrieve the ID of the debugging host. This is one of the constants described in "Host IDs." Palm OS Emulator always returns the value hostIDPalmOSEmulator.

Declared In

HostControl.h

Prototype

HostIDType HostGetHostID (
   void
)

Parameters

None.

Returns

The host ID.

See Also

HostGetHostPlatform()

HostGetHostPlatform Function ^TOP^

Purpose

Retrieve the host platform ID, which is one of the values described in "Host Platforms.".

Declared In

HostControl.h

Prototype

HostPlatformType HostGetHostPlatform (
   void
)

Parameters

None.

Returns

The platform ID.

See Also

HostGetHostID()

HostGetHostVersion Function ^TOP^

Purpose

Retrieve the version number of the debugging host.

Declared In

HostControl.h

Prototype

long HostGetHostVersion (
   void
)

Parameters

None.

Returns

The version number.

Comments

This function returns the version number in the same format that is used by the Palm OS, which means that you can access the version number components using the following macros from the SystemMgr.h file:

  • sysGetROMVerMajor(dwROMVer)
  • sysGetROMVerMinor(dwROMVer)
  • sysGetROMVerFix(dwROMVer)
  • sysGetROMVerStage(dwROMVer)
  • sysGetROMVerBuild(dwROMVer)

HostGetPreference Function ^TOP^

Purpose

Retrieve a specified preference value.

Declared In

HostControl.h

Prototype

HostBoolType HostGetPreference (
   const char *prefName,
   char *prefValue
)

Parameters

prefName
The name of the preference whose value you want to retrieve.
prefValue
The value of the specified preference, as a string.

Returns

If the specified preference was successfully retrieved, this function returns true, and *prefValue is set to the value of the preference. Otherwise, this function returns false and *prefValue isn't changed.

Comments

Each preference is identified by name. The preference names can be found in the appropriate Palm OS Emulator preferences file, depending on your platform. See Table 29.1 for the name and location of the Palm OS Emulator preference file for each supported platform.

Table 29.1  Palm OS Emulator preferences file names and locations 

Platform

File name

File location

Macintosh

Palm OS Emulator Prefs

The Preferences folder

Windows

Palm OS Emulator.ini

The Windows System directory

Unix

.poserrc

Your home directory

See Also

HostGetEnv(), HostSetPreference()

HostGMTime Function ^TOP^

Purpose

Get a time structure representation of a time value, expressed as Universal Time Coordinated, or UTC (UTC was formerly Greenwich Mean Time, or GMT).

Declared In

HostControl.h

Prototype

HostTmType *HostGMTime (
   const HostTimeType *time
)

Parameters

time
The HostTimeType value.

Returns

The specified time, as a HostTmType structure.

See Also

HostLocalTime(), HostMkTime()

HostHostControl68K Function ^TOP^

Purpose

Declared In

HostControl.h

Prototype

uint32_t HostHostControl68K (
   HostControlSelectorType selector,
   void *pceEmulState
)

Parameters

selector
pceEmulState

Returns

HostImportFile Function ^TOP^

Purpose

Copy a database from the desktop computer to the device.

Declared In

HostControl.h

Prototype

HostErrType HostImportFile (
   const char *fileName
)

Parameters

fileName
The file on the desktop computer that contains the database being copied.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

Comments

The database name on the device is the name stored in the file.

See Also

HostExportFile()

HostIsCallingTrap Function ^TOP^

Purpose

Determine if Palm OS Emulator is currently calling a trap.

Declared In

HostControl.h

Prototype

HostBoolType HostIsCallingTrap (
   void
)

Parameters

None.

Returns

A Boolean value indicating whether or not Palm OS Emulator is currently calling a trap.

HostIsSelectorImplemented Function ^TOP^

Purpose

Determine if a specified function selector is implemented on the debugging host.

Declared In

HostControl.h

Prototype

HostBoolType HostIsSelectorImplemented (
   long selector
)

Parameters

selector
The function selector. This must be one of the constants described in "Host Control Function Selectors."

Returns

A Boolean value indicating whether or not the specified function selector is implemented on the debugging host.

HostLocalTime Function ^TOP^

Purpose

Get a time structure representation of a time value, expressed as local time.

Declared In

HostControl.h

Prototype

HostTmType *HostLocalTime (
   const HostTimeType *time
)

Parameters

time
The HostTimeType value.

Returns

The specified time, as a HostTmType structure.

See Also

HostGMTime()

HostLogEvent Function ^TOP^

Purpose

Declared In

HostControl.h

Prototype

void HostLogEvent (
   void *
)

Parameters

Returns

Nothing.

HostLogFile Function ^TOP^

Purpose

Get a reference to the file that the Emulator is using to log information. You can use this reference to add your own information to the log file.

Declared In

HostControl.h

Prototype

HostFILEType *HostLogFile (
   void
)

Parameters

None.

Returns

A pointer to the log file, or NULL if the function was unable to obtain a reference to the log file.

HostMalloc Function ^TOP^

Purpose

Allocate a block of memory on the debugging host.

Declared In

HostControl.h

Prototype

void *HostMalloc (
   long size
)

Parameters

size
The number of bytes to allocate.

Returns

A pointer to the allocated memory block, or NULL if there is not enough memory available.

See Also

HostFree(), HostRealloc()

HostMkDir Function ^TOP^

Purpose

Create a directory on the debugging host.

Declared In

HostControl.h

Prototype

long HostMkDir (
   const char *directory
)

Parameters

directory
The directory to create.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

See Also

HostFOpen(), HostRmDir()

HostMkTime Function ^TOP^

Purpose

Convert a time structure representation of a time value to an equivalent encoded local time.

Declared In

HostControl.h

Prototype

HostTimeType HostMkTime (
   HostTmType *tm
)

Parameters

tm
The HostTmType structure containing the time to be converted.

Returns

Returns the calendar time equivalent to the encoded time, or returns a value of -1 if the calendar time cannot be represented.

See Also

HostGMTime()

HostOpenDir Function ^TOP^

Purpose

Open a directory.

Declared In

HostControl.h

Prototype

HostDIRType *HostOpenDir (
   const char *directory
)

Parameters

directory
The directory to open.

Returns

A directory structure that can be used with other directory operations.

See Also

HostCloseDir()

HostPrintF Function ^TOP^

Purpose

Send formatted output to stdout.

Declared In

HostControl.h

Prototype

long HostPrintF (
   const char *fmt,
   ...
)

Parameters

fmt
The format string. See the man page for the standard C function printf() for instructions on creating this argument.
...
Arguments to be sent to stdout, formatted according to fmt.

Returns

Returns the number of characters printed, not including the trailing null character used to end output to strings.

See Also

HostVFPrintF(), HostVPrintF()

HostProfileCleanup Function ^TOP^

Purpose

Release the memory used for profiling and disable profiling.

Declared In

HostControl.h

Prototype

HostErrType HostProfileCleanup (
   void
)

Parameters

None.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred. Returns hostErrProfilingNotReady if called out of sequence. For information on profiling sequence, see HostProfileInit().

Comments

This function is available only in the profiling version of the Emulator.

See Also

HostProfileDump(), HostProfileStart(), HostProfileStop()

HostProfileDetailFn Function ^TOP^

Purpose

Profile the function that contains a specified address.

Declared In

HostControl.h

Prototype

HostErrType HostProfileDetailFn (
   void *addr,
   HostBoolType logDetails
)

Parameters

addr
The address in which you are interested.
logDetails
If true, profiling is performed at a machine-language instruction level, which means that each opcode is treated as its own function.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

Comments

This function is available only in the profiling version of the Emulator.

See Also

HostProfileCleanup(), HostProfileDump(), HostProfileStart(), HostProfileStop()

HostProfileDump Function ^TOP^

Purpose

Write the current profiling information to a named file.

Declared In

HostControl.h

Prototype

HostErrType HostProfileDump (
   const char *filename
)

Parameters

filename
The name of the file to which the profile information gets written.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred. Returns hostErrProfilingNotReady if called out of sequence. For information on profiling sequence, see HostProfileInit().

Comments

This function is available only in the profiling version of the Emulator.

See Also

HostProfileCleanup(), HostProfileInit(), HostProfileStart(), HostProfileStop()

HostProfileInit Function ^TOP^

Purpose

Initialize and enable profiling in the debugging host.

Declared In

HostControl.h

Prototype

HostErrType HostProfileInit (
   long maxCalls,
   long maxDepth
)

Parameters

maxCalls
The maximum number of calls to profile. This parameter determines the size of the array used to keep track of function calls. A typical value for maxCalls is 65536.
maxDepth
The maximum profiling depth. This parameter determines the size of the array used to keep track of function call depth. A typical value for maxDepth is 200.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred. Returns hostErrProfilingNotReady if called out of sequence.

Comments

This function is available only in the profiling version of the Emulator.

The host control profiling functions are intended to be called in sequence:

  1. HostProfileInit() - All profiling starts with this function, which initializes and enables profiling.
  2. HostProfileStart() turns profiling on.
  3. HostProfileStop() turns profiling off. After calling HostProfileStop(), you can either call HostProfileStart() to restart profiling or call HostProfileDump(), which disables profiling and writes data to a file.
  4. HostProfileDump() disables profiling and writes data to a file. If you need to do more profiling after calling HostProfileDump(), you must call HostProfileInit() to re-enable profiling.
  5. HostProfileCleanup() releases the memory used for profiling and disables profiling.

HostProfileStart Function ^TOP^

Purpose

Turn profiling on.

Declared In

HostControl.h

Prototype

HostErrType HostProfileStart (
   void
)

Parameters

None.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred. Returns hostErrProfilingNotReady if called out of sequence. For information on profiling sequence, see HostProfileInit().

Comments

This function is available only in the profiling version of the Emulator.

See Also

HostProfileCleanup(), HostProfileDump(), HostProfileInit(), HostProfileStop()

HostProfileStop Function ^TOP^

Purpose

Turn profiling off.

Declared In

HostControl.h

Prototype

HostErrType HostProfileStop (
   void
)

Parameters

None.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred. Returns hostErrProfilingNotReady if called out of sequence. For information on profiling sequence, see HostProfileInit().

Comments

This function is available only in the profiling version of the Emulator.

See Also

HostProfileCleanup(), HostProfileDump(), HostProfileInit(), HostProfileStart()

HostPutFile Function ^TOP^

Purpose

Write a file, in support of the operating system Save As dialog box.

Declared In

HostControl.h

Prototype

const char *HostPutFile (
   const char *prompt,
   const char *defaultDir,
   const char *defaultName
)

Parameters

prompt
Text with which to prompt the user.
defaultDir
The default directory to use.
defaultName
The default file name to use.

Returns

Returns the file name as a character string.

See Also

HostGetFile()

HostReadDir Function ^TOP^

Purpose

Read a directory.

Declared In

HostControl.h

Prototype

HostDirEntType *HostReadDir (
   HostDIRType *directory
)

Parameters

directory
The directory to read.

Returns

Returns a character array for the directory.

HostRealloc Function ^TOP^

Purpose

Reallocate space for a specified memory block.

Declared In

HostControl.h

Prototype

void *HostRealloc (
   void *p,
   long size
)

Parameters

p
A pointer to a memory block to be resized.
size
The new size for the memory block.

Returns

A pointer to the reallocated memory block, or NULL if the memory block couldn't be reallocated.

Comments

Reallocation of the memory block can cause it to be relocated in memory. Thus you must use the pointer returned from this function to access the block after reallocation.

See Also

HostFree(), HostMalloc()

HostRemove Function ^TOP^

Purpose

Delete a file.

Declared In

HostControl.h

Prototype

long HostRemove (
   const char *name
)

Parameters

name
The name of the file to be deleted.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

See Also

HostRmDir()

HostRename Function ^TOP^

Purpose

Rename a file.

Declared In

HostControl.h

Prototype

long HostRename (
   const char *oldName,
   const char *newName
)

Parameters

oldName
The name of the file to be renamed.
newName
The new name of the file.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

HostRmDir Function ^TOP^

Purpose

Removes a directory.

Declared In

HostControl.h

Prototype

long HostRmDir (
   const char *directory
)

Parameters

directory
The directory to remove.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

See Also

HostRemove()

HostSessionClose Function ^TOP^

Purpose

Close the current emulation session.

Declared In

HostControl.h

Prototype

HostErrType HostSessionClose (
   const char *saveFileName
)

Parameters

saveFileName
The name of the file to which the current session is to be saved.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

Compatibility

This function is defined for external RPC clients to call; the effect of calling it for Palm OS applications running on the emulated device is undefined.

See Also

HostSessionCreate()

HostSessionCreate Function ^TOP^

Purpose

Create a new emulation session.

Declared In

HostControl.h

Prototype

HostErrType HostSessionCreate (
   const char *device,
   long ramSize,
   const char *romPath
)

Parameters

device
The name of the device to emulate in the session.
ramSize
The amount of emulated RAM in the new session.
romPath
The path to the ROM file for the new session.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

Compatibility

This function is defined for external RPC clients to call; the effect of calling it for Palm OS applications running on the emulated device is undefined.

See Also

HostSessionClose()

HostSessionOpen Function ^TOP^

Purpose

Open a previously saved emulation session.

Declared In

HostControl.h

Prototype

HostErrType HostSessionOpen (
   const char *psfFileName
)

Parameters

psfFileName
The name of the file containing the saved session to open.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

Compatibility

This function is defined for external RPC clients to call; the effect of calling it for Palm OS applications running on the emulated device is undefined.

HostSessionQuit Function ^TOP^

Purpose

Ask Palm OS Emulator to quit. Return an error if a session is already running.

Declared In

HostControl.h

Prototype

HostErrType HostSessionQuit (
   void
)

Parameters

None.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

Compatibility

This function is defined for external RPC clients to call; the effect of calling it for Palm OS applications running on the emulated device is undefined.

See Also

HostSessionCreate()

HostSetErrorLevel Function ^TOP^

Purpose

Change the error level, and write a message to the error log.

Declared In

HostControl.h

Prototype

void HostSetErrorLevel (
   uint32_t level,
   const char *msg
)

Parameters

level
The new error level. One of the values listed under "Error Levels.".
msg
A message to be recorded in the log file (ErrorLog.txt).

Returns

Returns nothing.

HostSetFileAttr Function ^TOP^

Purpose

Set the read-only, hidden, or system-file attribute for a file or directory.

Declared In

HostControl.h

Prototype

long HostSetFileAttr (
   const char *fileOrPathName,
   long attrFlag
)

Parameters

fileOrPathName
The file name or directory path for which you want to set the attribute.
long
The attribute to be set. Supply one of the values listed under "File Attributes."

Returns

Returns the file attribute.

See Also

HostGetFileAttr()

HostSetLogFileSize Function ^TOP^

Purpose

Specify the size of the logging file that Palm OS Emulator is to use.

Declared In

HostControl.h

Prototype

void HostSetLogFileSize (
   long size
)

Parameters

size
The new size for the logging file, in bytes.

Returns

Returns nothing.

Comments

By default, Palm OS Emulator saves the last 1 MB of log data to prevent logging files from becoming enormous. You can call this function to change the log file size.

HostSetPreference Function ^TOP^

Purpose

Set a specified preference value.

Declared In

HostControl.h

Prototype

void HostSetPreference (
   const char *prefName,
   const char *prefValue
)

Parameters

prefName
The name of the preference whose value is to be set.
prefValue
The new value of the preference, as a string.

Returns

Returns nothing.

Comments

Each preference is identified by name. The preference names can be found in the appropriate Palm OS Emulator preferences file, depending on your platform. See Table 29.1 for the name and location of the Palm OS Emulator preference file for each supported platform.

See Also

HostGetPreference()

HostSignalResume Function ^TOP^

Purpose

Restart Palm OS Emulator after it has issued a signal.

Declared In

HostControl.h

Prototype

HostErrType HostSignalResume (
   void
)

Parameters

None.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

Comments

Palm OS Emulator waits to be restarted after issuing a signal to allow external scripts to perform operations.

Compatibility

This function is defined for external RPC clients to call and returns an error if you call it from within a Palm OS application.

See Also

HostSignalSend(), HostSignalWait()

HostSignalSend Function ^TOP^

Purpose

Send a signal to any scripts with pending HostSignalWait() calls.

Declared In

HostControl.h

Prototype

HostErrType HostSignalSend (
   HostSignalType signalNumber
)

Parameters

signalNumber
The signal for which you want to wait. This can be a predefined signal or one that you have defined.

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred. Returns hostErrNoSignalWaiters if there aren't any scripts waiting for a signal.

Comments

Palm OS Emulator halts and waits to be restarted after sending the signal. This allows external scripts to perform operations. The external script must call the HostSignalResume() function to restart Palm OS Emulator.

If there are not any scripts waiting for a signal, Palm OS Emulator does not halt.

The predefined signals are documented under "Host Signals."

Compatibility

This function is defined for external RPC clients to call and returns an error if you call it from within a Palm OS application.

HostSignalWait Function ^TOP^

Purpose

Wait for a signal from Palm OS Emulator, and return the signalled value.

Declared In

HostControl.h

Prototype

HostErrType HostSignalWait (
   long timeout,
   HostSignalType *signalNumber
)

Parameters

timeout
The number of milliseconds to wait for the signal before timing out.
signalNumber
The number of the signal that occurred.

Returns

Returns errNone if the operation was successful, hostErrTimeout if the amount of time specified in timeout passed before a signal was received, or one of the error values listed in "Host Control Error Codes" if an error occurred.

Comments

Palm OS Emulator waits to be restarted after issuing a signal to allow external scripts to perform operations.

The predefined signals are documented under "Host Signals."

Compatibility

This function is defined for external RPC clients to call and returns an error if you call it from within a Palm OS application.

See Also

HostSignalResume(), HostSignalSend()

HostSlotHasCard Function ^TOP^

Purpose

Determine whether Emulator is emulating a Virtual File System (VFS) card for a specific slot number.

Declared In

HostControl.h

Prototype

HostBoolType HostSlotHasCard (
   long slotNo
)

Parameters

slotNo
The slot number. This number can be in the range from 1 up to and including the number returned by function HostSlotMax().

Returns

Returns true if the Emulator is emulating a VFS card in the specified slot, false otherwise.

Comments

This function may return false if the user has not selected to emulate a VFS card in the given slot, or if Emulator is emulating a different kind of card in that slot.

This function is provided in support of Expansion Manager emulation.

HostSlotMax Function ^TOP^

Purpose

Determine the number of Virtual File System (VFS) cards that Emulator is emulating.

Declared In

HostControl.h

Prototype

long HostSlotMax (
   void
)

Parameters

None.

Returns

The number of VFS cards Emulator is emulating.

Comments

The functions that accept card numbers, HostSlotHasCard() and HostSlotRoot(), accept numbers from 1 up to and including the number returned by this function.

This function is provided in support of Expansion Manager emulation.

HostSlotRoot Function ^TOP^

Purpose

Get a string representing the root directory of the emulated Virtual File System (VFS) card in a specified slot.

Declared In

HostControl.h

Prototype

const char *HostSlotRoot (
   long slotNo
)

Parameters

slotNo
The slot number. This number can be in the range from 1 up to and including the number returned by function HostSlotMax().

Returns

A character string in host path format representing the directory used as the root for the given VFS card. This function may return NULL if there is no VFS card mounted in the slot specified by slotNo, or if the user has not selected a root directory for that slot.

Comments

This function is provided in support of Expansion Manager emulation.

See Also

HostSlotHasCard()

HostStat Function ^TOP^

Purpose

Get status information about a file or directory.

Declared In

HostControl.h

Prototype

long HostStat (
   const char *fileOrDirectory,
   HostStatType *info
)

Parameters

fileOrDirectory
The name of the file or directory for which you want status information
info
A HostStatType structure that receives the status information

Returns

Returns errNone if the operation was successful, or one of the error values listed in "Host Control Error Codes" if an error occurred.

HostStrFTime Function ^TOP^

Purpose

Generate a text representation of the contents of a date/time structure using a specified format.

Declared In

HostControl.h

Prototype

HostSizeType HostStrFTime (
   char *buffer,
   HostSizeType maxSize,
   const char *format,
   const HostTmType *timeP
)

Parameters

buffer
The formatted text.
maxSize
The maximum number of characters (including the null terminator) to be placed into buffer.
format
The format definition. See the man page for the standard C library strftime() function for documentation on how to construct this string.
timeP
The date/time structure whose contents are to be converted to a text string.

Returns

Returns the number of characters generated if the number is less than the maxSize parameter; otherwise, returns zero, and the characters stored in buffer are undefined.

HostTime Function ^TOP^

Purpose

Get the current calendar time.

Declared In

HostControl.h

Prototype

HostTimeType HostTime (
   HostTimeType *time
)

Parameters

time
The time structure.

Returns

Returns the current calendar time if the operation is successful, or -1 if an error occurred.

See Also

HostErrNo()

HostTmpFile Function ^TOP^

Purpose

Identify the temporary file used by the debugging host.

Declared In

HostControl.h

Prototype

HostFILEType *HostTmpFile (
   void
)

Parameters

None.

Returns

A pointer to the temporary file, or NULL if an error occurred.

HostTmpNam Function ^TOP^

Purpose

Create a unique temporary filename.

Declared In

HostControl.h

Prototype

char *HostTmpNam (
   char *name
)

Parameters

name
A pointer to a buffer into which the newly-created temporary filename is written, or NULL.

Returns

A pointer to an internal static object that the calling program can modify.

HostTraceClose Function ^TOP^

Purpose

Close the connection to the external trace reporting tool.

Declared In

HostControl.h

Prototype

void HostTraceClose (
   void
)

Parameters

None.

Returns

Nothing.

See Also

HostTraceInit()

HostTraceInit Function ^TOP^

Purpose

Initiate a connection to the external trace reporting tool.

Declared In

HostControl.h

Prototype

void HostTraceInit (
   void
)

Parameters

None.

Returns

Nothing.

Comments

The HostTrace... functions are used in conjunction with an external trace reporting tool. Call these functions to send information to the external tool in real time.

See Also

HostTraceClose(), HostTraceOutput...

HostTraceOutputB Function ^TOP^

Purpose

Write a buffer of data, in hex dump format, to the external trace reporting tool.

Declared In

HostControl.h

Prototype

void HostTraceOutputB (
   unsigned short moduleId,
   const void *buffer,
   long len
)

Parameters

moduleId
The ID of the Palm OS subsystem from which this output originates. You can use this with the external tracing tool to filter traces according to their origin. The ID must match one of the error classes defined in CmnErrors.h.
buffer
Pointer to a buffer of raw data to be output.
len
The number of bytes of data in the buffer.

Returns

Nothing.

See Also

HostTraceOutputT(), HostTraceOutputTL(), HostTraceOutputVT(), HostTraceOutputVTL()

HostTraceOutputT Function ^TOP^

Purpose

Write a formatted text string to the external trace reporting tool.

Declared In

HostControl.h

Prototype

void HostTraceOutputT (
   unsigned short moduleId,
   const char *fmt,
   ...
)

Parameters

moduleId
The ID of the Palm OS subsystem from which this output originates. You can use this with the external tracing tool to filter traces according to their origin. The ID must match one of the error classes defined in CmnErrors.h.
fmt
A format string, as used in standard C-library calls such as printf(). See the Comments section, below, for more detail.
...
The list of variables to be formatted for output.

Returns

Returns nothing.

Comments

The format string has the following form:

% flags width type

Table 29.2 shows the flag types that you can use in the format specification for the tracing output functions.

Table 29.2  Trace function format specification flags 

Flag

Description

-

Left-justified output.

+

Always display the sign symbol.

space

Display a space when the value is positive, rather than a '+' symbol.

#

Alternate form specifier.

Table 29.3 shows the output types that you can use in the format specification for the tracing output functions.

Table 29.3  Trace function format specification types 

Flag

Description

%

Display the '%' character.

s

Display a null-terminated string value.

c

Display a character value.

ld

Display an int32_t value.

lu

Display a uint32_t value.

lx or lX

Display a uint32_t value in hexadecimal.

hd

Display an int16_t value.

hu

Display a uint16_t value.

hx or hX

Display an int16_t or uint16_t value in hexadecimal.

See Also

HostTraceOutputB(), HostTraceOutputTL(), HostTraceOutputVT(), HostTraceOutputVTL()

HostTraceOutputTL Function ^TOP^

Purpose

Write a formatted text string, followed by a newline, to the external trace reporting tool. This function performs the same operation as HostTraceOutputT() but adds the newline character.

Declared In

HostControl.h

Prototype

void HostTraceOutputTL (
   unsigned short moduleId,
   const char *fmt,
   ...
)

Parameters

moduleId
The ID of the Palm OS subsystem from which this output originates. You can use this with the external tracing tool to filter traces according to their origin. The ID must match one of the error classes defined in CmnErrors.h.
fmt
A format string, as used in standard C-library calls such as printf(). See the Comments section under HostTraceOutputT() for more detail.
...
The list of variables to be formatted for output.

Returns

Returns nothing.

See Also

HostTraceOutputB(), HostTraceOutputVT(), HostTraceOutputVTL()

HostTraceOutputVT Function ^TOP^

Purpose

Write a formatted text string to the external trace reporting tool.

Declared In

HostControl.h

Prototype

void HostTraceOutputVT (
   unsigned short moduleId,
   const char *fmt,
   va_list vargs
)

Parameters

moduleId
The ID of the Palm OS subsystem from which this output originates. You can use this with the external tracing tool to filter traces according to their origin. The ID must match one of the error classes defined in CmnErrors.h.
fmt
A format string, as used in standard C-library calls such as printf(). See the Comments section under HostTraceOutputT() for more detail.
vargs
A structure containing the variable argument list. This is the same kind of variable argument list used for standard C-library functions such as vprintf().

Returns

Returns nothing.

See Also

HostTraceOutputB(), HostTraceOutputTL(), HostTraceOutputVTL()

HostTraceOutputVTL Function ^TOP^

Purpose

Write a formatted text string, followed by a newline, to the external trace reporting tool. This function performs the same operation as HostTraceOutputVT() but adds the newline character.

Declared In

HostControl.h

Prototype

void HostTraceOutputVTL (
   unsigned short moduleId,
   const char *fmt,
   va_list vargs
)

Parameters

moduleId
The ID of the Palm OS subsystem from which this output originates. You can use this with the external tracing tool to filter traces according to their origin. The ID must match one of the error classes defined in CmnErrors.h.
fmt
A format string, as used in standard C-library calls such as printf(). See the Comments section under HostTraceOutputT() for more detail.
vargs
A structure containing the variable argument list. This is the same kind of variable argument list used for standard C-library functions such as vprintf().

Returns

Returns nothing.

See Also

HostTraceOutputB(), HostTraceOutputT(), HostTraceOutputTL()

HostTruncate Function ^TOP^

Purpose

Extend or truncate a file to a specified length.

Declared In

HostControl.h

Prototype

long HostTruncate (
   const char *fileName,
   long size
)

Parameters

fileName
The name of the file.
size
The size of the file.

Returns

Returns 0 if the file was successfully resized, or -1 if an error occurred.

See Also

HostErrNo()

HostUTime Function ^TOP^

Purpose

Set the modification time for a file.

Declared In

HostControl.h

Prototype

long HostUTime (
   const char *fileName,
   HostUTimeType *modTime
)

Parameters

fileName
The name of the file.
modTime
The time values to be applied to the file.

Returns

Returns 0 if the file-modification time was successfully changed, or –1 if an error occurred.

See Also

HostErrNo()

HostVFPrintF Function ^TOP^

Purpose

Write formatted output to a file.

Declared In

HostControl.h

Prototype

long HostVFPrintF (
   HostFILEType *f,
   const char *fmt,
   va_list args
)

Parameters

f
The file to which the formatted output is to be written.
fmt
The format string. See the man page for the standard C function printf() for instructions on creating this argument.
args
Arguments to be written to the file, formatted according to fmt.

Returns

Returns the number of characters written, not including the trailing null character used to end output to strings.

See Also

HostPrintF(), HostVFScanF(), HostVPrintF()

HostVFScanF Function ^TOP^

Purpose

Read input from a file using a variable argument list of pointers.

Declared In

HostControl.h

Prototype

long HostVFScanF (
   HostFILEType *f,
   const char *fmt,
   va_list args
)

Parameters

f
The file from which to read.
fmt
The format string that specifies how the input data is to be interpreted. See the man page for the standard C function vfscanf() for instructions on creating this argument.
args
Pointers to the variables in which the data is deposited.

Returns

Returns the number of input items assigned, or EOF if an input failure occurred before any conversion was done. Note that in the event of a matching failure the number of input items assigned can be fewer than provided for.

See Also

HostGetChar(), HostVFPrintF()

HostVPrintF Function ^TOP^

Purpose

Send formatted output to stdout.

Declared In

HostControl.h

Prototype

long HostVPrintF (
   const char *fmt,
   va_list args
)

Parameters

fmt
The format string. See the man page for the standard C function printf() for instructions on creating this argument.
args
Arguments to be sent to stdout, formatted according to fmt.

Returns

Returns the number of characters printed, not including the trailing null character used to end output to strings.

See Also

HostPrintF(), HostVFPrintF(), HostVFScanF()