This appendix covers call signaling protocols and application protocols included in Cisco CallManager. Call signaling protocols support communication with trunks and endpoints, and application protocols enable the development of additional applications that complement CallManager functionality.
CallManager uses the following signaling protocols to communicate with its devices:
H.323
QSIG
SIP (Session Initiation Protocol)
Skinny Client Control Protocol (SCCP)
Signaling protocols provide an agreed-upon set of rules that define the format of messages used to transmit information and commands between devices.
This chapter addresses each of the signaling protocols in detail in the following sections:
“H.323 Signaling” presents message details for Registration, Admission, and Status (RAS) and H.225 signaling described in Chapter 4, “Trunk Devices.”
“QSIG” presents message details for the QSIG feature-to-feature messages that CallManager uses for feature transparency. Chapter 4 provides an overview of QSIG.
“SIP Signaling” presents the message headers that CallManager sends and receives over its SIP trunk interface, which is described in Chapter 4.
“SCCP Call Signaling” presents an example message flow that CallManager uses when establishing calls to a Cisco IP Phone. Chapter 3, “Station Devices,” describes Cisco IP Phones in more detail.
H.323 operates using three main protocols, discussed at length in Chapter 4:
Registration, Admission, and Status (RAS) for interaction with H.323 gatekeepers
H.225 for the call signaling phase of a call
H.245 for the media control phase of a call
The RAS protocol supported by CallManager includes specific message types and information elements. The RAS message support provided by CallManager is the H.225 version 2 protocol. Tables C-1 through C-7 describe the specific fields. The tables are arranged alphabetically by message type. Table C-1 shows the fields that an H.323 entity uses to discover the gatekeeper. CallManager does not currently support RAS discovery messages, but they are included here for completeness.
Table C-1. H.225 RAS Terminal and Gateway Discovery Message Details: User-User Information Element (UUIE) Fields
Message | Field Name | Comments |
---|---|---|
GRQ (Gatekeeper Request) to GK (Gatekeeper) | requestSeqNumber | Not used in CallManager 4.1 |
protocolIdentifier | ||
nonStandardData | ||
rasAddress | ||
endpointType | ||
gatekeeperIdentifier | ||
callServices | ||
endpointAlias | ||
alternateEndpoints | ||
tokens | ||
cryptoTokens | ||
authenticationCapability | ||
algorithmsOIDs | ||
integrity | ||
integrityCheckValue | ||
GCF (Gatekeeper Confirmation) from GK | requestSeqNumber | Allowed, but ignored when received |
protocolIdentifier | ||
nonStandardData | ||
gatekeeperIdentifier | ||
rasAddress | ||
alternateGatekeeper | ||
authenticationMode | ||
tokens | ||
cryptoTokens | ||
algorithmsOIDs | ||
integrity | ||
integrityCheckValue | ||
GRJ (Gatekeeper Reject) from GK | requestSeqNumber | Allowed, but ignored when received |
protocolIdentifier | ||
nonStandardData | ||
gatekeeperIdentifier | ||
rejectReason | ||
altGKInfo | ||
Tokens | ||
cryptoTokens | ||
integrityCheckValue |
CallManager uses registration messages to register with the gatekeeper that the manual or automatic discovery process identifies. CallManager attempts to register with the gatekeeper and, if not successful, retries the registration at configurable intervals.
Table C-2 shows the fields that CallManager uses to register with the gatekeeper.
Table C-2. H.225 RAS Registration Message Details: UUIE Fields
Message | Field Name | Comments |
---|---|---|
RRQ (Registration Request) to GK | requestSeqNumber | Unique sequence number that is incremented for each new request |
protocolIdentifier | Set to v2 | |
nonStandardData | Not used | |
discoveryComplete | Set to false | |
callSignalAddress | Set to the IP and port of the call signaling address | |
rasAddress | Set to the IP and port of the RAS signaling address | |
terminalType | Set to indicate terminal or gateway device | |
terminalAlias | No alias set | |
gatekeeperIdentifier | Gatekeeper ID set | |
alternateEndpoints | Set to transport addresses of alternate CallManager nodes | |
timeTolive | Set to configuration value; defaults to 60 | |
tokens | Not supported | |
cryptoTokens | Not supported | |
integrityCheckValue | Not supported | |
keepAlive | Set to true if this is a refresh registration | |
endpointIdentifier | Endpoint ID set | |
willSupplyUUIEs | Defaults to false | |
RCF (Registration Confirmation) from GK | requestSeqNumber | Unique sequence number |
protocolIdentifier | CallManager does not screen this field | |
nonStandardData | Not used | |
callSignalAddress | CallManager sends H.225 signaling to this address | |
terminalAlias | Not used | |
gatekeeperIdentifier | Identifies the H.323 zone | |
endpointIdentifier | Endpoint identifier | |
alternateGatekeeper | Defines gatekeepers to contact if registering gatekeeper is unavailable | |
timeTolive | CallManager periodically reregisters according to this timer | |
tokens | Not supported | |
cryptoTokens | Not supported | |
integrityCheckValue | Not supported | |
willRespondToIRR | Ignored | |
pregrantedARQ | Not used | |
RRJ (Registration Reject) from GK | requestSeqNumber | Unique sequence number |
protocolIdentifier | Not screened | |
nonStandardData | Not used | |
rejectReason | Reject reason | |
gatekeeperIdentifier | Indicates the zone of the rejecting gatekeeper | |
altGKInfo | Indicates an alternate gatekeeper with which to register | |
tokens | Not supported | |
cryptoTokens | Not supported | |
integrityCheckValue | Not supported |
CallManager uses unregistration messages to unregister from the gatekeeper when a gatekeeper registered device is stopped. Table C-3 shows the fields that CallManager uses to unregister from the gatekeeper.
Table C-3. H.225 RAS Unregistration Message Details: UUIE Fields
Message | Field Name | Comments |
---|---|---|
URQ (Unregister Request) to GK | requestSeqNumber | Unique sequence number that is incremented for each new request |
protocolIdentifier | Not screened | |
callSignalAddress | Set to the IP and port of the call signaling address | |
endpointAlias | Not set | |
nonStandardData | Not used | |
endpointIdentifier | Indicates the identifier of the unregistering request | |
alternateEndpoints | Not used | |
gatekeeperIdentifier | Not set | |
tokens | Not supported | |
cryptoTokens | Not supported | |
integrityCheckValue | Not supported | |
reason | CallManager sets no reason and ignores the reason when receiving a URQ | |
UCF (Unregister Confirm) from GK | requestSeqNumber | Allowed, but ignored when received |
nonStandardData | ||
tokens | ||
cryptoTokens | ||
integrityCheckValue | ||
URJ (Unregister Reject) from GK | requestSeqNumber | Allowed, but ignored when received |
rejectReason | ||
nonStandardData | ||
altGKInfo | ||
tokens | ||
cryptoTokens | ||
integrityCheckValue |
CallManager uses call admission control to discover routes to other CallManager clusters and gateways and to determine whether enough bandwidth exists for CallManager to place or receive a call.
Table C-4 shows the fields that CallManager uses to exchange call admission control messages with the gatekeeper.
Table C-4. H.225 RAS Admission Message Details: UUIE Fields
Message | Field Name | Comments |
---|---|---|
ARQ (Admission Request) to GK | requestSeqNumber | Unique sequence number that is incremented for each new request |
callType | Set to point to point | |
callModel | Not set | |
endpointIdentifier | Set to endpoint ID | |
destinationInfo | Up to 16 E.164 addresses | |
destCallSignalAddress | IP address, if set by CallManager | |
destExtraCallInfo | Not set | |
srcInfo | If present, a list of up to 16 E.164 addresses | |
srcCallSignalAddress | Set to the IP and port of the call signaling address | |
bandwidth | Requested bandwidth to be used | |
callReferenceValue | Set to call reference value for this call | |
nonStandardData | Not used | |
callServices | Set to None | |
conferenceId | Unique conference identifier | |
activeMC | Set to false for no multipoint controller (MC) | |
answeredCall | Set to true if call is incoming, false on outgoing | |
canMapAlias | Set to true | |
callIdentifier | Unique call identifier | |
srcAlternatives | Set to None | |
gatekeeperIdentifier | Not set | |
tokens | Not supported | |
cryptoTokens | Not supported | |
integrityCheckValue | Not supported | |
transportQOS | Not supported | |
willSupplyUUIEs | Defaults to false | |
ACF (Admission Confirm) from GK | requestSeqNumber | Unique sequence number |
bandWidth | Not used | |
callModel | CallManager always acts as if the response is direct | |
destCallSignalAddress | Uses the IP address to specify the call signaling address; used if configured for anonymous device; ignored otherwise | |
irrFrequency | Used to specify the Information Request Response (IRR) frequency in seconds while on the call | |
nonStandardData | Not used | |
destinationInfo | Not used | |
destExtraCallInfo | Not used | |
destinationType | Not used | |
remoteExtensionAddress | Not used | |
alternateEndpoints | Transport address of associated H.323 trunks | |
tokens | Not supported | |
cryptoTokens | Not supported | |
integrityCheckValue | Not supported | |
transportQOS | Not supported | |
willRespondToIRR | Not used | |
uuiesRequested | Not used | |
ARJ (Admission Reject) from GK | requestSeqNumber | Unique sequence number |
rejectReason | Used only for ARJ trace display | |
nonStandardData | Not used | |
altGKInfo | If provided, CallManager contacts the alternate gatekeeper | |
tokens | Not supported | |
cryptoTokens | Not supported | |
callSignalAddress | Not used | |
integrityCheckValue | Not supported |
CallManager does not use bandwidth control messages by default. Bandwidth control messages are used if you set the service parameter to enable bandwidth control. Table C-5 shows the bandwidth message fields.
Table C-5. H.225 RAS Bandwidth Message Details: UUIE Fields
Message | Field Name | Comments |
---|---|---|
BRQ (Bandwidth Request) from GK | requestSeqNumber | CallManager returns a BRJ (Bandwidth Reject) |
endpointIdentifier | ||
conferenceID | ||
callReferenceValue | ||
callType | ||
bandWidth | ||
nonStandardData | ||
callIdentifier | ||
gatekeeperIdentifier | ||
tokens | ||
cryptoTokens | ||
integrityCheckValue | ||
answeredCall | ||
BRQ (Bandwidth Request) to GK | requestSeqNumber | Unique sequence number |
endpointIdentifier | Endpoint identifier | |
conferenceID | Unique conference identifier | |
callReferenceValue | Call reference value | |
callType | Point to point | |
bandWidth | New bandwidth | |
nonStandardData | Not used | |
callIdentifier | Unique call identifier | |
gatekeeperIdentifier | Not supported | |
tokens | Not supported | |
cryptoTokens | Not supported | |
integrityCheckValue | Not supported | |
answeredCall | True on terminating side | |
BCF (Bandwidth Confirm) from GK | requestSeqNumber | Unique sequence number |
bandWidth | Bandwidth granted | |
nonStandardData | Not used | |
tokens | Not used | |
cryptoTokens | Not used | |
integrityCheckValue | Not used | |
BRJ (Bandwidth Reject) from GK | requestSeqNumber | Unique sequence number |
rejectReason | Reason bandwidth change was disallowed | |
allowedBandWidth | Amount of bandwidth allowed | |
nonStandardData | Not used | |
altGKInfo | ID of alternate gatekeeper | |
tokens | Not used | |
cryptoTokens | Not used | |
integrityCheckValue | Not used |
Gatekeepers use disengage messages to force a call to be dropped. CallManager uses disengage messages to indicate that an endpoint is being dropped.
Table C-6 shows the fields that CallManager uses to exchange disengage messages with the gatekeeper.
Table C-6. H.225 RAS Disengage Message Details: UUIE Fields
Message | Field Name | Comments |
---|---|---|
DRQ (Disengage Request) to or from GK | requestSeqNumber | Unique sequence number |
endpointIdentifier | Endpoint identifier | |
conferenceID | Unique conference identifier | |
callReferenceValue | Call reference value | |
disengageReason | If sent, set to reason; if received, used to set the release complete reason | |
nonStandardData | Not used | |
callIdentifier | Unique call identifier | |
gatekeeperIdentifier | Not used | |
tokens | Not supported | |
cryptoTokens | Not supported | |
integrityCheckValue | Not supported | |
answeredCall | Supported | |
DCF (Disengage Confirm) to or from GK | requestSeqNumber | Unique sequence number |
nonStandardData | Not used | |
tokens | Not supported | |
cryptoTokens | Not supported | |
integrityCheckValue | Not supported | |
DRJ (Disengage Reject) from GK | requestSeqNumber | Unique sequence number |
rejectReason | CallManager ignores | |
nonStandardData | Not used | |
altGKInfo | Not supported | |
tokens | Not supported | |
cryptoTokens | Not supported | |
integrityCheckValue | Not supported |
The gatekeeper sends Information Request (IRQ) messages to request status information. CallManager responds to information request messages from the gatekeeper with Information Request Response (IRR) messages, but CallManager does not send unsolicited IRQ messages to the gatekeeper. IRR messages are sent at the intervals specified by the irrFrequency field in the ACF message.
Table C-7 shows the fields that CallManager uses to exchange information request messages with the gatekeeper.
Table C-7. H.225 RAS Information Request Message Details: UUIE Fields
Message | Field Name | Comments |
---|---|---|
IRQ (Information Request) from GK | requestSeqNumber | Unique sequence number |
callReferenceValue | Call reference value | |
nonStandardData | Not used | |
replyAddress | Not used | |
callIdentifier | Not used | |
tokens | Not supported | |
cryptoTokens | Not supported | |
integrityCheckValue | Not supported | |
uuiesRequested | Not used | |
IRR (Information Request Response) to GK | nonStandardData | Not used |
requestSeqNumber | Unique sequence number | |
endpointType | Set to terminal or gateway | |
endpointIdentifier | Endpoint identifier | |
rasAddress | Set to the IP address and port of the RAS signaling address | |
callSignalAddress | Not present | |
endpointAlias | Not present | |
perCallInfo | See the following perCall fields | |
perCallInfo.nonStandardData | Not used | |
perCallInfo.callReferenceValue | Call reference value | |
perCallInfo.conferenceId | Unique conference ID | |
perCallInfo.originator | Set to false | |
perCallInfo.audio | Not set | |
perCallInfo.video | Not set | |
perCallInfo.data | Not set | |
IRR (Information Request Response) to GK | perCallInfo.h245 | Set to false |
perCallInfo.callSignaling | Not present | |
perCallInfo.callType | Point to point | |
perCallInfo.bandwidth | Set to 1280 for a G.711 call; 480 for a G.729 call | |
perCallInfo.callModel | Set to direct | |
perCallInfo.callIdentifier | Call ID | |
perCallInfo.tokens | Not supported | |
perCallInfo.cryptoTokens | Not supported | |
perCallInfo.substituteConfIDs | Not supported | |
perCallInfo.pdu | Not supported | |
tokens | Not supported | |
cryptoTokens | Not supported | |
integrityCheckValue | Not supported | |
needResponse | Not supported | |
IACK (Information Request Acknowledgement) from GK | requestSeqNumber | Allowed, but ignored when received |
nonStandardData | ||
tokens | ||
cryptoTokens | ||
integrityCheckValue | ||
INAK (Information Request Negative Acknowledgement) from GK | requestSeqNumber | Allowed, but ignored when received |
nonStandardData | ||
nakReason | ||
altGKInfo | ||
tokens | ||
cryptoTokens | ||
integrityCheckValue |
H.323 messages, including the call signaling messages, follow the ITU-T Q.931 recommendation as specified in H.323. In H.323, the user-user information element (UUIE) conveys the H.323-related information. The H.323 user information protocol data unit (PDU) is ASN.1-encoded. The ASN.1 is encoded using the basic aligned variant of the packed encoding rules as specified in X.691. The ASN.1 structure begins with H323-UserInformation.
H.225 is the call signaling protocol that is supported in the H.323 protocol umbrella. H.225 includes the call signaling messages and the RAS messages. This section covers the specific details of the H.225 call signaling messages.
Table C-8 lists each H.225 message and provides the specific UUIE fields of the H.225 call signaling messages that CallManager exchanges with an H.323 gateway or CallManager H.323 trunk (gateway in table).
Table C-8. H.225 Call Signaling Message Details: UUIE Fields
Message | Field Name | Comments |
---|---|---|
Alerting from gateway | protocolIdentifier | Assumes version 2 (v2); only v2 fields are processed |
destinationInfo | Used | |
h245Address | Used if present | |
callIdentifier | Unique call identifier | |
h245SecurityMode | Not supported | |
tokens | Not supported | |
cryptoTokens | Not supported | |
fastStart | Supported | |
Alerting to gateway | protocolIdentifier | Set to v2 |
destinationInfo | Endpoint type terminal | |
h245Address | If present at alerting, contains the IP address and port of the CallManager H.245 transport address | |
callIdentifier | Unique call identifier | |
h245SecurityMode | Not supported | |
tokens | Not supported | |
cryptoTokens | Not supported | |
fastStart | Supported | |
CallProceeding from gateway | protocolIdentifier | Assumes v2; only v2 fields are processed |
destinationInfo | Used | |
h245Address | Used if present | |
callIdentifier | Unique call identifier | |
h245SecurityMode | Not supported | |
tokens | Not supported | |
cryptoTokens | Not supported | |
fastStart | Supported | |
CallProceeding to gateway | protocolIdentifier | Set to v2 |
destinationInfo | Endpoint type terminal | |
h245Address | If present at CallProceeding, contains the IP address and port of the CallManager H.245 transport address | |
callIdentifier | Unique call identifier | |
h245SecurityMode | Not supported | |
tokens | Not supported | |
cryptoTokens | Not supported | |
fastStart | Supported | |
Connect from gateway | protocolDiscriminator | Assumes v2; only v2 fields are processed |
h245Address | Used if present; required if not present in previous message | |
destinationInfo | Used | |
conferenceId | Required | |
callIdentifier | Unique call identifier | |
h245SecurityMode | Not supported | |
tokens | Not supported | |
cryptoTokens | Not supported | |
fastStart | Supported | |
protocolDiscriminator | Set to v2 | |
h245Address | Contains the IP address and port of the CallManager H.245 transport address | |
destinationInfo | Endpoint type terminal | |
conferenceId | Unique conference identifier | |
callIdentifier | Unique call identifier | |
h245SecurityMode | Not supported | |
tokens | Not supported | |
cryptoTokens | Not supported | |
fastStart | Supported | |
Facility from and to gateway | protocolDiscriminator | Set to v2 |
alternativeAddress | Not used | |
alternativeAliasAddress | Not used | |
conferenceID | Not used | |
reason | Used | |
callIdentifier | Unique call identifier | |
destExtraCallInfo | Not used | |
remoteExtensionAddress | Not used | |
tokens | Not used | |
cryptoTokens | Not used | |
conferences | Not used | |
h245Address | Not used | |
UserInformation from gateway | protocolIdentifier | Assumes v2; only v2 fields are processed |
callIdentifier | Not used | |
UserInformation to gateway | protocolIdentifier | Set to v2 |
callIdentifier | Unique call identifier | |
Progress from gateway | protocolIdentifier | Assumes v2; only v2 fields are processed |
destinationInfo | Not used | |
h245Address | Used if present; required if not present in previous message | |
callIdentifier | Unique call identifier | |
h245SecurityMode | Not supported | |
tokens | Not supported | |
cryptoTokens | Not supported | |
fastStart | Supported | |
Progress to gateway | protocolIdentifier | Set to v2 |
destinationInfo | Endpoint type terminal | |
h245Address | Contains the IP address and port of the CallManager H.245 transport address | |
callIdentifier | Unique call identifier | |
h245SecurityMode | Not supported | |
tokens | Not supported | |
cryptoTokens | Not supported | |
fastStart | Supported | |
ReleaseComplete from gateway | protocolIdentifier | Assumes v2; only v2 fields are processed |
reason | Reason for disconnect | |
callIdentifier | Unique call identifier | |
ReleaseComplete to gateway | protocolIdentifier | Set to v2 |
reason | Reason for disconnect | |
callIdentifier | Unique call identifier | |
protocolIdentifier | Assumes v2; only v2 fields are processed | |
h245Address | Contains the IP address and port of the CallManager H.245 transport address | |
sourceInfo | Not used | |
sourceAddress | Source address if provided | |
destinationAddress | Not used; E.164 address is in the Q.931 called party number IE (information element) | |
destCallSignalAddress | Not used | |
destExtraCallInfo | Not used | |
destExtraCRV | Not used | |
activeMC | Used | |
conferenceId | Unique conference identifier | |
conferenceGoal | Used | |
callServices | Not used | |
callType | Used | |
sourceCallSignalAddress | Used | |
remoteExtensionAddress | Not used | |
callIdentifier | Unique call identifier | |
h245SecurityCapability | Not supported | |
tokens | Not supported | |
cryptoTokens | Not supported | |
fastStart | Supported | |
mediaWaitForConnect | Used if present; defaults to false if not present | |
canOverlapSend | Not used | |
Setup to gateway | protocolIdentifier | Set to v2 |
h245Address | Contains the IP address and port of the CallManager H.245 transport address | |
sourceInfo | Endpoint type terminal | |
sourceAddress | Source address as E.164 address, H.323 alias, or both | |
destinationIAddress | E.164 address present here and also included in the Q.931 called party number IE (information element) | |
destinationCallSignalAdd ress | Not used | |
destExtraCallInfo | Not used | |
destExtraCRV | Not used | |
activeMC | Used | |
conferenceId | Unique conference identifier | |
conferenceGoal | Set to create | |
callServices | Not used | |
callType | Point to point | |
sourceCallSignalAddress | Used | |
remoteExtensionAddress | Not used | |
callIdentifier | Unique call identifier | |
h245SecurityCapability | Not supported | |
tokens | Not supported | |
cryptoTokens | Not supported | |
fastStart | Supported | |
mediaWaitForConnect | Set to true | |
canOverlapSend | Set to false |
Chapter 4 covers QSIG, a messaging framework that fosters feature transparency between Private Branch Exchanges (PBX). For CallManager, QSIG is almost a protocol within a protocol within a protocol—the QSIG feature messages wrapped in ISDN signaling communicated to MGCP gateways.
QSIG messages are called application protocol data units (APDU). They tend to contain a handful of fields at most. CallManager uses QSIG APDUs to implement the following features:
Call completion
Call diversion
Call transfer
Name services (calling name presentation and restriction, alerting name presentation and restriction, connected name presentation and restriction)
Message waiting indicator
Path replacement
The sections that follow describe the APDUs required for each of these features and the encoding rules that CallManager uses for the fields within the messages.
You’ll notice frequent use of the term PBX. In the QSIG section, PBX is used interchangeably for CallManager clusters as well as legacy PBXs.
The QSIG call completion feature allows a user who calls a destination that is busy or that does not answer to set a watch over the called party. When the called party becomes available, The IP phone prompts the calling user to redial the destination.
Call completion relies on the following APDUs:
ccnrRequest and ccbsRequest—. Communicate from one PBX to another that a user wants to start monitoring the called party.
The ccnrRequest and ccbsRequest APDUs contain the following fields:
— numberA–Indicates the number of the monitoring party.
— numberB–Indicates the number of the party to be monitored.
ccExecPossible—. Communicates the availability of the called user to the PBX that set the watch.
The ccExecPossible APDU contains the following fields:
— numberA–Indicates the number of the monitoring party.
— numberB–Indicates the number of the party to be monitored.
ccCancel—. Indicates the caller’s or the PBX’s desire to cancel the callback.
The ccExecPossible APDU contains the following fields:
— numberA–Indicates the number of the monitoring party.
— numberB–Indicates the number of the party to be monitored.
ccRingout—. Indicates that an incoming call is the result of a callback attempt; contains no APDU fields.
ccSuspend—. Pauses the watch when the calling user is busy at the time of the called party’s availability; contains no APDU fields.
ccResume—. Resumes the watch when the caller is idle; contains no APDU fields.
The QSIG call diversion feature causes the displays of the calling and called parties to update when a call is forwarded from one user to another.
Call diversion relies on the following APDUs:
divertingLegInformation1—. Communicates diversion information from the forwarded phone to the caller while the call diversion is being processed.
The divertingLegInformation1 APDU contains the following fields:
— diversionReason–Indicates why the diversion occurred (for example, the destination was busy or failed to answer).
— subscriptionOption–Determines whether to deliver number or name to the user.
— nominatedNr–Indicates the call forwarding target to the caller.
divertingLegInformation2—. Communicates diversion information from the forwarded phone to the forward target while the call diversion is being processed.
The divertingLegInformation2 APDU contains the following fields:
— diversionCounter–Indicates the number of times that the call has been previously diverted, to minimize the effect of call forwarding loops.
— diversionReason–Indicates why the diversion occurred.
— originalDiversionReason–In the case of multiple diversions, indicates why the original called party diverted the call.
— divertingNr–Indicates the number of the device that diverted the call.
— originalDivertingNr–In the case of multiple diversions, indicates the number associated with the original target of the call.
— redirectingName–Indicates the display name associated with the diverting user.
— redirectingName–In the case of multiple diversions, indicates the display name associated with the original target of the call.
divertingLegInformation3—. Communicates diversion information from the forward target to the caller when the call forward has completed.
The divertingLegInformation3 APDU contains the following fields:
— presentationAllowedIndicator–Indicates whether the caller is permitted to see the name of the forward target.
— redirectionName–Indicates the display name associated with the user to whom the call was diverted.
The QSIG call transfer feature causes the displays of the transferred and transfer destination to update when a user transfers a call from one party to the other.
Call transfer relies on the following APDUs:
ctComplete—. Communicates information about the transferred party to the transfer destination upon completion of the transfer.
The ctComplete APDU contains the following fields:
— redirectionNumber–Indicates the transferred-to number if sent to the calling party. If sent to the transferred-to user, it represents the calling party number.
— redirectionName–Indicates the transferred-to name if sent to the calling party. If sent to the transferred-to user, it represents the calling party name.
ctActive—. Communicates when a ringing transfer destination answers the call.
The ctActive APDU contains the following fields:
— connectedAddress–Is sent to the calling party and indicates the transferred-to number.
— redirectionName–Is sent to the calling party and indicates the transferred-to name.
ctUpdate—. Communicates display information about the transferred party to the transfer destination and vice versa, once the transfer is complete.
The ctUpdate APDU contains the following fields:
— redirectionNumber–Indicates the transferred-to number if sent to the calling party. If sent to the transferred-to user, it represents the calling party number.
— redirectionName–Indicates the transferred-to name if sent to the calling party. If sent to the transferred-to user, it represents the calling party name.
The QSIG message waiting feature allows a voice mail system attached to one PBX to deliver message waiting indications to users connected to another PBX.
QSIG message waiting relies on the following APDUs:
mwiActivate—. Communicates the number of the phone whose message waiting indicator must be lit from the system hosting voice mail to the system hosting the phone. This APDU contains the servedUserNr field, which indicates the number of the party whose lamp state needs to be altered.
mwiDeactivate—. Communicates the number of the phone whose message waiting indicator must be extinguished from the system hosting voice mail to the system hosting the phone. This APDU contains the servedUserNr field, which indicates the number of the party whose lamp state needs to be altered.
The QSIG name services features ensure that a caller can see the name of the called party (when permissible) and that a called party can see the name of the calling party (when permissible).
QSIG name services features include the following:
Calling name presentation and restriction
Alerting name presentation and restriction
Connected name presentation and restriction
QSIG name services APDUs communicate two main pieces of information:
The name of the calling, alerting, or called party
The presentation indicator associated with that party, which determines whether the recipient of the message can see the name of the sender
The QSIG path replacement feature permits PBXs that have been involved in a call diversion or call transfer to optimize the signaling path after the diversion or transfer completes. This process can free up trunk circuits when a call has hairpinned through the network.
QSIG path replacement relies on the following APDUs:
prPropose—. Allows one PBX to propose to another PBX that the path be optimized.
The prPropose APDU contains the following fields:
— callIdentity–Provides a numeric key that the receiving PBX should encode in the replacement call so that the sending PBX can identify the new incoming call.
— reroutingNumber–Indicates the number that the receiving PBX should use when placing the replacement call. This number is not the number of the actual party involved in the call but is instead a number associated with the CallManager node that is hosting the party.
prSetup—. A PBX embeds this APDU in a call setup attempt to the target PBX to indicate that the incoming call is not a new call but is an optimized call attempt that should replace the incoming leg of the original call. This APDU contains the callIdentity field, which indicates the numeric key that will be provided in the prPropose sent by the initiating PBX of the path replacement operation.
This section describes CallManager support for SIP methods and header fields. Chapter 4 provides an overview of CallManager support for SIP trunks.
SIP defines messages into requests and responses. Request messages are named; response messages are numbered. Table C-9 lists the request messages.
Table C-9. SIP Request Messages
Request | Supported by CallManager? | Comments |
---|---|---|
INVITE | Y | Establishes a session; CallManager originates and receives this message. |
ACK | Y | Acknowledges the establishment of a session; CallManager sends and receives this message. |
OPTIONS | Y | Queries a User Agent (UA) about its capabilities; CallManager never sends this message but does respond to it. |
BYE | Y | Terminates an established session. CallManager sends and receives this message. |
CANCEL | Y | Rescinds an INVITE before the session is established. |
REGISTER | N | Registers SIP addresses with a registrar. CallManager never sends this message and responds with a 405 Method Not Allowed if it receives it. |
PRACK | Y | Acknowledges the receipt of a provisional response (such as 180 Alerting) by the UA; used only when reliable provisional responses are in effect. |
UPDATE | Y | Allows session parameters for an unestablished session to be changed. CallManager never sends this message but can accept it. |
Response messages are numbered in the range 1xx to 6xx. Each group of a hundred represents a specific class of responses to the requests. Table C-10 lists the message classes and describes CallManager support for specific messages in the class.
Table C-10. SIP Response Messages
Request | Supported by CallManager? | Comments |
---|---|---|
1xx messages indicate events that occur as a session is being established | ||
100 Trying | Y | Indicates that the Proxy or UA has been able to resolve an address and continue routing. CallManager supports sending and receiving this message. |
180 Ringing | Y | Indicates the target UA is ringing. CallManager sends and receives this message. |
181 Call Forward | N | CallManager cannot send or receive this message. |
182 Call Queued | N | CallManager cannot send or receive this message. |
183 Progress | Y | CallManager can receive and send this message. CallManager may connect media on receipt of this message. |
2xx messages confirm the establishment of a session | ||
200 OK | Y | Confirms that a session has been established. |
3xx messages indicate that the session being established should be established to or via a different SIP entity | ||
300–302, 305, 380 | Y | CallManager never sends these messages. When it receives this class of message, CallManager attempts to re-establish the session to the contacts listed in the message. |
4xx messages are definitive, final failure responses from the target of the request | ||
4xx | Y | CallManager sends and receives this message. CallManager initiates a call disconnect upon receiving this message. |
5xx messages indicate that an unexpected condition was encountered that prevented the establishment of the session | ||
5xx | Y | CallManager sends this message. Upon receiving this message, CallManager issues a new request if the response contains an alternate contact. Otherwise, CallManager ends the call. |
6xx messages indicate that the target of the request was busy and cannot accept the incoming call | ||
6xx | Y | CallManager never sends this message. CallManager disconnects the call upon receiving this message. |
SIP requests and responses contain header fields. CallManager support for header fields is fairly consistent from message to message.
Table C-11 lists the header fields that CallManager sends in requests it originates.
Table C-11. SIP Response Messages
Header | Appears in Requests | Example with Comments |
---|---|---|
From | All | From: callerName <sip:cgpn@CCM_IP_addr> callerName is the caller’s display name; cgpn is the caller’s number; CCM_IP_addr is the IP address of CallManager. |
To | All | To: calledName <sip:cdpn@destIP;user=phone> calledName is the name of the call target, if available; cdpn is the number of the called party; destIP is the resolved IP address of the target of the SIP trunk. |
Via | All | Via:SIP/2.0 IPaddr:port;branch=number IPaddr is the IP address of CallManager; port is the port assigned to CallManager’s SIP trunk; branch is a unique number that identifies each branch of an outgoing forked call. CallManager SIP trunks don’t support forking, which means CallManager issues only a single request with a single branch identifier. |
Call-ID | All | Call-ID: number@IPaddr number is a unique call identifier determined by CallManager; IPaddr is the IP address of CallManager. |
Contact | All | Contact: <sip:cgpn@IPaddr:localPort;user=phone> IPAddr is the IP address of CallManager; cgpn is the calling number; localPort is the incoming port assigned to the issuing SIP trunk. |
Cseq | All | Cseq: number method number is a number that increments for each subsequent outgoing request; method is the name of the request (INVITE, ACK, and so on). |
Max-Forwards | All | Max-Forwards: number number indicates the maximum number of times that the message can propagate from call agent to call agent before the request expires. CallManager sets this value to 6 for originated SIP calls. |
Remote-Party-Id | INVITE | Remote-Party-Id: calledName <sip:cdpn@called_IP_address;user=phone>;party=calling;screen=no;privacy=off Indicates the display information for the party issuing the response. user indicates the class of responding device; party indicates the role of the responder in the call; screen indicates whether an intermediary entity has validated the display information; privacy indicates whether the information should be displayed to the requestor. |
Diversion | INVITE | Diversion: <sip:divertingNumber @diverting_IP_address >;reason=no-answer Indicates the prior history of the call. If the call has been previously diverted, this information must be communicated to the downstream voice mail server. reason indicates the reason for the diversion. |
Table C-12 lists the header fields that CallManager sends in responses to requests that it receives.
Table C-12. SIP Response Messages
Header | Appears in Message Classes | Example with Comments |
---|---|---|
From | All | From: <sip:cgpn@CCM_IP_Addr>;tag=16777234 cgpn is the number of the caller; CCM_IP_Addr is the address that issued the request; tag is part of a unique call identifier. |
To | All | To: <sip:cdpn@destIP>;tag=xxyyzz cdpn is the number of the responder; destIP is the IP address of the responder; tag is part of a unique call identifier. |
Via | All | Via: SIP/2.0/TCP CCM_IP_Addr:localPort;received=CCM_IP_Addr; branch=z9hG4bKfe8d27ec The Via chain—this header often occurs multiple times in a SIP request—indicates the path that the request took. branch is a unique identifier that indicates which fork of a branching call is issuing the response. |
Contact | All | Contact: <sip:cdpn@destIP:calledPort> The Contact represents the address of the specific entity that is responding to the message. |
Remote-Party-Id | 18X 2XX | Remote-Party-Id: calledName <sip:cdpn@destIP;user=phone>;party=called; screen=no;privacy=off Indicates the display information for the party issuing the response. user indicates the class of the responding device; party indicates the role of the responder in the call; screen indicates whether an intermediary entity has validated the display information; privacy indicates whether the information should be displayed to the requestor. |
The Skinny Client Control Protocol (SCCP) is a simple stimulus interface between the Cisco IP Phone and CallManager. Communication takes place over a TCP/IP connection that the phone establishes to CallManager on port 2000 by default (port number is configurable). Secure connections communicate on port 2443. Once established, the connection remains as long as the phone is capable of initiating or accepting calls.
SCCP provides a means of receiving stimulus events from the phone such as off-hook, on-hook, and button press events (including keypad digits, fixed keys, softkeys, and line keys). SCCP also provides a means of sending control information to the phone to drive the specific behavior required for the phone to provide the user with the correct information as calls are made and features are handled. You can review the details of SCCP in this appendix.
Figure C-1 illustrates calls made between Cisco IP Phones.
Table C-13 provides a step-by-step description of calls placed between two Cisco IP Phones.
Table C-13. Making a Call (Audio, Video, and Data) Between IP Phones that Are Each Connected to Cisco IP Communicator
Phone A | Cisco CallManager | Phone B | Description |
---|---|---|---|
OffHook --> | When you perform any number of off-hook actions, such as lifting the handset of IP Phone A or pressing the NewCall softkey, the phone reports off-hook to CallManager. | ||
SetLamp <-- | CallManager sends this message for several possible reasons. SetLamp has a lineInstance field. When the lineInstance field is 0, it lights or extinguishes the MWI lamp. If the lineInstance is other than 0, it turns on the envelope icon next to the line button on which a message is waiting. If the line button can be lit, it will be lit as well. | ||
CallState <-- | CallManager sends the CallState information, which the Cisco IP Phones 79xx series use to update the icon of the appropriate line as a visual indication of call state. | ||
SelectSoftKeys <-- | CallManager sends SelectSoftKeys to activate a set of softkeys and a mask to select which softkeys are enabled and which keys are disabled. Cisco 79xx series IP Phones use softkeys. | ||
DisplayPrompt Status <-- | CallManager sends the DisplayPromptStatus to update the prompt line, which is the display line just above the softkey text line on Cisco 79xx series IP Phones. This initial prompt for off-hook state is “Enter number.” For idle state, the phone displays “Your current options.” The prompt message is associated with a particular line. If a different line is selected, the prompt changes to the prompt associated with the selected line. | ||
DisplayText <-- | CallManager sends the text to update the display of a limited-display phone, such as the 30VIP. | ||
ActivateCallPlane <-- | CallManager sends ActivateCallPlane to activate the call plane for the specified line. In this case, the call is line 1 as the default because no specific line was selected. Cisco 79xx series IP Phones use the ActivateCallPlane command. | ||
StartTone <-- | CallManager directs the phone to play an inside dial tone. The phone internally generates a dial tone. | ||
KeyPad Button --> | As you enter the number of the desired destination—Phone B in this case—the phone sends a KeyPadButton for each digit dialed. The KeyPadButton messages continue until CallManager determines that you have entered the required number of digits to reach your destination. When CallManager determines the called party—Phone B in this case—CallManager initiates the message sequence to Phone B to extend the call to Phone B. | ||
StopTone <-- | CallManager directs the phone to stop playing dial tone after you enter the first digit. | ||
SelectSoftKeys <-- | CallManager sends SelectSoftKeys to activate the next set of softkeys and the mask to select which softkeys are enabled and which softkeys are disabled. Cisco 79xx series IP Phones use softkeys. | ||
CallState --> | CallManager sends CallState information, which Cisco 79xx series IP Phones use to update the call state information and the icon of the appropriate line as a visual indication of call state. In this case, the call state indicates an incoming call. | ||
SelectSoftKeys --> | CallManager sends SelectSoftKeys to Phone B to activate the appropriate softkeys. | ||
DisplayPrompt Status --> | CallManager sends DisplayPromptStatus to Phone B to update the display associated with the particular line of the incoming call. This display persists for the selected line until it is changed by another DisplayPromptStatus message of an equal or higher priority. | ||
--> | CallManager sends DisplayPriNotify to Phone B to indicate an incoming call. DisplayPriNotify, which has an associated timeout that defaults to 10 seconds, updates the display immediately and is not associated with a particular line. The priority of the incoming call is included with the notification. | ||
CallInfo --> | CallManager sends CallInfo to the station to provide the specific information about the call, which includes calling and called party name and number, the line number for the call, and the type of call (inbound, outbound, or forwarded). In this case, the call type is inbound. The name might not be provided in all cases. A gateway call, for example, might not provide calling party name. | ||
SetLamp --> | CallManager sends this message for several possible reasons. SetLamp has a lineInstance field. When the lineInstance field is 0, it lights or extinguishes the MWI lamp. If the lineInstance is other than 0, it turns on the envelope icon next to the line button on which a message is waiting. If the line button can be lit, it will be lit as well. | ||
SetRinger --> | CallManager sends the SetRinger to Phone B to cause the phone to ring, indicating an incoming call. The ring type is InsideRing, as distinguished from OutsideRing, because this is an internal call from Phone A to Phone B. | ||
StartTone <-- | CallManager sends StartTone to Phone A to initiate the ringback tone to the caller at Phone A. The tone is generated internally by Phone A. | ||
CallState <-- | CallManager updates the call state of Phone A to indicate that Phone B is now ringing. | ||
SelectSoftKeys <-- | CallManager sends SelectSoftKeys to Phone A to activate the appropriate softkeys for the ringing call. | ||
DisplayPrompt Status <-- | CallManager sends DisplayPromptStatus to Phone A to display the prompt appropriate for the updated softkeys. | ||
CallInfo <-- | CallManager sends CallInfo to Phone A to provide the specific information about the call, which includes calling and called party name and number, the line number for the call, and the type of call. Because Phone A originated the call, the call is outbound. | ||
OffHook <-- | When you perform any number of off-hook actions, such as lifting the handset of Phone B or pressing the Answer softkey, the phone reports off-hook to CallManager. | ||
SetRinger --> | CallManager turns off the ringer because the call has been answered. | ||
SetLamp --> | CallManager uses this message to set the line lamp of the line answered on Phone B. | ||
CallState --> | CallManager updates the call state information for the call because it has changed from ringing to answered. | ||
ActivateCallPlane --> | CallManager activates the call plane for the line that was answered. | ||
StopTone <-- --> | CallManager stops the ringback tone on Phone A and the ringer tone on Phone B. | ||
OpenReceive Channel (audio) <-- --> | CallManager sends OpenReceiveChannel to both Phone A and B to cause the phone to begin receiving audio sent from the other phone. This is only half of the audio path, and because neither phone is transmitting at this point, the connection is not yet fully established. | ||
OpenMultiMedia ReceiveChannel (video) <-- --> | CallManager sends OpenMultiMediaReceiveChannel (video) to both Phone A and B to cause the phone to begin receiving video sent from the other phone. This is only half of the video path, and because neither phone is transmitting at this point, the connection is not yet fully established. | ||
OpenMultiMedia ReceiveChannel (data) <-- --> | CallManager sends OpenMultiMediaReceiveChannel (data) to both Phone A and B to cause the phone to begin receiving data sent from the other phone. This is only half of the data path, and because neither phone is transmitting at this point, the connection is not yet fully established. | ||
CallState <-- --> | The call state is updated to connected for both Phone A and B. | ||
SelectSoftKeys <-- --> | The softkeys are updated on both Phone A and B. | ||
DisplayPrompt Status <-- --> | The prompt line is updated on both Phone A and B. | ||
CallInfo <-- --> | The call info is updated for both Phone A and B. | ||
Open Receive Channel Ack (audio) --> | Open Receive Channel Ack (audio) <-- | Both phones have responded with an OpenReceiveChannelAck (audio), indicating that they are ready to receive audio transmission. | |
Open MultiMedia Receive Channel Ack (video) --> | Open MultiMedia Receive Channel Ack (video) <-- | Both phones have responded with an OpenMultiMediaReceiveChannelAck (video), indicating that they are ready to receive video transmission. | |
Open MultiMedia Receive Channel Ack (data) --> | Open MultiMedia Receive Channel Ack (data) <-- | Both phones have responded with an OpenMultiMediaReceiveChannelAck (data), indicating that they are ready to receive data transmission. | |
StartMedia Transmission (audio) <-- --> | CallManager sends StartMediaTransmission (audio) to both Phone A and B to cause the phone to begin sending audio to the other phone. Because both phones are transmitting and receiving audio at this point, the audio connection is now fully established. | ||
StartMultiMedia Transmission (video) <-- --> | CallManager sends StartMultiMediaTransmission (video) to both Phone A and B to cause the phone to begin sending video to the other phone. Because both phones are transmitting and receiving video at this point, the video connection is now fully established. | ||
StartMultiMedia Transmission (data) <-- --> | CallManager sends StartMultiMediaTransmission (data) to both Phone A and B to cause the phone to begin sending data to the other phone. Because both phones are transmitting and receiving data at this point, the data connection is now fully established. |
CallManager provides support for application development. The protocols to support applications include TAPI, JTAPI, and XML for application development. TAPI is not covered in this appendix; you can learn about TAPI in Chapter 3.
JTAPI supports call control and primitive media support. JTAPI consists of a set of packages. A package is a means of grouping the functionality used by applications. Telephony server implementations choose the functionality that they support in each of the packages to leverage the underlying capabilities offered to the application. Applications can query to discover what packages and functionality is provided. The Core package support is the central functionality and the surrounding JTAPI packages include Call Center, Call Control, and Media packages, described in the tables that follow.
Table C-14 lists each JTAPI interface in the JTAPI Core Package, all of which are supported in the Cisco JTAPI implementation.
Table C-14. JTAPI Core Package Support
Class Name | Method Name | Comments |
---|---|---|
Address | addCallObserver | |
addressObserver | ||
getAddressCapabilities | ||
getCallObservers | ||
getCapabilities | ||
getConnections | ||
getName | ||
getObservers | ||
getProvider | ||
getTerminals | ||
removeCallObserver | ||
removeObserver | ||
AddressObserver | addressChangedEvent | |
Call | addObserver | |
connect | A CallObserver must exist for the terminal or address originating the call. | |
getCallCapabilities | ||
getCapabilities | ||
getConnections | ||
getObservers | ||
getProvider | ||
getState | ||
removeObserver | ||
CallObserver | callChangedEvent | |
Connection | disconnect | |
getAddress | ||
getCall | ||
getCapabilities | ||
getConnectionCapabilities | ||
getState | ||
getTerminalConnections | ||
JtapiPeer | getName | |
getProvider | ||
getServices | ||
JtapiPeerFactory | getJtapiPeer | |
Provider | addObserver | |
createCall | ||
getAddress | ||
getAddressCapabilities() | ||
getAddressCapabilities(Terminal) | ||
getAddresses | ||
getCallCapabilities() | ||
getCallCapabilities(Terminal, Address) | ||
getCalls | This method returns calls only when there are CallObservers attached to addresses or terminals, when a RouteAddress is registered for routing, or when a CiscoMedia Terminal is registered. | |
getCapabilities | ||
getConnectionCapabilities() | ||
getConnectionCapabilities(Terminal, Address) | ||
getName | ||
getObservers | ||
getProviderCapabilities() | ||
getProviderCapabilities(Terminal) | ||
getState | ||
getTerminal | ||
getTerminalCapabilities() | ||
getTerminalCapabilities(Terminal) | ||
getTerminalConnectionCapabilities() | ||
getTerminalConnectionCapabilities (Terminal) | ||
getTerminals | ||
removeObserver | ||
shutdown | ||
ProviderObserver | providerChangedEvent | |
Terminal | addCallObserver | |
addObserver | ||
getAddresses | ||
getCallObservers | ||
getCapabilities | ||
getName | ||
getObservers | ||
getProvider | ||
getTerminalCapabilities | ||
getTerminalConnections | ||
removeCallObserver | ||
removeObserver | ||
TerminalConnection | answer | |
getCapabilities | ||
getConnection | ||
getState | ||
getTerminal | ||
getTerminalConnectionCapabilities | ||
TerminalObserver | terminalChangedEvent |
Table C-15 lists each JTAPI interface in the JTAPI Call Center Package and the support provided by the Cisco JTAPI implementation.
Table C-15. JTAPI Call Center Package Support
Class Name | Method Name | Cisco JTAPI Support |
---|---|---|
ACDAddress | getACDManagerAddress | No |
getLoggedOnAgents | No | |
getNumberQueued | No | |
getOldestCallQueued | No | |
getQueueWaitTime | No | |
getRelativeQueueLoad | No | |
ACDAddressObserver | No | |
ACDConnection | getACDManagerConnection | No |
ACDManagerAddress | getACDAddresses | No |
ACDManagerConnection | getACDConnections | No |
Agent | getACDAddress | No |
getAgentAddress | No | |
getAgentID | No | |
getAgentTerminal | No | |
getState | No | |
setState | No | |
AgentTerminal | addAgent | No |
getAgents | No | |
removeAgents | No | |
setAgents | No | |
AgentTerminalObserver | No | |
CallCenterAddress | addCallObserver | No |
CallCenterCall | connectPredictive | No |
getApplicationData | No | |
getTrunks | No | |
setApplicationData | No | |
CallCenterCallObserver | No | |
CallCenterProvider | getACDAddresses | No |
getACDManagerAddresses | No | |
getRouteableAddresses | No | |
CallCenterTrunk | getCall | No |
getName | No | |
getState | No | |
getType | No | |
RouteAddress | cancelRouteCallback | Yes |
getActiveRouteSessions | Yes | |
getRouteCallback | Yes | |
registerRouteCallback | Yes | |
RouteCallback | reRouteEvent | Yes |
routeCallbackEndedEvent | Yes | |
routeEndEvent | Yes | |
routeEvent | Yes | |
routeUsedEvent | Yes | |
RouteSession | endRoute | Yes |
getCause | Yes | |
getRouteAddress | Yes | |
getState | Yes | |
selectRoute | Yes |
Table C-16 lists each JTAPI interface in the JTAPI Call Center Capabilities Package and the support provided by the Cisco JTAPI implementation.
Table C-16. JTAPI Call Center Capabilities Package Support
Class Name | Method Name | Cisco JTAPI Support |
---|---|---|
ACDAddressCapabilities | canGetACDManagerAddress | No |
canGetLoggedOnAgents | No | |
canGetNumberQueued | No | |
canGetOldestCallQueued | No | |
canGetQueueWaitTime | No | |
canGetRelativeQueueLoad | No | |
ACDConnectionCapabilities | canGetACDManagerConnection | No |
ACDManagerAddressCapabilities | canGetACDAddresses | No |
ACDManagerConnectionCapabilities | canGetACDConnections | No |
AgentTerminalCapabilities | canHandleAgents | No |
CallCenterAddressCapabilities | canAddCallObserver | No |
CallCenterCallCapabilities | canConnectPredictive | No |
canGetTrunks | No | |
canHandleApplicationData | No | |
CallCenterProviderCapabilities | canGetACDAddresses | Yes |
canGetACDManagerAddresses | Yes | |
canGetRouteableAddresses | Yes | |
RouteAddressCapabilities | canRouteCalls | Yes |
Table C-17 lists each JTAPI interface in the JTAPI Call Center Events Package and the support provided by the Cisco JTAPI implementation.
Table C-17. JTAPI Call Center Events Package Support
Class Name | Method Name | Cisco JTAPI Support |
---|---|---|
ACDAddrBusyEv | No | |
ACDAddrEv | getAgent | No |
getAgentAddress | No | |
getAgentTerminal | No | |
getState | No | |
getTrunks | No | |
ACDAddrLoggedOffEv | No | |
ACDAddrLoggedOnEv | No | |
ACDAddrNotReadyEv | No | |
ACDAddrReadyEv | No | |
ACDAddrUnknownEv | No | |
ACDAddrWorkNotReadyEv | No | |
ACDAddrWorkReadyEv | No | |
AgentTermBusyEv | No | |
AgentTermEv | getACDAddress | No |
getAgent | No | |
getAgentAddress | No | |
getAgentID | No | |
getState | No | |
AgentTermLoggedOffEv | No | |
AgentTermLoggedOnEv | No | |
AgentTermNotReadyEv | No | |
AgentTermReadyEv | No | |
AgentTermUnknownEv | No | |
AgentTermWorkNotReadyEv | No | |
AgentTermWorkReadyEv | No | |
CallCentCallAppDataEv | getApplicationData | No |
CallCentCallEv | getCalledAddress | No |
getCallingAddress | No | |
getCallingTerminal | No | |
getLastRedirectedAddress | No | |
getTrunks | No | |
CallCentConnEv | No | |
CallCentConnInProgressEv | No | |
CallCentEv | getCallCenterCause | No |
CallCentTrunkEv | getTrunk | No |
CallCentTrunkInvalidEv | No | |
CallCentTrunkValidEv | No | |
ReRouteEvent | Yes | |
RouteCallbackEndedEvent | getRouteAddress | Yes |
RouteEndEvent | Yes | |
RouteEvent | getCallingAddress | Yes |
getCallingTerminal | Yes | |
getCurrentRouteAddress | Yes | |
getRouteSelectAlgorithm | Yes | |
getSetupInformation | Yes | |
RouteSessionEvent | getRouteSession | Yes |
RouteUsedEvent | getCallingAddress | Yes |
getCallingTerminal | Yes | |
getDomain | Yes | |
getRouteUsed | Yes |
Table C-18 lists each JTAPI interface in the JTAPI Call Control Package and the support provided by the Cisco JTAPI implementation.
Table C-18. JTAPI Call Control Package Support
Class Name | Method Name | Cisco JTAPI Support | Comments |
---|---|---|---|
CallControlAddress | cancelForwarding | Yes | Only for Call Forward All. |
getDoNotDisturb | No | ||
getForwarding | Yes | Only for Call Forward All. | |
getMessageWaiting | No | ||
setDoNotDisturb | No | ||
setForwarding | Yes | Only for Call Forward All. | |
setMessageWaiting | No | ||
CallControlCall | addParty | No | |
conference | Yes | In a consultation conference scenario where the conference controller speaks with the potential conference participant prior to adding the participant to the conference, only OriginalCall.conference (ConsultCall) is supported. ConsultCall.conference (OriginalCall) is not supported. | |
CallControlCall | consult(TerminalConnection) | Yes | |
consult(TerminalConnection, String) | Yes | ||
drop | Yes | ||
getCalledAddress | Yes | ||
getCallingAddress | Yes | ||
getCallingTerminal | Yes | ||
getConferenceController | Yes | ||
getConferenceEnable | Yes | ||
getLastRedirectedAddress | Yes | ||
getTransferController | Yes | ||
getTransferEnable | Yes | ||
offHook | Yes | ||
setConferenceController | Yes | ||
setConferenceEnable | Yes | ||
setTransferController | Yes | ||
setTransferEnable | Yes | ||
transfer(Call) | Yes | In a consultation transfer scenario, only OriginalCall.transfer (ConsultCall) is supported. ConsultCall.transfer (OriginalCall) is not supported. | |
transfer(String) | Yes | ||
CallControlCallObserver | Yes | ||
CallControlConnection | accept | Yes | |
addToAddress | Yes | ||
getCallControlState | Yes | ||
park | Yes | ||
redirect | Yes | Redirect allows a connection in the state, CallControlConnection. ESTABLISHED, to be redirected. | |
reject | Yes | ||
CallControlForwarding | getDestinationAddress | No | |
getFilter | No | ||
getSpecificCaller | No | ||
getType | No | ||
CallControlTerminal | getDoNotDisturb | No | |
pickup (Address, Address) | No | ||
pickup (Connection, Address) | No | ||
pickup (TerminalConnection, Address) | No | ||
pickupFromGroup(Address) | No | ||
pickupFromGroup(String, Address) | No | ||
setDoNotDisturb | No | ||
CallControlTerminal Connection | getCallControlState | Yes | |
hold | Yes | ||
join | No | ||
leave | No | ||
unhold | Yes | ||
CallControlTerminal Observer | No |
Table C-19 lists each JTAPI interface in the JTAPI Call Control Capabilities Package, all of which are supported in the Cisco JTAPI implementation.
Table C-19. JTAPI Call Control Capabilities Package Support
Class Name | Method Name |
---|---|
CallControlAddressCapabilities | canCancelForwarding |
canGetDoNotDisturb | |
canGetForwarding | |
canGetMessageWaiting | |
canSetDoNotDisturb | |
canSetForwarding | |
canSetMessageWaiting | |
CallControlCallCapabilities | canAddParty |
canConference | |
canConsult | |
canConsult(TerminalConnection) | |
canConsult(TerminalConnection, String) | |
canDrop | |
canOffHook | |
canSetConferenceController | |
canSetConferenceEnable | |
canSetTransferController | |
canSetTransferEnable | |
canTransfer | |
canTransfer(Call) | |
canTransfer(String) | |
CallControlConnectionCapabilities | canAccept |
canAddToAddress | |
canPark | |
canRedirect | |
canReject | |
CallControlTerminalCapabilities | canGetDoNotDisturb |
canPickup | |
canPickup(Address, Address) | |
canPickup(Connection, Address) | |
canPickup(TerminalConnection, Address) | |
canPickupFromGroup | |
canPickupFromGroup(Address) | |
canPickupFromGroup(String, Address) | |
canSetDoNotDisturb | |
CallControlTerminalConnectionCapabilities | canHold |
canJoin | |
canLeave | |
canUnhold |
Table C-20 lists each JTAPI interface in the JTAPI Call Control Events Package and the support provided by the Cisco JTAPI implementation.
Table C-20. JTAPI Call Control Events Package Support
Class Name | Method Name | Cisco JTAPI Support |
---|---|---|
CallCtlAddrDoNotDisturbEv | getDoNotDisturbState | No |
CallCtlAddrEv | No | |
CallCtlAddrForwardEv | getForwarding | Yes |
CallCtlAddrMessageWaitingEv | getMessageWaitingState | No |
CallCtlCallEv | getCalledState | Yes |
getCallingAddress | Yes | |
getCallingTerminal | Yes | |
getLastRedirectedAddress | Yes | |
CallCtlConnAlertingEv | Yes | |
CallCtlConnDialingEv | getDigits | Yes |
CallCtlConnDisconnectedEv | Yes | |
CallCtlConnEstablishedEv | Yes | |
CallCtlConnEv | Yes | |
CallCtlConnFailedEv | Yes | |
CallCtlConnInitiatedEv | Yes | |
CallCtlConnNetworkAlertingEv | Yes | |
CallCtlConnNetworkReachedEv | Yes | |
CallCtlConnOfferedEv | Yes | |
CallCtlConnQueuedEv | getNumberInQueue | Yes |
CallCtlConnUnknownEv | Yes | |
CallCtlEv | getCallControlCause | Yes |
CallCtlTermConnBridgedEv | No | |
CallCtlTermConnDroppedEv | Yes | |
CallCtlTermConnEv | Yes | |
CallCtlTermConnHeldEv | Yes | |
CallCtlTermConnInUseEv | No | |
CallCtlTermConnRingingEv | Yes | |
CallCtlTermConnTalkingEv | Yes | |
CallCtlTermConnUnknownEv | Yes | |
CallCtlTermDoNotDisturbEv | No | |
CallCtlTermEv | No |
Table C-21 lists each JTAPI interface in the JTAPI Capabilities Package, all of which are supported by the Cisco JTAPI implementation.
Table C-22 lists each JTAPI interface in the JTAPI Events Package and the support provided by the Cisco JTAPI implementation.
Table C-22. JTAPI Events Package Support
Class Name | Method Name | Cisco JTAPI Support |
---|---|---|
AddrEv | getAddress | Yes |
AddrObservationEndedEv | Yes | |
CallActiveEv | Yes | |
CallEv | getCall | Yes |
CallInvalidEv | Yes | |
CallObservationEndedEv | getEndedObject | Yes |
ConnAlertingEv | Yes | |
ConnConnectedEv | Yes | |
ConnCreatedEv | Yes | |
ConnDisconnectedEv | Yes | |
ConnEv | getConnection | Yes |
ConnFailedEv | Yes | |
ConnInProgressEv | Yes | |
ConnUnknownEv | Yes | |
Ev | getCause | Yes |
getID | Yes | |
getMetaCode | Yes | |
getObserved | Yes | |
isNewMetaEvent | Yes | |
ProvEv | getProvider | Yes |
ProvInServiceEv | Yes | |
ProvObservationEndedEv | Yes | |
ProvOutOfServiceEv | Yes | |
ProvShutdownEv | Yes | |
TermConnActiveEv | Yes | |
TermConnCreatedEv | Yes | |
TermConnDroppedEv | Yes | |
TermConnEvgetTerminalConnection | Yes | |
TermConnPassiveEv | No | |
TermConnRingingEv | Yes | |
TermConnUnknownEv | Yes | |
TermEv | getTerminal | Yes |
TermObservationEndedEv | Yes |
Table C-23 lists each JTAPI interface in the JTAPI Media Package and the support provided by the Cisco JTAPI implementation.
Table C-24 lists each JTAPI interface in the JTAPI Media Capabilities Package, all of which are supported by the Cisco JTAPI implementation.
Table C-25 lists each JTAPI interface in the JTAPI Media Events Package and the support provided by the Cisco JTAPI implementation.
This section provides the details of the XML support provided by the Cisco IP Phones to support the development of IP phone services described in Chapter 3.
Several of the XML data types described here have optional Title and Prompt fields. These fields behave identically, so this section describes them and the remainder of this chapter does not repeat the description.
Text defined in the Title field appears at the top of the page. If the data page specifies no Title field, the IP phone displays the Name field of the last selected MenuItem in the Title field.
The Prompt field defines text to appear at the bottom of the display page. If the data page specifies no Prompt parameter, the prompt area of the display is cleared.
The XML type CiscoIPPhoneMenu simply lists text items, one per line. Users select individual menu items either by using the scroll and entry selector or by number from the numeric keypad. The XML format allows you to specify a menu Title and Prompt, followed by up to 100 MenuItems. Each MenuItem has a name and an associated URL. After the user selects a menu option, the phone sends an HTTP request based on the URL associated with the menu item selected. Example C-1 shows the CiscoIPPhoneMenu XML type.
Example C-1. CiscoIPPhoneMenu XML Type
<CiscoIPPhoneMenu> <Title>Title text goes here</Title> <Prompt>Prompt text goes here</Prompt> <MenuItem> <Name>The name of each menu item</Name> <URL>The URL associated with the menu item</URL> </MenuItem> <SoftKeyItem> <Name>Name of softkey</Name> <URL>URL or URI of softkey</URL> <Position>Position information of the softkey</Position> </SoftKeyItem> </CiscoIPPhoneMenu>
Icon menus, like text menus, enable you to select a URL from a list. The icon menu allows you the additional capability to display visual information, such as item state or category, for each item in the list. Example C-2 shows the IconMenu XML type.
Example C-2. CiscoIPPhoneIconMenu XML Type
<CiscoIPPhoneIconMenu> <Title>Title text goes here</Title> <Prompt>Prompt text goes here</Prompt> <MenuItem> <IconIndex>Indicates what IconItem to display</IconIndex> <Name>The name of each menu item</Name> <URL>The URL associated with the menu item</URL> </MenuItem> <SoftKeyItem> <Name>Name of softkey</Name> <URL>URL or URI of softkey</URL> <Position>Position information of the softkey</Position> </SoftKeyItem> <IconItem> <Index>A unique index from 0 to 9</Index> <Height>size information for the icon</Height> </CiscoIPPhoneIconMenu>
The XML type CiscoIPPhoneText displays text on the phone display. The text should contain no control characters other than carriage return, line feed, or tab. The phone provides pagination and word-wrap to fit the text to the phone display. Plain text can be delivered either through this XML type or as plain text through HTTP. Text delivered as type text/HTML behaves the same as type CiscoIPPhoneText, except for the inability to include a Title or Prompt. Example C-3 shows the CiscoIPPhoneText XML type.
Example C-3. CiscoIPPhoneText XML Type
<CiscoIPPhoneText> <Title>Title text goes here</Title> <Prompt>The prompt text goes here</Prompt> <Text>The text to be displayed as the message body goes here</Text> <SoftKeyItem> <Name>Name of softkey</Name> <URL>URL or URI of softkey</URL> <Position>Position information of the softkey</Position> </SoftKeyItem> </CiscoIPPhoneText>
The Cisco IP Phones 7960 and 7940 have a bitmapped display that is 133 by 65 pixels. Each pixel has four grayscale settings. The CiscoIPPhoneImage is used to render graphics on the Cisco IP Phone 7960 or 7940 display. The CiscoIPPhoneImage objects will display on the 7971, 7970, 7961, 7941, and IP Communicator phones, and the image size is doubled to compensate for the difference in screen resolution. The values specified by parameters LocationX and LocationY control the position of the graphic. These values specify the location, in pixels, of the upper-left corner of the graphic. The values 0, 0 position the graphic at the upper-left corner of the display. The values –1, –1 instruct the phone to center the graphic in the display area.
Width and Height, used to control those two dimensions, must be matched up properly with the pixel stream in the Data field to produce the desired results. Depth specifies the number of bits per pixel, which currently can be set to 1 for black and white image support or 2 bits per pixel grayscale yielding white, light gray, dark gray, and black.
The Data tag delimits a string of hexadecimal digits that contain the packed value of pixels in the display. In the Cisco IP Phones 7960 and 7940, each pixel has only three possible states, allowing 4 pixels packed per byte. Each byte is specified as 2 hex digits.
Table C-26 shows how the hex digits are packed to specify the pixel values, 2 bits per pixel. A contiguous stream of hex digits, with no separators or spaces, specifies the entire display. The stream is (width × height + 3)/4 characters in length. The phone display is cleared at the time the graphic is displayed. For a single pixel depth of 1 (black and white), the pixels are packed 8 pixels per byte.
Example C-4 shows the CiscoIPPhoneImage XML type.
Example C-4. CiscolPPhoneImage XML Type
<CiscoIPPhoneImage> <Title>Image title goes here</Title> <Prompt>Prompt text goes here</Prompt> <LocationX>Position information of graphic</LocationX> <LocationY>Position information of graphic</LocationY> <Width>Size information for the graphic</Width> <Height>Size information for the graphic</Height> <Depth>Number of bits per pixel</Depth> <Data>Packed Pixel Data</Data> <SoftKeyItem> <Name>Name of softkey</Name> <URL>URL or URI of softkey</URL> <Position>Position information of the softkey</Position> </SoftKeyItem> </CiscoIPPhoneImage>
Because the latest generation of Cisco IP Phones—7971, 7970, 7961, and 7941, for example—have higher-resolution displays with more color depth, the ImageFile object has been added to allow the use of color Portable Network Graphics (PNG) images. The PNG image can either be palletized or RGB. The maximum image size and the color depth differ for the various Cisco IP Phone models. For the best display results, the number of colors in the image should be matched to the capabilities of the Cisco IP Phone. Table C-27 lists the resolution and color depth supported in each of the phone models.
Table C-27. Display Size and Color Depth
Model | Resolution Width × Height | Color/Grayscale | Color Depth (Bits) |
---|---|---|---|
7905/7912 | Does not support DisplayImage | N/A | 1 |
7920 | 128 × 59 | Grayscale | 1 |
7940/7960 | 133 × 65 | Grayscale | 2 |
7941/7961 | 298 × 144 | Grayscale | 4 |
7970/7971 | 298 × 168 | Color | 12 |
IP Communicator | 298 × 168 | Color | 24 |
Example C-5 shows the CiscoIPPhoneImageFile XML type.
Example C-5. CiscoIPPhoneImageFile XML Type
<CiscoIPPhoneImageFile> <Title>Image title goes here</Title> <Prompt>Prompt text goes here</Prompt> <LocationX>Position information of graphic</LocationX> <LocationY>Position information of graphic</LocationY> <UR>Points to the PNG image</URL> </CiscoIPPhoneImageFile>
Graphic menus, like text menus, enable a user to select a menu item. The graphic menu allows a graphic to be used rather than text for the menu items. The menu item is presented as a bitmapped graphic. The user enters a menu selection by using the keypad to enter a number that selects the menu item. The XML tags for GraphicMenu are identical to the tag definitions for CiscoIPPhoneImage and CiscoIPPhoneMenu. Example C-6 shows the CiscoIPPhoneGraphicMenu XML type.
Example C-6. CiscoIPPhoneGraphicMenu XML Type
<CiscoIPPhoneGraphicMenu> <Title>Menu title goes here</Title> <LocationX>Position information of graphic</LocationX> <LocationY>Position information of graphic</LocationY> <Width>Size information for the graphic</Width> <Height>Size information for the graphic</Height> <Depth>Number of bits per pixel</Depth> <Data>Packed Pixel Data</Data> <Prompt>Prompt text goes here</Prompt> <MenuItem> <Name>The name of each menu item</Name> <URL>The URL associated with the menu item</URL> </MenuItem> <SoftKeyItem> <Name>Name of softkey</Name> <URL>URL or URI of softkey</URL> <Position>Position information of the softkey</Position> </SoftKeyItem> </CiscoIPPhoneGraphicMenu>
The GraphicFileMenu enables you to leverage the pointer devices available on some of the Cisco IP Phones, including the touch-screen overlay of the Cisco IP Phone 7971 and 7970 and the standard Windows mouse pointer for Cisco IP Communicator. The GraphicFileMenu behaves similarly to the GraphicMenu but defines touch areas for the selection rather that the keypad. Example C-7 shows the CiscoIPPhoneGraphicFileMenu XML type.
Example C-7. CiscolPPhoneGraphicMenu XML Type
<CiscoIPPhoneGraphicMenu> <Title>Image title goes here</Title> <Prompt>Prompt text goes here</Prompt> <LocationX>Horizontal position of graphic</LocationX> <LocationY>Vertical position of graphic</LocationY> <URL>Points to the PNG background image</URL> <MenuItem> <Name>Same as CiscoIPPhoneGraphicMenu</Name> <URL>Invoked when the TouchArea is touched</URL> <TouchArea X1="left edge" Y1="top edge" X2="right edge" Y2="bottom edge"/> </MenuItem> </ CiscoIPPhoneGraphicFileMenu >
CiscoIPPhoneDirectory XML data type is used for directory-type operations. The directory entry is selected just like menu items. Up to 32 directory entries can be included in the directory. In addition, the Cisco IP Phones 7971, 7970,, 7961, 7960, 7941, 7940, 7912, and 7905 display the appropriate softkeys that are needed to initiate a call to the selected number. One softkey is EditDial, which allows the user to insert an access code or other necessary digits before dialing. The DirectoryEntry field is repeated as many times as is necessary to send all the entries to the phone. Example C-8 shows the CiscoIPPhoneDirectory XML type.
Example C-8. CiscoIPPhoneDirectory XML Type
<CiscoIPPhoneDirectory> <Title>Directory title goes here</Title> <Prompt>Prompt text goes here</Prompt> <DirectoryEntry> <Name>The name of the directory entry</Name> <Telephone>The telephone number for the entry</Telephone> </DirectoryEntry> <SoftKeyItem> <Name>Name of softkey</Name> <URL>URL or URI of softkey</URL> <Position>Position information of the softkey</Position> </SoftKeyItem> </CiscoIPPhoneDirectory>
In response to a CiscoIPPhoneInput, the phone builds and displays the input form. The input form prompts the user for specific data. When the user enters the data, the phone collects that data according to the input form specifications and sends the data to the target URL. The URL tag specifies the URL to receive the results. The HTTP request sent to the server is the URL with a list of parameters appended as a query string. The parameters are name/value pairs, one pair for each input item.
Cisco IP Phones do not support the HTTP POST method. POST is an HTTP method for submitting data to a web server.
The InputItem tag delimits each of the lists of input items. Each item has a DisplayName, a QueryStringParam, a DefaultValue, and a set of InputFlags. The DisplayName specifies the prompt that is written to the display for the input list item. The QueryStringParam provides the parameter name used in the URL that is returned to the server when the input is complete. The DefaultValue tag, if specified, denotes the default value to be displayed. The set of InputFlags controls the input to be used for the input item. The input types include
A—Plain ASCII text. The dual-tone multifrequency (DTMF) keypad is used to enter text consisting of uppercase and lowercase letters, numbers, and special characters.
T—Telephone number. DTMF digits are the only acceptable input for this field. This includes numbers, the pound key (#), and the asterisk key (*).
N—Numeric. Numbers are the only acceptable input.
E—Equation. This includes numbers and special math symbols.
U—Uppercase. This is only uppercase letters.
L—Lowercase. This is only lowercase letters.
P—Password field. Individual characters are displayed as they are keyed in using the standard keypad-repeat entry mode. As soon as each character is accepted, it is converted to an asterisk, allowing for privacy of the entered value. The password type is always a modifier to one of the other types and not used by itself. AP, for example, is valid and uses the Password field to modify the plain ASCII text field.
Example C-9 shows the CiscoIPPhoneInput XML type.
Example C-9. CiscoIPPhoneInput XML Type
<CiscoIPPhoneInput> <Title>Directory title goes here</Title> <Prompt>Prompt text goes here</Prompt> <URL>The target URL for the completed input goes here</URL> <InputItem> <DisplayName>Name of the input field to display</DisplayName> <QueryStringParam>The URL query parameter</QueryStringParam> <DefaultValue>Value</DefaultValue> <InputFlagsThe default display name></InputFlags> </InputItem> <SoftKeyItem> <Name>Name of softkey</Name> <URL>URL or URI of softkey</URL> <Position>Position information of the softkey</Position> </SoftKeyItem> </CiscoIPPhoneInput>
During the entry of the text, as shown in Example C-9, the Cisco IP Phones 7971, 7970, 7961, 7960, 7941, and 7940 display softkeys that are intended to help the data-entry process. The following softkeys are used:
Select—Select an item for action.
OK—Leave the current page, committing any value changes made on the page.
Cancel—Leave the current page, and cancel any value changes made on the page.
Exit—Exit the current menu page.
Next—Use to move to the next item or page.
Back—Use to go back to the previous item or page.
Update—Reload and update the current page.
Dial—Initiate a call to the current entry selected.
EditDial—Open an edit screen for the current entry selected.
Submit—Indicates that the form is complete and the resulting URL should be sent by HTTP.
<<—Backspace within a field.
Field-to-field navigation can be performed with the navigation control (vertical scroll bar or 4-way control) used to navigate menus.
Status is a displayable object that enables you to display information on the call plane of a Cisco IP Phone. The display object is typically used by CTI applications to present status updates to the user, which can be refreshed or replaced as needed.
Example C-10 shows the CiscoIPPhoneStatus XML type.
Example C-10. CiscoIPPhoneStatus XML Type
<CiscoIPPhoneStatus> <Text>This is the text area</Text> <Timer>Timer seed value in seconds</Timer> <LocationX>Horizontal alignment</LocationX> <LocationY>Vertical alignment</LocationY> <Width>Pixel width of graphic</Width> <Height>Pixel height of graphic</Height> <Depth>Color depth in bits</Depth> <Data>Hex binary image data</Data> </CiscoIPPhoneStatus>
Use the Execute object to push a request to the phone via the web server using the HTTP POST method, providing HTTP authentication information with the POST. You can include up to three ExecuteItems in a single POST composed of URIs and URLs. You can include one URL or none in a POST, and the rest of the items, up to the maximum, are URIs as needed. The optional Priority attribute determines when the requested action is performed by the phone.
0—Execute immediately (default priority). The URL executes regardless of the state of the phone.
1—Execute when idle. Delay the URL execution until the phone is idle.
2—Execute if idle. Execute the URL if the phone is idle; otherwise do not execute.
Example C-11 shows the CiscoIPPhoneExecute XML type.
You receive a response item for every ExecuteItem sent to the phone. The URL attribute identifies the URL or URI that you sent with the request. Data contains any special data and the Status attribute returns the status code. A status code of zero indicates no error; if an error occurs, the CiscoIPPhoneError object described below is returned. Example C-12 shows the CiscoIPPhoneResponse XML type.
The error response provides a means of returning an error status to an execute request. Example C-13 shows the CiscoIPPhoneError XML type.
The error response values are as follows:
Error 1—Error parsing CiscoIPPhoneExecute object. There is a syntax error in the executed code. You should correct the syntax of the object and rerun.
Error 2—Error framing CiscoIPPhoneResponse object. There is a problem rendering the object data. Review the rendering that the object attempted and make the required changes to allow it to be properly framed and rerun.
Error 3—Internal file error. You should correct the file problems encountered and rerun.
Error 4—Authentication error. You should correct the improper authentication issues and then rerun.
Table C-28 and the sections that follow describe the URIs that you can use in conjunction with the XML objects with support provided by the various Cisco IP Phone models.
Table C-28. URIs Supported
Phone Model URI | 7905/7912 | 7920 | 7940/7960 | 7941/7961 | 797x/IP Communicator |
---|---|---|---|---|---|
Key | X | X | X | X | X |
SoftKey | X | X | X | X | X |
Init | X | X | X | X | |
Dial, EditDial | X | X | X | X | X |
Play | X | X | X | X | X |
QueryStringParam | X | X | X | X | |
Unicast RTP (RTPRx,RTRTx) | v parameter not supported | v parameter not supported; single stream in/out | X | X | X |
Multicast RTP (RTPMRx,RTRMTx) | v parameter not supported | X | X | X |
With the Key URI, you are able to send an event that a key has been pressed and have the same effect as if the button had been pressed on the phone. Just as with actual keypress events, the keypress must be valid at the time of the keypress to have the desired effect.
Key: n
where n = one of the following key names:
Key:Line1 to Key:Line36
Key:KeyPad0 to Key:Keypad9
Key:Soft1 to Key:Soft4 or Soft5 (to Soft5 for 7971/7970/IP Communicator only)
Key:KeyPadStar
Key:KeyPadPound
Key:VolDwn
Key:Headset
Key:Speaker
Key:Mute
Key:Info
Key:Messages
Key:Services
Key:Directories
Key:Settings
Key:NavUp
Key:NavDwn
Key:NavLeft
Key:NavRight
The QueryStringParam URI enables you to collect more user information with less interaction. You can, for example, append a query string parameter to a highlighted menu item or apply the query string parameter from the menu item to the URL of the softkey.
QueryStringParam: d
where d = the data to be appended to a corresponding URL.
The RTP Streaming Control URIs are a collection of URIs that control media to and from the Cisco IP Phones, enabling you to instruct the phone to start or stop sending or receiving a Unicast or Multicast RTP stream. These URIs are as follows:
RTPRx:i:p:v—Receive Unicast RTP stream
RTPRx:Stop—Stop Unicast RTP stream receive
RTPTx:i:p—Transmit Unicast RTP stream
RTPMRx:i:p:v—Receive Multicast RTP stream
RTPMRx:Stop—Stop Multicast RTP stream receive
RTPMTx:i:p—Transmit Multicast RTP stream
RTPMTx:Stop—Stop Multicast RTP stream transmit
where:
i—the Unicast or Multicast IP address for the transmit or receive.
p—the Unicast or Multicast TCP port number. If specified, make sure the port number is an even number in the decimal range 20480 to 32768.
v—optional volume setting that specifies a percentage of the max volume level of the phone on the range 0–100.
The init URI allows you to initialize a feature or data:
Init: o
where o is the object name and can take on the following values:
CallHistory—Used to clear the call history logs and initialize missed calls, received calls, and placed calls.
AppStatus—Used to clear the application status window, which is the window above the status line of the phone.
The Dial URI enables you to initiate a new call to the specified number. The URI is contained in a menu item and is invoked when the menu item is highlighted and the phone goes off-hook:
Dial: n
where n is the number to be dialed.