Contents > Library Reference > System |
System
Functions for retrieving and manipulating system status, dynamic memory, dates, and the clipboard.
Objects and Structures
Date | Encapsulates date and time operations. | |
Preferences | Stores and retrieves application preferences. | |
Serial | Serial I/O and raw IR support. | |
SerialStream | Exposes a Serial object as a Stream. | |
Stream | Base object for a Stream. | |
ISerializable | Interface for an object that can be serialized. |
Functions
void events(bool blocking) | Processes all pending events, calling user provided event handlers, returning when the queue is empty. If blocking is true and no events are in the queue, the function will not return until an event is processed. If an appStopEvent is received, the app's onstop handler is called but this function never returns. This function should be called during long calculations to allow the user interface to respond (for example, allowing the user to cancel). | |
void fatal(string str) | Displays a runtime error message containing the specified text and information about the current function. When the error message is dismissed, the app exits. This function does not return. | |
string callstack() | Creates a string containing a list of functions in the current callstack, one per line. | |
void debuglog(string str) | Writes the text as a line to the debug log. See Debug support for details. This is not a real function, as no code is generated unless the project is compiled with the debug property set. | |
void assert(bool expr) | When expr is false, displays an error message containing the text of the expression and a call stack. See Debug support for details. This is not a real function, as no code is generated unless the project is compiled with the debug property set. | |
int ticks() | Returns the number of clock ticks since the device was last reset. | |
int tickspersec() | Returns the number of clock ticks that occur each second. | |
void resetaot() | Reset the device's auto off timer. If the device goes without input for a short time, it will turn itself off. To prevent this, periodically call this function. | |
void sleep(int ms) | Causes the app to sleep for ms milliseconds. While sleeping, the CPU will be put into low power mode, but the user will not be able to interact with the device (including turning it off). | |
void launch(string creatorid) | Launch the app with the given 4 character creator id. This function will post a message to quit the current app if the specified app is found. However, it will return and allow the current app to process its queued events. | |
void launchGoto(string creatorid, string database, int recId, int searchStrLen, int matchPos, int matchField, int matchCustom) | Launch the app with the given 4 character creator id using the system defined sysAppLaunchCmdGoTo launch code. The other parameters refer to fields in the system defined GoToParamsType structure. Different applications use the GoToParamsType differently, and not all field may be required/used by all applications. This function will post a message to quit the current app if the specified app is found. However, it will return and allow the current app to process its queued events. | |
void launchCustomString(string creatorid, int code, string param) | Launch the app with the given 4 character creator id passing a custom launch code and a pointer to the specified string param. Only use this function if the app you are launching supports a char* launch parameter. This function will post a message to quit the current app if the specified app is found. However, it will return and allow the current app to process its queued events. | |
string username() | Returns the HotSync username associated with the device. | |
string serialnum() | Returns the string representation of the device's serial number, or the empty string if it does not have one. | |
int osver() | Returns the integer version of the OS, using the standard Palm OS version specification - 32-bit number with the high 8 bits being the major version, the the next 8 bits being the minor version, and the remaining bits representing the fix number, build number, and build type. | |
string osvers() | Returns the string representation of the OS version. | |
int orbver() | Returns the OrbC runtime version the current app is using - 16-bit number with the high 8 bits being the major version, and the low 8 bits being the minor version. | |
string getclip() | Returns the contents of the clipboard if it currently contains text, otherwise it returns the empty string. | |
void setclip(string text) | Copys text to the clipboard. | |
void memcpy(void* pDest, void* pSrc, int len) | Copies len values from pSrc to pDst. The data types at the destination must be the same as the source, or the application's behavior will be unpredictable. | |
void* malloct(string type, int count) | Allocates count blocks of memory, initializing the memory elements to the types specified by the type string type. | |
void free(void* ptr) | Releases the memory allocated by calling malloct. | |
int freemem() | Returns the amount of free dynamic memory. Because the OrbC runtime has some overhead, this value cannot be used to make any direct calculations about how much memory can be allocated. | |
int battery(bool volts) | Returns the requested battery status - voltage or percent remaining. |
Contents > Library Reference > System > Date object |
Date
A Date object encapsulates date and time operations. The Palm OS stores time as a count of the seconds since January 1st, 1904, so the OrbC Date object does the same.
Object Properties
int secs | Gets or sets the seconds since January 1st, 1904. | |
int year | Gets or sets the year | |
int month | Gets or sets the month. January = 1, December = 12. | |
int day | Gets or sets the day. First day of the month is 1. | |
int hour | Gets or sets the hour. Valid range is 0-23. | |
int min | Gets or sets the minute. Valid range is 0-59. | |
int sec | Gets or sets the second. Valid range is 0-59. | |
int weekday | Gets the day of week, with 0 being Sunday. | |
int ymd | Gets or sets the date as an integer in yyyymmdd format, such as 20000527 for May 27th, 2000. |
Object Methods
void now() | Sets the date object to the current date and time. | |
bool selectdate(int selby, string title) | Displays the system date selector dialog, using the mode specified by selby, using title as the dialog title. If the user selects a date, true is returned; if the user cancels, false is returned. | |
bool selecttime(string title) | Displays the system time selector dialog, using title as the dialog title. If the user selects a time, true is returned; if the user cancels, false is returned. Available only on OS v3.1 and higher. | |
void addsecs(int s) | Adds s seconds to the date object. | |
void adddays(int days) | Adds d days to the date object. | |
void subsecs(int s) | Subtracts s seconds from the date object. | |
void subdays(int days) | Subtracts d days from the date object. | |
int diffsecs(Date d) | Returns the difference of this date and d. If d is before this date, the result will be positive. | |
int diffdays(Date d) | Returns the difference of this date and d. If d is before this date, the result will be positive. | |
string time() | Returns the string representation of the time in the format specified by the system preferences. | |
string date() | Returns the short string representation of the date in the format specified by the system preferences. | |
string ldate() | Returns the long string representation of the date in the format specified by the system preferences. |
Contents > Library Reference > System > Preferences object |
Preferences
The Preferences object is used to store and retrieve application preferences. There are two types of preferences - saved and unsaved. Saved preferences are backed up to the desktop during a HotSync operation.
Object Methods
bool get(string creatorid, bool saved, void* pdata, string type, int count) | Load the preference associated with creatorid into the memory pointed to by pdata. The memory must be in a format compatible with that specified by the type string type. The format is repeated count. If the preference does not exist, or is shorter than requested, this method returns false. | |
bool set(string creatorid, bool saved, void* pdata, string type, int count) | Save the data pointed to by pdata into the saved or unsaved preference associated with creatorid using the format specified by type. The format is repeated count. This method returns true if successful. | |
void del(string creatorid, bool saved) | Delete the preference, saved or unsaved, associated with the app creatorid. |
Contents > Library Reference > System > Serial object |
Serial
The Serial object implements serial I/O, raw IR, IrComm, and RfComm, (depending on which port is opened). The Serial object is implemented using the New Serial Manager which is only available on OS 3.3 and higher.
The Serial object is implemented in the OrbSerial native add-in. To use it, you must #include "OrbSerial.oc". The source code is available in the samples directory.
Object Properties
int error | Gets the current set of line error bits. Call clearerr() to clear.
Possible bits are serErrorParity , serErrorHWOverrun ,
serErrorFraming , serErrorBreak , serErrorHShake ,
serErrorSWOverrun , serErrorCarrierLost .
|
|
int status | Gets the current set of status bits. Possible bits are
serStatusCTS , serStatusRTS ,
serStatusDSR , serStatusBreak .
|
Object Methods
bool open(int port, int baud) | Open the specified port at the specified baud rate, using default settings (1 stop bit, 8 bits per char, parity off, RTS receive flow control). | |
void close() | Closes the open port. | |
void settings(int charbits, int stopbits, int parity, char flowctl, int ctstimeout) | Apply the given settings to the open port. | |
bool setbuffer(int size) | Allocates a new receive buffer of the specified size. The default buffer is 512 bytes, so most applications will not need to enlarge it. | |
void clearerr() | Clears all pending line errors. This method must be called if a line error occurs before further sending and receiving can be done. | |
bool send(void* pdata, string type, int count) | Sends count blocks of data over the port from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. | |
bool recv(void* pdata, string type, int count, int timeout) | Attempts to receive count blocks of data from the port into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. timeout is the number of ticks to wait for the data. | |
bool sendb(char byte) | Sends the given byte over the port. | |
bool recvb(char* pbyte) | Recieves one byte from the port, waiting up to one second to receive it. If successful, the received byte is stored in the char pointed to by pbyte. | |
int sendcheck() | Retrieves the number of bytes remaining to be sent. | |
int recvcheck() | Retrieves the number of bytes in the recieve buffer. | |
bool sendwait() | Waits for all pending data to be sent. | |
bool recvwait(int bytes, int timeout) | Waits for the specified number of bytes to be received into the receive buffer, waiting up to timeout ticks. Returns when the data is received or the timeout is reached. | |
void sendflush() | Flushes all pending send data. | |
void recvflush(int timeout) | Flushes all data from the recieve buffer, and waits until timeout ticks have passed with no new data received. |
Contents > Library Reference > System > SerialStream object |
SerialStream
The SerialStream is derived from Stream, providing read/write access to the serial port. To use this object, create and open a Serial object, assign it to the serial property, then call the read and write methods on Stream.
Object Properties
Serial serial | Sets the Serial object that this stream should read/write to. |
Object Methods
bool read(void* pdata, string type, int count) | Reads count blocks of data from the stream into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. | |
bool write(void* pdata, string type, int count) | Writes count blocks of data to the stream from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. | |
bool readInt(int* pi) | Read an int from the stream into the memory pointed to by pi. | |
bool writeInt(int i) | Write an int to the stream. | |
bool readWord(int* pw) | Read an 2-byte word from the stream into the memory pointed to by pw. | |
bool writeWord(int w) | Write a 2-byte word to the stream. | |
bool readFloat(float* pf) | Read a float from the stream into the memory pointed to by pf. | |
bool writeFloat(float f) | Write a float to the stream. | |
bool readString(string* ps) | Read a string from the stream into the memory pointed to by ps. | |
bool writeString(string s) | Write a string to the stream. | |
bool readChar(char* pc) | Read a char from the stream into the memory pointed to by pc. | |
bool writeChar(char c) | Write a char to the stream. |
Contents > Library Reference > System > Stream object |
Stream
The Stream object provides a common set of methods for reading and writing data. The Stream object is a base object for specialized implementations, so you should never create an instance of this object. Instead, create an instance of the desired derived object.
Object Methods
bool read(void* pdata, string type, int count) | Reads count blocks of data from the stream into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. | |
bool write(void* pdata, string type, int count) | Writes count blocks of data to the stream from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. | |
bool readInt(int* pi) | Read an int from the stream into the memory pointed to by pi. | |
bool writeInt(int i) | Write an int to the stream. | |
bool readWord(int* pw) | Read an 2-byte word from the stream into the memory pointed to by pw. | |
bool writeWord(int w) | Write a 2-byte word to the stream. | |
bool readFloat(float* pf) | Read a float from the stream into the memory pointed to by pf. | |
bool writeFloat(float f) | Write a float to the stream. | |
bool readString(string* ps) | Read a string from the stream into the memory pointed to by ps. | |
bool writeString(string s) | Write a string to the stream. | |
bool readChar(char* pc) | Read a char from the stream into the memory pointed to by pc. | |
bool writeChar(char c) | Write a char to the stream. |
Contents > Library Reference > System > ISerializable object |
ISerializable
The ISerializable interface can be implemented by any object which can be written to and read from a Stream.
Object Methods
bool serialize(Stream* stream) | This method should write all of the important data of the implementing object to the stream. | |
bool deserialize(Stream* stream) | This method should read all of the important data of the implementing object to the stream. |
Contents > Library Reference > System > Date object > now |
Date.now
void now() |
Sets the date object to the current date and time.
Contents > Library Reference > System > Date object > selectdate |
Date.selectdate
bool selectdate(int selby, string title) |
Parameters:
selby | select by mode | |
title | dialog title |
Return value: user selected something
Displays the system date selector dialog, using the mode specified by selby, using title as the dialog title. If the user selects a date, true is returned; if the user cancels, false is returned.
Note: Available selection modes are dateDayByDay, dateDayByWeek, dateDayByMonth.Contents > Library Reference > System > Date object > selecttime |
Date.selecttime
bool selecttime(string title) |
Parameters:
title | dialog title |
Return value: user selected something
Displays the system time selector dialog, using title as the dialog title. If the user selects a time, true is returned; if the user cancels, false is returned. Available only on OS v3.1 and higher.
Contents > Library Reference > System > Date object > addsecs |
Date.addsecs
void addsecs(int s) |
Parameters:
s | seconds |
Adds s seconds to the date object.
Contents > Library Reference > System > Date object > adddays |
Date.adddays
void adddays(int days) |
Parameters:
days | days |
Adds d days to the date object.
Contents > Library Reference > System > Date object > subsecs |
Date.subsecs
void subsecs(int s) |
Parameters:
s | seconds |
Subtracts s seconds from the date object.
Contents > Library Reference > System > Date object > subdays |
Date.subdays
void subdays(int days) |
Parameters:
days | days |
Subtracts d days from the date object.
Contents > Library Reference > System > Date object > diffsecs |
Date.diffsecs
int diffsecs(Date d) |
Parameters:
d | end date |
Return value: difference in seconds
Returns the difference of this date and d. If d is before this date, the result will be positive.
Contents > Library Reference > System > Date object > diffdays |
Date.diffdays
int diffdays(Date d) |
Parameters:
d | end date |
Return value: difference in days
Returns the difference of this date and d. If d is before this date, the result will be positive.
Contents > Library Reference > System > Date object > time |
Date.time
string time() |
Return value: string represention of the time
Returns the string representation of the time in the format specified by the system preferences.
Contents > Library Reference > System > Date object > date |
Date.date
string date() |
Return value: string representation of the date
Returns the short string representation of the date in the format specified by the system preferences.
Contents > Library Reference > System > Date object > ldate |
Date.ldate
string ldate() |
Return value: string representation of the date
Returns the long string representation of the date in the format specified by the system preferences.
Contents > Library Reference > System > Preferences object > get |
Preferences.get
bool get(string creatorid, bool saved, void* pdata, string type, int count) |
Parameters:
creatorid | creator id | |
saved | true for saved preferences, false for unsaved | |
pdata | data pointer | |
type | format string | |
count | format count |
Return value: true if successful, false otherwise
Load the preference associated with creatorid into the memory pointed to by pdata. The memory must be in a format compatible with that specified by the type string type. The format is repeated count. If the preference does not exist, or is shorter than requested, this method returns false.
Example:
Load the array 'people' from the saved preferences of "MyAp".
struct Person { string name; int age; }; Person people[2]; bool LoadPrefs() { Preferences prefs; return prefs.get("MyAp", true, people, typeof(Person), 2); } |
Contents > Library Reference > System > Preferences object > set |
Preferences.set
bool set(string creatorid, bool saved, void* pdata, string type, int count) |
Parameters:
creatorid | creator id | |
saved | true for saved preferences, false for unsaved | |
pdata | data pointer | |
type | format string | |
count | format count |
Return value: true if successful, false otherwise
Save the data pointed to by pdata into the saved or unsaved preference associated with creatorid using the format specified by type. The format is repeated count. This method returns true if successful.
Example:
Save the array 'people' into the saved preferences of "MyAp".
struct Person { string name; int age; }; Person people[2]; bool SavePrefs() { Preferences prefs; people[0].name = "Jeremy"; people[0].age = 26; people[1].name = "Hudson"; people[1].age = 7; // in dog years return prefs.set("MyAp", true, people, typeof(Person), 2); } |
Contents > Library Reference > System > Preferences object > del |
Preferences.del
void del(string creatorid, bool saved) |
Parameters:
creatorid | creator id | |
saved | true for saved preferences, false for unsaved |
Delete the preference, saved or unsaved, associated with the app creatorid.
Contents > Library Reference > System > Serial object > open |
Serial.open
bool open(int port, int baud) |
Parameters:
port | port number | |
baud | baud rate |
Return value: true if the port was opened successfully.
Open the specified port at the specified baud rate, using default settings (1 stop bit, 8 bits per char, parity off, RTS receive flow control).
Note: Possible port values are serCradlePort, serIRPort (raw IR - does not work on devices with OMAP processor), serIrComm (works on most current devices), and serRfComm (bluetooth).Contents > Library Reference > System > Serial object > close |
Serial.close
void close() |
Closes the open port.
Contents > Library Reference > System > Serial object > settings |
Serial.settings
void settings(int charbits, int stopbits, int parity, char flowctl, int ctstimeout) |
Parameters:
charbits | bits per char | |
stopbits | stop bits | |
parity | parity setting (0=off, 1=on, 2=even) | |
flowctl | flow control ('r'=RTS, 'c'=CTS, 'h'=RTS+CTR, 'x'=XonXoff, 'n'=none) | |
ctstimeout | inter-byte timeout |
Apply the given settings to the open port.
Contents > Library Reference > System > Serial object > setbuffer |
Serial.setbuffer
bool setbuffer(int size) |
Parameters:
size | size of buffer to allocate |
Return value: true if the buffer was allocated successfully.
Allocates a new receive buffer of the specified size. The default buffer is 512 bytes, so most applications will not need to enlarge it.
Contents > Library Reference > System > Serial object > clearerr |
Serial.clearerr
void clearerr() |
Clears all pending line errors. This method must be called if a line error occurs before further sending and receiving can be done.
Contents > Library Reference > System > Serial object > send |
Serial.send
bool send(void* pdata, string type, int count) |
Parameters:
pdata | data pointer | |
type | format string | |
count | format count |
Return value: true if all data was sent without error
Sends count blocks of data over the port from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.
Contents > Library Reference > System > Serial object > recv |
Serial.recv
bool recv(void* pdata, string type, int count, int timeout) |
Parameters:
pdata | data pointer | |
type | format string | |
count | format count | |
timeout | timeout in ticks |
Return value: true if all data was received without error
Attempts to receive count blocks of data from the port into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. timeout is the number of ticks to wait for the data.
Note: If the return value is false, but the no line error occured (error property is 0), then the request timed out.Contents > Library Reference > System > Serial object > sendb |
Serial.sendb
bool sendb(char byte) |
Parameters:
byte | byte to send |
Return value: true if the data was sent without error
Sends the given byte over the port.
Contents > Library Reference > System > Serial object > recvb |
Serial.recvb
bool recvb(char* pbyte) |
Parameters:
pbyte | pointer to byte receive |
Return value: true if the data was received without error
Recieves one byte from the port, waiting up to one second to receive it. If successful, the received byte is stored in the char pointed to by pbyte.
Contents > Library Reference > System > Serial object > sendcheck |
Serial.sendcheck
int sendcheck() |
Return value: Bytes remaining to be sent
Retrieves the number of bytes remaining to be sent.
Contents > Library Reference > System > Serial object > recvcheck |
Serial.recvcheck
int recvcheck() |
Return value: Bytes in the receive buffer
Retrieves the number of bytes in the recieve buffer.
Contents > Library Reference > System > Serial object > sendwait |
Serial.sendwait
bool sendwait() |
Return value: true if no error occured
Waits for all pending data to be sent.
Contents > Library Reference > System > Serial object > recvwait |
Serial.recvwait
bool recvwait(int bytes, int timeout) |
Parameters:
bytes | number of bytes to wait for | |
timeout | timeout in ticks |
Return value: true if no error or timeout occured
Waits for the specified number of bytes to be received into the receive buffer, waiting up to timeout ticks. Returns when the data is received or the timeout is reached.
Contents > Library Reference > System > Serial object > sendflush |
Serial.sendflush
void sendflush() |
Flushes all pending send data.
Contents > Library Reference > System > Serial object > recvflush |
Serial.recvflush
void recvflush(int timeout) |
Parameters:
timeout | inter-byte timeout |
Flushes all data from the recieve buffer, and waits until timeout ticks have passed with no new data received.
Contents > Library Reference > System > SerialStream object > read |
SerialStream.read
bool read(void* pdata, string type, int count) |
Parameters:
pdata | data pointer | |
type | format string | |
count | format count |
Return value: true if all the data was read
Reads count blocks of data from the stream into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.
Contents > Library Reference > System > SerialStream object > write |
SerialStream.write
bool write(void* pdata, string type, int count) |
Parameters:
pdata | data pointer | |
type | format string | |
count | format count |
Return value: true if all the data was written
Writes count blocks of data to the stream from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.
Contents > Library Reference > System > SerialStream object > readInt |
SerialStream.readInt
bool readInt(int* pi) |
Parameters:
pi | int pointer |
Return value: true if successful
Read an int from the stream into the memory pointed to by pi.
Contents > Library Reference > System > SerialStream object > writeInt |
SerialStream.writeInt
bool writeInt(int i) |
Parameters:
i | int to write |
Return value: true if successful
Write an int to the stream.
Contents > Library Reference > System > SerialStream object > readWord |
SerialStream.readWord
bool readWord(int* pw) |
Parameters:
pw | int pointer |
Return value: true if successful
Read an 2-byte word from the stream into the memory pointed to by pw.
Contents > Library Reference > System > SerialStream object > writeWord |
SerialStream.writeWord
bool writeWord(int w) |
Parameters:
w | word to write |
Return value: true if successful
Write a 2-byte word to the stream.
Contents > Library Reference > System > SerialStream object > readFloat |
SerialStream.readFloat
bool readFloat(float* pf) |
Parameters:
pf | float pointer |
Return value: true if successful
Read a float from the stream into the memory pointed to by pf.
Contents > Library Reference > System > SerialStream object > writeFloat |
SerialStream.writeFloat
bool writeFloat(float f) |
Parameters:
f | float to write |
Return value: true if successful
Write a float to the stream.
Contents > Library Reference > System > SerialStream object > readString |
SerialStream.readString
bool readString(string* ps) |
Parameters:
ps | string pointer |
Return value: true if successful
Read a string from the stream into the memory pointed to by ps.
Contents > Library Reference > System > SerialStream object > writeString |
SerialStream.writeString
bool writeString(string s) |
Parameters:
s | string to write |
Return value: true if successful
Write a string to the stream.
Contents > Library Reference > System > SerialStream object > readChar |
SerialStream.readChar
bool readChar(char* pc) |
Parameters:
pc | char pointer |
Return value: true if successful
Read a char from the stream into the memory pointed to by pc.
Contents > Library Reference > System > SerialStream object > writeChar |
SerialStream.writeChar
bool writeChar(char c) |
Parameters:
c | char to write |
Return value: true if successful
Write a char to the stream.
Contents > Library Reference > System > Stream object > read |
Stream.read
bool read(void* pdata, string type, int count) |
Parameters:
pdata | data pointer | |
type | format string | |
count | format count |
Return value: true if all the data was read
Reads count blocks of data from the stream into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.
Contents > Library Reference > System > Stream object > write |
Stream.write
bool write(void* pdata, string type, int count) |
Parameters:
pdata | data pointer | |
type | format string | |
count | format count |
Return value: true if all the data was written
Writes count blocks of data to the stream from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.
Contents > Library Reference > System > Stream object > readInt |
Stream.readInt
bool readInt(int* pi) |
Parameters:
pi | int pointer |
Return value: true if successful
Read an int from the stream into the memory pointed to by pi.
Contents > Library Reference > System > Stream object > writeInt |
Stream.writeInt
bool writeInt(int i) |
Parameters:
i | int to write |
Return value: true if successful
Write an int to the stream.
Contents > Library Reference > System > Stream object > readWord |
Stream.readWord
bool readWord(int* pw) |
Parameters:
pw | int pointer |
Return value: true if successful
Read an 2-byte word from the stream into the memory pointed to by pw.
Contents > Library Reference > System > Stream object > writeWord |
Stream.writeWord
bool writeWord(int w) |
Parameters:
w | word to write |
Return value: true if successful
Write a 2-byte word to the stream.
Contents > Library Reference > System > Stream object > readFloat |
Stream.readFloat
bool readFloat(float* pf) |
Parameters:
pf | float pointer |
Return value: true if successful
Read a float from the stream into the memory pointed to by pf.
Contents > Library Reference > System > Stream object > writeFloat |
Stream.writeFloat
bool writeFloat(float f) |
Parameters:
f | float to write |
Return value: true if successful
Write a float to the stream.
Contents > Library Reference > System > Stream object > readString |
Stream.readString
bool readString(string* ps) |
Parameters:
ps | string pointer |
Return value: true if successful
Read a string from the stream into the memory pointed to by ps.
Contents > Library Reference > System > Stream object > writeString |
Stream.writeString
bool writeString(string s) |
Parameters:
s | string to write |
Return value: true if successful
Write a string to the stream.
Contents > Library Reference > System > Stream object > readChar |
Stream.readChar
bool readChar(char* pc) |
Parameters:
pc | char pointer |
Return value: true if successful
Read a char from the stream into the memory pointed to by pc.
Contents > Library Reference > System > Stream object > writeChar |
Stream.writeChar
bool writeChar(char c) |
Parameters:
c | char to write |
Return value: true if successful
Write a char to the stream.
Contents > Library Reference > System > ISerializable object > serialize |
ISerializable.serialize
bool serialize(Stream* stream) |
Parameters:
stream | stream pointer |
Return value: true if all the data was written
This method should write all of the important data of the implementing object to the stream.
Contents > Library Reference > System > ISerializable object > deserialize |
ISerializable.deserialize
bool deserialize(Stream* stream) |
Parameters:
stream | stream pointer |
Return value: true if all the data was read
This method should read all of the important data of the implementing object to the stream.
Contents > Library Reference > System > events |
events
void events(bool blocking) |
Parameters:
blocking | true to wait for an event to occur |
Processes all pending events, calling user provided event handlers, returning when the queue is empty. If blocking is true and no events are in the queue, the function will not return until an event is processed. If an appStopEvent is received, the app's onstop handler is called but this function never returns. This function should be called during long calculations to allow the user interface to respond (for example, allowing the user to cancel).
Example:
Displays a dialog synchronously. Calling executeDialog() will open myDialog, process all its events, and return when the dialog has been closed.
bool myDialogClosed; handler myDialog.onclose() { myDialogClosed = true; } void executeDialog() { myDialogClosed = false; myDialog.domodal(); while (!myDialogClosed) { events(true); } } |
Contents > Library Reference > System > fatal |
fatal
void fatal(string str) |
Parameters:
str | text to display |
Displays a runtime error message containing the specified text and information about the current function. When the error message is dismissed, the app exits. This function does not return.
Contents > Library Reference > System > callstack |
callstack
string callstack() |
Return value: a formatted callstack
Creates a string containing a list of functions in the current callstack, one per line.
Contents > Library Reference > System > debuglog |
debuglog
void debuglog(string str) |
Parameters:
str | text to log |
Writes the text as a line to the debug log. See Debug support for details. This is not a real function, as no code is generated unless the project is compiled with the debug property set.
Contents > Library Reference > System > assert |
assert
void assert(bool expr) |
Parameters:
expr | expression to check |
When expr is false, displays an error message containing the text of the expression and a call stack. See Debug support for details. This is not a real function, as no code is generated unless the project is compiled with the debug property set.
Contents > Library Reference > System > ticks |
ticks
int ticks() |
Return value: tick count
Returns the number of clock ticks since the device was last reset.
Contents > Library Reference > System > tickspersec |
tickspersec
int tickspersec() |
Return value: ticks per second
Returns the number of clock ticks that occur each second.
Contents > Library Reference > System > resetaot |
resetaot
void resetaot() |
Reset the device's auto off timer. If the device goes without input for a short time, it will turn itself off. To prevent this, periodically call this function.
Contents > Library Reference > System > sleep |
sleep
void sleep(int ms) |
Parameters:
ms | milliseconds to sleep |
Causes the app to sleep for ms milliseconds. While sleeping, the CPU will be put into low power mode, but the user will not be able to interact with the device (including turning it off).
Contents > Library Reference > System > launch |
launch
void launch(string creatorid) |
Parameters:
creatorid | creator id of app to launch |
Launch the app with the given 4 character creator id. This function will post a message to quit the current app if the specified app is found. However, it will return and allow the current app to process its queued events.
Contents > Library Reference > System > launchGoto |
launchGoto
void launchGoto(string creatorid, string database, int recId, int searchStrLen, int matchPos, int matchField, int matchCustom) |
Parameters:
creatorid | creator id of app to launch | |
database | name of database to open (used to set GoToParamsType.dbID) | |
recId | record to open (sets GoToParamsType.recordNum) | |
searchStrLen | sets GoToParamsType.searchStrLen | |
matchPos | sets GoToParamsType.matchPos | |
matchField | sets GoToParamsType.matchFieldNum | |
matchCustom | sets GoToParamsType.matchCustom |
Launch the app with the given 4 character creator id using the system defined sysAppLaunchCmdGoTo launch code. The other parameters refer to fields in the system defined GoToParamsType structure. Different applications use the GoToParamsType differently, and not all field may be required/used by all applications. This function will post a message to quit the current app if the specified app is found. However, it will return and allow the current app to process its queued events.
Contents > Library Reference > System > launchCustomString |
launchCustomString
void launchCustomString(string creatorid, int code, string param) |
Parameters:
creatorid | creator id of app to launch | |
code | launch code to send | |
param | string to pass with the launch code |
Launch the app with the given 4 character creator id passing a custom launch code and a pointer to the specified string param. Only use this function if the app you are launching supports a char* launch parameter. This function will post a message to quit the current app if the specified app is found. However, it will return and allow the current app to process its queued events.
Note: In order to launch an OrbC application with a string parameter (as retrieved by UIApp.launchArgs, specify launchCodeOrbCAppWithArgs as the launch code.Contents > Library Reference > System > username |
username
string username() |
Return value: HotSync username
Returns the HotSync username associated with the device.
Contents > Library Reference > System > serialnum |
serialnum
string serialnum() |
Return value: serial number
Returns the string representation of the device's serial number, or the empty string if it does not have one.
Contents > Library Reference > System > osver |
osver
int osver() |
Return value: OS version
Returns the integer version of the OS, using the standard Palm OS version specification - 32-bit number with the high 8 bits being the major version, the the next 8 bits being the minor version, and the remaining bits representing the fix number, build number, and build type.
Contents > Library Reference > System > osvers |
osvers
string osvers() |
Return value: OS version string
Returns the string representation of the OS version.
Contents > Library Reference > System > orbver |
orbver
int orbver() |
Return value: OrbC version
Returns the OrbC runtime version the current app is using - 16-bit number with the high 8 bits being the major version, and the low 8 bits being the minor version.
Contents > Library Reference > System > getclip |
getclip
string getclip() |
Return value: clipboard contents
Returns the contents of the clipboard if it currently contains text, otherwise it returns the empty string.
Contents > Library Reference > System > setclip |
setclip
void setclip(string text) |
Parameters:
text | new clipboard text |
Copys text to the clipboard.
Contents > Library Reference > System > memcpy |
memcpy
void memcpy(void* pDest, void* pSrc, int len) |
Parameters:
pDest | destination pointer | |
pSrc | source pointer | |
len | number of values |
Copies len values from pSrc to pDst. The data types at the destination must be the same as the source, or the application's behavior will be unpredictable.
Note: Each data type (int, float, string, char) has a length of 1 from the perspective of this function.Contents > Library Reference > System > malloct |
malloct
void* malloct(string type, int count) |
Parameters:
type | type string | |
count | type count |
Return value: pointer to allocated data
Allocates count blocks of memory, initializing the memory elements to the types specified by the type string type.
Contents > Library Reference > System > free |
free
void free(void* ptr) |
Parameters:
ptr | pointer to memory block |
Releases the memory allocated by calling malloct.
Contents > Library Reference > System > freemem |
freemem
int freemem() |
Return value: free memory available
Returns the amount of free dynamic memory. Because the OrbC runtime has some overhead, this value cannot be used to make any direct calculations about how much memory can be allocated.
Contents > Library Reference > System > battery |
battery
int battery(bool volts) |
Parameters:
volts | true to retrieve voltage * 100, false to retrieve the percent remaining |
Return value: percent remaining or voltage * 100
Returns the requested battery status - voltage or percent remaining.