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

8    Host Control API Reference

Using Palm OS® Emulator

Palm OS Developer Suite

This chapter describes the host control API. The following topics are covered in this chapter:

About the Host Control API ^TOP^

You can use the host control API 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.

Host control functions are defined in the HostControl.h header file. These 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 this selector.


IMPORTANT: This chapter describes the version of the host control API that shipped with Palm OS Emulator 3.5. If you are using a different version, the features in your version might be different than the features described here.

Constants ^TOP^

This section lists the constants that you use with the host control API.

Host Error Constants ^TOP^

Several of the host control API functions return a HostErrType value.

enum
{
hostErrNone = 0,
hostErrBase = hostErrorClass,
hostErrUnknownGestaltSelector,
hostErrDiskError,
hostErrOutOfMemory,
hostErrMemReadOutOfRange,
hostErrMemWriteOutOfRange,
hostErrMemInvalidPtr,
hostErrInvalidParameter,
hostErrTimeout,
hostErrInvalidDeviceType,
hostErrInvalidRAMSize,
hostErrFileNotFound,
hostErrRPCCall,
hostErrSessionRunning,
hostErrSessionNotRunning,
hostErrNoSignalWaiters,
hostErrSessionNotPaused,
hostErrPermissions,
hostErrFileNameTooLong,
hostErrNotADirectory,
hostErrTooManyFiles,
hostErrFileTooBig,
hostErrReadOnlyFS,
hostErrIsDirectory,
hostErrExists,
hostErrOpNotAvailable,
hostErrDirNotEmpty,
hostErrDiskFull,
hostErrUnknownError
};
hostErrNone No error.
hostErrBase An administrative value for the HostError class. This value is not returned to applications.
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 handheld 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 HostSendSignal 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 HostSendSignal.
hostErrPermissions
The standard C library error code 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 code 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.
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 Function Selector Constants ^TOP^

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 portion replaced by HostSelector.

For a complete list of the constants available, see the HostControl.h header file.

Host ID Constants ^TOP^

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

enum
{
hostIDPalmOS,
hostIDPalmOSEmulator,
hostIDPalmOSSimulator
};
hostIDPalmOS A Palm Powered hardware handheld.
hostIDPalmOSEmulator
The Palm OS Emulator application.
hostIDPalmOSSimulator
Returned for both Palm OS Simulator and the Macintosh Palm Simulator application.

Host Platform Constants ^TOP^

The HostGetHostPlatform function uses a HostPlatform value to specify operating system hosting the emulation.

enum
{
hostPlatformPalmOS,
hostPlatformWindows,
hostPlatformMacintosh,
hostPlatformUnix
};
hostPlatformPalmOS
The Palm OS platform.
hostPlatformWindows
The Windows operating system platform.
hostPlatformMacintosh
The Mac OS platform.
hostPlatformUnix
The Unix operating system platform.

Host Signal Constants ^TOP^

This section describes the host signal values, which you can use with the HostSendSignal.

enum
{
hostSignalReserved,
hostSignalIdle,
hostSignalQuit
};
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.

Data Types ^TOP^

This section describes the data types that you use with the host control API.

HostBoolType ^TOP^

The host control API defines HostBoolType for use as a Boolean value.

typedef long HostBoolType;

HostClockType ^TOP^

The host control API defines HostClockType as a platform-independent representation of the standard C library clock_t type.

typedef long HostClockType;

HostDirEntType ^TOP^

The host control API defines HostDirEntType as a return value for the HostReadDir function. The contents are platform-specific, usually a simple null-terminated file name.

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

HostDIRType ^TOP^

The host control API defines HostDIRType for use in directory-related functions. It is returned by HostOpenDir and used by HostReadDir and HostCloseDir. It represents an open directory whose contents can be read.

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

HostFILEType ^TOP^

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. It represents an open file whose contents can be manipulated.

typedef struct HostFILEType
{
long _field;
} HostFILEType;

HostGremlinInfoType ^TOP^

The host control API defines the HostGremlinInfoType structure type to store information about a horde of gremlins.

typedef struct HostGremlinInfoType
{
long fFirstGremlin;
long fLastGremlin;
long fSaveFrequency;
long fSwitchDepth;
long fMaxDepth;
char fAppNames[200];
};
typedef struct HostGremlinInfoType HostGremlinInfoType;

HostGremlinInfo Fields

fFirstGremlin The number of the first gremlin to run.
fLastGremlin The number of the last gremlin to run.
fSaveFrequency The gremlin snapshot frequency.
fSwitchDepth The number of gremlin events to generate before switching to another gremlin.
fMaxDepth The maximum number of gremlin events to generate for each gremlin.
fAppNames A comma-separated string containing a list of application names among which the gremlin horde is allowed to switch.

If this string is empty, all applications are available for use with the gremlins.

If this string begins with a dash ('-'), the applications named in the string are excluded, rather than included in the list of available applications.

HostIDType ^TOP^

The host control API defines HostIDType for use as an identifier value.

typedef long HostIDType;

HostPlatformType ^TOP^

The host control API defines HostPlatformType for use as a platform identifier value.

typedef long HostPlatformType;

HostSignalType ^TOP^

The host control API defines HostSignalType for use in signal functions.

typedef long HostSignalType;

HostSizeType ^TOP^

The host control API defines HostSizeType as a platform-independent version of the standard C library size_t type.

