WPI Interface Enhancements

The Wiki of Unify contains information on clients and devices, communications systems and unified communications. - Unify GmbH & Co. KG is a Trademark Licensee of Siemens AG.

Jump to: navigation, search
Family: OpenStage
Model: OpenStage 60
OpenStage 80
Relation: API/SDK related
Release: V2 R1

These are the additions to the DLS protocol for V2 R1 compared to V1R5 that are related to the new features. It is included what we did for step 2 (in V2 R0) as well as what we've done in step 3 (V2 R1). It is also included a description of XML app on FPK.

The changes fall into five separate areas: XML application configuration, assign XML application shortcut to programmable key, message waiting options, send URL, and "fixed" key programming.

For detailed information see Configurable Keys on OpenStage.

XML application configuration

There are three new tags defined; these are:

to indicate which key if any the application is associated with
to indicate whether the application is automatically started in the back-ground or only when first selected
to indicate whether all the tabs in an application start at once or only the first one

In protocol form they look like this:

<Item name="XML-app-control-key" index="NN">xx</Item>
<Item name="XML-app-auto-start" index="NN">yyyyy</Item> 
<Item name="XML-app-all-tabs-start" index="NN">yyyyy</Item>

The range of values for the index NN is the same as for all the existing XML application related items and is unchanged, i.e. from 1 to 20.

The xx value for the control key item represents an enumeration defined as follows:

  • 0 = No mode key.
    This is the default and indicates that the application is run via the applications menu.
  • 2 = Phonebook mode key.
    Application runs on the Phonebook mode key (like the existing XMLPhonebook option).
  • 3 = CallLog mode key.
    Application runs on the CallLog mode key.
  • 4 = Messages mode key.
    Application runs on the Messages mode key (like the existing Xpressions option).
  • 6 = Help mode key.
    Application runs on the Help mode key.

The values 1 and 5 are reserved for future use.

To some extent, the existing special-instance tag overlaps with the new control-key tag. We want to deprecate the special-instance tag but we need to retain it for backwards compatibility. Ideally, all applications would be specified with a special instance of normal and the new control key tag used to indicate the key to be used if the application is to run on a mode key. However, if the configuration system is to be used to configure applications on both V1R5 and V2R1 phones, then the use of special instance mist be retained in which case the following constraints apply:

If special instance is set to indicate Xpressions then the control key item must indicate Messages (i.e. value 4). Also the application name must be Xpressions.

If special instance is set to indicate XMLPhonebook then the control key item must indicate Phone-book (i.e. value 2). Also the application name must be XMLPhonebook.

No more than one application can be configured to run on the same mode key.

The yyyyy value for the all-tabs-start item and the auto-start item represents a boolean flag so should be set to true or false.

The all-tabs-start item only has meaning for applications where the number of tabs is 2 or 3.

Assign XML application shortcut to programmable key

An application can be associated with a programmable key by setting its function key def value to 60. The key can then be associated with an application by using the new tag FPK-app-name. The value associated with FPK-app-name is the application's display name (not the application name).

<Item index="1" name="function-key-def">60</Item> 
<Item index="1" name="FPK-app-name">MyApp</Item>
<Item index="1" name="key-label-unicode">MyApp</Item>

Message waiting options

The display options for Message Waiting Indication are based on the following 7 new attributes:

  • New count label
  • New urgent count label
  • Old count label
  • Old urgent count label
  • New urgent count show/hide flag
  • Old count show/hide flag
  • Old urgent count show/hide flag

These attributes specify alternative labels for the phone to use in place of the built-in labels for any (or all) of the existing four messages counts and whether for the new urgent, old and old urgent counts the count should be displayed or hidden (the new count does not have a show/hide flag because it is always shown). The items have the format:

<Item name="MWI-new-label">xxxx</Item>
<Item name="MWI-new-urgent-label">xxxx</Item>
<Item name="MWI-old-label">xxxx</Item>
<Item name="MWI-old-urgent-label">xxxx</Item>

<Item name="MWI-new-urgent-show">true</Item>
<Item name="MWI-old-show">true</Item>
<Item name="MWI-old-urgent-show">true</Item>

Where in the case of the label tags xxxx is a string of up to 17 unicode characters and in the case of the show/hide flags, the alternative value (meaning to hide the count) is "false". An empty (zero length) label indicates that the phone should use its built-in (default) label; an empty label would typically be sent to remove any previously configured alternative label.

All items are optional in that sending one item does not require the sending of any of the other items if the current settings of those other items do not need to be changed, but there is no harm in re-sending items with values identical to the values already store in the phone.

Default values for these tags should be empty strings for the label tags and true for the show tags.

Send URL

A new value for the indexed function-key-def tag is defined - this is 63 meaning send URL.

In addition the following new indexed tags are introduced to be sent to configure the necessary attrib-utes when the corresponding key is given the function-key-def value 63:

the value of this tag indicates the location of the server, e.g. or
the value of this tag indicates the protocol: 3 = http, 0 = https
the value of this tag indicates the port ID
the value of this tag indicates where the target is on the server
the value of this tag indicates the key value pair(s) associated with the re-quest
the value of this tag indicates the method used: 0 = get, 1 = post
the value of this tag indicates the user ID
the value of this tag indicates the user's password

