API Guide Home (Online version only) |

# HsExtCommon.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2005 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  * @defgroup HSExt Handspring Extensions
    00007  *
    00008  * @{
    00009  * @}
    00010  */
    00011 /**
    00012  *
    00013  * @ingroup HSExt
    00014  *
    00015  */
    00016
    00017 /**
    00018  * @file    HsExtCommon.h
    00019  * @brief   Common defines shared between HsExt.h (#include for 68K programs)
    00020  * and HsExtArm.h (#include for ARM programs).
    00021  *
    00022  */
    00023
    00024
    00025
    00026 #ifndef   __HS_EXT_COMMON_H__
    00027 #define   __HS_EXT_COMMON_H__
    00028
    00029 #if 0
    00030 #pragma mark --------  Public Defines   ----------------
    00031 #endif
    00032
    00033
    00034 /******************************************************************************
    00035  * Public Defines
    00036  *****************************************************************************/
    00037
    00038 ////////////////////////////////////////
    00039 #if 0
    00040 #pragma mark Version String
    00041 #endif
    00042 ////////////////////////////////////////
    00043
    00044 #define hsVersionStringSize       32
    00045
    00046
    00047 ////////////////////////////////////////
    00048 #if 0
    00049 #pragma mark Attributes
    00050 #endif
    00051 ////////////////////////////////////////
    00052
    00053 /**
    00054  * Current system activity. Possible bits for hsAttrSysActivity
    00055  **/
    00056 /*@{*/
    00057 #define hsAttrSysActiveHotSync        0x0001    /**< Hot sync in progress  */
    00058 #define hsAttrSysActiveProgress       0x0002    /**< Progress dialog is up (any progress dialog) */
    00059 #define hsAttrSysActiveBeamProgress   0x0004    /**< Beam Progress dialog is up */
    00060 /*@{*/
    00061
    00062 /**
    00063  * Type of phone. Possible values of hsAttrPhoneType
    00064  **/
    00065 /*@{*/
    00066 #define hsAttrPhoneTypeCDMA       0x0001   /**< CDMA Phone  */
    00067 #define hsAttrPhoneTypeGSM        0x0002   /**< GSM Phone  */
    00068 /*@}*/
    00069
    00070 /** Possible values of hsAttrRingSwitch
    00071  *  For now there are only two values, but it's left open to have a control
    00072  *  that works more like a volume control and has a range of settings. The
    00073  *  value of the "loud" setting was chosen so that it can be decided later
    00074  *  to make this a bit field or a scalar value. */
    00075 #define hsAttrRingSwitchMute          0    /**< Silent position*/
    00076 #define hsAttrRingSwitchLoud          0x8000 /**< Sounds-on position */
    00077
    00078
    00079 /**
    00080  * Max length (in bytes) of a word (corrected or not) in the word
    00081  * correction dictionary.  With null, word can be 26 bytes.
    00082  **/
    00083 #define hsWordCorrectMaxWordLen     25      /**<        */
    00084
    00085
    00086
    00087 ////////////////////////////////////////
    00088 #if 0
    00089 #pragma mark Errors
    00090 #endif
    00091 ////////////////////////////////////////
    00092
    00093 /**
    00094  * Error codes
    00095  **/
    00096 /*@{*/
    00097 #define hsOLDErrorClass                   (appErrorClass+0x0100)
    00098 #define hsErrNotSupported                 (hsOLDErrorClass | 0x01)
    00099 #define hsErrInvalidCardNum               (hsOLDErrorClass | 0x02)
    00100 #define hsErrReadOnly                     (hsOLDErrorClass | 0x03)
    00101 #define hsErrInvalidParam                 (hsOLDErrorClass | 0x04)
    00102 #define hsErrBufferTooSmall               (hsOLDErrorClass | 0x05)
    00103 #define hsErrInvalidCardHdr               (hsOLDErrorClass | 0x06)
    00104 #define hsErrCardPatchAlreadyInstalled    (hsOLDErrorClass | 0x07)
    00105 #define hsErrCardPatchNotInstalled        (hsOLDErrorClass | 0x08)
    00106 #define hsErrNotEnoughPower               (hsOLDErrorClass | 0x09)
    00107 #define hsErrCardNotInstalled             (hsOLDErrorClass | 0x0A)
    00108 #define hsErrInvalidPeriod                (hsOLDErrorClass | 0x0B)
    00109 #define hsErrPeriodicNotInstalled         (hsOLDErrorClass | 0x0C)
    00110 #define hsErrFixedStorageRequired         (hsOLDErrorClass | 0x0D)
    00111 #define hsErrPeriodicAlreadyInstalled     (hsOLDErrorClass | 0x0E)
    00112 #define hsErrInUse                        (hsOLDErrorClass | 0x0F)
    00113 #define hsErrIndicatorInvalidSequence     (hsOLDErrorClass | 0x10)
    00114 #define hsErrIndicatorInvalidCap          (hsOLDErrorClass | 0x11)
    00115 #define hsErrIndicatorDisabled            (hsOLDErrorClass | 0x12)
    00116 // ***DO NOT DEFINE ANY MORE ERRORS IN THIS RANGE*** USE hsExtErrorClass
    00117 // BASED DEFINITIONS BELOW FOR NEW ERROR CODES!
    00118
    00119 // IMPORTANT: THE OLD ERROR CLASS USED FOR HANDSPRING EXTENSIONS ERROR
    00120 // CODES WAS IN **APP** ERROR CODE SPACE. ALL NEW CODES MUST BE DEFINED
    00121 // IN TERMS OF THE UNIQUE ERROR CLASS hsExtErrorClass
    00122
    00123 /** Unexpected numerical underflow encountered */
    00124 #define hsErrUnderflow                    (hsExtErrorClass | 0x13)
    00125
    00126 /** The user replied "No" when prompted to turn on wireless mode */
    00127 #define hsErrUserNoRadio                  (hsExtErrorClass | 0x14)
    00128
    00129 /** Failed to register on carrier's network, or timed out while
    00130  *  waiting to register. */
    00131 #define hsErrOutOfCoverage                (hsExtErrorClass | 0x15)
    00132
    00133 /** The blocking call was interrupted by AppStop event */
    00134 #define hsErrAppStopEvent                 (hsExtErrorClass | 0x16)
    00135
    00136 /** Request failed because of insufficient memory */
    00137 #define hsErrOutOfMemory                  (hsExtErrorClass | 0x17)
    00138
    00139 /** The SIM is missing, invalid, wrong unlock code, or some other SIM
    00140  *  problem detected that prevented network registration from completing. */
    00141 #define hsErrSIMMissing                   (hsExtErrorClass | 0x18)
    00142
    00143 /** Failed to attach GPRS, or timed out while waiting to register */
    00144 #define hsErrGPRSNotAttached              (hsExtErrorClass | 0x19)
    00145
    00146 /** The requiested operation timed out, without completing its objective */
    00147 #define hsErrTimeOut                      (hsExtErrorClass | 0x1A)
    00148
    00149 /** The requiested operation was interrupted or cancelled by user,
    00150  *  before completing its objective */
    00151 #define hsErrUserInterrupted              (hsExtErrorClass | 0x1B)
    00152
    00153 /*@}*/
    00154
    00155
    00156 ////////////////////////////////////////
    00157 #if 0
    00158 #pragma mark Libraries
    00159 #endif
    00160 ////////////////////////////////////////
    00161
    00162 /**
    00163  * Library alias names that SysLibFind maps to a real library name
    00164  *  according to the appropriate hsPrefSerialLibXXX setting.
    00165  *
    00166  * By Convention, library alias names start with a '*'. The exception
    00167  *  is the "Serial Library" name which is mapped in order to
    00168  *  be compatible with pre-existing applications that already use it.
    00169  **/
    00170 /*@{*/
    00171 #define hsLibAliasDefault             "Serial Library" /**< hsPrefSerialLibDef */
    00172 #define hsLibAliasHotSyncLocal        "*HsLoc  SerLib" /**< hsPrefSerialLibHotSyncLocal */
    00173 #define hsLibAliasHotSyncModem        "*HsMdm  SerLib" /**< hsPrefSerialLibHotSyncModem */
    00174 #define hsLibAliasIrda                "*Irda   SerLib" /**< hsPrefSerialLibIrda */
    00175 #define hsLibAliasConsole             "*Cons   SerLib" /**< hsPrefSerialLibConsole */
    00176 /*@{*/
    00177
    00178 /**
    00179  * Actual library name of the Dragonball's built-in serial library.
    00180  * This is the default value of the hsPrefDefSerialLib pref setting which
    00181  *  SysLibFind uses to map an incoming library name to an actual library
    00182  *  name.
    00183  **/
    00184 #define hsLibNameBuiltInSerial        "BuiltIn SerLib"
    00185
    00186
    00187 ////////////////////////////////////////
    00188 #if 0
    00189 #pragma mark Features
    00190 #endif
    00191 ////////////////////////////////////////
    00192
    00193 /**
    00194  * This is the Handspring feature id. Apps can tell if they're on
    00195  * a handspring device if they get 0 err back from:
    00196  * err = FtrGet (hsFtrCreator, hsFtrIDVersion, &value)
    00197  **/
    00198 #define hsFtrCreator                 'hsEx'
    00199
    00200
    00201 /**
    00202  * Version of Handspring extensions
    00203  *  0xMMmfsHHh, where:
    00204  *
    00205  *   MM.mm.f are the major, minor, and fix revs of PalmOS which is modified
    00206  *            by this version of HsExtensions
    00207  *
    00208  *   s is the release stage (3-release,2-beta,1-alpha,0-development)
    00209  *
    00210  *   HH.h are the major and minor rev of HsExtensions for the relevant
    00211  *            version of PalmOS
    00212  **/
    00213 #define hsFtrIDVersion                0
    00214
    00215
    00216 #define hsFtrIDModDate                1
    00217
    00218 /**
    00219  * Feature number indicating that the Launcher Database Mgr library is loaded.
    00220  *  The value of the feature is the refNum of the loaded library.
    00221  *  Call FtrGet (hsFtrCreator, hsFtrIDLdbMgrLibRefNum, ...) to get this feature.
    00222  *
    00223  * THIS FEATURE IS DEPRICATED
    00224  *
    00225  **/
    00226 #define hsFtrIDLdbMgrLibRefNum        2
    00227
    00228 /**
    00229  * If this feature is present, then we won't use the optimization to grab the
    00230  * memory semaphore before doing multiple data manager calls.
    00231  **/
    00232 #define hsFtrIDNoMemSemaphore         3
    00233
    00234 /** This features contains boolean flags to let developers know that a bug
    00235  * present in older devices has been fixed.
    00236  */
    00237 #define hsFtrIDBugsFixed              4
    00238
    00239 /**
    00240  * This feature tells what type of hardware keys a device has.
    00241  */
    00242
    00243 /*@{*/
    00244 #define hsFtrIDTypeOfKeyboard         5
    00245
    00246 /**
    00247  *  The masks used to interpret the hardware keyboard feature
    00248  **/
    00249 #define hsFtrValKeyboardBasic       0x0001  /**< Basic keys (pwr/scroll/app) */
    00250 #define hsFtrValKeyboardQwerty      0x0002  /**< Qwerty keys (A-Z, Period, Space, Backspace, Enter,
    00251                                                   Menu, Option, Shift) */
    00252 #define hsFtrValKeyboardJog         0x0004  /**< Jog keys (jog-up, jog-down,jog-scan) */
    00253 #define hsFtrValKeyboardCommCentric 0x0008  /**< DEPRICATED - Communicator centric buttons */
    00254 #define hsFtrValKeyboardCustomApps  0x0010  /**< Non-standard app keys (Standard is: date/addr/todo/memo)
    00255                                                   replaces hsFtrValKeyboardCommCentric */
    00256
    00257 /*@{*/
    00258
    00259 /** This feature describes the radio hardware available */
    00260 #define hsFtrIDRadioAttributes        6
    00261
    00262 // The masks used to interpret the radio attributes feature
    00263 #define hsFtrValRadioAvailable      0x0001      /**< Radio is present and available for use */
    00264 #define hsFtrValRadioBuiltin        0x0002      /**< Radio is part of the base hardware and not on a module */
    00265
    00266 /**
    00267  *  This feature defines how the power putton behaves
    00268  *  Note: In HsExtensions 1.0 for PalmOS 5.2.1 this feature is set, but ignored
    00269  **/
    00270 /*@{*/
    00271 #define hsFtrIDPowerKeyResponse       7
    00272 #define hsFtrValPowerKeyDoubleClkBacklight  0x0001  /**< Double click for backlight */
    00273 #define hsFtrValPowerKeyTripleClkInvert     0x0002  /**< Triple click for invers (requires DblClkBacklight)*/
    00274 #define hsFtrValPowerKeyHoldRadioPower      0x0004  /**< Hold for radio power */
    00275 /*@{*/
    00276
    00277 /**
    00278  *  This feature indicates the functionality of the status gadgets API
    00279  **/
    00280 #define hsFtrIDStatusGadgetRev        8
    00281
    00282 #define hsFtrValStatusGadgetRev1      0x0001    /**< Revision 1 of API */
    00283
    00284 /**
    00285  *  If this feature is set, the graffiti area is disabled
    00286  **/
    00287 #define hsFtrIDGrfAreaDisabled        9
    00288
    00289 /**
    00290  *  This feature tells which keyboard layout is being used
    00291  **/
    00292 #define hsFtrIDKeyboardLayout         10
    00293
    00294 /**
    00295  * The values used to interpret the keyboard layout feature
    00296  **/
    00297 /*@{*/
    00298 #define hsFtrValKeyboardLayout_enUS     0x0001  /**< English */
    00299 #define hsFtrValKeyboardLayout_deDE     0x0002  /**< German */
    00300 #define hsFtrValKeyboardLayout_frFR     0x0003  /**< French */
    00301 /*@{*/
    00302
    00303 /**
    00304  * This features contains the DB Id to open and
    00305  * play the resource with type 'smfr' with resource id 1
    00306  * when the lid opens
    00307  *
    00308  * THIS FEATURE IS DEPRICATED
    00309  **/
    00310 #define hsFtrIDToneOnLidOpen          11
    00311
    00312 /**
    00313  * This feature and value (s) is used to see if PhoneApp should be relaunched
    00314  * when waking up.
    00315  *
    00316  * THIS FEATURE IS DEPRICATED
    00317  **/
    00318 #define hsFtrIDCurrentAppOnSleep      12
    00319 #define hsFtrValCurrentAppOnSleepPhoneAppSpeedDialView   0x0001  /**< PhoneApp current view is Speed dial */
    00320
    00321 /**
    00322  * This feature indicates whether the Manufacturing test app is
    00323  * present on the device.
    00324  **/
    00325 #define hsFtrIDTestingBootMode        13
    00326
    00327 /**
    00328  * If this feature exists, then our navigation support exists.  The
    00329  *version of the navigation support is stored in the feature's value.
    00330  **/
    00331 #define hsFtrIDNavigationSupported    14
    00332
    00333 /**
    00334  * This feature can be used to determine the hardware "API" revision.
    00335  * It changes when there's a revision of the hardware, but the device
    00336  * is otherwise the same.  Very few apps should ever need this.  Drivers
    00337  * should generally ask the HAL directly for this info (though HALAttr)
    00338  * since that's more efficient.
    00339  **/
    00340 #define hsFtrIDHardwareApiRevision    15
    00341
    00342
    00343 /**
    00344  * Display Attribute Features
    00345  */
    00346
    00347 #define hsDispFtrCreator                      'DisA'
    00348
    00349 /** Attributes about the display / controller combination... */
    00350 #define hsDispFtrIDDisplayAttributes          0
    00351
    00352 /**
    00353  * @name Values for the display attributes, which is a bitfield.
    00354  *
    00355  */
    00356 /*@{*/
    00357 #define hsDispFtrValLCDControllerTypeMask     0x000000FF
    00358 #define hsDispFtrValDragonballVZ              0x00000000
    00359 #define hsDispFtrValSed1375                   0x00000001
    00360 #define hsDispFtrValSed1376                   0x00000002
    00361 #define hsDispFtrValSed13A3                   0x00000003
    00362 #define hsDispFtrValOmapX10             0x00000004  /**< TI OMAP 1510/310 */
    00363 #define hsDispFtrValBulverdePxa27X            0x00000005    /**< Intel Bulverde PXA 270, 271, etc. */
    00364
    00365 #define hsDispFtrValLCDDisplayTypeMask        0x0000FF00        /**<        */
    00366 #define hsDispFtrValBwStn                0x00000100 /**< The black and white STN used in black and white Visors and Treos. */
    00367 #define hsDispFtrValColorStn                  0x00000200    /**< Color STN */
    00368 #define hsDispFtrValColorTft                  0x00000300    /**< Color TFT (used in Prism) */
    00369 #define hsDispFtrValColorOled                 0x00000400    /**< Organic LED */
    00370 /*@}*/
    00371
    00372 /**
    00373  * @name Available Shades
    00374  *   This feature contains the number of shades of gray, red, green, and blue
    00375  *   available on this display.  Note that this will _never_ be bigger than
    00376  *   the number of shades available on the controller, since the display is
    00377  *   fundamentally limited by what you can set the controller to.  See masks
    00378  *   below for accessing...
    00379  */
    00380 /*@{*/
    00381 #define hsDispFtrIDDisplayShades              1
    00382
    00383 /**
    00384  * This feature contains the number of shades of gray, red, green, and blue
    00385  * available on this controller.  This can be larger than the number of shades
    00386  * that the display can show, since the controller can do hardware dithering
    00387  * to deal with the fact that the display can't show all the shades.
    00388  *
    00389  * Software dithering is handled separately.  If there is software dithering, it
    00390  * can be suppressed.  See hsAttrDitherSuppress
    00391  **/
    00392 #define hsDispFtrIDControllerShades           2
    00393
    00394 /**
    00395  * You can use these bitmasks to get the number of shades
    00396  * ...note that the actual number of shades is the (value+1).  This is needed
    00397  * so in the future we can support displays/controllers that can have 256 shades.
    00398  **/
    00399 #define hsDispFtrValGrayOffset                24
    00400 #define hsDispFtrValRedOffset                 16
    00401 #define hsDispFtrValGreenOffset                8
    00402 #define hsDispFtrValBlueOffset                 0
    00403 /*@}*/
    00404
    00405
    00406 // Sample usage:
    00407 //
    00408 // UInt32 displayShades;
    00409 // UInt16 redShades;
    00410 // Err err = 0;
    00411 //
    00412 // err = FtrGet (hsDispFtrCreator, hsDispFtrIDDisplayShades, &displayShades);
    00413 // if (!err)
    00414 //   {
    00415 //     // Get the number of red shades - 1...
    00416 //     redShades = (UInt16) ((UInt8) (displayShades >> hsDispFtrValRedOffset));
    00417 //
    00418 //     // Account for +1 after doing the conversion to 8-bit...
    00419 //     redShades++;
    00420 //   }
    00421
    00422
    00423
    00424 ////////////////////////////////////////
    00425 #if 0
    00426 #pragma mark Utilities
    00427 #endif
    00428 ////////////////////////////////////////
    00429
    00430 /** This is the buffer size that should be sent to HsExtDoSaveAsDialog() */
    00431 #define hsMaxSaveAsNameSize 32
    00432
    00433
    00434
    00435 #if 0
    00436 #pragma mark --------  Public Enums   ----------------
    00437 #endif
    00438
    00439 /******************************************************************************
    00440  * Public Enums
    00441  *****************************************************************************/
    00442
    00443 ////////////////////////////////////////
    00444 #if 0
    00445 #pragma mark Version String
    00446 #endif
    00447 ////////////////////////////////////////
    00448
    00449 typedef enum
    00450   {
    00451     hsVerStrComplete,       /**< Composite, formatted for display in info dialog */
    00452     hsVerStrSerialNo,       /**< Complete serial number (ROM token 'snum' is limited to 12 digits) */
    00453     hsVerStrHardware,       /**< Revision of the hardware */
    00454     hsVerStrProductName,        /**< Like, "Treo 600" */
    00455     hsVerStrCarrierID,      /**< Carrier ID code for carrier branding */
    00456     hsVerStrProductRev,     /**< Complete product; covering hardware, radio firmware and software */
    00457     hsVerStrROMBuild,       /**< ROM buld number (not the same as the build number in sysFtrNumROMVersion) */
    00458     hsVerStrFirmwareVer,        /**< Version of the radio firmware */
    00459     hsVerStrPalmOSVer,      /**< See sysFtrNumROMVersion */
    00460     hsVerStrLifeTime        /**< Radio life timer */
    00461   } HsVerStrEnum;
    00462
    00463
    00464 ////////////////////////////////////////
    00465 #if 0
    00466 #pragma mark Attributes
    00467 #endif
    00468 ////////////////////////////////////////
    00469
    00470 /**
    00471  * Parameters to HsAttrGet/Set calls
    00472  **/
    00473
    00474 typedef enum
    00475   { /*
    00476      *  These attributes with various sizes are defined
    00477      *  only for compatability with existing 68K code, and
    00478      *  are explicitly marshalled by the 68K/ARM shim for
    00479      *  the HsAttrGet() and HsAttrSet() functions.
    00480      *
    00481      *  Note: The definitions for hsAttrE911Mode in the
    00482      *  OS 3.5 headers, and for hsAttrKeyboardLocked in
    00483      *  the OS 4.0 headers both had an enum value of 8.
    00484      *  Apps using hsAttrE911Mode will probably have to be
    00485      *  recompiled anyway so backward compatability has
    00486      *  been maintained hsAttrKeyboardLocked.
    00487      */
    00488     hsAttr68KLidOpen,               /**< UInt16 @see hsAttrLidOpen */
    00489     hsAttr68KSysSleepReason,        /**< UInt16 @see hsAttrSysSleepReason */
    00490     hsAttr68KDisplayOn,             /**< UInt16  @see hsAttrDisplayOn */
    00491     hsAttr68KRingSwitch,            /**< UInt16 @see hsAttrRingSwitch */
    00492     hsAttr68KPostProcessRsc,        /**< UInt32 @see hsAttrPostProcessRsc */
    00493     hsAttr68KSysActive,             /**< UInt16 @see hsAttrSysActive */
    00494     hsAttr68KActiveCalls,           /**< UInt16 @see hsAttrActiveCalls */
    00495     hsAttr68KPhoneType,             /**< UInt32 @see hsAttrPhoneType */
    00496     hsAttr68KKeyboardLocked,        /**< Boolean @see hsAttrKeyboardLocked */
    00497     hsAttr68KKeyLockNextWakeTicks,  /**< UInt32 @see hsAttrKeyLockNextWakeTicks */
    00498
    00499     /*
    00500      * All new 68K and ARM code shall use only the following
    00501      * attributes, all of which take a 32-bit value parameter.
    00502      */
    00503     hsAttrLidOpen = 0x80,       /**< false=lid closed, true=lid open
    00504                                     (returns hsErrNotSupported if no lid) */
    00505     hsAttrSysSleepReason,       /**< Same as the SleepEventParamType.reason
    00506                                        from the last sysNotifySleepRequestEvent
    00507                                        unless the real reason is different
    00508                                        (e.g. hsSysSleepLid) */
    00509     hsAttrDisplayOn,            /**< true = display is on, false = dispay is off */
    00510     hsAttrRingSwitch,       /**< State of ring switch, can be either hsAttrRingSwitchMute or hsAttrRingSwitchLoud */
    00511     hsAttrPostProcessRsc,       /**< Pointer to resource containing the post-processing lists */
    00512     hsAttrSysActive,            /**< Bits representing various system activity. Current
    00513                                      implementation sets only the hsAttrSysActiveHotSync
    00514                                      bit if the HotSync dialog is active*/
    00515     hsAttrActiveCalls,          /**< Number of active voice calls */
    00516     hsAttrPhoneType,            /**< returns hsAttrPhoneTypeCDMA if a CDMA phone
    00517                                      or hsAttrPhoneTypeGSM if a GSM phone */
    00518     hsAttrKeyboardLocked,       /**< true = keyguard active */
    00519     hsAttrKeyLockNextWakeTicks, /**< deprecated */
    00520     hsAttrKeyboardDB,           /**< DmOpenRef of database containing keyboard layout resources */
    00521     hsAttrDigitizerLock,        /**< true = digitizer is locked */
    00522     hsAttrE911Mode,             /**< true = phone is in 911 mode */
    00523     hsAttrDitherSuppress,       /**< count of requests to supress dithering
    00524                                         Set to non-zero to increment, set to zero to decrement */
    00525     hsAttrHotSyncSuppress,      /**< count of requests to suppress HotSync
    00526                                         Set to non-zero to increment, set to zero to decrement */
    00527
    00528     hsAttrPhoneRadioPowerState, /**< notifies HsExt that cell phone radio was just powered on
    00529                                         or off; non-zero if cell phone radio was powered on, zero if
    00530                                         powered down.  Power on does *not* imply completion of SIM
    00531                                         detection or registration */
    00532
    00533     hsAttrAllKeysWakeFromSleep, /**< (Refcount) sets the device in a mode where _all_ keys wake
    00534                                         the device from sleep and are processed.  This is intended in
    00535                                         special cases where we've powered off the screen to save power
    00536                                         (or something similar), but the user still thinks the device of
    00537                                         the device as on.  As a side effect, this will stop 'keyboard lock'
    00538                                         from starting when the device turns off.
    00539                                         Set to non-zero to increment, set to zero to decrement */
    00540
    00541     hsForcePrefAutoOffDurationSecs, //  Forces the Keyguard dialog to have a timeout period of prefAutoOffDurationSecs
    00542     hsAttrKeyguardDialogOn,         //  Denotes if the Keyguard dialog is On or not.
    00543
    00544     // This section is reserved so that if we need to add adds more attributes in "SDK 2.0"
    00545     // products that they won't conflict with attributes added in "SDK 2.1"
    00546     hsAttrReserved_SDK20_1,
    00547     hsAttrReserved_SDK20_2,
    00548     hsAttrReserved_SDK20_3,
    00549     hsAttrReserved_SDK20_4,
    00550     hsAttrReserved_SDK20_5,
    00551     hsAttrReserved_SDK20_6,
    00552     hsAttrReserved_SDK20_7
    00553
    00554     /*
    00555      * Attributes greater than 0x9000 are defined for internal use
    00556      * in Prv/HsExtAttr.h
    00557      */
    00558   } HsAttrEnum;
    00559
    00560
    00561 ////////////////////////////////////////
    00562 #if 0
    00563 #pragma mark Preferences
    00564 #endif
    00565 ////////////////////////////////////////
    00566
    00567 /**
    00568  * Equates for the HsPrefGet/Set calls
    00569  **/
    00570 typedef enum
    00571   {
    00572
    00573     // The following are used by SysLibFind() to resolve a virtual library
    00574     //  name to an actual one.  They are also used directly by SrmOpen()
    00575     //  to figure out whether to override a new-style driver w/ an old-style
    00576     //  driver.
    00577     hsPrefSerialLibDef,     /**< Char[] : Name of serial library to substitute for hsLibAliasDefault */
    00578     hsPrefSerialLibHotSyncLocal,    /**< Char[] : Name of serial library to substitute for hsLibAliasHotSyncLocal */
    00579     hsPrefSerialLibHotSyncModem,    /**< Char[] : Name of serial library to substitute for hsLibAliasHotSyncModem */
    00580     hsPrefSerialLibIrda,        /**< Char[] : Name of serial library to substitute for hsLibAliasIrda */
    00581     hsPrefSerialLibConsole,     /**< Char[] : Name of serial library to substitute for hsLibAliasConsole */
    00582
    00583     /**** End of prefs recognized by Visor, Visor Deluxe, Platnium, Prism, Edge ****/
    00584
    00585     // The following are used in SysHandleEvent() to launch apps in response
    00586     //  to associated virtual characters.
    00587     hsPrefJogScanCharAppCreator,      /**< UInt32 : Creator type of app to launch in response to hsChrJogScan */
    00588     hsPrefLidStatusChgCharAppCreator, /**< UInt32 : Creator type of app to launch in response to hsChrLidStatusChg */
    00589     hsPrefOptHard1CharAppCreator,     /**< UInt32 : Creator type of app to launch n response to hsChrOptHard1 */
    00590     hsPrefOptHard2CharAppCreator,     /**< UInt32 : Creator type of app to launch in response to hsChrOptHard2 */
    00591     hsPrefOptHard3CharAppCreator,     /**< UInt32 : Creator type of app to launch in response to hsChrOptHard3 */
    00592     hsPrefOptHard4CharAppCreator,     /**< UInt32 : Creator type of app to launch in response to hsChrOptHard4 */
    00593
    00594     // The following are used to set Key Manager preferences
    00595     hsPrefTempShiftTimeOut,           /**< UInt32 : Number of ticks until a temporary
    00596                         shift state (upper shift or option shift) times out. */
    00597
    00598     hsPrefLidClosedAutoOffSeconds,    /**< UInt16 : Number of seconds for auto-off when the lid is closed */
    00599
    00600     hsPrefLCDRefreshRate,         /**< UInt16 : Type of refresh rate for lighting see HsLCDRefreshRateEnum */
    00601
    00602     /**** End of prefs recognized by Treo 90, 180, 270, 300 ****/
    00603
    00604     hsPrefNetworkTimeSelected,    /**< UInt16: used by CDMA devices - should it read the time from the network*/
    00605
    00606     hsPrefKeyguardAutoEnableTime,     /**< UInt16: How many seconds to wait before enabling keyguard*/
    00607
    00608
    00609     hsPrefKeyguardAutoEnableAutoOffExtraTime, /**< UInt16 : How many seconds to wait before enabling
    00610                                                       keyguard when hsPrefKeyguardAutoEnableTime is
    00611                                                       set to hsKeyguardAutoPowerOff and the device
    00612                                                       powers off due to the auto-off timer */
    00613
    00614     hsPrefKeyguardFlags,              /**< UInt16 : Flags controlling keyguard's behaviour */
    00615
    00616     hsPrefTouchscreenDisableFlags,    /**< UInt16: Used by the phone app to determine when to disable touchscreen */
    00617
    00618     // The following are used in SysHandleEvent() to launch apps in response
    00619     //  to associated virtual characters.
    00620     hsPrefOptHardPowerCharAppCreator, /**< UInt32 : Creator type of app to launch in response to hsChrOptHardPower */
    00621
    00622     hsPrefOptReservedCharAppCreator,  /**< UInt32 : Creator type of app to launch in response to hsChrOptReserved (for future use) */
    00623
    00624     hsPrefPowerOnAppCreator,              /**< UInt32 : Creator type of app to launch
    00625                                               instead of the normally mapped app when
    00626                                               the app key turned the power on */
    00627
    00628     /**** End of prefs recognized by Treo 600 ****/
    00629
    00630     hsPrefSideHardCharAppCreator,       /**< UInt32 : Creator type of app to launch
    00631                                               instead of the normally mapped app when
    00632                                               the side key is pressed */
    00633
    00634     hsPrefBlinkGreenLEDInCoverage,      /**< UInt16 : Set to true if we want the green
    00635                                               LED to blink when the device is in coverage */
    00636
    00637     /**** End of prefs recognized by Treo 650 ****/
    00638
    00639     hsPrefHard11CharAppCreator,       /**< UInt32 : Creator type of app to launch
    00640                                               in response to vchrHard11 */
    00641
    00642     hsPrefOptHard11CharAppCreator,    /**< UInt32 : Creator type of app to launch
    00643                                               in response to hsChrOptHard11 */
    00644
    00645     hsPrefUserNotLookingTime,           /**< Int32 : After this many seconds since the last
    00646                                                 action, the user has stopped looking
    00647                                                 at the device. (auto display/kbd dim) */
    00648
    00649     // <chg 2005-DEC-14 Monte Benaresh> Added next pref
    00650
    00651     hsPrefNetworkTZSelected,            /**< UInt16: used by phones - should it read
    00652                                                 the time zone from the network*/
    00653
    00654     // RJS 22May06 Added next pref for PTT
    00655     hsPrefShortSideHardCharAppCreator,      /**< UInt32: Creator ID of app to launch on short press of side button */
    00656
    00657     // RTS April 06 Added pref for Gnome/Gandalf
    00658     hsPrefPowerSaveMode,            /**< Int32 : tied to the hsPrefUserNotLookingTime to turn off the backlight
    00659                              rather than just dim it.  LCD remains on.*/
    00660
    00661     // Leave this one at end!!!
    00662     hsPrefLast
    00663
    00664   } HsPrefEnum;
    00665
    00666
    00667 /**
    00668  * @name Special values for hsPrefKeyguardAutoEnableTime
    00669  *
    00670  */
    00671 /*@{*/
    00672 #define hsKeyguardAutoDisabled                  0   /**< Never */
    00673 #define hsKeyguardAutoPowerOff                  0xFFFF  /**< When device powers off */
    00674 /*@}*/
    00675
    00676 /**
    00677  * @name Values for hsPrefKeyguardFlags
    00678  *
    00679  */
    00680 /*@{*/
    00681 #define hsKeyguardFlagPowerOnDialog             0x0001  /**< Show keyguard dialog at power-on */
    00682 /*@}*/
    00683
    00684 /**
    00685  * @name Bit definitions for hsPrefTouchscreenDisableFlags
    00686  *
    00687  */
    00688 /*@{*/
    00689 #define hsTouchscreenDisableFlagIncomingCall    0x0001          /**<        */
    00690 #define hsTouchscreenDisableFlagDuringCall      0x0002      /**<        */
    00691 /*@}*/
    00692
    00693 ////////////////////////////////////////
    00694 #if 0
    00695 #pragma mark Status Gadgets
    00696 #endif
    00697 ////////////////////////////////////////
    00698
    00699 /**
    00700  * Equates for supporting system handled status gadgets
    00701  **/
    00702 typedef enum
    00703   {
    00704     hsStatusGadgetBattery = 1,          /**< Status gadget is a battery meter */
    00705     hsStatusGadgetSignal = 2            /**< Status gadget is a signal strength indicator */
    00706   } HsStatusGadgetTypeEnum;
    00707
    00708
    00709
    00710 ////////////////////////////////////////
    00711 #if 0
    00712 #pragma mark Light Manager
    00713 #endif
    00714 ////////////////////////////////////////
    00715
    00716 /**
    00717  * Light manager equates
    00718  **/
    00719
    00720 /**
    00721  * These are different modes that can be used to affect the light manager,
    00722  * which is in charge of temporary changes in the lighting situation.
    00723  **/
    00724
    00725 typedef enum
    00726   {
    00727     // Preset modes
    00728     // ------------
    00729     // These modes have saved values associated with them...
    00730     hsLightModeNormal = 0,      /**< Light mode is at normal presets */
    00731     hsLightModeNight  = 1,      /**< Light mode is at night-mode presets */
    00732
    00733     hsLightModeNumPresets,  /**< Num presets.  SUBJECT TO CHANGE. */
    00734
    00735     /** Reserved mode to force compiler to use 16-bit for enum... */
    00736     hsLightModeReserved = 0x7FFF
    00737   }
    00738 HsLightModeEnum;
    00739
    00740
    00741 /**
    00742  *  These circumstances modify the mode and allow us to handle
    00743  *  different logical circumstances on devices with different hardware.
    00744  *
    00745  *  - These are applied in the following order:
    00746  *   1. Alert woke device
    00747  *   2. keylight off
    00748  *   3. Quick typing
    00749  *   4. User not looking
    00750  *   5. User not looking for a long time
    00751  **/
    00752 typedef enum
    00753   {
    00754     hsLightCircumstanceFirst        = 0,    /**<        */
    00755     hsLightCircumstanceAlertWokeDevice  = 0,    /**< An important alert woke the  device up from sleep.*/
    00756     hsLightCircumstanceQuickTyping      = 1,    /**< We want the user to be able  to access the keyboard easily */
    00757     hsLightCircumstanceUserNotLooking   = 2,    /**< We suspect the user isn't looking at the device if they're
    00758                                  not actively using the device, so we'll dim the screen (but we don't
    00759                                                   actually want to turn it off).*/
    00760     hsLightCircumstanceUserNotLookingLongTime = 3,  /**< similar to above, but if the inactivity persists then
    00761                                we want to turn the screen off **/
    00762
    00763     hsLightCircumstanceKeylightOff      = 4,    /* turn keylight off */
    00764
    00765     hsLightCircumstanceNumCircumstances,        /**< Num circumstances.   SUBJECT TO CHANGE.*/
    00766
    00767     /**
    00768      *  Reserved circumstance to force compiler to use 16-bit for enum...
    00769      **/
    00770     hsLightCircumstanceReserved = 0x7FFF
    00771   }
    00772 HsLightCircumstanceEnum;
    00773
    00774
    00775 /**
    00776  * @name Bit Flag for Light Circumstances
    00777  *
    00778  * application may call HsCurrentLightCircumstance() to get current
    00779  * enabled light circumstances
    00780  *
    00781  * test bit to see if light circumstance is enabled or disabled
    00782  *
    00783  */
    00784 /*@{*/
    00785 #define hsLightCircumstanceAlertWokeDeviceFlagBit       0x0001      /**<        */
    00786 #define hsLightCircumstanceQuickTypingFlagBit           0x0002      /**<        */
    00787 #define hsLightCircumstanceUserNotLookingFlagBit        0x0004      /**<        */
    00788 #define hsLightCircumstanceUserNotLookingLongTimeFlagBit    0x0008      /**<        */
    00789 #define hsLightCircumstanceKeylightOffFlagBit           0x0010      /**<        */
    00790 /*@}*/
    00791
    00792 ////////////////////////////////////////
    00793 #if 0
    00794 #pragma mark Indicators
    00795 #endif
    00796 ////////////////////////////////////////
    00797
    00798 /**
    00799  *
    00800  **/
    00801 typedef enum
    00802   {
    00803     kIndicatorTypeLed,
    00804     kIndicatorTypeVibrator,
    00805
    00806     // This must be last
    00807     kIndicatorTypeCount
    00808   }
    00809 HsIndicatorTypeEnum;
    00810
    00811 /**
    00812  *  Pass a numeric count or one of these special values to HsIndicatorState()
    00813  **/
    00814 typedef enum
    00815   {
    00816     kIndicatorCountGetState = 0,        /**< retrieve the current state */
    00817     kIndicatorCountForever  = 0xFFFF    /**< run forever */
    00818   }
    00819 HsIndicatorCountEnum;
    00820
    00821
    00822 /**
    00823  * There are several different sources of turning on the indicator,
    00824  * (Charge, Signal, Ring, App) with each source being in exactly one
    00825  * state at any moment. The high byte of these enum values indicates
    00826  * the source, and the low byte indicates which state that source is
    00827  * in. Each source has a hard-coded priority, so only the indication
    00828  * of the highest priority source not in its "None" state will appear
    00829  * on the indicator. The value of the high byte does not represent
    00830  * the priority.
    00831
    00832  * A virtual state that is used to get the state that is currently
    00833  * active on the indicator (the highest priority active source). This
    00834  * value is also the result when there is no active source.
    00835  * (States with * aren't used at present)
    00836  **/
    00837 typedef enum
    00838   {
    00839
    00840     kIndicatorStateNull   = 0x0000,
    00841
    00842     kIndicatorForceNone   = 0x0100,     /**< Don't force anything */
    00843     kIndicatorForceOn     = 0x0101,     /**< Force the indicator on */
    00844     kIndicatorForceRed    = 0x0101,     /**< Force the red led on */
    00845     kIndicatorForceGreen,               /**< Force the green led on */
    00846     kIndicatorForceRedGreen,            /**< Force both leds on (orange) */
    00847     kIndicatorForceOff    = 0x0180,     /**< Force both leds off */
    00848
    00849     kIndicatorRingNone    = 0x0200,     /**< Phone not ringing */
    00850     kIndicatorRingActive,               /**< Phone ringing */
    00851     kIndicatorRingContact,              /**< *Phone ringing, CID recognized */
    00852     kIndicatorRingRoam,                 /**< *Phone ringing, roaming */
    00853
    00854     kIndicatorAlertNone   = 0x0300,     /**< Alert not active */
    00855     kIndicatorAlertAlert,               /**< Generic alert */
    00856     kIndicatorAlertMail,                /**< Incoming mail */
    00857     kIndicatorAlertCalendar,            /**< Datebook alarm */
    00858     kIndicatorAlertSMS,                 /**< Incoming SMS */
    00859     kIndicatorAlertVoicemail,           /**< Voicemail waiting */
    00860     kIndicatorAlertPending,             /**< Attention alert pending */
    00861
    00862     kIndicatorBattNone    = 0x0400,     /**< Not connected to a charger */
    00863     kIndicatorBattCharge,               /**< Battery is charging */
    00864     kIndicatorBattTrickle,              /**< Battery is topping off */
    00865     kIndicatorBattFull,                 /**< Battery is fully charged */
    00866     kIndicatorBattLow,                  /**< *Battery is low (and not on a charger) */
    00867
    00868     kIndicatorUsageNone   = 0x0600,     /**< Not in use */
    00869     kIndicatorUsageVoiceCall,           /**< Phone on an active voice call */
    00870     kIndicatorUsageDataCall,            /**< Phone on an active data call */
    00871
    00872     kIndicatorSignalNone  = 0x0500,         /**< Radio turned off */
    00873     kIndicatorSignalBad,                /**< Out of coverage */
    00874     kIndicatorSignalGood,               /**< In coverage */
    00875     kIndicatorSignalRoam                /**< *In coverage, roaming */
    00876   }
    00877 HsIndicatorStateEnum;
    00878
    00879
    00880 ////////////////////////////////////////
    00881 #if 0
    00882 #pragma mark Company / HAL / Device IDs
    00883 #endif
    00884 ////////////////////////////////////////
    00885
    00886 // These constants can be used to tell one device from another...
    00887 //
    00888 // See the following, in Palm's SystemMgr.h:
    00889
    00890 // #define  sysFtrNumOEMCompanyID           20  // GHwrOEMCompanyID value       (PalmOS 3.5)
    00891 // #define  sysFtrNumOEMDeviceID            21  // GHwrOEMDeviceID value        (PalmOS 3.5)
    00892 // #define  sysFtrNumOEMHALID               22  // GHwrOEMHALID value           (PalmOS 3.5)
    00893
    00894
    00895 // Company ID
    00896 // ----------
    00897
    00898 // This is defined in HwrMiscFlags.h already...
    00899 // #define hwrOEMCompanyIDHandspring    'hspr'  // Devices made by Handspring
    00900
    00901
    00902 /**
    00903  * @name HAL IDs
    00904  *   Handspring generally doesn't differentiate different HALs and uses the same
    00905  *   ID in multiple places...  Use the device ID to figure out which devide you're
    00906  *   on.  If you're looking to see which version of HsExtensions is available, see
    00907  *   the HsExtensions feature (hsFtrIDVersion)...
    00908  */
    00909 /*@{*/
    00910 #define hsHALIDHandspringOs35_40      'Hs01'    /**< Used by all Handspring OS 3.5 HALs and 4.0 HALs */
    00911
    00912 #define hsHALIDHandspringOs5Rev1      'H5_1'    /**< Used by Handspring's 5.0 HALs */
    00913 #define hsHALIDHandspringOs5Rev1Sim   'H5s1'    /**< Used by Handspring's 5.0 Simulator HALs */
    00914
    00915 #define hsHALIDHandspringOs5Rev2      'H5_2'    /**< Used by Handspring's 5.2 HALs */
    00916 #define hsHALIDHandspringOs5Rev2Sim   'H5s2'    /**< Used by Handspring's 5.2 Simulator HALs */
    00917
    00918 #define hsHALIDHandspringOs5Rev3      'P052'    /**< Used by Handspring's 5.3 HALs */
    00919 #define hsHALIDHandspringOs5Rev3Sim   'S052'    /**< Used by Handspring's 5.3 Simulator HALs */
    00920
    00921 #define hsHALIDHandspringOs5Rev4      'P053'    /**< Used by Handspring's 5.4 HALs */
    00922 #define hsHALIDHandspringOs5Rev4Sim   'S053'    /**< Used by Handspring's 5.4 Simulator HALs */
    00923 /*@}*/
    00924
    00925 /**
    00926  * @name Device IDs
    00927  *   Older devices don't use 4-character constants; newer devices do.  Sometimes
    00928  *   devices will have the same ID if they are extremely similar.  You may need
    00929  *   to use alternate means to differentiate between such products.
    00930  */
    00931 /*@{*/
    00932 #define hsDeviceIDVisor           0x00      /**< Visor, Visor Deluxe */
    00933 #define hsDeviceIDVisorPlatinum   0x08          /**< Visor Platinum, some Visor Neos */
    00934 #define hsDeviceIDVisorEdge       0x09      /**< Visor Edge */
    00935 #define hsDeviceIDVisorPrism      0x0A          /**< Visor Prism */
    00936 #define hsDeviceIDTreo180         0x0B      /**< Treo 180 */
    00937 #define hsDeviceIDTreo270         0x0D      /**< Treo 270 */
    00938 #define hsDeviceIDTreo300         0x0E      /**< Treo 300 */
    00939 #define hsDeviceIDVisorNeo        0x8A      /**< Visor Neo (some Neos may have 0x08) */
    00940 #define hsDeviceIDVisorPro        0x8B      /**< Visor Pro */
    00941 #define hsDeviceIDTreo90          0x8C      /**< Treo 90 */
    00942 /*@}*/
    00943
    00944 // kPalmOneDeviceID constants defined in palmOneResources.h.  From now on device IDs should
    00945 //  be defined there.
    00946
    00947 #define hsDeviceIDTreo600         kPalmOneDeviceIDTreo600   /**< Treo 600 */
    00948 #define hsDeviceIDTreo600Sim      kPalmOneDeviceIDTreo600Sim        /**< Treo 600 Simulator */
    00949
    00950 // For backward compatibility
    00951 #define hsDeviceIDOs5Device1      kPalmOneDeviceIDTreo600
    00952 #define hsDeviceIDOs5Device1Sim   kPalmOneDeviceIDTreo600Sim
    00953
    00954
    00955 // Sample code
    00956 // -----------
    00957
    00958 // To use this to detect Handspring devices, do something like:
    00959 //  {
    00960 //    UInt32 company = 0, deviceID = 0;
    00961 //
    00962 //    FtrGet (sysFtrCreator, sysFtrNumOEMCompanyID, &company);
    00963 //    FtrGet (sysFtrCreator, sysFtrNumOEMDeviceID, &deviceID);
    00964 //
    00965 //    if ((company == hwrOEMCompanyIDHandspring) && (deviceID == hsDeviceIDOs5Device1))
    00966 //      {
    00967 //        ...
    00968 //      }
    00969 //  }
    00970 //
    00971 // To check for Handspring devices in general and to get the versions
    00972 // of HsExtensions, use something like:
    00973 //  {
    00974 //    UInt32 version = 0;
    00975 //
    00976 //    FtrGet (hsFtrCreator, hsFtrIDVersion, &version);
    00977 //    if (version >= 0x05000000)
    00978 //      {
    00979 //        ...
    00980 //      }
    00981 //  }
    00982
    00983 #endif    // __HS_EXT_COMMON_H__

Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:06:53 2008 for Palm API Guide