typedef long HostSizeType;

HostStatType ^TOP^

The host control API defines HostStatType for status information about files.

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;

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 handheld. 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 returns 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.

HostTimeType ^TOP^

The host control API defines HostTimeType as a platform-independent version of the standard C library time_t type.

typedef long HostTimeType;

HostTmType ^TOP^

The host control API defines HostTmType for use in time functions.

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;

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 ^TOP^

The host control API defines HostUTimeTypefor use in time functions.

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

HostUTimeType Fields

crtime_ Creation time.
actime_ Access time.
modtime_ Modification time.

Functions ^TOP^

This section describes the host control API functions.


NOTE: For host control API functions that return pointers to character strings (that is, functions that return type char *), the returned value is valid only until the next call to a function that returns a pointer to a character string. If you need ongoing access to a character string, you should make a copy of the string before making the subsequent host control function call.

HostAscTime ^TOP^

Purpose

Returns a character string representation of the time encoded in time.

Prototype

char* HostAscTime(const HostTmType* time);
   

Parameters

time The time structure.
Result
The time as a character string.

HostClock ^TOP^

Purpose

Returns an elapsed time.

Prototype

HostClockType HostClock(void);
   

Parameters

None.

Result
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 ^TOP^

Purpose

Closes a directory.

Prototype

long HostCloseDir(HostDIRType* directory);
   

Parameters

directory The directory to be closed.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

HostCTime ^TOP^

Purpose

Converts the calendar time in *timeofday to a text representation.

Prototype

char* HostCTime(const HostTimeType* timeofday)


Parameters

timeofday The calendar time.
Result
The calendar time as a time string.
New HostDbgClearDataBreak

Purpose

Clears all data breakpoints that have been set by the HostDbgSetDataBreak function.

Prototype

HostErr HostDbgClearDataBreak (void)


Parameters

None.
Result

Returns 0 if the operation was successful, and a non-zero value if not.

New HostDbgSetDataBreak

Purpose

Sets a breakpoint for Emulator to enter an external debugger or to display a message if the bytes starting at the address (addr) and continuing for the given number of bytes (size) are accessed in any way (either written to or read from). This function provides the same function as the data breakpoint section of the Breakpoints dialog box (as described in "Setting Breakpoints").

Prototype

HostErr HostDbgSetDataBreak (UInt32 addr, UInt32 

size)


Parameters

addr The starting address for the range of bytes to be monitored for access.
size The number of bytes, starting from the address addr, that will be monitored for access.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

HostErrNo ^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.


IMPORTANT: The HostErrNo function is only applicable to functions that wrap standard C library functions that affect errno. It is not applicable to all Host Control functions.

Prototype

long HostErrNo(void);
   

Parameters

None.
Result
The error number.

HostExportFile ^TOP^

Purpose

Copies a database from the handheld to the desktop computer.

Prototype

HostErr HostExportFile(const char* fileName,


long cardNum, const char* dbName);
   

Parameters

fileName The file name to use on the desktop computer.
cardNum The number of the card on the handheld on which the database is contained.
dbName The name of the handheld database.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

HostFClose ^TOP^

Purpose

Closes a file on the desktop computer.

Prototype

long HostFClose(HostFILE* f);
   

Parameters

f The file to close.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

HostFEOF ^TOP^

Purpose

Determines if the specified file is at its end.

Prototype

long HostFEOF(HostFILE* f);
   

Parameters

f The file to test.
Result
Returns 0 if the specified file is at its end, and a non-zero value otherwise.

HostFError ^TOP^

Purpose

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

Prototype

long HostFError(HostFILE* f);
   

Parameters

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

HostFFlush ^TOP^

Purpose

Flushes the buffer for the specified file.

Prototype

long HostFFlush(HostFILE* f);
   

Parameters

f The file to flush.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

HostFGetC ^TOP^

Purpose

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

Prototype

long HostFGetC(HostFILE* f);
   

Parameters

f The file.
Result
The character, or EOF to indicate an error.

HostFGetPos ^TOP^

Purpose

Retrieves the current position in the specified file.

Prototype

long HostFGetPos(HostFILE* f, long* posn);
   

Parameters

f The file.
posn Upon successful return, the current position in the file.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

HostFGetS ^TOP^

Purpose

Retrieves a character string from the selected file and returns a pointer to that string.

Prototype

char* HostFGetS(char* s, long n, HostFILE* f);
   

Parameters

s A pointer to the string buffer to be filled with characters from the file.
n The number of characters to retrieve.
f The file.
Result
The character string, or NULL to indicate an error.

HostFOpen ^TOP^

Purpose

Opens a file on the desktop computer.

Prototype

HostFILE* 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.
Result
The file stream pointer, or NULL to indicate an error.

HostFPrintF ^TOP^

Purpose

Writes a formatted string to a file.

Prototype

long HostFPrintF(HostFILE* f, const char* format, 

...);
   

Parameters

f The file to which the string is written.
format The format specification.
... String arguments.
Result
The number of characters actually written.

HostFPutC ^TOP^

Purpose

Writes a character to the specified file.

Prototype

long HostFPutC(long c, HostFILE* f);
   

Parameters

c The character to write.
f The file to which the character is written.
Result
The number of characters written, or EOF to indicate an error.

HostFPutS ^TOP^

Purpose

Writes a string to the specified file.

Prototype

long HostFPutS(const char* s, HostFILE* f);
   

