PktCSysLib is a native library for PocketC for Palm that is free to use for PocketC users. The program is not in the public domain however and is Copyright © 1998 Marvin E. Wilborne III, all rights reserved.

Download everything (including this documentation) for later.

Introduction

This module gives your PocketC program the ability to:

• Check the setting for the Automatic shutoff timer
• Set the value of the automatic shutoff timer
• Check different values related to the batteries
• Check several system feature values such as the ROM version, etc.
• Turn on or off the backlight feature

Functions added to PocketC by PktCSysLib

Several functions get added to PocketC when you use PktCSysLib. Here is a description of each function, the parameters the functions take, and values returned.

Some functions are demonstrated in the Sample Source below.

• Backlight - int Backlight(int value)

  Where value is: 0 to explicitly turn off the backlight even if it's already off, 1 to turn on the backlight, and 2 test what state the backlight is in.

  The return value is the state (0 = off, 1 = on) the backlight was in BEFORE turning it on or off, or the current state if 2 was passed to the function.

  NOTE: These backlight functions don't appear to manipulate the "emulated" backlight on CoPilot or the Palm OS Emulator.

• BatteryInfo - int BatteryInfo(int getvalue)

  Where getvalue is one of these values:

  • 0 (zero) to get the Current Battery voltage times 100 (i.e. divide the value by 100 hundred and cast to a float to get the actual voltage)
  • 1 (one) to get the Warning Threshold voltage times 100 (i.e. this is the voltage where the Palm device starts warning you about battery voltage)
  • 2 (two) to get the Critical voltage below which the Palm device will not turn on.
  • 3 (three) CheckTicks - according the PalmOS API, "Warning Threshold and CheckTicks are the battery-warning voltage threshold and time out. If the battery voltage falls below the threshold, or the timeout expires, a lowBatteryChr key event is put on the queue. Normally, applications call SysHandleEvent which calls SysBatteryWarningDialog in response to this event." This particular piece of information may have little value for PocketC programmers.
  • 4 (four) Type of Battery. Returns 0 for Alkaline, 1 for NiCad, and 2 for Lithium.
  • 5 (five) Plugged In??? Returns 1 if the pluggedIn value returned by SysBatteryInfo is true, otherwise returns 0 for false. I'm not sure what this does.

• GetAutoOffTime - int GetAutoOffTime()

  Returns the value, in seconds, that the automatic shut off timer of the Palm device is set to.

• GetSystemFeature - int GetSystemFeature(int feature)

  Returns the value of the feature passed in:

  • 0 - Get the Major ROM Version
  • 1 - Get the Minor ROM Version
  • 2 - Get the ROM Fix Value
  • 3 - Get the ROM Stage Value, returns 0 for development, 1 for alpha, 2 for beta, and 3 for release.
  • 4 - Get the ROM Build Number for non-releases.
  • 5 - Get the Product ID Model Number
  • 6 - Get the Product ID Revision Number
  • 7 - Returns 0 if no backlight or backlight feature is present. Returns 1 if backlight feature is available.

• PCSLVersion - int PCSLVersion()

  PCSLVersion returns the version of PktCSysLib that is installed on the Palm device. This can be used by your program to make sure that features you want to use in PktCSysLib are available. See the release history below to see what features were added with which version.

• SetAutoOffTime - int SetAutoOffTime(int seconds)

  Sets the automatic shutoff timer to the value passed in as seconds. Use the value 0 (zero) to disable the automatic shutoff timer. The function returns the value of the automatic shutoff timer before setting it to the new value.

Using PktCSysLib in your programs

Download PktCSysLib.prc and install it on your Palm device using the Palm Intall tool. Then HotSync your Palm device.

To use PktCSysLib in your PocketC program, you need to include the compiler directive that tells the PocketC compiler to link in the library when compiling and executing your code.

To do that, include the line: library "PktCSysLib" in your program before using any of the functions defined by PktCSysLib. Keep in mind that you must use the exact case as specified in the library line above and in the example below.

Example Source Code

// PktCSysLibTest

library "PktCSysLib"

main() {
  int secs;

  if (GetSystemFeature(7)) // do we have a backlight?
    Backlight(1);          // yes, turn it on!

  secs = GetAutoOffTime();

  if (secs) {
    puts("Pilot will turn off in ");
    puts(secs);
    puts("seconds");
  }
  else
    puts("Pilot is set to not turn off.");

  puts("\n");
}

Release History

• 8 December 1998
  • Documentation updated.
• 23 September 1998
  • PCSLVersion() returns the value 101
  • Corrected library name byte string which may have caused a conflict between this library and other native libraries.
• 22 September 1998
  • Documentation updated
• 21 September 1998 Version 1.0.0
  • Initial release
  • PCSLVersion() returns the value 100