# 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:

- Have an `#include "PDL.h` line in your source file. For more information on the calls included in `PDL.h`, see Plug-in APIs.

- Link with `"-- lpdl"`. The `libpdl.so` file can be found in your PDK's `/lib` directory.

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