Parameters

s The string to write.
f The file to which the character is written.
Result
A non-negative value if the operation was successful, or a negative value to indicate failure.

HostFRead ^TOP^

Purpose

Reads a number of items from the file into a buffer.

Prototype

long HostFRead(void* buffer, long size,


long count, HostFILE* 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.
Result
The number of items that were actually read.

HostFree ^TOP^

Purpose

Frees memory on the desktop computer.

Prototype

void HostFree(void* p);
   

Parameters

p A pointer to the memory block to be freed.
Result
None.

HostFReopen ^TOP^

Purpose

Changes the file with which the stream f is associated. HostFReopen first closes the file that was associated with the stream, then opens the new file and associates it with the same stream.

Prototype

HostFILE* HostFReopen(const char* name,


const char* mode, HostFILE *f);
   

Parameters

name The name of the file to open.
mode The mode to use when opening the file.
f The file from which to read.
Result
The file stream pointer, or NULL to indicate an error.

HostFScanF ^TOP^

Purpose

Reads formatted text from a file.

Prototype

long HostFReopen(HostFILE* f, const char *fmt, ...);
   

Parameters

f The file from which to read input.
fmt A format string, as used in standard C-library calls such as scanf.
... The list of variables into which scanned input are written.
Result
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.

HostFSeek ^TOP^

Purpose

Moves the file pointer to the specified position.

Prototype

long HostFSeek(HostFILE* f, long offset,


long origin);
   

Parameters

f The file.
offset The number of bytes to move from the initial position, which is specified in the origin parameter.
origin The initial position.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

HostFSetPos ^TOP^

Purpose

Sets the position indicator of the file.

Prototype

long HostFSetPos(HostFILE* f, long posn);
   

Parameters

f The file.
posn The position value.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

HostFTell ^TOP^

Purpose

Retrieves the current position of the specified file.

Prototype

long HostFTell(HostFILE* f);
   

Parameters

f The file.
Result
Returns -1 to indicate an error.

HostFWrite ^TOP^

Purpose

Writes data to a file.

Prototype

long HostFWrite(const void* buffer, long size,


long count, HostFILE* 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.
Result
The number of items actually written.

HostGestalt ^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.

Prototype

HostErr HostGestalt(long gestSel, long* response);
   

Parameters

gestSel

response

HostGetDirectory ^TOP^

Purpose

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

Prototype

const char* HostGetDirectory(const char* prompt,	

const char* defaultDir);
   

Parameters

prompt
defaultDir The default directory to get.
Result

Returns the directory as a character string.

HostGetEnv ^TOP^

Purpose

Retrieves the value of an environment variable.

Prototype

char* HostGetEnv(char* varName);
   

Parameters

varName The name of the environment variable that you want to retrieve.
Result
The string value of the named variable, or NULL if the variable cannot be retrieved.

HostGetFile ^TOP^

Purpose

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

Prototype

const char* HostGetFile(const char* prompt, 


const char* defaultFile)


Parameters

prompt
defaultFile The default file to get.
Result

Returns the file as a character string.

HostGetFileAttr ^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.

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 One of the following attribute flags:
- hostFileAttrReadOnly
- hostFileAttrHidden
- hostFileAttrSystem

The file attribute flags match the EmFileAttr flags:

enum { hostFileAttrReadOnly = 1, hostFileAttrHidden = 2, hostFileAttrSystem = 4
}
Result
The file attribute.

HostGetHostID ^TOP^

Purpose

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

Prototype

HostID HostGetHostID(void);
   

Parameters

None.
Result
The host ID.

HostGetHostPlatform ^TOP^

Purpose

Retrieves the host platform ID, which is one of the values described in Host Platform Constants.

Prototype

HostPlatform HostGetHostPlatform(void);
   

Parameters

None.
Result
The platform ID.

HostGetHostVersion ^TOP^

Purpose

Retrieves the version number of the debugging host.

Prototype

long HostGetHostVersion(void);
   

Parameters

None.
Result
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 ^TOP^

Purpose

Retrieves the specified preference value.

Prototype

HostBool HostGetPreference(const char* prefName,


char* prefValue);
   

Parameters

prefName The name of the preference whose value you want to retrieve.
prefValue Upon successful return, the string value of the specified preference.
Result
A Boolean value that indicates whether the preference was successfully retrieved.

Comments

Each preference is identified by name. You can view the preference names in the Palm OS Emulator preferences file for your platform, as shown in Table 8.1.

Table 8.1 Palm OS Emulator preferences file names and locations 

Platform

File name

File location

Macintosh

Palm OS Emulator Prefs

In the Preferences folder

Windows

Palm OS Emulator.ini

In the Windows System directory

Unix

.poserrc

In your home directory

See Also

The HostSetPreference function.

HostGMTime ^TOP^

Purpose

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

Prototype

HostTmType* HostGMTime(const HostTimeType* time);
   

Parameters

time
Result

The time structure.

HostGremlinCounter ^TOP^

Purpose

Returns the current event count of the currently running gremlin.

Prototype

long HostGremlinCounter(void);
   

Parameters

None.
Result
The event count.

Comments

This return value of this function is only valid if a gremlin is currently running.

HostGremlinIsRunning ^TOP^

Purpose

Determines if a gremlin is currently running.

Prototype

HostBool HostGremlinIsRunning(void);
   

Parameters

None.
Result
A Boolean value indicating whether a gremlin is currently running.

HostGremlinLimit ^TOP^

Purpose

Retrieves the limit value of the currently running gremlin.

Prototype

long HostGremlinLimit(void);
   

Parameters

None.
Result
The limit value of the currently running gremlin.

Comments

This return value of this function is only valid if a gremlin is currently running.

HostGremlinNew ^TOP^

Purpose

Creates a new gremlin.

Prototype

HostErr HostGremlinNew(


const HostGremlinInfo* info);
   

Parameters

info A HostGremlinInfo structure with information about the new horde of gremlins

HostGremlinNumber ^TOP^

Purpose

Retrieves the number of the currently running gremlin.

Prototype

long HostGremlinNumber(void);
   

Parameters

None.
Result
The gremlin number of the currently running gremlin.

Comments

This return value of this function is only valid if a gremlin is currently running.

HostImportFile ^TOP^

Purpose

Copies a database from the desktop computer to the handheld, and stores it on the specified card number. The database name on the handheld is the name stored in the file.

Prototype

HostErr HostImportFile(const char* fileName,


long cardNum);
   

Parameters

fileName The file on the desktop computer that contains the database.
cardNum The card number on which the database is to be installed. You almost always use 0 to specify the built-in RAM.
Result
Returns 0 if the operation was successful, and a non-zero value if not.
New HostImportFileWithID

Purpose

Copies a database from the desktop computer to the handheld, stores it on the specified card number, and returns the local ID of the installed database. The database name on the handheld is the name stored in the file.

Prototype

HostErr HostImportFileWithID(const char* fileName,


long cardNum, LocalID* newIDP);
   

Parameters

fileName The file on the desktop computer that contains the database.
cardNum The card number on which the database is to be installed. You almost always use 0 to specify the built-in RAM.
newIDP The local ID of the installed database.
Result

Returns 0 if the operation was successful, and a non-zero value if not.

HostIsCallingTrap ^TOP^

Purpose

Determines if Palm OS Emulator is currently calling a trap.

Prototype

HostBool HostIsCallingTrap(void);
   

Parameters

None.
Result
TRUE if Palm OS Emulator is currently calling a trap, and FALSE if not.

HostIsSelectorImplemented ^TOP^

Purpose

Determines if the specified function selector is implemented on the debugging host.

Prototype

HostBool HostIsSelectorImplemented(long selector);
   

Parameters

selector The function selector. This must be one of the constants described in Host Function Selector Constants.
Result
TRUE if the specified function selector is implemented on the host, and FALSE if not

HostLocalTime ^TOP^

Purpose

Returns time structure representation of the time, expressed as local time.

Prototype

HostTmType* HostLocalTime(const HostTimeType* 

time);
   

Parameters

time The time structure.
Result

The time structure.

HostLogFile ^TOP^

Purpose

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

Prototype

HostFILE* HostLogFile(void);
   

Parameters

None.
Result

A pointer to the log file, or NULL if not successful.

HostMalloc ^TOP^

Purpose

Allocates a memory block on the debugging host.

Prototype

void* HostMalloc(long size);
   

Parameters

size The number of bytes to allocate.
Result
A pointer to the allocated memory block, or NULL if there is not enough memory available.

HostMkDir ^TOP^

Purpose

Creates a directory.

Prototype

long HostMkDir(const char* directory);
   

Parameters

directory The directory to create.
Result

Returns 0 if the operation was successful, and a non-zero value if not.

HostMkTime ^TOP^

Purpose

Alters the parameter values to represent an equivalent encoded local time, but with the values of all members within their normal ranges.

Prototype

HostTimeType HostMkTime(HostTmType* time)


Parameters

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

HostOpenDir ^TOP^

Purpose

Opens a directory.

Prototype

HostDIRType* HostOpenDir(const char* directory);
   

Parameters

directory The directory to open.
Result

Returns a directory structure.

HostProfileCleanup ^TOP^

Purpose

Releases the memory used for profiling and disables profiling.

Prototype

HostErr HostProfileCleanup(void);
   

Parameters

None.
Result

Returns 0 if the operation was successful, and a non-zero value if not. 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

The HostProfileStart, HostProfileStop, and HostProfileDump functions.

HostProfileDetailFn ^TOP^

Purpose

Profiles the function that contains the specified address.

Prototype

HostErr HostProfileDetailFn(void* addr,


HostBool logDetails);
   

Parameters

addr The address in which you are interested.
logDetails A Boolean value. If this is TRUE, profiling is performed at a machine-language instruction level, which means that each opcode is treated as its own function.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

Comments

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

See Also

The HostProfileInit, HostProfileStart, HostProfileStop, HostProfileDump, and HostProfileCleanup functions.

HostProfileDump ^TOP^

Purpose

Writes the current profiling information to the named file.

Prototype

HostErr HostProfileDump(const char* filename);
   

Parameters

filename The name of the file to which the profile information gets written.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

Comments

This function is available only in the profiling version of the emulator. Returns hostErrProfilingNotReady if called out of sequence. For information on profiling sequence, see "HostProfileInit".

See Also

The HostProfileInit, HostProfileStart, HostProfileStop, and HostProfileCleanup functions.

HostProfileGetCycles ^TOP^

Purpose

Returns the current running CPU cycle count.

Prototype

long HostProfileGetCycles(void)


Parameters

None.
Result
Returns the current running CPU cycle count.

Comments

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

See Also

The HostProfileInit, HostProfileStart, HostProfileStop, HostProfileDump, and HostProfileCleanup functions.

HostProfileInit ^TOP^

Purpose

Initializes and enables profiling in the debugging host.

Prototype

HostErr 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.
Result
Returns 0 if the operation was successful, and a non-zero value if not. 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 the HostProfileInit function, which initializes and enables profiling.
  2. HostProfileStart - This function turns profiling on.
  3. HostProfileStop - This function 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 - This function disables profiling and writes data to a file. If you need to do more profiling after calling HostProfileDump, you need to call HostProfileInit to re-enable profiling.
  5. HostProfileCleanup - This function releases the memory used for profiling and disables profiling.

See Also

The HostProfileStart, HostProfileStop, HostProfileDump, and HostProfileCleanup functions.

HostProfileStart ^TOP^

Purpose

Turns profiling on.

Prototype

HostErr HostProfileStart(void);
   

Parameters

None.
Result

Returns 0 if the operation was successful, and a non-zero value if not. 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

The HostProfileInit, HostProfileStop, HostProfileDump, and HostProfileCleanup functions.

HostProfileStop ^TOP^

Purpose

Turns profiling off.

Prototype

HostErr HostProfileStop(void);
   

Parameters

None.
Result
Returns 0 if the operation was successful, and a non-zero value if not. 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

The HostProfileInit, HostProfileStop, HostProfileDump, and HostProfileCleanup functions.

HostPutFile ^TOP^

Purpose

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

Prototype

const char* HostPutFile(const char* prompt, const 

char* defaultDir, const char* defaultName);
   

Parameters

prompt
defaultDir The default directory to use.
defaultName The default file name to use.
Result

Returns the file name as a character string.

HostReadDir ^TOP^

Purpose

Reads a directory.

Prototype

HostDirEntType* HostReadDir(HostDIRType* 

directory);
   

Parameters

directory The directory to read.
Result

Returns a character array for the directory.

HostRealloc ^TOP^

Purpose

Reallocates space for the specified memory block.

Prototype

void* HostRealloc(void* ptr, long size);
   

Parameters

ptr A pointer to a memory block that is being resized.
size The new size for the memory block.
Result
A pointer to the allocated memory block, or NULL if there is not enough memory available.

HostRemove ^TOP^

Purpose

Deletes a file.

Prototype

long HostRemove(const char* name);
   

Parameters

name The name of the file to be deleted.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

HostRename ^TOP^

Purpose

Renames a file.

Prototype

long HostRemove(const char* oldName,


const char* newName);
   

Parameters

oldName The name of the file to be renamed.
newName The new name of the file.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

HostRmDir ^TOP^

Purpose

Removes a directory.

Prototype

long HostRmDir(const char* directory);
   

Parameters

directory The directory to remove.
Result

Returns 0 if the operation was successful, and a non-zero value if not.

HostSaveScreen ^TOP^

Purpose

Saves the LCD frame buffer to the given file name.

Prototype

HostErrType HostSaveScreen(const char* fileName)


Parameters

fileName The name of the file to which the current LCD frame buffer is to be saved.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

HostSessionClose ^TOP^

Purpose

Closes the current emulation session.

Prototype

HostErr HostSessionClose(const char* psfFileName);
   

Parameters

psfFileName The name of the file to which the current session is to be saved.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

Comments

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

HostSessionCreate ^TOP^

Purpose

Creates a new emulation session.

Prototype

HostErr HostSessionCreate(const char* device,


long ramSize, const char* romPath);
   

Parameters

device The name of the handheld 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.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

Comments

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


IMPORTANT: This function is not implemented in the current version of Palm OS Emulator; however, it will be implemented in the near future.

HostSessionOpen ^TOP^

Purpose

Opens a previously saved emulation session.

Prototype

HostErr HostSessionOpen(const char* psfFileName);
   

Parameters

psfFileName The name of the file containing the saved session that you want to open.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

Comments

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


IMPORTANT: This function is not implemented in the current version of Palm OS Emulator; however, it will be implemented in the near future.

HostSessionQuit ^TOP^

Purpose

Asks Palm OS Emulator to quit. Returns an error if a session is already running.

Prototype

HostErr HostSessionQuit(void);
   

Parameters

None.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

Comments

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


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

Purpose

Saves a session to a file with the specified name.

Prototype

HostBoolType HostSessionSave(const char* 

saveFileName);
   

Parameters

saveFileName A file name for the session that you are saving.
Result
Returns false when saving a session to a file, whether or not the save attempt is successful. When the session file is reloaded, execution starts at the point where HostSessionSave is returning, and it then returns true.

Comments

This function can be useful when you want to save a session file for later analysis. When you reload the session file later, you can break into a debugger.

Example

void MyFunc (void) { // Check to see if our application's data is internally // consistant. If not, save the state for later analysis. if (ASSERT_VALID () == false) if (HostSessionSave ("c:\\temp\foo.psf")) DbgBreak (); }

HostSetFileAttr ^TOP^

Purpose

Set the attribute settings of a file or directory. This function can set the read-only, hidden, or system-file attribute for the file or directory.

Prototype

long HostSetFileAttr(const char* fileOrPathName, 

long* attrFlag)


Parameters

fileOrPathName The file name or directory path for which you want to set the file attribute setting.
attrFlag One of the following attribute flags:
- hostFileAttrReadOnly
- hostFileAttrHidden
- hostFileAttrSystem

The file attribute flags match the EmFileAttr flags:

enum { hostFileAttrReadOnly = 1, hostFileAttrHidden = 2, hostFileAttrSystem = 4 }
Result

The file attribute.

HostSetLogFileSize ^TOP^

Purpose

Determines the size of the logging file that Palm OS Emulator is using.

Prototype

void HostSetLogFileSize(long size);
   

Parameters

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

Comments

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

HostSetPreference ^TOP^

Purpose

Sets the specified preference value.

Prototype

void HostSetPreference(const char* prefName,


const char* prefValue);
   

Parameters

prefName The name of the preference whose value you are setting.
prefValue The new value of the preference.
Result
None.

Comments

Each preference is identified by name. You can view the preference names in the Palm OS Emulator preferences file for your platform, as shown in Table 8.1.

See Also

The HostGetPreference function.

HostSignalResume ^TOP^

Purpose

Restarts Palm OS Emulator after it has issued a signal.

Prototype

HostErr HostSignalResume(void);
   

Parameters

None.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

Comments

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

See Also

The HostSignalSend and HostSignalWait functions.


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

HostSignalSend ^TOP^

Purpose

Sends a signal to any scripts that have HostSignalWait calls pending.

Prototype

HostErr HostSignalSend(HostSignal signalNumber);
   

Parameters

signalNumber The signal for which you want to wait. This can be a predefined signal or one that you have defined.
Result
Returns 0 if the operation was successful, and a non-zero value if not.

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:

  • hostSignalIdle, which Palm OS Emulator issues when it detects that it is going into an idle state.
  • hostSignalQuit, which Palm OS Emulator issues when it is about to quit.

See Also

The HostSignalResume and HostSignalWait functions.


IMPORTANT: 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 ^TOP^

Purpose

Waits for a signal from Palm OS Emulator, and returns the signalled value.

Prototype

HostErr HostSignalWait(long timeout,


HostSignal* signalNumber);
   

Parameters

timeout The number of milliseconds to wait for the signal before timing out.
signalNumber The number of the signal that occurred.
Result
Returns 0 if the operation was successful, and a non-zero value if not. Returns the number of the signal that occurred in signalNumber.

Comments

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

The predefined signals are:

  • hostSignalIdle, which Palm OS Emulator issues when it detects that it is going into an idle state.
  • hostSignalQuit, which Palm OS Emulator issues when it is about to quit.

See Also

The HostSignalResume and HostSignalSend functions.


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

HostSlotHasCard ^TOP^

Purpose

Ask whether Emulator is emulating a Virtual File System card for a specific slot number.

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.
Result
A Boolean value that indicates whether Emulator is emulating a Virtual File System card in the slot specified by slotNo. This function is provided in support of Expansion Manager emulation.

Comments

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

HostSlotMax ^TOP^

Purpose

Returns the number of Virtual File System cards that Emulator is emulating.

Prototype

long HostSlotMax(void)


Parameters

None.
Result
A long value indicating the number of Virtual File System cards Emulator is emulating. This function is provided in support of Expansion Manager emulation.

Comments

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

HostSlotRoot ^TOP^

Purpose

Returns a string representing the root directory of the emulated slot.

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.
Result
The character string representing the directory to be used as the root for the given Virtual File System card. This function is provided in support of Expansion Manager emulation.

Comments

The string returned is in host path format. This function may return NULL if there is no Virtual File System card mounted in the slot specified by slotNo or if the user has not selected a root directory for that slot.

HostStat ^TOP^

Purpose

Returns status information about a file.

Prototype

long HostStat(const char* filename, HostStatType* 

buffer);
   

Parameters

filename The name of the file or directory for which you want status information
buffer The structure that stores the status information
Result

Returns 0 if the operation was successful, and a non-zero value if not.

HostStrFTime ^TOP^

Purpose

Generates formatted text, under the control of the format parameter and the values stored in the time structure parameter.

Prototype

HostSizeType HostStrFTime(char* string, 

HostSizeType size, const char* format, const 

HostTmType* time)


Parameters

string The formatted text
size The size of an array element in the formatted text
format The format definition
time A time structure
Result

Returns the number of characters generated, if the number is less than the size parameter; otherwise, returns zero, and the values stored in the array are indeterminate.

HostTime ^TOP^

Purpose

Returns the current calendar time.

Prototype

HostTimeType HostTime(HostTimeType* time);
   

Parameters

time The time structure.
Result

Returns the current calendar time if the operation is successful, and returns -1 if not.

HostTmpFile ^TOP^

Purpose

Returns the temporary file used by the debugging host.

Prototype

HostFILE* HostTmpFile(void);
   

Parameters

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

HostTmpNam ^TOP^

Purpose

Creates a unique temporary file name.

Prototype

char* HostTmpNam(char* s);
   

Parameters

s Either be a NULL pointer or a pointer to a character array. The character array must be at least L_tmpnam characters long.
If s is not NULL, the newly created temporary file name is stored into s.
Result
A pointer to an internal static object that the calling program can modify.

HostTraceClose ^TOP^

Purpose

Closes the connection to the external trace reporting tool.

Prototype

void HostTraceClose(void);
   

Parameters

None.
Result

None.

HostTraceInit ^TOP^

Purpose

Initiates a connection to the external trace reporting tool.

Prototype

void HostTraceInit(void);
   

Parameters

None.

NOTE: The tracing functions are used in conjunction with an external trace reporting tool. You can call these functions to send information to the external tool in real time.
Result
None.

HostTraceOutputB ^TOP^

Purpose

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

Prototype

void HostTraceOutputB(unsigned short moduleId, 


const void* buffer, 


unsigned long len/*size_t*/);
   

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 the SystemMgr.h file.
buffer A pointer to a buffer of raw data.
len The number of bytes of data in the buffer.
Result

None.

HostTraceOutputT ^TOP^

Purpose

Outputs a text string to the external trace reporting tool.

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 the SystemMgr.h file.
fmt A format string, as used in standard C-library calls such as printf. The format string has the following form:
% flags width type
... The list of variables to be formatted for output.

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

Table 8.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 8.3 shows the output types that you can use in the format specification for the tracing output functions.

Table 8.3 Trace function format specification types 

Flag

Description

%

Displays the '%' character.

s

Displays a null-terminated string value.

c

Displays a character value.

ld

Displays an Int32 value.

lu

Displays a UInt32 value.

lx or lX

Displays a UInt32 value in hexadecimal.

hd

Displays an Int16 value.

hu

Displays a UInt16 value.

hx or hX

Displays an Int16 or UInt16 value i hexadecimal.

Result
None.

HostTraceOutputTL ^TOP^

Purpose

Outputs a text string, followed by a newline, to the external trace reporting tool. This function performs the same operation as the HostTraceOutputT function, and adds the newline character.

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 the SystemMgr.h file.
fmt A format string, as used in standard C-library calls such as printf. For more information about the formatting specification, see the description of the HostTraceOutputT function.
... The list of variables to be formatted for output.
Result
None.

HostTraceOutputVT ^TOP^

Purpose

Outputs a text string to the external trace reporting tool.

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 the SystemMgr.h file.
fmt A format string, as used in standard C-library calls such as printf. For more information about the formatting specification, see the description of the HostTraceOutputT function.
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.
Result
None.

HostTraceOutputVTL ^TOP^

Purpose

Outputs a text string, followed by a newline, to the external trace reporting tool. This function performs the same operation as the HostTraceOutputVT function, and adds the newline character.

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 the SystemMgr.h file.
fmt A format string, as used in standard C-library calls such as printf. For more information about the formatting specification, see the description of the HostTraceOutputT function.
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.
Result
None.

HostTruncate ^TOP^

Purpose

Extends or truncates the file associated with the file handle to the length specified by the size.

Prototype

long HostTruncate(const char* filename, long 

filesize);
   

Parameters

filename The name of the file.
filesize The size of the file.
Result

Returns the value 0 if the file is successfully changed, or returns -1 if there was an error.

HostUTime ^TOP^

Purpose

Sets the modification time for a file.

Prototype

long HostUTime (const char* filename, 

HostUTimeType* buffer);
   

Parameters

filename The filename of the file.
buffer The stored time values.
Result

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

Reference Summary ^TOP^

The tables in this section summarize the host control API functions.

Host Control Database Functions ^TOP^

Table 8.4 Host Control Database Functions 

Function

Description

HostExportFile

Copies a database from the handheld to the desktop computer.

HostImportFile

Copies a database from the desktop computer to the handheld, and stores it on the specified card number. The database name on the handheld is the name stored in the file.

HostImportFileWithID

Copies a database from the desktop computer to the handheld, stores it on the specified card number, and returns the local ID of the installed database.

HostSaveScreen

Saves the LCD frame buffer to a file.

Host Control Directory Handler Functions ^TOP^

Table 8.5 Host Control Directory Handler Functions 

Function

Description

HostCloseDir

Closes a directory.

HostMkDir

Makes a directory.

HostOpenDir

Opens a directory.

HostReadDir

Reads a directory.

HostRmDir

Removes a directory.

Host Control Environment Functions ^TOP^

Table 8.6 Host Control Environment Functions 

Function

Description

HostGestalt

Currently does nothing except to return an "invalid selector" error.

HostGetHostID

Retrieves the ID of the debugging host. Palm OS Emulator always returns the value hostIDPalmOSEmulator.

HostGetHostPlatform

Retrieves the host platform ID.

HostGetHostVersion

Returns the version number of the debugging host.

HostIsCallingTrap

Returns a Boolean indicating whether the specified function selector is implemented on the debugging host.

HostIsSelectorImplemented

Returns a Boolean indicating whether the specified function selector is implemented on the debugging host.

Host Control File Chooser Support Functions ^TOP^

Table 8.7 Host Control File Chooser Support Functions 

Function

Description

HostGetDirectory

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

HostGetFile

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

HostPutFile

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

Host Control Gremlin Functions ^TOP^

Table 8.8 Host Control Gremlin Functions 

Function

Description

HostGremlinCounter

Returns the current count for the currently running gremlin.

HostGremlinIsRunning

Returns a Boolean value indicating whether a gremlin is currently running.

HostGremlinLimit

Returns the limit value of the currently running gremlin.

HostGremlinNew

Creates a new gremlin.

HostGremlinNumber

Returns the gremlin number of the currently running gremlin.

Host Control Debugging Functions ^TOP^

Table 8.9 Host Control Debugging Functions

Function

Description

HostDbgSetDataBreak

Sets a breakpoint for Emulator to enter an external debugger to display a message if the specified address range is accessed.

HostDbgClearDataBreak

Clears all data breakpoints that have been set by the HostDbgSetDataBreak function.

Host Control Logging Functions ^TOP^

Table 8.10 Host Control Logging Functions 

Function

Description

HostLogFile

Returns a reference to the file that Palm OS Emulator is using to log information.

HostSetLogFileSize

Modifies the size of the logging file.

Host Control Preference Functions ^TOP^

Table 8.11 Host Control Preference Functions 

Function

Description

HostGetPreference

Retrieves the value of a preference.

HostSetPreference

Sets a new value for a preference.

Host Control Profiling Functions ^TOP^

Table 8.12 Host Control Profiling Functions 

Function

Description

HostProfileCleanup

Releases the memory used for profiling and disables profiling.

HostProfileDetailFn

Profiles the function that contains the specified address.

HostProfileDump

Writes the current profiling information to the named file.

HostProfileGetCycles

Returns the current running CPU cycle count.

HostProfileInit

Initializes and enables profiling in the debugging host.

HostProfileStart

Turns profiling on.

HostProfileStop

Turns profiling off.

Host Control RPC Functions ^TOP^

Table 8.13 Host Control RPC Functions 

Function

Description

HostSessionClose

Closes the current emulation session

HostSessionCreate

Creates a new emulation session.

HostSessionOpen

Opens a previously saved emulation session.

HostSessionQuit

Asks Palm OS Emulator to quit.

HostSessionSave

Saves a session to a file with a specified name.

HostSignalResume

Resumes Palm OS Emulator after it has halted to wait for external scripts to handle a signal.

HostSignalSend

Sends a signal to external scripts.

HostSignalWait

Waits for Palm OS Emulator to send a signal.

Host Control Standard C Library Functions ^TOP^

Table 8.14 Host Control Standard C Library Functions 

Function

Description

HostErrNo

Returns the error number from the most recent host control API operation.

HostFClose

Closes a file on the desktop computer. Returns 0 if the operation was successful, and a non-zero value if not.

HostFEOF

Returns 0 if the specified file is at its end, and a non-zero value otherwise.

HostFError

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

HostFFlush

Flushes the buffer for the specified file.

HostFGetC

Returns the character at the current position in the specified file. Returns EOF to indicate an error.

HostFGetPos

Retrieves the current position in the specified file. Returns 0 if the operation was successful, and a non-zero value if not.

HostFGetS

Retrieves a character string from the selected file and returns a pointer to that string. Returns NULL to indicate an error.

HostFOpen

Opens a file on the desktop computer and returns a HostFILE pointer for that file. Returns NULL to indicate an error.

HostFPrintF

Writes a formatted string to a file, and returns the number of characters written.

HostFPutC

Writes a character to the specified file, and returns the character written. Returns EOF to indicate an error.

HostFPutS

Writes a string to the specified file, and returns a non-negative value to indicate success.

HostFRead

Reads a number of items from the file into a buffer. Returns the number of items that were actually read.

HostFree

Frees memory on the desktop computer.

HostFReopen

Associates a file stream with a different file.

HostFScanF

Scans a file for formatted input.

HostFSeek

Moves the file pointer to the specified position, and returns 0 to indicate success.

HostFSetPos

Sets the position indicator of the file, and returns 0 to indicate success.

HostFTell

Retrieves the current position of the specified file. Returns -1 to indicate an error.

HostFWrite

Writes data to a file, and returns the actual number of items written.

HostGetEnv

Retrieves the value of an environment variable.

HostMalloc

Allocates a memory block on the debugging host, and returns a pointer to the allocated memory. Returns NULL if there is not enough memory available.

HostRealloc

Reallocates space for the specified memory block.

HostRemove

Deletes a file.

HostRename

Renames a file.

HostTmpFile

Returns the temporary file used by the debugging host.

HostTmpNam

Creates a unique temporary file name.

Host Control Time Functions ^TOP^

Table 8.15 Host Control Time Functions 

Function

Description

HostAscTime

Returns a character string representation of the time.

HostClock

Returns an elapsed time.

HostCTime

Converts calendar time to a text representation.

HostGMTime

Returns time structure representation of the time expressed as Universal Time Coordinated (UTC). UTC was formerly Greenwich Mean Time (GMT).

HostLocalTime

Returns time structure representation of the time expressed as local time.

HostMkTime

Alters the parameter values to represent an equivalent encoded local time, but with the values of all members within their normal ranges.

HostStrFTime

Generates formatted text, under the control of the format parameter and the values stored in the time structure parameter.

HostTime

Returns the current calendar time.

HostUTime

Sets the modification time for a file.

Host Control Tracing Functions ^TOP^

Table 8.16 Host Control Tracing Functions 

Function

Description

HostTraceClose

Must be called when done logging trace information.

HostTraceInit

Must be called before logging any trace information.

HostTraceOutputT

Outputs text to the trace log using printf-style formatting.

HostTraceOutputTL

Outputs text to the trace log using printf-style formatting, and appends a newline character to the text.

HostTraceOutputVT

Outputs text to the trace log using vprintf-style formatting.

HostTraceOutputVTL

Outputs text to the trace log using vprintf-style formatting, and appends a newline character to the text.

HostTraceOutputB

Outputs a buffer of raw data to the trace log in hex dump format.