This chapter describes the host control API. The following topics are covered in this chapter:
- "About the Host Control API" - Conceptual information about the host control API.
- "Constants" - A list of the constants that can be used with the host control functions.
- "Data Types" - A list of the data types that can be used with the host control functions.
- "Functions" - A list of all host control functions, sorted alphabetically.
- "Reference Summary" - A summary of all host control functions, sorted by category.
About the Host Control API
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
This section lists the constants that you use with the host control API.
Host Error Constants
Several of the host control API functions return a HostErrType
value.
hostErrBase
An administrative value for the HostError class. This value is not returned to applications. 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.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.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
.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.hostErrTooManyFiles
The standard C library error code
EMFILE
and ENFILE
are mapped to this error constant.hostErrOpNotAvailable
The standard C library error codes
ENOSYS
and ENODEV
are 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
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
The HostGetHostID function uses a Host ID value to specify the debugging host type.
hostIDPalmOSSimulator
Returned for both Palm OS Simulator and the Macintosh Palm Simulator application.
Host Platform Constants
The HostGetHostPlatform function uses a HostPlatform
value to specify operating system hosting the emulation.
Host Signal Constants
This section describes the host signal values, which you can use with the HostSendSignal.
Data Types
This section describes the data types that you use with the host control API.
HostBoolType
The host control API defines HostBoolType
for use as a Boolean value.
HostClockType
The host control API defines HostClockType
as a platform-independent representation of the standard C library clock_t
type.
HostDirEntType
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.
HostDIRType
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.
HostFILEType
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.
HostGremlinInfoType
The host control API defines the HostGremlinInfoType
structure type to store information about a horde of gremlins.
HostGremlinInfo Fields
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
The host control API defines HostIDType
for use as an identifier value.
HostPlatformType
The host control API defines HostPlatformType
for use as a platform identifier value.
HostSignalType
The host control API defines HostSignalType
for use in signal functions.
HostSizeType
The host control API defines HostSizeType
as a platform-independent version of the standard C library size_t
type.
HostStatType
The host control API defines HostStatType
for status information about files.
HostStatType Fields
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.HostTimeType
The host control API defines HostTimeType
as a platform-independent version of the standard C library time_t
type.
HostTmType
The host control API defines HostTmType
for use in time functions.
HostTmType Fields
HostUTimeType
The host control API defines HostUTimeTypefor use in time functions.
HostUTimeType Fields
Functions
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
Purpose
Returns a character string representation of the time encoded in time
.
Prototype
char* HostAscTime(const HostTmType* time);
Parameters
HostClock
Purpose
Prototype
HostClockType HostClock(void);
Parameters
HostCloseDir
Purpose
Prototype
long HostCloseDir(HostDIRType* directory);
Parameters
HostCTime
Purpose
Converts the calendar time in *timeofday
to a text representation.
Prototype
char* HostCTime(const HostTimeType* timeofday)
Parameters
Purpose
Clears all data breakpoints that have been set by the HostDbgSetDataBreak
function.
Prototype
HostErr HostDbgClearDataBreak (void)
Parameters
Returns 0
if the operation was successful, and a non-zero value if not.
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
HostErrNo
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
HostExportFile
Purpose
Copies a database from the handheld to the desktop computer.
Prototype
HostErr HostExportFile(const char* fileName, long cardNum, const char* dbName);
Parameters
HostFClose
Purpose
Closes a file on the desktop computer.
Prototype
long HostFClose(HostFILE* f);
Parameters
HostFEOF
Purpose
Determines if the specified file is at its end.
Prototype
long HostFEOF(HostFILE* f);
Parameters
HostFError
Purpose
Retrieves the error code from the most recent operation on the specified file.
Prototype
long HostFError(HostFILE* f);
Parameters
0
if no errors have occurred on the file.HostFFlush
Purpose
Flushes the buffer for the specified file.
Prototype
long HostFFlush(HostFILE* f);
Parameters
HostFGetC
Purpose
Retrieves the character at the current position in the specified file.
Prototype
long HostFGetC(HostFILE* f);
Parameters
HostFGetPos
Purpose
Retrieves the current position in the specified file.
Prototype
long HostFGetPos(HostFILE* f, long* posn);
Parameters
HostFGetS
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
HostFOpen
Purpose
Opens a file on the desktop computer.
Prototype
HostFILE* HostFOpen(const char* name, const char* mode);
Parameters
HostFPrintF
Purpose
Writes a formatted string to a file.
Prototype
long HostFPrintF(HostFILE* f, const char* format, ...);
Parameters
HostFPutC
Purpose
Writes a character to the specified file.
Prototype
long HostFPutC(long c, HostFILE* f);
Parameters
HostFPutS
Purpose
Writes a string to the specified file.
Prototype
long HostFPutS(const char* s, HostFILE* f);
Parameters
HostFRead
Purpose
Reads a number of items from the file into a buffer.
Prototype
long HostFRead(void* buffer, long size, long count, HostFILE* f);
Parameters
HostFree
Purpose
Frees memory on the desktop computer.
Prototype
void HostFree(void* p);
Parameters
HostFReopen
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
HostFScanF
Purpose
Reads formatted text from a file.
Prototype
long HostFReopen(HostFILE* f, const char *fmt, ...);
Parameters
Returns EOF
if end of file was reached while scanning.
HostFSeek
Purpose
Moves the file pointer to the specified position.
Prototype
long HostFSeek(HostFILE* f, long offset, long origin);
Parameters
offset
The number of bytes to move from the initial position, which is specified in the origin
parameter.HostFSetPos
Purpose
Sets the position indicator of the file.
Prototype
long HostFSetPos(HostFILE* f, long posn);
Parameters
HostFTell
Purpose
Retrieves the current position of the specified file.
Prototype
long HostFTell(HostFILE* f);
Parameters
HostFWrite
Purpose
Prototype
long HostFWrite(const void* buffer, long size, long count, HostFILE* f);
Parameters
HostGestalt
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
HostGetDirectory
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
Returns the directory as a character string.
HostGetEnv
Purpose
Retrieves the value of an environment variable.
Prototype
char* HostGetEnv(char* varName);
Parameters
HostGetFile
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
Returns the file as a character string.
HostGetFileAttr
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.The file attribute flags match the EmFileAttr flags:
enum { hostFileAttrReadOnly = 1, hostFileAttrHidden = 2, hostFileAttrSystem = 4HostGetHostID
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
HostGetHostPlatform
Purpose
Retrieves the host platform ID, which is one of the values described in Host Platform Constants.
Prototype
HostPlatform HostGetHostPlatform(void);
Parameters
HostGetHostVersion
Purpose
Retrieves the version number of the debugging host.
Prototype
long HostGetHostVersion(void);
Parameters
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:
HostGetPreference
Purpose
Retrieves the specified preference value.
Prototype
HostBool HostGetPreference(const char* prefName, char* prefValue);
Parameters
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
See Also
The HostSetPreference function.
HostGMTime
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
HostGremlinCounter
Purpose
Returns the current event count of the currently running gremlin.
Prototype
long HostGremlinCounter(void);
Parameters
Comments
This return value of this function is only valid if a gremlin is currently running.
HostGremlinIsRunning
Purpose
Determines if a gremlin is currently running.
Prototype
HostBool HostGremlinIsRunning(void);
Parameters
HostGremlinLimit
Purpose
Retrieves the limit value of the currently running gremlin.
Prototype
long HostGremlinLimit(void);
Parameters
Comments
This return value of this function is only valid if a gremlin is currently running.
HostGremlinNew
Purpose
Prototype
HostErr HostGremlinNew( const HostGremlinInfo* info);
Parameters
HostGremlinNumber
Purpose
Retrieves the number of the currently running gremlin.
Prototype
long HostGremlinNumber(void);
Parameters
Comments
This return value of this function is only valid if a gremlin is currently running.
HostImportFile
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
cardNum
The card number on which the database is to be installed. You almost always use 0
to specify the built-in RAM. 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
cardNum
The card number on which the database is to be installed. You almost always use 0
to specify the built-in RAM. Returns 0
if the operation was successful, and a non-zero value if not.
HostIsCallingTrap
Purpose
Determines if Palm OS Emulator is currently calling a trap.
Prototype
HostBool HostIsCallingTrap(void);
Parameters
HostIsSelectorImplemented
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.HostLocalTime
Purpose
Returns time structure representation of the time, expressed as local time.
Prototype
HostTmType* HostLocalTime(const HostTimeType* time);
Parameters
HostLogFile
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
A pointer to the log file, or NULL
if not successful.
HostMalloc
Purpose
Allocates a memory block on the debugging host.
Prototype
void* HostMalloc(long size);
Parameters
HostMkDir
Purpose
Prototype
long HostMkDir(const char* directory);
Parameters
Returns 0
if the operation was successful, and a non-zero value if not.
HostMkTime
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
HostOpenDir
Purpose
Prototype
HostDIRType* HostOpenDir(const char* directory);
Parameters
Returns a directory structure.
HostProfileCleanup
Purpose
Releases the memory used for profiling and disables profiling.
Prototype
HostErr HostProfileCleanup(void);
Parameters
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
Purpose
Profiles the function that contains the specified address.
Prototype
HostErr HostProfileDetailFn(void* addr, HostBool logDetails);
Parameters
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.Comments
This function is available only in the profiling version of the emulator.
See Also
The HostProfileInit, HostProfileStart, HostProfileStop, HostProfileDump, and HostProfileCleanup functions.
HostProfileDump
Purpose
Writes the current profiling information to the named file.
Prototype
HostErr HostProfileDump(const char* filename);
Parameters
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
Purpose
Returns the current running CPU cycle count.
Prototype
long HostProfileGetCycles(void)
Parameters
Comments
This function is available only in the profiling version of the emulator.
See Also
The HostProfileInit, HostProfileStart, HostProfileStop, HostProfileDump, and HostProfileCleanup functions.
HostProfileInit
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.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:
- HostProfileInit - All profiling starts with the HostProfileInit function, which initializes and enables profiling.
- HostProfileStart - This function turns profiling on.
- 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.
- 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.
- HostProfileCleanup - This function releases the memory used for profiling and disables profiling.
See Also
The HostProfileStart, HostProfileStop, HostProfileDump, and HostProfileCleanup functions.
HostProfileStart
Purpose
Prototype
HostErr HostProfileStart(void);
Parameters
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
Purpose
Prototype
HostErr HostProfileStop(void);
Parameters
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
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
Returns the file name as a character string.
HostReadDir
Purpose
Prototype
HostDirEntType* HostReadDir(HostDIRType*
directory);
Parameters
Returns a character array for the directory.
HostRealloc
Purpose
Reallocates space for the specified memory block.
Prototype
void* HostRealloc(void* ptr, long size);
Parameters
HostRemove
Purpose
Prototype
long HostRemove(const char* name);
Parameters
HostRename
Purpose
Prototype
long HostRemove(const char* oldName, const char* newName);
Parameters
HostRmDir
Purpose
Prototype
long HostRmDir(const char* directory);
Parameters
Returns 0
if the operation was successful, and a non-zero value if not.
HostSaveScreen
Purpose
Saves the LCD frame buffer to the given file name.
Prototype
HostErrType HostSaveScreen(const char* fileName)
Parameters
HostSessionClose
Purpose
Closes the current emulation session.
Prototype
HostErr HostSessionClose(const char* psfFileName);
Parameters
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
Purpose
Creates a new emulation session.
Prototype
HostErr HostSessionCreate(const char* device, long ramSize, const char* romPath);
Parameters
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
Purpose
Opens a previously saved emulation session.
Prototype
HostErr HostSessionOpen(const char* psfFileName);
Parameters
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
Purpose
Asks Palm OS Emulator to quit. Returns an error if a session is already running.
Prototype
HostErr HostSessionQuit(void);
Parameters
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.
Purpose
Saves a session to a file with the specified name.
Prototype
HostBoolType HostSessionSave(const char* saveFileName);
Parameters
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
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.The file attribute flags match the EmFileAttr flags:
enum { hostFileAttrReadOnly = 1, hostFileAttrHidden = 2, hostFileAttrSystem = 4 }HostSetLogFileSize
Purpose
Determines the size of the logging file that Palm OS Emulator is using.
Prototype
void HostSetLogFileSize(long size);
Parameters
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
Purpose
Sets the specified preference value.
Prototype
void HostSetPreference(const char* prefName, const char* prefValue);
Parameters
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
Purpose
Restarts Palm OS Emulator after it has issued a signal.
Prototype
HostErr HostSignalResume(void);
Parameters
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
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.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.
-
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
Purpose
Waits for a signal from Palm OS Emulator, and returns the signalled value.
Prototype
HostErr HostSignalWait(long timeout, HostSignal* signalNumber);
Parameters
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.
-
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
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. slotNo
. This function is provided in support of Expansion Manager emulation. Comments
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
Purpose
Returns the number of Virtual File System cards that Emulator is emulating.
Prototype
long HostSlotMax(void)
Parameters
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
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.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
Purpose
Returns status information about a file.
Prototype
long HostStat(const char* filename, HostStatType*
buffer);
Parameters
Returns 0
if the operation was successful, and a non-zero value if not.
HostStrFTime
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
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
Purpose
Returns the current calendar time.
Prototype
HostTimeType HostTime(HostTimeType* time);
Parameters
Returns the current calendar time if the operation is successful, and returns -1 if not.
HostTmpFile
Purpose
Returns the temporary file used by the debugging host.
Prototype
HostFILE* HostTmpFile(void);
Parameters
HostTmpNam
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.HostTraceClose
Purpose
Closes the connection to the external trace reporting tool.
Prototype
void HostTraceClose(void);
Parameters
HostTraceInit
Purpose
Initiates a connection to the external trace reporting tool.
Prototype
void HostTraceInit(void);
Parameters
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.
HostTraceOutputB
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.HostTraceOutputT
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: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
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
HostTraceOutputTL
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.HostTraceOutputVT
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
.HostTraceOutputVTL
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
.HostTruncate
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
Returns the value 0 if the file is successfully changed, or returns -1 if there was an error.
HostUTime
Purpose
Sets the modification time for a file.
Prototype
long HostUTime (const char* filename, HostUTimeType* buffer);
Parameters
Returns 0 if the file-modification time was successfully changed, or returns -1 if there was an error.
Reference Summary
The tables in this section summarize the host control API functions.
Host Control Database Functions
Table 8.4 Host Control Database Functions
Host Control Directory Handler Functions
Table 8.5 Host Control Directory Handler Functions
Host Control Environment Functions
Table 8.6 Host Control Environment Functions
Host Control File Chooser Support Functions
Table 8.7 Host Control File Chooser Support Functions
Host Control Gremlin Functions
Table 8.8 Host Control Gremlin Functions
Returns the current count for the currently running gremlin. |
|
Returns a Boolean value indicating whether a gremlin is currently running. |
|
Returns the gremlin number of the currently running gremlin. |
Host Control Debugging Functions
Table 8.9 Host Control Debugging Functions
Host Control Logging Functions
Table 8.10 Host Control Logging Functions
Host Control Preference Functions
Table 8.11 Host Control Preference Functions
Host Control Profiling Functions
Table 8.12 Host Control Profiling Functions
Host Control RPC Functions
Table 8.13 Host Control RPC Functions
Host Control Standard C Library Functions
Table 8.14 Host Control Standard C Library Functions
Host Control Time Functions
Table 8.15 Host Control Time Functions
Host Control Tracing Functions
Table 8.16 Host Control Tracing Functions