Share via


Using the PhCommon Core Component (Windows Embedded CE 6.0)

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.

Ee501574.note(en-US,WinEmbedded.60).gifNote:
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.

Ee501574.collapse(en-US,WinEmbedded.60).gifUsage 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:

  1. It contains only TextDisplayItems
  2. 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.

Ee501574.collapse(en-US,WinEmbedded.60).gifTesting 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.
Ee501574.note(en-US,WinEmbedded.60).gifNote:
  • 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.

See Also

Reference

PhCommon Reference

Concepts

VoIP Application Development
IP Phone Suite

Other Resources

Customizing the Supplied UI