Key:n

Where

n = a Key name

Display:State:Interval

Where

State = whether the phone display is turned on or off, or set to default to return the display to its specified state.

Interval = duration (in minutes) in which the phone state remains in the specified state (unless activated by automated or user input). Value must be an integer ranging from 0-1440 minutes. If the value is set to 0, the display remains in the indicated state indefinitely (unless activated by automated or user input).

Examples

Display:Off:60 turns the phone display off for 1 hour (60 minutes).

Display:On:10 turns the phone display on for 10 minutes.

Display:Off:0 turns off the display off until activated.

Display:Default returns the display to its specified state for that time.

SoftKey:n

Where

n = one of the following softkey names:

• Back

• Cancel

• Exit

• Next

• Search

• Select

• Submit

• Update

• Dial

• EditDial

• <<

The following table contains valid softkey actions for each XSI object type follow. The URI invokes the native functionality that each key possesses in the given object context.

Note

The SoftKey URI is not allowed in an Execute object, except for the Cisco Wireless IP Phone 8821 and 8821-EX. For the Cisco Wireless IP Phone 8821 and 8821-EX Firmware Release 11.0(4) and previous, the Softkey:Back button takes the user up one screen level and the Softkey:Exit closes all open applications. For the Cisco Wireless IP Phone 8821 and 8821-EX Firmware Release 11.0(4)SR1 and later, the Softkey:Back and Softkey:Exit buttons take the user up one screen level. Only when used under the Directories button. The SoftKey:Dial and SoftKey:EditDial URIs can be used only for Directory objects, but the Dial:xxx and EditDial:xxx URIs can be used as the URL of any SoftKeyItem or MenuItem.

The following table shows this table from the document and denotes the Cisco Wireless Phone 840 or 860 behavior:

QueryStringParam:d

Where

d = the data to be appended to a corresponding URL.

<CiscoIPPhoneMenu>
	<Title>Message List</Title>
	<Prompt>Two Messages</Prompt>
	<MenuItem>
		<Name>Message One</Name>
		<URL>QueryStringParam:message=1</URL>
	</MenuItem>
	<MenuItem>
		<Name>Message Two</Name> 
		<URL>QueryStringParam:message=2</URL>
	</MenuItem>
	<SoftKeyItem>
		<Name>Read</Name>
		<URL>http://server/read.asp</URL>
	</SoftKeyItem>
	<SoftKeyItem>
		<Name>Delete</Name>
		<URL>http://server/delete.asp</URL>
	</SoftKeyItem>
</CiscoIPPhoneMenu>

The following example shows how to use the QueryStringParam URI in a CiscoIPPhoneMenu object. The CiscoIPPhoneMenu object includes two MenuItems with QueryStringParam URIs. If the user chooses the MenuItems with the numeric keypad, the cursor moves to that entry, but nothing executes because the values are QueryStringParam URIs.

If the user presses either custom softkey, the currently highlighted MenuItem URI value gets appended to the softkey URL that was pressed and requested from the web server.

If the user highlights the first MenuItem and press the Read softkey, the phone generates the following URL:

http://server//read.asp?message=1

<CiscoIPPhoneMenu>
	<Title>Message List</Title>
	<Prompt>Two Messages</Prompt>
	<MenuItem>
		<Name>Message One</Name>
		<URL>http://server/messages.asp?message=1</URL>
	</MenuItem>
	<MenuItem>
		<Name>Message Two</Name>
		<URL>http://server/messages.asp?message=2</URL>
	</MenuItem>
	<SoftKeyItem>
		<Name>Read</Name>
		<Position>1</Position><URL>QueryStringParam:action=read</URL> 
	</SoftKeyItem>
	<SoftKeyItem>
		<Name>Delete</Name>
		<Position>2</Position><URL>QueryStringParam:action=delete</URL>
	</SoftKeyItem>
</CiscoIPPhoneMenu>

The Cisco Unified IP Phones allow you to implement the QueryStringParam URI in either manner although Example: Item Selection with Numeric Keypad Calls URI is not as efficient as Example: QueryStringParam URI in CiscoIPPhoneMenu Object. Choose the best way to perform the action based on your applications needs.

The Item selection example has a slight advantage in that if the user chooses an item with the numeric keypad, the URL gets called. This action would allow you to invoke some default behavior, such as to read the message in the example. By highlighting the first message and pressing the Read softkey, the phone creates the following URL: http://server/messages.asp?message=1&action=read

Using the QueryStringParam URI reduces the size of the XML objects that you generate by removing redundant portions of a URL in every MenuItem.

• Existing Tx or MTx URI streams are terminated if a new call begins or an existing call resumes.

