PDL

From WebOS101

Contents 1 Introduction 2 Using the PDL 3 Defines, Structures, Enums and More 3.1 Defines 3.2 Enums 3.3 Enum Arrays 3.3.1 PDL_Err 3.3.2 PDL_Orientation 3.3.3 PDL_TouchAggression 3.4 Typedefs 3.5 Structs 3.5.1 PDL_Location 3.5.2 PDL_NetInfo 3.5.3 PDL_ScreenMetrics 3.5.4 PDL_OSVersion 4 External Resources

Introduction

The PDL, or Palm Development Library (or PDK Library), extends the SDL to give access to Palm-specific features. For more information on the calls included in PDL.h, see PDK APIs.

Using the PDL

To use the PDK Library in your code:

1. Include the PDL header file in your source code:

   #include "PDL.h"

2. Link the PDL library file when linking your app. For gcc, add:

   –lpdl

   The libpdl.so file can be found in your PDK installation's /lib directory.

Defines, Structures, Enums and More

The following are defined in PDL.h and are useful in your applications:

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_GetDataFilePath PDL_GetDeviceName PDL_GetLanguage PDL_GetLocation PDL_GetNetInfo PDL_GetUniqueID PDL_Init PDL_LaunchBrowser PDL_LaunchEmail PDL_JSException PDL_JSRegistrationComplete PDL_JSReply PDL_NotifyMusicPlaying PDL_RegisterJSHandler PDL_ScreenTimeoutEnable PDL_ServiceCall PDL_ServiceCallWithCallback PDL_SetFirewallPortStatus PDL_SetOrientation PDL_UnregisterServiceCallback PDL_GetNetInfo PDL_GetOSVersion PDL_SetTouchAggression
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, i.e., PDL_EnableLocationTracking was not called before calling PDL_GetLocation.
PDL_NOTALLOWED	6	A non-configured option prevents success, i.e., The user has disabled Location Services which prevents GPS from working (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 singles-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 comptability.

Structs

Name	Description	APIs
PDL_Location	Used to contain GPS latitude and longitude information.	PDL_GetLocation
PDL_NetInfo	Used to store information about a particular network interface (i.e., 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_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 (i.e., 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 networks 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".

External Resources

• PDK - PDL Intro