Features/Mass Deployment/Setting Files/XML/XmlSubTags

From Snom User Wiki

Jump to: navigation, search

Contents

Settings

NOTE: If you are using a FW version lower than 8.7.3, please go to this link for instructions and examples.

A number of settings may be described using the here described general xml-syntax. The settings currently (8.7.3) are:

general_purpose_xml_descriptions
fkey
user_event_list_uri
springboard_pkey
action_received_subscr_notify_url
idle_ok_key_action
idle_cancel_key_action
idle_up_key_action
idle_down_key_action
idle_left_key_action
idle_right_key_action
dkey_retrieve
dkey_dnd
dkey_directory
dkey_menu
dkey_transfer
dkey_hold
dkey_record
dkey_conf
dkey_record
dkey_retrieve
dkey_redial
dkey_directory
dkey_menu
dkey_conf
dkey_hold
dkey_settings
dkey_help
dkey_snom
dkey_transfer
dkey_dnd
gui_fkey

Structure

An Xml Description may has the following subtrees:

Example

Here an example how one would setup a line-key to monitor another user:


<general type="BusyLampField" identity="1"/>

<initialization>
  <state value="initial"/>
  <variable name="subscr_uri" value="sip:424711@com.snom"/>
</initialization>

<subscription type="dialog" to="&lt;$(subscr_uri)&gt;" for="$(subscr_uri)"/>

<NotifyParsingRules type="applies">     
  <level1 translates_to='OK'>/dialog-info[@entity="$(subscr_uri)"]</level1>   
</NotifyParsingRules>   
<NotifyParsingRules type="state">
  <level1 translates_to="ringing">/dialog-info/dialog/state[.="early"]</level1>
  <level1-1 translates_to="calling">/dialog-info/dialog[@direction="initiator"]</level1-1>
  <level2 translates_to="ringing">/dialog-info/dialog/state[.="proceeding"]</level2>
  <level2-1 translates_to="calling">/dialog-info/dialog[@direction="initiator"]</level2-1>
  <level3 translates_to="in_a_call">/dialog-info/dialog/state[.="confirmed"]</level3>
  <level4 translates_to="offhook">/dialog-info/dialog/state[.="trying"]</level4>
  <level5 translates_to="free"/>
</NotifyParsingRules>
<NotifyParsingRules type="variable" id="call_id" state="ringing">     
  <level1 fetch_attribute="call-id">/dialog-info/dialog[@call-id]</level1>   
</NotifyParsingRules>   
<NotifyParsingRules type="variable" id="remote_tag" state="ringing">     
  <level1 fetch_attribute="remote-tag">/dialog-info/dialog[@remote-tag]</level1>   
</NotifyParsingRules>   
<NotifyParsingRules type="variable" id="local_tag" state="ringing">     
  <level1 fetch_attribute="local-tag">/dialog-info/dialog[@local-tag]</level1>   
</NotifyParsingRules>   
<NotifyParsingRules type="variable" id="remote_uri" state="ringing">     
  <level1 fetch_attribute="uri">/dialog-info/dialog/remote/target[@uri]</level1>   
</NotifyParsingRules>  
<NotifyParsingRules type="variable" id="remote_name" state="ringing">     
  <level1 fetch_attribute="display">/dialog-info/dialog/remote/identity[@display]</level1>   
</NotifyParsingRules>

<action>   
  <invite target="$(remote_name)<$(remote_uri)>" when="on press" state="ringing" request_uri="$(remote_uri)" replaces="$(call_id);to-tag=$(remote_tag);from-tag=$(local_tag)"/>
  <dial target="$(subscr_uri)" when="on press"/> 
</action>

Special variables/arrays

Variables can be set through various ways (actions, NotifyParsingRules or in the initialization). Some variables and arrays have a special meaning.

Labeling (since 8.7.3)

When displaying a key in the phones user interface (PUI) it is often desired to give it a speaking name. The various situations where an XML-button may be displayed, i.e. springboard, context-key, virtual-key-screen (vkeys), line-info-layer (lil) or on the vision - each have their default-way of doing so:

  • springboard-icons do not render texts
  • vkey and lil show name, state ant type
  • context-keys show the state associated with the button

Several special variables give you more control over what is actually being shown as text on the screen in the above scenarios.