• Tx or MTx URI stream requests received when a call is active are rejected with an errorNo=4 unauthorized. If a call is in a Held state (connected but not actively streaming), the Tx or MTx URI request is accepted, but will terminate if the call resumes.

  Note	Returning errorNo=4 allows the application to distinguish this error from the normal errorNo=1 busy response.

• Existing Rx or MRx URI streams are terminated if a new call begins or an existing call resumes.

  The user has no explicit mechanism for terminating the Rx or MRx URI stream independent of the call. Thus, if the Rx or MRx stream is not terminated automatically, it would continue to play. For example, a user is listening to Internet radio feed and gets an incoming call. The user answers the call, which either closes or minimizes the Internet radio XSI application. Otherwise, the user has no intuitive way to stop the music stream.

• New Rx or MRx URI stream requests received during an active call are accepted (whisper), but the volume parameter of the URI is ignored.

  If the Rx or MRx URI request was done using push, then the associated application is responsible for using push Priority attributes and for stopping and starting the stream.

  If the user initiates the Rx or MRx URI using an application, then the user likely is not concerned about having the audio mixed with the current call. However, the user should also be presented with an option to stop the application, when needed.

• For the Rx or MRx URI, the Mute indicator light is only lit when both these conditions are met:

  • There are no active transmit streams from either a call or an XML services stream.

  • There is at least one active receive stream.

  For example, if an active call is ended or put on hold while a Rx or MRx URI stream is active, the Mute indicator will light.

• If a Rx or MRx or Tx or MTx URI request is received and there is already an active XML services stream in that direction, then a response with errorNo=1 Tx/Rx is already active is returned. The previous stream must be terminated (either by the user or by an RTP Stop URI) before a new stream can be started.

  This response provides visibility to the application if the phone is currently busy. It then allows the application to decide whether or not to terminate the existing stream and start a new one, rather than being controlled by the phone firmware.

The RTPRx URI instructs the phone to receive a Unicast RTP stream or to stop receiving Unicast or Multicast RTP streams.

Use the RTPTx URI to instruct the phone to transmit a Unicast RTP stream or to stop transmitting Unicast or Multicast RTP streams.

The RTPMRx URI instructs the phone to receive a Multicast RTP.

The RTPMTx URI instructs the phone to transmit a Multicast RTP stream.

The Play URI and incoming calls (ringing) have equal priority access to the DSP ringer resources resulting in the following interactions:

• If a Play URI is currently playing, an incoming call (ringing) will not preempt the Play URI; the Play URI will finish playing first.

• If the phone is ringing and a Play URI request is sent to the phone, the execution of the Play URI defers until the phone stops ringing (the DSP ringer resource becomes available) and then the Play URI will play.

Play:f

Where

f = the filename of a raw audio file in the TFTP path (such as Play:Classic2.raw).

The audio files for the rings must meet the following requirements for proper playback on Cisco Unified IP Phones:

• Raw PCM (no header)

• 8000 samples per second

• 8 bits per sample

• uLaw compression

• Maximum ring size: 16080 samples

• Minimum ring size: 240 samples

• Number of samples in the ring is evenly divisible by 240.

• Ring starts and ends at the zero crossing.

To create PCM files for custom phone rings, you can use any standard audio editing packages that support these file format requirements.

RTPRx:i:p:v:s or RTPMRx:i:p:v:s

Where

i = equals IP address (x.x.x.x).

p = equals UDP port (20480-32768).

v = volume (0-100).

Examples

Device:{command}

Where

command = The command the device follows:

• Type: Enum

• Valid Value: Unlock

• Default-value: N/A

This alert example performs the following actions:

1. Plays a tone on the phone

2. Unlocks the phone

3. Displays an alarm message on the phone

<CiscoIPPhoneExecute>
  <ExecuteItem URL="Device:Unlock"/>
  <ExecuteItem URL="Play:alert.wav"/>
</CiscoIPPhoneExecute>

On processing the above command, the following response is sent:

<CiscoIPPhoneText>
<Title>Alert</Title>
<Prompt>Urgent</Prompt>
<Text>
Please go to room 1234.
</Text>
<SoftKeyItem>
<Name>Accept</Name>
<URL>http://<ip>/AlertResponse.jsp?reason=accept</URL>
</SoftKeyItem>
<SoftKeyItem>
<Name>Busy</Name>
<URL>http://<ip>/AlertResponse.jsp?reason=busy</URL>
</SoftKeyItem>
</CiscoIPPhoneText> 

When the Device URI is invoked from an Execute object, it uses the standard URI Status and Data values in the ResponseItems.

