Palm PDK Library

The PDK comes with the Palm Development Library (PDL), a library of function calls that extend SDL capabilities specifically for webOS 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

On Windows, you can find these files in the PDK include directory, for example: 

C:\Program Files\HP webOS\PDK\include\PDL_types.h

In this section:

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.
HARDWARE_UNKNOWN -1 Unknown hardware
HARDWARE_PRE 101 Pre
HARDWARE_PRE_PLUS 102 Pre Plus
HARDWARE_PIXI 201 Pixi and Pixi Plus
HARDWARE_VEER 301 Veer
HARDWARE_PRE_2 401 Pre2
HARDWARE_PRE_3 501 Pre3
HARDWARE_TOUCHPAD 601 TouchPad
HARDWARE_TOUCHPAD_GO 701 TouchPad GO
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_COMPASS 0xE110 The user event code for a compass event. You can identify a compass event with this. The event type is SDL_USEREVENT. The event union's user.code value will be PDL_COMPASS. The event union's user.data1 will be a pointer to a PDL_Compass structure.
PDL_PENDING_JSS 0xE120 The user event code that means there are queued downstream JS calls pending. Your app should call PDL_HandleJSCalls to respond to this. The event type is SDL_USEREVENT. The event union's user.code value will be PDL_PENDING_JS. There is no data associated with this event.
PDL_VERSION_STR_SIZE 256 Maximum length of the full webOS version string in the PDL_OSVersion struct.
PDLKey PDL_key Provided for backward compatibility.
PDLNETinfo PDL_NetInfo Provided for backward compatibility.

Sensor Defines

These defines are used to set the value for a variable of type PDL_SensorType.

Name Value Description
PDL_SENSOR_NONE (-1) Unknown sensor
PDL_SENSOR_ACCELEROMETER 0 Accelerometer sensor
PDL_SENSOR_COMPASS 1 Compass sensor
PDL_SENSOR_ALS 2 Ambient light sensor
PDL_SENSOR_ANGULAR_VELOCITY 3 Angular velocity sensor
PDL_SENSOR_GRAVITY 4 Gravity sensor
PDL_SENSOR_LINEAR_ACCELERATION 5 Linear acceleration sensor
PDL_SENSOR_MAGNETIC_FIELD 6 Magnetic field sensor
PDL_SENSOR_ORIENTATION 7 Orientation sensor
PDL_SENSOR_PROXIMITY 8 Proximity sensor
PDL_SENSOR_ROTATION 9 Rotation sensor
PDL_SENSOR_SHAKE 10 Shake sensor


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.
PDLK_GESTURE_DISMISS_KEYBOARD 24 Returned as a key event on the TouchPad when the user dismisses the keyboard.


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_EnableCompass
  • PDL_EnableLocationTracking
  • PDL_EnableSensor
  • 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_PollActiveSensors
  • PDL_PollSensor
  • PDL_RegisterJSHandler
  • PDL_RegisterPollingJSHandler
  • PDL_ScreenTimeoutEnable
  • PDL_ServiceCall
  • PDL_ServiceCallWithCallback
  • PDL_SetAutomaticSoundPausing
  • 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_OGLVersion Enums used to dynamically open a specific OpenGL version. PDL_LoadOGL

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_ESTATE 12 The system's runtime state does not allow the attempted operation.

PDL_OGLVersion

Enums used to dynamically open a specific OpenGL version.

Name Value Description
PDL_OGL_1_1 0 OpenGL version 1.1.
PDL_OGL_2_0 1 OpenGL version 2.0.

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.
PDL_ItemInfo struct PDL_ItemInfo Used for purchases.
PDL_ItemCollection struct PDL_ItemCollection Used for purchases.
PDL_SensorType Sint32 Used for sensor type defines (see sensor defines section). For the PDK APIs it is used to either detect or enable a particular sensor or identify one for a sensor event.


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".

Sensor Structs

PDL_AccelerometerEvent

Struct returned for a PDL_SENSOR_ACCELEROMETER event.

Each axis value returned measures direction and force. A zero result for a specific axis means there is no force acting on the accelerometer. For example, if you set the device flat on a table, the X and Y axes will measure at, or close to, zero. As you tilt the device left, the X-axis acceleration becomes increasingly negative. If you then center it and tilt it right, it becomes increasingly positive. 

typedef struct
{
        PDL_SensorType type;
        float32 x;
        float32 y;
        float32 z;
} PDL_AccelerometerEvent;
Field Type Description
type PDL_SensorType PDL_SENSOR_ACCELEROMETER (0)
x float32 Acceleration value for x-axis as a fraction of "g"
y float32 Acceleration value for y-axis as a fraction of "g"
z float32 Acceleration value for z-axis as a fraction of "g"

PDL_ALSEvent

Struct returned for a PDL_SENSOR_ALS event.

An ALS event returns the ambient light level in SI lux units, a measure of a surface's luminosity. One lux is equal to one lumen per square meter. Office lighting typically measures between 320-500 lux. 

