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
HostBool Typedef
Purpose
An alias for HostBoolType
.
Declared In
HostControl.h
Prototype
typedef HostBoolType HostBool
HostBoolType Typedef
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
Purpose
A platform-independent representation of the standard C library clock_t
type.
Declared In
HostControl.h
Prototype
typedef long HostClockType
HostControlSelectorType Typedef
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
Purpose
An alias for HostControlSelectorType
.
Declared In
HostControl.h
Prototype
typedef HostControlSelectorType HostControlTrapNumber
HostDirEntType Struct
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
Comments
This type is used by HostReadDir()
to return a directory name.
HostDIRType Struct
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
Comments
Values of this type are returned by HostOpenDir()
. The HostReadDir()
and HostCloseDir()
functions take values of this type.
HostErr Typedef
Purpose
An alias for HostErrType
.
Declared In
HostControl.h
Prototype
typedef HostErrType HostErr
HostErrType Typedef
Purpose
A type that contains a host control error.
Declared In
HostControl.h
Prototype
typedef long HostErrType
HostFILE Typedef
Purpose
An alias for HostFILEType
.
Declared In
HostControl.h
Prototype
typedef HostFILEType HostFILE
HostFILEType Struct
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
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
Purpose
An alias for HostIDType
.
Declared In
HostControl.h
Prototype
typedef HostIDType HostID
HostIDType Typedef
Purpose
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
Purpose
An alias for HostPlatformType
.
Declared In
HostControl.h
Prototype
typedef HostPlatformType HostPlatform
HostPlatformType Typedef
Purpose
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
Purpose
An alias for HostSignalType
.
Declared In
HostControl.h
Prototype
typedef HostSignalType HostSignal
HostSignalType Typedef
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
Purpose
A platform-independent version of the standard C library size_t
type.
Declared In
HostControl.h
Prototype
typedef long HostSizeType
HostStatType Struct
Purpose
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
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
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
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
Comments
This structure is used in conjunction with the HostUTime()
function to alter the modification time for a file.
Host Control Constants
Host Control Function Selectors
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
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
, andEINVAL
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()
, andHostSignalResume()
. -
hostErrSessionRunning
- A session is already running and one of the following functions was called:
HostSessionCreate()
,HostSessionOpen()
, orHostSessionQuit()
. -
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 toHostSignalSend()
. -
hostErrPermissions
- The standard C library error codes
EACCES
andEPERM
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
andENFILE
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
andENODEV
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
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
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
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
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
Purpose
Declared In
HostControl.h
Constants
-
#define kErrorLevelFatal 2
- Fatal error.
-
#define kErrorLevelNone 0
- No error.
-
#define kErrorLevelWarning 1
- Warning.
Miscellaneous Host Control Constants
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
toFtrGet()
to see if you are running under the Palm OS Emulator. If not,FtrGet()
returnsftrErrNoSuchFeature
. -
#define kPalmOSEmulatorFeatureNumber (0)
- Feature number of the Palm OS Emulator feature. Pass this value along with
kPalmOSEmulatorFeatureCreator
toFtrGet()
to see if you are running under the Palm OS Emulator. If not,FtrGet()
returnsftrErrNoSuchFeature
.
Host Control Functions and Macros
HostAscTime Function
Purpose
Obtain a character string representation of a HostTmType
structure.
Declared In
HostControl.h
Prototype
char *HostAscTime (
const HostTmType *time
)
Parameters
Returns
The time as a character string.
See Also
HostClock Function
Purpose
Declared In
HostControl.h
Prototype
HostClockType HostClock ( void )
Parameters
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
Purpose
Declared In
HostControl.h
Prototype
long HostCloseDir (
HostDIRType *directory
)
Parameters
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
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
Purpose
Generate a text representation of a HostTimeType
structure.
Declared In
HostControl.h
Prototype
char *HostCTime (
const HostTimeType *timeOfDay
)
Parameters
Returns
A text representation of the specified time.
See Also
HostEnteringApp Function
Purpose
Record an application's name for later use in various logging messages.
Declared In
HostControl.h
Prototype
void HostEnteringApp (
char *appName
)
Parameters
Returns
See Also
HostErrNo Function
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
Returns
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
HostExgLibAccept Function
Purpose
Internal function intended for system use only. Applications should not call this function.
Declared In
HostControl.h
Prototype
status_t HostExgLibAccept ( uint16_tlibRefNum
, void*exgSocketP
)
HostExgLibClose Function
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
Purpose
Internal function intended for system use only. Applications should not call this function.
Declared In
HostControl.h
Prototype
status_t HostExgLibConnect ( uint16_tlibRefNum
, void*exgSocketP
)
HostExgLibControl Function
Purpose
Internal function intended for system use only. Applications should not call this function.
Declared In
HostControl.h
Prototype
status_t HostExgLibControl ( uint16_tlibRefNum
, uint16_top
, void*valueP
, uint16_t*valueLenP
)
HostExgLibDisconnect Function
Purpose
Internal function intended for system use only. Applications should not call this function.
Declared In
HostControl.h
Prototype
status_t HostExgLibDisconnect ( uint16_tlibRefNum
, void*exgSocketP
, status_terror
)
HostExgLibGet Function
Purpose
Internal function intended for system use only. Applications should not call this function.
Declared In
HostControl.h
Prototype
status_t HostExgLibGet ( uint16_tlibRefNum
, void*exgSocketP
)
HostExgLibHandleEvent Function
Purpose
Internal function intended for system use only. Applications should not call this function.
Declared In
HostControl.h
Prototype
Boolean HostExgLibHandleEvent ( uint16_tlibRefNum
, void*eventP
)
HostExgLibOpen Function
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
Purpose
Internal function intended for system use only. Applications should not call this function.
Declared In
HostControl.h
Prototype
status_t HostExgLibPut ( uint16_tlibRefNum
, void*exgSocketP
)
HostExgLibReceive Function
Purpose
Internal function intended for system use only. Applications should not call this function.
Declared In
HostControl.h
Prototype
uint32_t HostExgLibReceive ( uint16_tlibRefNum
, void*exgSocketP
, void*bufP
, const uint32_tbufSize
, status_t*errP
)
HostExgLibRequest Function
Purpose
Internal function intended for system use only. Applications should not call this function.
Declared In
HostControl.h
Prototype
status_t HostExgLibRequest ( uint16_tlibRefNum
, void*exgSocketP
)
HostExgLibSend Function
Purpose
Internal function intended for system use only. Applications should not call this function.
Declared In
HostControl.h
Prototype
uint32_t HostExgLibSend ( uint16_tlibRefNum
, void*exgSocketP
, const void *constbufP
, const uint32_tbufLen
, status_t*errP
)
HostExgLibSleep Function
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
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
Purpose
Declared In
HostControl.h
Prototype
void HostExitedApp ( char *, uint32_t )
Parameters
Returns
HostExportFile Function
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
HostFClose Function
Purpose
Close a file on the desktop computer.
Declared In
HostControl.h
Prototype
long HostFClose (
HostFILEType *f
)
Parameters
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
HostFEOF Function
Purpose
Determine the status of a specified file's end-of-file indicator.
Declared In
HostControl.h
Prototype
long HostFEOF (
HostFILEType *f
)
Parameters
Returns
Returns 0 if the specified file's end-of-file indicator is set, or a nonzero value otherwise.
HostFError Function
Purpose
Retrieve the error code from the most recent operation on the specified file.
Declared In
HostControl.h
Prototype
long HostFError (
HostFILEType *f
)
Parameters
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
HostFFlush Function
Purpose
Flush the buffer for the specified file.
Declared In
HostControl.h
Prototype
long HostFFlush (
HostFILEType *f
)
Parameters
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
Purpose
Retrieve the character at the current position in the specified file.
Declared In
HostControl.h
Prototype
long HostFGetC (
HostFILEType *f
)
Parameters
Returns
The character at the current position, or EOF
if the current position is at the end of the file.
See Also
HostFGetPos Function
Purpose
Retrieve the current position in the specified file.
Declared In
HostControl.h
Prototype
long HostFGetPos ( HostFILEType*f
, long*posP
)
Parameters
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
HostFGetS Function
Purpose
Retrieve a character string from the selected file.
Declared In
HostControl.h
Prototype
char *HostFGetS ( char*s
, longn
, 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
HostFOpen Function
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
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
Purpose
Write a character to the specified file.
Declared In
HostControl.h
Prototype
long HostFPutC ( longc
, HostFILEType*f
)
Parameters
Returns
The number of characters written, or EOF
if an error occurred.
See Also
HostFError()
, HostFGetC()
, HostFPutS()
HostFPutS Function
Purpose
Write a string to the specified file.
Declared In
HostControl.h
Prototype
long HostFPutS ( const char*s
, HostFILEType*f
)
Parameters
Returns
The number of characters written, or EOF
if an error occurred.
See Also
HostFError()
, HostFGetS()
, HostFPrintF()
, HostFPutC()
HostFRead Function
Purpose
Read a number of items from a file into a buffer.
Declared In
HostControl.h
Prototype
long HostFRead ( void*buffer
, longsize
, longcount
, 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
HostFree Function
Purpose
Free memory on the desktop computer.
Declared In
HostControl.h
Prototype
void HostFree (
void *p
)
Parameters
Returns
See Also
HostFReopen Function
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
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
HostFSeek Function
Purpose
Move the file pointer to a specified position.
Declared In
HostControl.h
Prototype
long HostFSeek ( HostFILEType*f
, longoffset
, longorigin
)
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
Purpose
Set the file's position indicator.
Declared In
HostControl.h
Prototype
long HostFSetPos ( HostFILEType*f
, long*pos
)
Parameters
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
Purpose
Retrieve the current position of the specified file.
Declared In
HostControl.h
Prototype
long HostFTell (
HostFILEType *f
)
Parameters
Returns
Returns errNone
if the operation was successful, or -1 if an error occurred.
See Also
HostFError()
, HostFGetPos()
, HostFSeek()
, HostFSetPos()
HostFWrite Function
Purpose
Declared In
HostControl.h
Prototype
long HostFWrite ( const void*buffer
, longsize
, longcount
, 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
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 ( longgestSel
, long*response
)
Parameters
-
→ gestSel
- A selector.
-
← response
- The response. This function currently does nothing with this parameter.
Returns
Returns hostErrUnknownGestaltSelector.
HostGetChar Function
Purpose
Get a character from the host user.
Declared In
HostControl.h
Prototype
long HostGetChar ( void )
Parameters
Returns
HostGetDirectory Function
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
Returns
Returns the directory as a character string.
See Also
HostGetEnv Function
Purpose
Retrieve the value of an environment variable.
Declared In
HostControl.h
Prototype
char *HostGetEnv (
const char *varName
)
Parameters
Returns
The value of the named variable as a string, or NULL
if the variable cannot be retrieved.
See Also
HostGetFile Function
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
Returns
Returns the file as a character string.
See Also
HostGetDirectory()
, HostGetFileAttr()
, HostPutFile()
HostGetFileAttr Function
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
Purpose
Declared In
HostControl.h
Prototype
uint32_t HostGetFirstApp ( void )
Parameters
Returns
HostGetHostID Function
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
Returns
See Also
HostGetHostPlatform Function
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
Returns
See Also
HostGetHostVersion Function
Purpose
Retrieve the version number of the debugging host.
Declared In
HostControl.h
Prototype
long HostGetHostVersion ( void )
Parameters
Returns
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
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
See Also
HostGetEnv()
, HostSetPreference()
HostGMTime Function
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
HostHostControl68K Function
Purpose
Declared In
HostControl.h
Prototype
uint32_t HostHostControl68K ( HostControlSelectorTypeselector
, void*pceEmulState
)
Parameters
Returns
HostImportFile Function
Purpose
Copy a database from the desktop computer to the device.
Declared In
HostControl.h
Prototype
HostErrType HostImportFile (
const char *fileName
)
Parameters
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
HostIsCallingTrap Function
Purpose
Determine if Palm OS Emulator is currently calling a trap.
Declared In
HostControl.h
Prototype
HostBoolType HostIsCallingTrap ( void )
Parameters
Returns
A Boolean value indicating whether or not Palm OS Emulator is currently calling a trap.
HostIsSelectorImplemented Function
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
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
HostLogEvent Function
Purpose
Declared In
HostControl.h
Prototype
void HostLogEvent (
void *
)
Parameters
Returns
HostLogFile Function
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
Returns
A pointer to the log file, or NULL
if the function was unable to obtain a reference to the log file.
HostMalloc Function
Purpose
Allocate a block of memory on the debugging host.
Declared In
HostControl.h
Prototype
void *HostMalloc (
long size
)
Parameters
Returns
A pointer to the allocated memory block, or NULL
if there is not enough memory available.
See Also
HostMkDir Function
Purpose
Create a directory on the debugging host.
Declared In
HostControl.h
Prototype
long HostMkDir (
const char *directory
)
Parameters
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
HostMkTime Function
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
HostOpenDir Function
Purpose
Declared In
HostControl.h
Prototype
HostDIRType *HostOpenDir (
const char *directory
)
Parameters
Returns
A directory structure that can be used with other directory operations.
See Also
HostPrintF Function
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
HostProfileCleanup Function
Purpose
Release the memory used for profiling and disable profiling.
Declared In
HostControl.h
Prototype
HostErrType HostProfileCleanup ( void )
Parameters
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
Purpose
Profile the function that contains a specified address.
Declared In
HostControl.h
Prototype
HostErrType HostProfileDetailFn ( void*addr
, HostBoolTypelogDetails
)
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
Purpose
Write the current profiling information to a named file.
Declared In
HostControl.h
Prototype
HostErrType HostProfileDump (
const char *filename
)
Parameters
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
Purpose
Initialize and enable profiling in the debugging host.
Declared In
HostControl.h
Prototype
HostErrType HostProfileInit ( longmaxCalls
, longmaxDepth
)
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:
-
HostProfileInit()
- All profiling starts with this function, which initializes and enables profiling. -
HostProfileStart()
turns profiling on. -
HostProfileStop()
turns profiling off. After callingHostProfileStop()
, you can either callHostProfileStart()
to restart profiling or callHostProfileDump()
, which disables profiling and writes data to a file. -
HostProfileDump()
disables profiling and writes data to a file. If you need to do more profiling after callingHostProfileDump()
, you must callHostProfileInit()
to re-enable profiling. -
HostProfileCleanup()
releases the memory used for profiling and disables profiling.
HostProfileStart Function
Purpose
Declared In
HostControl.h
Prototype
HostErrType HostProfileStart ( void )
Parameters
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
Purpose
Declared In
HostControl.h
Prototype
HostErrType HostProfileStop ( void )
Parameters
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
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
HostReadDir Function
Purpose
Declared In
HostControl.h
Prototype
HostDirEntType *HostReadDir (
HostDIRType *directory
)
Parameters
Returns
Returns a character array for the directory.
HostRealloc Function
Purpose
Reallocate space for a specified memory block.
Declared In
HostControl.h
Prototype
void *HostRealloc ( void*p
, longsize
)
Parameters
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
HostRemove Function
Purpose
Declared In
HostControl.h
Prototype
long HostRemove (
const char *name
)
Parameters
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
HostRename Function
Purpose
Declared In
HostControl.h
Prototype
long HostRename ( const char*oldName
, const char*newName
)
Parameters
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
Purpose
Declared In
HostControl.h
Prototype
long HostRmDir (
const char *directory
)
Parameters
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
HostSessionClose Function
Purpose
Close the current emulation session.
Declared In
HostControl.h
Prototype
HostErrType HostSessionClose (
const char *saveFileName
)
Parameters
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 Function
Purpose
Create a new emulation session.
Declared In
HostControl.h
Prototype
HostErrType HostSessionCreate ( const char*device
, longramSize
, 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
HostSessionOpen Function
Purpose
Open a previously saved emulation session.
Declared In
HostControl.h
Prototype
HostErrType HostSessionOpen (
const char *psfFileName
)
Parameters
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
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
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
HostSetErrorLevel Function
Purpose
Change the error level, and write a message to the error log.
Declared In
HostControl.h
Prototype
void HostSetErrorLevel ( uint32_tlevel
, 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
HostSetFileAttr Function
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
, longattrFlag
)
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
See Also
HostSetLogFileSize Function
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
Returns
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
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
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
HostSignalResume Function
Purpose
Restart Palm OS Emulator after it has issued a signal.
Declared In
HostControl.h
Prototype
HostErrType HostSignalResume ( void )
Parameters
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
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
Purpose
Wait for a signal from Palm OS Emulator, and return the signalled value.
Declared In
HostControl.h
Prototype
HostErrType HostSignalWait ( longtimeout
, 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
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
Purpose
Determine the number of Virtual File System (VFS) cards that Emulator is emulating.
Declared In
HostControl.h
Prototype
long HostSlotMax ( void )
Parameters
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
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
HostStat Function
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
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, HostSizeTypemaxSize
, 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
Purpose
Get the current calendar time.
Declared In
HostControl.h
Prototype
HostTimeType HostTime (
HostTimeType *time
)
Parameters
Returns
Returns the current calendar time if the operation is successful, or -1 if an error occurred.
See Also
HostTmpFile Function
Purpose
Identify the temporary file used by the debugging host.
Declared In
HostControl.h
Prototype
HostFILEType *HostTmpFile ( void )
Parameters
Returns
A pointer to the temporary file, or NULL
if an error occurred.
HostTmpNam Function
Purpose
Create a unique temporary filename.
Declared In
HostControl.h
Prototype
char *HostTmpNam (
char *name
)
Parameters
Returns
A pointer to an internal static object that the calling program can modify.
HostTraceClose Function
Purpose
Close the connection to the external trace reporting tool.
Declared In
HostControl.h
Prototype
void HostTraceClose ( void )
Parameters
Returns
See Also
HostTraceInit Function
Purpose
Initiate a connection to the external trace reporting tool.
Declared In
HostControl.h
Prototype
void HostTraceInit ( void )
Parameters
Returns
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
Purpose
Write a buffer of data, in hex dump format, to the external trace reporting tool.
Declared In
HostControl.h
Prototype
void HostTraceOutputB ( unsigned shortmoduleId
, const void *buffer
, longlen
)
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
See Also
HostTraceOutputT()
, HostTraceOutputTL()
, HostTraceOutputVT()
, HostTraceOutputVTL()
HostTraceOutputT Function
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
Comments
The format string has the following form:
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
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
See Also
HostTraceOutputB()
, HostTraceOutputTL()
, HostTraceOutputVT()
, HostTraceOutputVTL()
HostTraceOutputTL Function
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 shortmoduleId
, 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 underHostTraceOutputT()
for more detail. -
→ ...
- The list of variables to be formatted for output.
Returns
See Also
HostTraceOutputB()
, HostTraceOutputVT()
, HostTraceOutputVTL()
HostTraceOutputVT Function
Purpose
Write a formatted text string to the external trace reporting tool.
Declared In
HostControl.h
Prototype
void HostTraceOutputVT ( unsigned shortmoduleId
, const char *fmt
, va_listvargs
)
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 underHostTraceOutputT()
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
See Also
HostTraceOutputB()
, HostTraceOutputTL()
, HostTraceOutputVTL()
HostTraceOutputVTL Function
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 shortmoduleId
, const char *fmt
, va_listvargs
)
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 underHostTraceOutputT()
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
See Also
HostTraceOutputB()
, HostTraceOutputT()
, HostTraceOutputTL()
HostTruncate Function
Purpose
Extend or truncate a file to a specified length.
Declared In
HostControl.h
Prototype
long HostTruncate ( const char *fileName
, longsize
)
Parameters
Returns
Returns 0 if the file was successfully resized, or -1 if an error occurred.
See Also
HostUTime Function
Purpose
Set the modification time for a file.
Declared In
HostControl.h
Prototype
long HostUTime ( const char*fileName
, HostUTimeType*modTime
)
Parameters
Returns
Returns 0 if the file-modification time was successfully changed, or –1 if an error occurred.
See Also
HostVFPrintF Function
Purpose
Write formatted output to a file.
Declared In
HostControl.h
Prototype
long HostVFPrintF ( HostFILEType*f
, const char*fmt
, va_listargs
)
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
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_listargs
)
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
HostVPrintF Function
Purpose
Send formatted output to stdout.
Declared In
HostControl.h
Prototype
long HostVPrintF ( const char*fmt
, va_listargs
)
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()