Using the PhCommon Core Component (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/2010

PhCommon is a dll (PhCommon.dll) that implements the common control and User Interface (UI) functionality. It ensures that all client (CE 6.0 and custom OEM) applications have a consistent user experience (shared bitmaps, colors, dialog layout etc). It also exposes the APIs of the other IP Phone Suite components. This enables centralized access to tasks that are common across all client applications.

APIs Exposed by the PhCommon Core Component

The following table lists the APIs that are exposed by PhCommon.dll.

For more information, please see PhCommon Reference.

Component	API
PhCommon Controls	PHInitCommonControls
	PHUnInitCommonControls
	PHDrawBackground
	PHMenuScreen
	PHMessageBox
	PHCreateTextDisplayItem
	PHDialogScreen
	PHRegisterSingletonApplication
	PHCreateLabeledEditDisplayItem
	PHGetColor
	PHGetFont
Provisioning API	PHProcessProvisionXML
	PHValidateProvisionXM
Database API	PHInitCallLogDB
	PHInitCallerInfoDB
Phone API	PHMakePhoneCall
	PHOnHookDialing
AddSpeedDial API	PHAddSpeedDialEntry
Settings API	PHGetSetting
	PHSetValue
	PHGetVolumeSettings
	PHSetVolume
	PHGetActiveVolume
	PHSetActiveVolume
Command API	PHGetAppWindow
	PHLaunchProcess
	PHSendCommandLine
Authentication API	PHAuthenticateUser
	PHCancelAuthenticationRequest
	PHWritePIN
	PHReadPIN

COMMON UI CONTROLS

The VoIP Common Controls are a set of Win32 custom controls supported by PhCommon. The controls are designed to facilitate application development (either internal applications or OEM custom applications) with a consistent UI design.

In various cases, the controls subclass the default OS Controls and Common Controls to offer custom rendering as well as more specific behavior. The controls offer a flexible user interface experience by supporting a "skinnable" UI (metrics, fonts, background and text colors) through a replaceable resource file.

The following list shows the controls supported by the PhCommon library:

VoIP Common Control	Class Name
Edit	WNDCLASS_EDIT
Menu Bar	WNDCLASS_MENUBAR
Menu Button	WNDCLASS_MENUBUTTON
Popup Menu	WNDCLASS_POPUPMENU
Status Header	WNDCLASS_STATUSHEADER
Tool Tip	WNDCLASS_TOOLTIP
Track Bar	WNDCLASS_TRACKBAR

Wrappers for the controls are defined to aid the manipulation of the controls (for example, send messages to add items, get items, insert menus, etc). The complete definition can be found under \private\voip\new\inc\Controls.hpp.

A set of PhCommon APIs are also supported. The following list shows the supported API.

For more information about all the PhCommon APIs, please see the PhCommon Reference.

API	Description
PHInitCommonControls	Used to register the VoIP Common Controls and initialize default set of Common Controls
PHUnInitCommonControls	Used to clean up any resources used by PhCommon.dll
PHDrawBackground	Used to draw a gradient background within the desired rectangle
PHMenuScreen	Displays a modal / modeless Menu Screen dialog. Note: this is a special case of dialog screen which contains only TextDisplayItems
PHMessageBox	Used to display a modal / modeless popup Message dialog box
PHCreateTextDisplayItem	This function creates a textual display item for use in a listbox control, including a tooltip, if necessary.
PHDialogScreen	Display a modal / modeless Dialog Screen
PHRegisterSingletonApplication	Used to ensure there is only one instance of a given app running at a time
PHCreateLabeledEditDisplayItem	This function creates a labeled edit control, including a tooltip, if necessary.
PHGetColor	This function retrieves the specified color from the resources.
PHGetFont	This function retrieves the specified font from the GDI cache.

Usage Recommendations

Linking Common Controls

To use the VoIP Common Controls in your applications you must statically link to PhCommon.lib or dynamically load PhCommon.dll.

Environment settings

set SYSGEN_VOIPPHONE_CONTROLS=1

Initialization

Before calling any other API or creating a control, an application must call PHInitCommonControls function.

Do not call PHInitCommonControls when inside DllMain.

UnInitialization

Before exiting, an application must call PHUnInitCommonControls to free any resources loaded by the current instance of PhCommon library.

Draw Background

When painting the background of your application, you must pass a rectangle which specifies the entire client area of your window.

An application usually calls PHDrawBackground in response to WM_ERASEBKGND or during WM_PAINT in case the former is intentionally disregarded. However, it can be called at any time. Its' effects should be visible as long as there is a visible region for the context used. It can also be useful to paint onto an off-screen buffer.

Dialog Screens

A Dialog Screen consists of the following set of child controls:

Status Header at the top which is used to set up a title
Virtual List Box (variable height) which serves as a container for the Menu Screen
Menu Bar with 4 available buttons

When working with a Dialog Screen, remember that a Dialog Screen is created from a predefined template. The identifiers for each control are public and are always the same for any given screen. They can be accessed via standard Win32 API.

The following example shows how to populate a list box (after calling PHDialogScreen for a modeless dialog):

.
.
ListBox_t ListBox;
ListBox = GetDlgItem(DialogScreenWindow, IDC_LISTBOX);
ListBox.AddItem(0, IVoIPDisplayItem*);
.
.

An application uses PHMenuScreen to display a menu of options for the user to select. A Menu Screen is a subtype of Dialog Screen. There are two major differences:

It contains only TextDisplayItems
The Status Header and the Title are predefined.

Message Boxes

You call PHMessageBox to create a message box. To use the default menu button bar (“Ok / Cancel”) set ButtonInfo.MenuId to zero. Otherwise, specify your own menu structure (HMENU). For Title and Text parameters you can specify null terminated strings or use the MAKEINTRESOURCE macro and pass the corresponding string resource identifiers.

Testing and Troubleshooting Recommendations

Testing

All controls can be accessed through standard win32 APIs. Existing wrappers for the controls should be reusable. However, Control window class names and control window messages may change over time.
You should be able to test a particular screen by using one of the following:
- GetForegroundWindow or GetForegroundInfo
- FindWindow by class name
- GetDlgItem and look for one of the predefined controls within Dialog / Menu Screen IDC_MENUBAR IDC_STATUSREGIONIDC_LISTBOX IDC_BUTTON1 + …
- SendMessages to the controls (.for example,. WM_GETTEXT / WM_GETTEXTLENGTH)
In order to minimize testing impact, the controls should provide backwards compatibility for all the messages used by previous tests.

Troubleshooting

Problem	Recommendation
Cannot create VoIP Common Control	Verify that the control class is registered. Verify that PHInitCommonControls was called before calling any other API or creating a control. Try probing code with the debugger.`SetLastError(0); \\ before calling CreateWindow or wrapper to create controlGetLastError(); \\ right after call to create control then see winerror.h`
Cannot load icon or text (MAKEINTRESOURCE) for Dialog / Menu Screen or Message Box	Verify that a handle to the instance of your module in was passed in the parameter list. This instance should contain the resources to be loaded. Verify that the resource was properly added to the RC file.
Text is garbled in Dialog / Menu Screen or Message Box	Verify that RCADDNULL=1.Strings passed by ID to PhCommon APIs, using the MAKEINTRESOURCE macro, must be NULL terminated.

Note:

All headers exposed to OEM applications (public\voip\oak\inc) are located under private\voip\new\inc.
The virtual List Box currently is not available. Use menu screen or the default system list box.
The resource IDs for Menu Screen and Menu Button Bar controls are exposed by ControlDefinitions.h
Currently, only TextDisplayItems are supported by PhCommon.dll.