typedef struct
{
        PDL_SensorType type;
        Sint32 lux;
} PDL_ALSEvent;
Field Type Description
type PDL_SensorType PDL_SENSOR_ALS (2)
lux Sint32 Ambient light level in SI lux units, a measure of a surface's luminosity. One lux is equal to one lumen per square metre. Office lighting typically measures between 320-500 lux.

PDL_AngularVelocityEvent

Struct returned for a PDL_SENSOR_ANGULAR_VELOCITY event.

The angular velocity sensor returns a vector quantity specifying the angular speed of a device and the axis about which the device is rotating. Angular velocity around each axis is returned in radians per second. 

typedef struct
{
        PDL_SensorType type;
        float32 x;
        float32 y;
        float32 z;
} PDL_AngularVelocityEvent;
Field Type Description
type PDL_SensorType PDL_SENSOR_ANGULAR_VELOCITY (3)
x float32 Angular velocity around x-axis in radians per second.
y float32 Angular velocity around y-axis in radians per second.
z float32 Angular velocity around z-axis in radians per second.

PDL_CompassEvent

Struct returned for a PDL_SENSOR_COMPASS event.

The compass sensor returns magnetic north and true north bearings. 

typedef struct
{
        PDL_SensorType type;
        float32 magnetic;
        float32 trueBearing;
        float32 confidence;
} PDL_CompassEvent;
Field Type Description
type PDL_SensorType PDL_SENSOR_COMPASS (1)
magnetic float32 Magnetic north bearing in degrees.
trueBearing float32 True north bearing in degrees.
confidence float32 Bearing confidence rating percentage (0-100). Confidence is less than 100% if the magnetic environment changes significantly in a short amount of time. Confidence increases to 100% as the device rotates around a bit in its new environment.

PDL_GravityEvent

Struct returned for a PDL_SENSOR_GRAVITY event.

This struct contains a three-dimensional vector indicating the direction and magnitude of gravity. Units are m/s^2 (meters per second squared). The coordinate system is the same as that used by the accelerometer. 

typedef struct
{
        PDL_SensorType type;
        float32 x;
        float32 y;
        float32 z;
} PDL_GravityEvent;
Field Type Description
type PDL_SensorType PDL_SENSOR_GRAVITY (4)
x float32 Gravitational acceleration unit vector x component
y float32 Gravitational acceleration unit vector y component
z float32 Gravitational acceleration unit vector z component

PDL_LinearAccelerationEvent

Struct returned for a PDL_SENSOR_LINEAR_ACCELERATION event.

This struct contains a three dimensional vector indicating acceleration along each device axis, not including gravity. All values have units of m/s^2 (meters per second squared).

The output of the accelerometer, gravity and linear-acceleration sensors has the following relation: 

acceleration = gravity + linear-acceleration

Data points for two reference frames are provided:

  1. Regular coordinate values in a body reference frame
  2. World coordinate values in a world reference frame.

Both of these measure acceleration with gravity removed. 

typedef struct
{
        PDL_SensorType type;
        float32 x;
        float32 y;
        float32 z;
        float32 worldX;
        float32 worldY;
        float32 worldZ;
} PDL_LinearAccelerationEvent;
Field Type Description
type PDL_SensorType PDL_SENSOR_LINEAR_ACCELERATION (5)
x float32 Acceleration value for x-axis in meters per second squared.
y float32 Acceleration value for y-axis in meters per second squared.
z float32 Acceleration value for z-axis in meters per second squared.
worldX float32 World coordinate acceleration value for x-axis in meters per second squared.
worldY float32 World coordinate acceleration value for y-axis in meters per second squared.
worldZ float32 World coordinate acceleration value for z-axis in meters per second squared.

PDL_MagneticFieldEvent

Struct returned for a PDL_SENSOR_MAGNETIC_FIELD event.

This struct contains data that measure the ambient magnetic field in the X, Y and Z axes. All values are in micro Teslas (uT).

Two types of values are returned:

Raw axis values are what the magnetometer is reading without any other math applied. In other words, this is the actual magnetic field that the magnetometer sees. The regular values have had any bias and offsets removed so that the values are centered around (0,0,0). 

typedef struct
{
        PDL_SensorType type;
        float32 x;
        float32 y;
        float32 z;
        float32 rawX;
        float32 rawY;
        float32 rawZ;
} PDL_MagneticFieldEvent;
Field Type Description
type PDL_SensorType PDL_SENSOR_MAGNETIC_FIELD (6)
x float32 Magnetic field strength for x-axis in micro Teslas (uT).
y float32 Magnetic field strength for y-axis in micro Teslas (uT).
z float32 Magnetic field strength for z-axis in micro Teslas (uT).
rawX float32 Raw magnetic field strength for x-axis in micro Teslas (uT).
rawY float32 Raw magnetic field strength for y-axis in micro Teslas (uT).
rawZ float32 Raw magnetic field strength for z-axis in micro Teslas (uT).

PDL_OrientationEvent

Struct returned for a PDL_SENSOR_ORIENTATION event.

An orientation event gives the device's general position - face up, face down, upside down, etc. 

