Palm PDK Library

The PDK comes with the Palm Development Library (PDL), a library of function calls that extend SDL capabilities specifically for Palm devices.

To use the PDK Library in your code:

Note:

Though they have no effect if invoked, PDL calls can not be used on the desktop.

Palm Development Library Data Structures

You can find the code for the data types and structures described here in PDL_types.h.

On Windows, you can find this file at:

C:\Program Files\Palm\PDK\include\PDL_types.h

In this section:

  • Defines
  • Enums
  • Enum Arrays
  • Typedefs
  • Structs

Defines

Name Value Description
PDL_FALSE SDL_FALSE Provided for consistent naming.
PDL_TRUE SDL_TRUE Provided for consistent naming.
CALLBACK_PAYLOAD_MAX 1024 Maximum size of buffer that can be passed from a JavaScript function to a Plug-in app's registered JS handler function.
PDL_GPS_UPDATE 0xE100 The user event code for a GPS event. For a GPS event, the event type will be SDL_USEREVENT . The event union's user.code value is PDL_GPS_UPDATE. The event union's user.data1 is a pointer to a PDL_Location structure.
PDL_GPS_FAILURE 0xE101 Event sent for a GPS system failure. In this case, the event union's user.data1 is a PDL_Err * cast you can dereference to find the PDL_Err code.

For example:
PDL_Err err = *(PDL_Err *)Event.user.data;
PDL_VERSION_STR_SIZE 256 Maximum length of the full webOS version string in the PDL_OSVersion struct.
PDLKey PDL_key Provided for backward compatability.
PDLNETinfo PDL_NetInfo Provided for backward compatability.

Enums

Name Value Description
PDLK_GESTURE_AREA 231 Returned as a key event when the user touches anywhere in the gesture area, which is the black area extending from the bottom of the screen to halfway down the Center button (or where the Center button would be).
PDLK_GESTURE_BACK 27 Returned as a key event when the user swipes from right to left anywhere in the gesture area.
PDLK_GESTURE_FORWARD 229 Returned as a key event when the user swipes from left to right anywhere in the gesture area.

Enum Arrays

Name Description APIs
PDL_Err Enums used to indicate PDL API calls' success or failure and failure reason.
  • PDL_BannerMessagesEnable
  • PDL_CustomPauseUiEnable
  • PDL_EnableLocationTracking
  • PDL_GesturesEnable
  • PDL_GetAppinfoValue
  • PDL_GetCallingPath
  • PDL_GetCompass
  • PDL_GetDataFilePath
  • PDL_GetDeviceName
  • PDL_GetLanguage
  • PDL_GetLocation
  • PDL_GetNetInfo
  • PDL_GetOSVersion
  • PDL_GetRegionCountryCode
  • PDL_GetRegionCountryName
  • PDL_GetUniqueID
  • PDL_Init
  • PDL_LaunchBrowser
  • PDL_LaunchEmail
  • PDL_LaunchEmailTo
  • PDL_JSException
  • PDL_JSRegistrationComplete
  • PDL_JSReply
  • PDL_Minimize
  • PDL_NotifyMusicPlaying
  • PDL_RegisterJSHandler
  • PDL_ScreenTimeoutEnable
  • PDL_ServiceCall
  • PDL_ServiceCallWithCallback
  • PDL_SetFirewallPortStatus
  • PDL_SetOrientation
  • PDL_SetTouchAggression
  • PDL_UnregisterServiceCallback
  • PDL_Vibrate
PDL_Orientation Enums used for setting the alignment of pop-up alerts and banner. PDL_SetOrientation
PDL_TouchAggression Enums used for setting the device's touch aggression. PDL_SetTouchAggression

PDL_Err

Array of enums used to indicate API calls' success or failure and failure reason.

Note:

For failure responses, use the PDL_GetError API to retrieve a text message containing more information about the error.

Name Value Description
PDL_NOERROR 0 No error.
PDL_EMEMORY 1 Memory error.
PDL_ECONNECTION 2 Connection error.
PDL_INVALIDINPUT 3 Something was wrong with one or more passed parameters.
PDL_EOTHER 4 Unspecified error.
PDL_UNINIT 5 A needed initialization function was not called, e.g., PDL_EnableLocationTracking was not called before calling PDL_GetLocation.
PDL_NOTALLOWED 6 A non-configured option prevents success, e.g., the user has disabled Location Services, which prevents GPS from working (see PDL_GetLocation).
PDL_LICENSEFAILURE 7 Indicates the device does not have a valid license for the application. See PDL_isAppLicensedForDevice.
PDL_STRINGTOOSMALL 8 Passed string is too small to hold returned value.
PDL_SYSTEMERROR_FILE 9 Could not access the internal Luna preferences database.
PDL_SYSTEMERROR_NET 10 Could not access network information.
PDL_APPINFO 11 The appinfo.json file was not found.