Dial:{dialSequence}[:{useAppUI}:{applicationId}[:audibleFeedback]]

Where

dialSequence = The sequence of DTMF digits to be dialed. Commas represent 1 second pauses.

• Value Type: String

• Values: minLength=0, no maxLength, can only contain 0123456789#*ABCD and comma (,)

• Default value: N/A

useAppUI = Specifies whether or not this application will be used as the user interface for this call. A value of true will cause the application to keep UI focus when the call is made instead of switching to the Call UI application. The appId must be specified or this parameter will have no effect: it will always be false. This optional field is supported only on the Cisco IP Phone 8800 Series.

• Value Type: boolean

• Values: 0 or 1 (0=false 1=true)

• Default value: 0

applicationId = The unique name of the XSI web application requesting this call. This optional field is supported only on the Cisco Unified IP Phone 7900, 8800, 8900, and 9900 Series.

• Value Type: String

• Values: minLength=1, no maxLength, cannot contain semicolons – should be in the format Company/Product.

• Default value: Nil, which means this dial request will not be associated with any application

audibleFeedback = Whether or not to provide audible feedback to the user when the DTMF digits are dialed. This optional field is supported only on the Cisco Unified IP Phone 8800 Series.

• Value Type: Boolean

• Values: 0, 1 (0=false 1=true)

• Default value: 1

EditDial:n

Where

n = the number dialed

Example

EditDial:1000 initiates a call to the phone with DN 1000.

SendDigits:dtmfSequence:audibleFeedback::applicationId

Where

dtmfSequence = the sequence of DTMF digits to be sent. Value must contain only 0123456789#*ABCD and comma (,). The comma represents a one second pause.

audibleFeedback = indicates whether to provide audible feedback to the user as the DTMF digits are entered. Values can be 0 (false) or 1 (true).

applicationId = optional identifier of the application associated with the call which must receive the DTMF digits. Value must be 0-64 and cannot contain colons. The default value is null indicating that the active call should receive the DTMF digits, regardless of any application association.

Example

Make a call using a calling card service that implements these steps:

1. Connects to a 800 calling card service (using the Dial URI).

2. Application waits to give call time to connect.

3. Dials the destination number, ensuring that the digits can only be dialed from this application.

4. Pauses 2 seconds.

5. Dials the calling card number.

6. Pauses 1 second.

7. Dials the pin number.

<CiscoIPPhoneExecute>
  <ExecuteItem URL="Dial:918005551212:1:Cisco/Dialer"/>
</CiscoIPPhoneExecute>
<CiscoIPPhoneExecute>
  <ExecuteItem URL="SendDigits:6185551212,,987654321,1234:1:Cisco/Dialer"/>
</CiscoIPPhoneExecute>

When the SendDigits URI is invoked from an Execute object, it uses the standard URI Status and Data values in ResponseItems.

Init:o

Where

o = the Object name.

Valid object name:

• CallHistory: When the phone encounters an Init:CallHistory URI, it clears the internal call history logs that are stored in the phone. This action initializes Missed Calls, Received Calls, and Placed Calls.

• Services: When the phone encounters an Init:SERVICES URI, it closes the Services application. If Services is not currently open, it has no effect.

• Messages: When the phone encounters an Init:Messages URI, it closes the Messages application. If Messages is not currently open, it has no effect.

• Directories: When the phone encounters an Init:Directories URI, it closes the Directories application. If Directories is not currently open, it has no effect.

Notify:protocol:host:port:path:credentials:data

Where

protocol = network protocol to use for the Notify connection; http is the only supported protocol.

host = network host designated to receive the notification. Value must be entered as a hostname or IP address.

port = network port to use for the Notify connection. Value must be a number from 1-65535.

path = protocol-specific information. Value cannot contain colons or semicolons.

credentials = optional protocol-specific credentials used to authenticate to the server. For HTTP, this is a base64-encoded version of userid:password. Value cannot contain colors or semicolons. If the credentials parameter is not specified or if it is null, no Authorization header will be included in the request. The HTTP notification service will retry the request 3 times before failing and logging an error message.

data = optional application-specific event data. Value cannot contain semicolons.

• Called from RTP onStreamStopped Event Handler, no credentials, with data:

  Notify:http:myserver:8080:path/streamhandler?event=stopped:
  :myStreamStoppedData
  HTTP POST /path/streamhandler?event=stopped HTTP/1.1
  Accept: */*
  Content-Type: application/x-www-form-urlencoded; charset=”UTF-8”
  Host: myserver:8080
  Content-Length: 23
  DATA=myStreamStoppedData

• Called from RTP onStreamStopped Event Handler, no credentials, no data:

  Notify:http:server:8080:path/streamhandler?event=stopped
  HTTP POST /path/streamhandler?event=stopped HTTP/1.1
  Accept: */*
  Content-Type: application/x-www-form-urlencoded; charset=”UTF-8”
  Host: myserver:8080
  Content-Length: 40
  DATA=<notifyStreamStopped id=”stream1”/>
  