A typical request to configure a key would also include the key-label-unicode tag (to provide a label for the key) and, if appropriate, the stimulus-led-control-uri tag if control of the key's LED is required. So, for example:

<Item index="1" name="function-key-def">63</Item> 
<Item index="1" name="key-label-unicode">Send URL</Item>
<Item index="1" name="stimulus-led-control-uri"></Item>
<Item index="1" name="send-url-address"></Item> 
<Item index="1" name="send-url-protocol">3</Item>
<Item index="1" name="send-url-port">8080</Item>
<Item index="1" name="send-url-path">webpage/checkin.html</Item>
<Item index="1" name="send-url-query">key1=value1&key2=value2</Item>
<Item index="1" name="send-url-method">1</Item>
<Item index="1" name="send-url-user-id">dave</Item> 
<Item index="1" name="send-url-passwd">password</Item>

There can also be up to three certificates associated with this feature when the protocol in use is https. The type of certificate must be a .pem file containing a single (root) CA certificate or certificate chain obtained from an appropriate authority. The tag for sending a certificate is "send-url-server-ca", which is indexed with an index value of 0, 1 or 2. For example, setting up index 0 as a single pem file:

<Item name="send-url-server-ca" index="0">-----BEGIN CERTIFICATE-----


If the item is empty, then this implies the certificate at that index is to be deleted.

"Fixed" key programming

Apart from the "key-functionality" item described below, there are no extra protocol items for this, what we have done is introduced new index values so that the current tags used for programming FPKs can be associated with some of the other keys on the phone. The new index values are:

  • Release key - index 4001
  • Forwarding key - index 4002
  • Voice dial key - index 4003
  • Redial key - index 4009

These keys can then be programmed similarly to the FPKs by sending a function-key-def tag for the index with the appropriate value, and then accompanying this with the tags associated with the fea-ture indicated by the function-key-def value.

However, unlike FPKs, these keys cannot be programmed for any function, they are restricted to:

  • server feature (function-key-def value = 58)
  • send URL (function-key-def value = 63)
  • start XML application (function-key-def value = 60)
  • the key's corresponding "built-in" function

In the case of the key's corresponding "built-in" function, there are new values for the function-key-def value defined, but these can only be used with the corresponding key index. So:

  • function-key-def can be set as built-in-release (65), but only for the release key index (4001)
  • function-key-def can be set as built-in-forwarding (64), but only for the forwarding key index (4002)
  • function-key-def can be set as built-in-voicedial (66), but only for the voicedial key index (4003)
  • function-key-def can be set as built-in-redial (67), but only for the redial key index (4009)

In addition, the same parameters associated with the function also need to be settable against the 400X key indexes, so for example for server feature the stimulus feature code, dtmf sequence and led control URI for that index can be set. For send URL send-url-address, send-url-protocol, etc. can be set (i.e. the same set of data as described above for the send URL feature except that there is no key label as the phone does not have labels for the 400X indexed keys) and similarly for start application we need to be able to set FPK-app-name.

Finally there is a new tag specific for use with programming the forwarding key which has relevance when the key is programmed for something other than its built in functionality. This is the key-functionality tag. It is an indexed tag but currently only defined for index 4002. Its possible values are:

0 - Toggle call forwarding - this allows some of the phone's built-in forwarding capability to be tied to the use of the key. Modification of the phone's internal call forwarding capability is disabled, including the greying-out of any existing configured functionality on FPKs, but the key's LED state (as controlled via the associated led-control-uri) is assumed to represent the user's forwarding state and this is re-flected on the phone's idle screen. This means that the forwarding icon is display if the LED is on, al-though no indication of the forwarding destination is displayed. In addition a confirmation popup is displayed when the key is pressed.

1 - Unspecified call forwarding - this disables configuration of the phone's internal call forwarding capability but does not tie the LED state to the phone's idle screen (which will show no forwarding indication) and no popup is shown when the key is pressed.

2 - Unspecified - the setting of the LED has no impact elsewhere on the phone. In particular the phone's internal call forwarding may be configured (e.g. on an FPK)This option is expected to be con-figured if the key is being used from the user's point of view for something not related to call forward-ing.

So, for example, to indicate that the configuration of the forwarding key (e.g. as server feature) should have no influence on any other behaviour of the phone, the following would be sent:

<Item index="4002" name="key-functionality">2</Item>

DHCP-Reuse (DHCP to use last provided IP Address on Restart)

Both of these are non-indexed and are boolean so they have the value true or false.

Thus for DHCP re-use the format of the protocol associated with re-use being on is:

<Item name="dhcp-reuse">true</Item>

and for re-use being off the protocol is:

<Item name="dhcp-reuse">false</Item>

This data item is persisted in the phone and is considered as part of the device profile for mobility pur-poses. The default value assumed by both the phone and the DLS should be false.

Clear-Call Log (Configurable flag to delete call log contents)

For clearing the call log, since this is a command from the DLS to the phone it does not correspond to a permanent data item in the phone. In order to clear the call log, the DLS would send:

<Item name="clear-calllog">true</Item>

If the DLS asks the phone for the current setting of this attribute (either explicitly or via a read all), then the phone will always return:

<Item name="clear-calllog">false</Item>

The DLS should never try to set clear-calllog to false; if it does then the phone will simply ignore the request.