Cisco Collaboration Endpoint Software
Introduction xConfiguration xCommand
Command line shortcuts
If your client supports it, there are some timesaving shortcuts you can use:
• Tab-completion to complete the commands and arguments.
• Arrow up and arrow down keys to navigate your command history.
• <CTRL-a>: Jump to the beginning of the line.
• <CTRL-e>: Jump to the end of the line.
• <CTRL-r>: Incremental command history search.
• <CTRL-w>: Erase the current line.
Searching
You can use // to search for elements anywhere in the status or configuration hierarchy (Example 1).
You can also combine multiple // ’s (Example 2).
NOTE: The search shortcuts work well for inspecting the
API, but should not be used in applications. We recommend that you always use the complete paths to avoid command ambiguity when upgrading to newer firmware releases.
Example 1:
List all configurations that include words that starts with OUT and HDMI: xconfiguration //out//hdmi
*c xConfiguration Audio Output HDMI 1 Level: 0
*c xConfiguration Audio Output HDMI 1 Mode: On
*c xConfiguration Audio Output HDMI 2 Level: 0
*c xConfiguration Audio Output HDMI 2 Mode: Off
** end
Example 2:
Get the resolution width of all connected sources for both inputs and outputs: xStatus //vid//res//wid
*s Video Input Source 1 Resolution Width: 1920
*s Video Input Source 2 Resolution Width: 0
*s Video Input Source 3 Resolution Width: 0
*s Video Input Source 4 Resolution Width: 0
*s Video Output Connector 1 Resolution Width: 1920
*s Video Output Connector 2 Resolution Width: 1280
*s Video Output Connector 3 Resolution Width: 1280
** end xStatus
API Reference Guide
Appendices
Value types and formats
The device supports the following value types:
• Integer values: <x..y>
Defines the valid range for an integer input. x = min value, y = max value.
• Literal values: <X/Y/../Z>
Defines the possible values for a given configuration.
• String values: <S: x, y>
Defines that the valid input for this configuration is a string with minimum length of x and maximum length of y characters. Strings can have rules that further specify their format and length.
Input values that contain spaces need to be quoted
Any values for configurations and commands containing spaces must be enclosed in quotes. Quotes are not necessary for values without spaces.
Example:
Correct: xCommand dial number: “my number contains spaces”
Correct: xCommand dial number: 12345
Incorrect: xCommand dial number: my number contains spaces
Case sensitivity
All commands are case-insensitive. All of the following commands will work.
XCOMMAND DIAL NUMBER: [email protected]
xcommand dial number: [email protected]
xCommand Dial Number: [email protected]
D15407.13 Cisco Collaboration Endpoint Software API Reference Guide CE9.12, APRIL 2020 78 Copyright © 2020 Cisco Systems, Inc. All rights reserved.
Cisco Collaboration Endpoint Software
Introduction xConfiguration xCommand xStatus
API Reference Guide
Appendices
Commands
Commands instruct the device to execute actions, such as to dial a number or to search the phone book. All commands start with the prefix xCommand followed by a command path.
Writing xCommand ?
on the command line will list all the top level commands.
To view the complete list of commands and their parameters, write xCommand ??
on the command line.
Command arguments are key-value pairs.
When issuing a xCommand, the command consists of one argument and one required parameter. In this document the command usage is described for all xCommands, with both required and optional parameters. The optional parameters are in brackets.
Example: xCommand Dial Number: 123 xCommand is the command prefix. The command to be executed is Dial.
The example contains one argument, Number: 123. Number is the key and 123 is its value. The key/value pair is separated with ‘:’.
Configurations
Configurations are device settings that are persistent across boots. Like commands, also configurations are structured in a hierarchy.
Writing xConfiguration ?
on the command line lists all the top level configurations.
Writing xConfiguration ??
lists all configurations and their value spaces.
Writing xConfiguration lists all configurations and their current values. To list out only some of the configurations, write xConfiguration followed by one or more parts of the configuration paths.
Example : Set the H323 Alias ID
Type: xConfiguration H323 Profile 1 H323Alias ID:
“[email protected]”
Example: Get the H323 Alias ID
Type: xConfiguration H323 Profile 1 H323Alias ID
Result:
*c xConfiguration H323 Profile 1 H323Alias ID:
“[email protected]”
**end
Status
A status contains the current state of the device, such as connected calls, the status of the gatekeeper registration, connected inputs and output sources.
Writing xStatus ?
on the command line lists all top level statuses.
Writing xStatus lists all statuses and their current values.
To list out only some of the statuses, write xstatus followed by the relevant part of the status path (address expression): xStatus <address expression>
D15407.13 Cisco Collaboration Endpoint Software API Reference Guide CE9.12, APRIL 2020 79 Copyright © 2020 Cisco Systems, Inc. All rights reserved.
Cisco Collaboration Endpoint Software
Introduction
Multiline commands
Multiline commands are commands that support larger amounts of data as input than the single line commands.
Typical use for these commands is to allow for provisioning of in-room control definitions, branding images
(base64 encoded), macros, welcome banners, and security certificates.
To issue a multiline command, you start issuing it like any other xAPI command. However, once you enter the command, you have set the API into an input mode where anything you issue on the API after this is treated as input to that command, including line breaks. You now enter the payload for this command in accordance to the input format expected by this command
When done, finish with a line break(“\n”) and a separate line containing just a period ending with a line break (“.\n”). The command will now be executed, and you get a command result with an OK or ERROR depending on the command being executed successfully or not.
The commands that require multiline input format are marked as such in the command descriptions in this guide.
The multiline commands are marked as multiline in xCommand overview section in this guide. xConfiguration xCommand
Example: Set up welcome banner text xCommand SystemUnit WelcomeBanner Set
Hello!
This is the second line of text.
This is the third.
.
Thank you!
OK
*r WelcomeBannerSetResult (status=OK):
** end xStatus
API Reference Guide
Appendices
D15407.13 Cisco Collaboration Endpoint Software API Reference Guide CE9.12, APRIL 2020 80 Copyright © 2020 Cisco Systems, Inc. All rights reserved.
Cisco Collaboration Endpoint Software
Introduction
Synchronous API calls
The API works asynchronously. This means that there is no guarantee that command responses arrive in the same order as the commands were issued. The device may also respond with feedback between your request and the response, in form of status changes or events, due to changes on the device.
For some applications it might be crucial to match requests with responses. The API therefore supports a responsetagging mechanism.
This mechanism works with all command types: xcommand, xconfiguration, and xstatus. A typical use of this would be to create a command queue in your application and assign unique IDs to every command sent to the device. A listener then listens to all feedback from the device and matches the ID on the response with the corresponding ID in the command queue. This enables matching the original request with the specific response.
xConfiguration xCommand xStatus
Example: xcommand Video Layout Add | resultId=”mytag _ 1”
OK
*r VideoLayoutAddResult (status=OK):
LayoutId: 1
** resultId: “mytag _ 1”
** end
In XML mode the resultId is added as an attribute to the top-level XmlDoc tag: xgetxml /Configuration/Video/Layout/Scaling | resultId=”mytag _ 2”
<XmlDoc resultId=”mytag _ 2”>
<Configuration item=”1”>
<Video item=”1”>
<Layout item=”1”>
<Scaling item=”1” valueSpaceRef=”...”>Off</Scaling>
</Layout>
</Video>
</Configuration>
</XmlDoc>
API Reference Guide
Appendices
D15407.13 Cisco Collaboration Endpoint Software API Reference Guide CE9.12, APRIL 2020 81 Copyright © 2020 Cisco Systems, Inc. All rights reserved.
Cisco Collaboration Endpoint Software
Introduction
Events
Event returns information about the events that are available for feedback. This overview presents examples of some the events that are available on the API.
To get an overview of the supported events:
• xEvent - Lists the top level events
• xEvent <top level category> - List all of the available events in that category
• xEvent * - Lists all available events on that device
The result for events depends on the state of the device.
xConfiguration xCommand xStatus
API Reference Guide
Appendices
Example 1: Outgoing Call Indication
Outgoing Call Indication is an event reported when an outgoing call is about to be dialled. Returns the CallId the call has been assigned.
*e OutgoingCallIndication CallId: x
** end
Example 2: Call Disconnect
Call Disconnect is an event reported when a call is disconnected. Returns the CallId of the disconnected call and reason for the call’s disconnection.
*e CallDisconnect CallId: x CauseValue: 0
CauseString: “” CauseType: LocalDisconnect
OrigCallDirection: “outgoing”
** end
Example 3: Call Successful
Call Successful is an event reported when a call is connected successfully, that is when all channels are up and established.
*e CallSuccessful CallId: 132 Protocol: “h223”
Direction: “outgoing” CallRate: 768 RemoteURI:
“h223:[email protected]” EncryptionIn:
“Off” EncryptionOut: “Off”
** end
Example 4: FECC Action request
FECC Action request is an event reported when far end is sending FECC commands.
*e FeccActionInd Id: 132 Req: 1 Pan: 1 PanRight:
1 Tilt: 0 TiltUp: 0 Zoom: 0 ZoomIn: 0 Focus: 0
FocusIn: 0 Timeout: 300 VideoSrc: 0 m: 0
** end
Example 5: TString message received
TString message received is an event reported when far end has sent a TString message.
*e TString CallId: 132 Message: “ee”
** end
Example 6: SString message received
SString message received is an event reported when far end has sent a SString message.
*e SString String: “ee” Id: 132
** end
D15407.13 Cisco Collaboration Endpoint Software API Reference Guide CE9.12, APRIL 2020 82 Copyright © 2020 Cisco Systems, Inc. All rights reserved.