• Called from SoftKey, with credentials, with data:

  Notify:http:myserver:8080:path/streamhandler?event=stopped:
  8fh4hf7s7dhf :myStreamStoppedData
  HTTP POST /path/streamhandler?event=stopped HTTP/1.1
  Accept: */*
  Authorization: Basic 8fh4hf7s7dhf
  Content-Type: application/x-www-form-urlencoded; charset=”UTF-8”
  Host: myserver:8080
  Content-Length: 23=

• Called from SoftKey, no credentials, no data

  Notify:http:server:8080:path/streamhandler?event=stopped
  HTTP POST /path/streamhandler?event=stopped HTTP/1.1
  Accept: */*
  Content-Type: application/x-www-form-urlencoded; charset=”UTF-8”
  Host: myserver:8080
  Content-Length: 5

• Called from SoftKey with QueryStringParam URI:

  <CiscoIPPhoneMenu>
    <MenuItem>
      <Name>Voicemail1</Name>
      <URL>QueryStringParam:id=1</URL>
    </MenuItem>
    <MenuItem>
      <Name>Voicemail2</Name>
      <URL>QueryStringParam:id=2</URL>
    </MenuItem>
    <SoftKeyItem>
      <Name>Play</Name>
      <URL>Notify:http:vmailSrvr:8080:path/play</URL>
    </SoftKeyItem>
  </CiscoIPPhoneMenu>
  

  If the Voicemail2 menu item was selected when the Play softkey was pressed, the following notification would be sent:

  HTTP POST /path/play HTTP/1.1
  Accept: */*
  Content-Type: application/x-www-form-urlencoded; charset=”UTF-8”
  Host: vmailSrvr:8080
  Content-Length: 9
  DATA=id=2

App:action:priority:idleTimer:applicationId

Where

action = action to be taken with the application. Values include:

• RequestFocus: Makes a request to the application manager to bring the application context (window) containing this application into focus (maximize). This is a request, not a demand, as higher priority applications may prevent the application from actually gaining focus. Applications must use onAppFocusGained event handlers to know when focus is actually gained.

  • If the requested application is Open, but not currently Active, this request will not succeed (error response).

  • If the application already has focus, the request has no effect.

• ReleaseFocus: Makes a request to the application manager to relinquish focus to another application context (essentially, a “move-to-back” request). Applications must use onAppFocusLost event handlers to know when focus is actually lost.

  • If the application does not have focus, the request has no effect.

  • If there are no other applications open (available to receive focus) then this application will retain focus.

• Minimize: Makes a request to the application manager to minimize the application context containing this application. This request always results in the application (eventually) being minimized. If the application has focus when this URI executes, the onAppFocusLost event handler will be invoked first, then the onAppMinimize handler.

  • If the requested application is Open, but not currently Active, this request will not succeed (error response).

  • If the application is already minimized, the request has no effect.

• Close: Makes a request to the application manager to close the application context containing this application.

  • If the requested application is open, but not currently active, this request will not succeed (error response). This request will result in the application context (and all applications within that context) being closed.

  • If the application has focus when this URI executes, the onAppFocusLost event handler will be invoked prior to the onAppClosed event handler (which will always be invoked).

priority = priority at which the action should be take. Values include:

• 0: Do immediately, even if user is interacting with the phone. This priority is unavailable if the Application URI is contained within an Application Management Event Handler.

• 1: Do when user is done interacting with the phone.

• 2: Do only if the user is not interacting with the phone.

idleTimer = duration of time (in seconds) the phone or application must be idle before the action should be taken. Values must range from 10-86400 (seconds); default is 60 seconds. The idleTimer value has no effect on priority=0 requests. Any pending timers are automatically cancelled when the displayable object changes for an application context.

applicationId = optional identifier of the application on which the action should be taken. Values must range in length from 1-64 string characters and cannot contain colons. The default value is the application of the displayable object in which the URI is defined.

Note	If the Application URI is used in an ExecuteItem, you must specify the applicationId because the application context of the request cannot be inferred.

All Application URI requests are asynchronous, so the only return value indicates that the URI was successfully parsed and that the specified application was valid and currently active in its context. The application is notified of the actual state change asynchronously using the event handlers.