typedef struct
{
    PDL_SensorType type;
    Sint32 orientation;
} PDL_OrientationEvent;
Field Type Description
type PDL_SensorType PDL_SENSOR_ORIENTATION (7)
orientation Sint32
  • 0 - Unknown orientation
  • 1 - Facing up
  • 2 - Facing down
  • 3 - Normal orientation
  • 4 - Upside-down
  • 5 - Left-side facing down
  • 6 - Right-side facing down

PDL_ProximityEvent

Struct returned for a PDL_SENSOR_PROXIMITY event.

This struct contains data about one of two events:

  1. An object is close to the device (one inch or less)
  2. A close object has moved away from the device

For example, the Phone app uses the proximity sensor value to turn the screen off when a person holds the phone close to their face. This is done to prevent the user from accidentally pressing buttons with their cheek while talking on the phone. 

typedef struct
{
        PDL_SensorType type;
        Sint32 presence;
} PDL_ProximityEvent;
Field Type Description
type PDL_SensorType PDL_SENSOR_PROXIMITY (8)
presence Sint32
  • 0 - Close object not detected
  • 1 - Close object detected

PDL_RotationEvent

Struct returned for a PDL_SENSOR_ROTATION event.

This struct contains three roughly equivalent sets of numbers - a rotation matrix, a quaternion, and a set of Tait-Bryan angles. Each can be used to represent an object's rotation. It is up to you to decide which set you want to use for rotation.

In linear algebra, a rotation matrix is a matrix that is used to perform a rotation in Euclidean space.

A quaternion represents two things. It has an x, y, and z component, which represents the axis about which a rotation will occur. It also has a w component, which represents the amount of rotation that will occur about this axis or, in short, a vector, and a float. With these four numbers, it is possible to build a matrix which that represents all the rotations perfectly, with no chance o gimbal lock.

Tait-Bryan angles are three angles that describe device orientation. These angles are also known as "yaw", "pitch" and "roll" and are used in conventional flight dynamics. 

typedef struct
{
        PDL_SensorType type;
        float32 matrix[9];
        float32 quatW;
        float32 quatX;
        float32 quatY;
        float32 quatZ;
        float32 yaw;
        float32 pitch;
        float32 roll;
} PDL_RotationEvent;
Field Type Description
type PDL_SensorType PDL_SENSOR_ROTATION (9)
martix[] float32 array A matrix used to perform a rotation in Euclidean space. All matrix values are in the range of -1 to 1.
quatW float32 The W component of the quaternion.
quatX float32 The X component of the quaternion.
quatY float32 The Y component of the quaternion.
quatZ float32 The Z component of the quaternion.
yaw float32 Amount of yaw in degrees.
pitch float32 Amount of pitch in degrees.
roll float32 Amount of roll in degrees.

PDL_ShakeEvent

Struct returned for PDL_SENSOR_SHAKE event.

Shaking starts above 1.3 g's and stops at 1.1 g's. 

typedef struct
{
        PDL_SensorType type;
        Sint32 state;
        float32 magnitude;
} PDL_ShakeEvent;
Field Type Description
type PDL_SensorType PDL_SENSOR_SHAKE (10)
state Sint32
  • 0 - Device is not shaking.
  • 1 - Device has started shaking.
  • 2 - Device continues to shake.
  • 3 - Device has stopped shaking.
magnitude float32 How vigorous the shaking is in units of gravitational acceleration or g's.

PDL_SensorEvent

Struct used for all sensor events.

This struct is a union of all possible sensor type event structs. The PDL_PollSensor and PDL_PollActiveSensors APIs return this struct for a sensor event. 

typedef union PDL_SensorEvent
{
        PDL_SensorType                 type;
        PDL_AccelerometerEvent         accelerometer;
        PDL_CompassEvent               compass;
        PDL_ALSEvent                   als;
        PDL_AngularVelocityEvent       angularVelocity;
        PDL_GravityEvent               gravity;
        PDL_LinearAccelerationEvent    linearAcceleration;
        PDL_MagneticFieldEvent         magneticField;
        PDL_OrientationEvent           orientation;
        PDL_ProximityEvent             proximity;
        PDL_RotationEvent              rotation;
        PDL_ShakeEvent                 shake;
        unsigned char                  reserved[128];
} PDL_SensorEvent;
Field Type Description
type PDL_SensorType Sensor type - compass, accelerometer, gyro, etc.
accelerometer PDL_AccelerometerEvent Accelerometer event struct
compass PDL_CompassEvent Compass sensor event struct
als PDL_ALSEvent Ambient light sensor event struct
angularVelocity PDL_AngularVelocityEvent Angular velocity sensor event struct
gravity PDL_GravityEvent Gravity sensor event struct
linearAcceleration PDL_LinearAccelerationEvent Linear acceleration sensor event struct
magneticField PDL_MagneticFieldEvent Magnetic field sensor event struct
orientation PDL_OrientationEvent Orientation sensor event struct
proximity PDL_ProximityEvent Proximity sensor event struct
rotation PDL_RotationEvent Rotation sensor event struct
shake PDL_ShakeEvent Shake event struct
reserved[128] unsigned char array Field used to standardize size of return object.
Includes room for future expansion.