PDL_Orientation

Array of enums used for setting the alignment of pop-up alerts and banner messages.

Name Value Description
PDL_ORIENTATION_0 0 Indicates center button is below screen.
PDL_ORIENTATION_90 1 Indicates center button is to screen's left.
PDL_ORIENTATION_180 2 Indicates center button is above screen.
PDL_ORIENTATION_270 3 Indicates center button is to screen's right.

PDL_TouchAggression

Array of enums used for setting the device's touch aggression.

Name Value Description
PDL_AGGRESSION_LESSTOUCHES 0 The device is more likely to interpret indistinct input as single-touches than multi-touches. This is the default.
PDL_AGGRESSION_MORETOUCHES 1 The device is more likely to interpret indistinct input as multi-touches than single-touches.

Typedefs

Type Defines Description
PDL_ServiceParameters struct PDL_ServiceParameters A hidden and internally managed type passed as a parameter to a callback function. The callback function is passed as a parameter to PDL_ServiceCallWithCallback.
PDL_JSParameters struct PDL_JSParameters A hidden and internally managed type used when a JS app calls a registered JS handler function.
PDL_ServiceCallbackFunc PDL_bool (PDL_ServiceParameters *params, void *user) The required function signature for a callback function passed to PDL_ServiceCallWithCallback.
PDL_JSHandlerFunc PDL_bool (PDL_JSParameters *params) The function signature for a Plug-in app function registered as a JavaScript handler with PDL_RegisterJSHandler.
PDL_bool SDL_bool Provided for consistent naming.
PDL_key SDLKey Provided for consistent naming.
PDL_NetInfo struct _PDL_NetInfo Provided for backward compatibility.

Structs

Name Description APIs
PDL_Compass Used to contain magnetic and true north bearings. PDL_Compass
PDL_Location Used to contain GPS latitude and longitude information. PDL_GetLocation
PDL_NetInfo Used to store information about a particular network interface (e.g., eth0). On Windows, only the IP address is populated. PDL_GetNetInfo
PDL_ScreenMetrics Used to contain data about the device's screen metrics. PDL_GetScreenMetrics
PDL_OSVersion Used to contain data about the device's webOS version. PDL_GetOSVersion

PDL_Compass

Struct containing magnetic and true north bearings.

Name Type Description
confidence int 0-100. Bearing confidence rating.
magneticBearing double Magnetic north bearing.
trueBearing double True north bearing.

PDL_Location

Struct containing latitude and longitude information.

Name Type Description
latitude double Set to -1 if unknown.
longitude double Set to -1 if unknown.
altitude double Set to -1 if unknown.
horizontalAccuracy double In meters; set to -1 if unknown.
verticalAccuracy double In meters; set to -1 if unknown.
heading double Travel compass direction; set to -1 if unknown.
velocity double Velocity in meters per second; set to -1 if unknown.

PDL_NetInfo

Struct used to store information about a particular network interface (e.g., eth0). On Windows, only the IP address is populated.

Name Type Description
ipaddress Uint32 IP address.
netmask Uint32 A 32-bit mask that divides an IP address into subnets and specifies the network's available hosts.
broadcast Uint32 A network address that allows information to be sent to all nodes on a network.

PDL_ScreenMetrics

Struct used to contain data about the device's screen metrics.

Name Type Description
horizontalPixels int Number of pixels horizontally.
verticalPixels int Number of pixels vertically.
horizontalDPI int Number of pixels per inch horizontally.
verticalDPI int Number of pixels per inch vertically.
aspectRatio double horizontalDPI / verticalDPI.

PDL_OSVersion

Struct used to contain data about the device's webOS version.

Name Type Description
majorVersion int The webOS major version number. If the version is "1.4.5", then this value will be 1.
minorVersion int The webOS minor version number. If the version is "1.4.5", then this value will be 4.
revision int The webOS revision number. If the version is "1.4.5", then this value will be 5.
versionStr string The full webOS version as a string, added in case it contains more than 3 numbers. For example: "Palm WebOS 1.4.5.1".