First and foremost there is the one called label, it gets show instead of the name within vkey (*1) and lil and replaces the state on a context-key and thus is the only text shown on it. For the vision it is used as the one-and-only text to be shown too - but here it may hold a specially formated rich-text.

*1): (since 8.7.4) so long as label is the only label-variable, as soon as you define positioning for the label, it not only replaces the name, but state and type will also not be shown.

Starting with fw-versions 8.7.3.18 and 8.7.4.6 the contents of the variable label_type replaces the actual key-type wherever and whenever it is shown in PUI. Same goes for the variable label_state which replaces the normally shown state of a key.

Certain PUI-key-views allow a more detailed control on how to display a text or even display multiple texts. Vision-keys, springboard-buttons and vkeys (see version info in table below) may define an area in which a text gets printed and how it aligns within using the following variables:

  • label_x and label_y - upper left corner for the text
  • label_width - width of the text
  • label_height - height of the text (not available for vision, it uses fixed height font)
  • label_align - says how to align the text within it's provided area: left, right or center

For springboard-buttons and vkeys one may also define the text color using label_rgba which must contain a space-separated list of values (0-255) for the three colors red, green and blue and their visibility (255 being solid).

Also springboard-buttons, vkeys and 870's context keys may show multiple texts at once when you use arrays instead of variables for all the mentioned label-keywords. Note that comfortable array-setting-mechanisms are only available for 8.7.4, so this feature is all but useless in 8.7.3.

name(s) of variable(s) used for context-key used for line-info-layer used for virtual keys used for springboard used for vision used for D7 and D3
label (since 8.7.3) (since 8.7.3) (since 8.7.3) (since 8.7.3) (since 8.7.4) (since 8.7.5.10)
label_x & label_y 870 only (since 8.7.4.7) (since 8.7.4) (since 8.7.3) (since 8.7.4)
label_width 870 only (since 8.7.4.7) (since 8.7.4) (since 8.7.3) (since 8.7.4)
label_height 870 only (since 8.7.4.7) (since 8.7.4) (since 8.7.3)
label_align 870 only (since 8.7.4.7) (since 8.7.4) (since 8.7.3) (since 8.7.4)
label_rgba 870 only (since 8.7.4.7) (since 8.7.4) (since 8.7.3)

Since you may want to use the same xml design for several different keys (springboard, vkey, etc) but the positioning in one PUI-key-view most likely is incompatible with another, you may also say which PUI-key-view a variable applies to by changing its name. If you put springboard_ up front the label-variable-name, it is only used when showing as springboard icon, similary there are these other prefixes: context_key_label, lil_label, vkey_label, vision_label and d7_label (starting from firmware 8.9.3.27 d7_label is replaced by uxm_label, which applies to the D3 too).

The vision itself may differ the coordinates (label_x & label_y) and alignment (label_align) of the label depending on where it is displayed (left or right half), use the postfixes _when_left and _when_right to differ these two situations.

The context keys of 870 come in two varieties: in a wider version in compination with a slim sidebar or in a smaller version for when the sidebar needs more space to accommodate the ongoing calls. You may specify diferent labels for either situation via the postfixes _when_slim and _when_wide.

Button Color (vkeys only, since 8.7.4)

The color of a vkey is usually determined by it's state and the settings vkey_red, _green, _orange and _blue. You may also define it directly, by setting a variable named vkey_bgnd_color to either red, green, orange or blue.

Led State/Color (vision only in versions since 8.7.4 .. 8.7.4.8 - since 8.7.4.9)

The color of a led associated with a button is usually determined by it's state and the LED control settings. Starting with version 8.7.4 you may also define it directly but only for vision-leds, by setting the variable named vision_led_state to either On, Off, Blink, Blink_Fast or Blink_Slow and one named vision_led_color to either Red, Green or Orange. Since 8.7.4.9 / 8.7.5.3 you can also directly set the color for line-key-leds on the phone by using the variable led_color.

Icons

Some buttons may render icons when they show on screen. The icon files need to be provisioned the same way the standard images are.(further details).
Which icon is to be used gets determined by the state the key is in. It's name is inserted into the filename (replaces the XXX in the following list):

820 context keys (since 8.7.3): snom820_button_XXX.png and snom820_button_XXX_PRESSED.png
870 context keys (since 8.7.4.7): snom870_ctxBtnThirds_stateXXX.png
870 springboard (since 8.4.3): snom870_springboardicon_linekeyStateXXX.png
Personal tools
Interoperability