Appendix C. Protocol Details

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 Signaling

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

RAS Messaging Details

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.225 Messaging Details

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

Connect to gateway

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

Setup from gateway

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

QSIG

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.

Note

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.

Call Completion

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.

Call Diversion

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.

Call Transfer

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.

Message Waiting Indicator

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.

Name Services

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

Path Replacement

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.

SIP Signaling

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.

SCCP Call Signaling

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.

Making a Call Between IP Phones

Figure C-1. Making a Call Between 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.

 

DisplayPriNotify

-->

 

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.

Application Protocols

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 Package Support

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.

Core Package

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

 

Call Center Package

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

Call Center Capabilities Package

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

Call Center Events Package

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

Call Control Package

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

 

Call Control Capabilities Package

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

Call Control Events Package

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

Capabilities Package

Table C-21 lists each JTAPI interface in the JTAPI Capabilities Package, all of which are supported by the Cisco JTAPI implementation.

Table C-21. JTAPI Capabilities Package Support

Class Name

Method Name

AddressCapabilities

isObservable

CallCapabilities

canConnect

 

isObservable

ConnectionCapabilities

canDisconnect

ProviderCapabilities

isObservable

TerminalCapabilities

isObservable

TerminalConnectionCapabilities

canAnswer

Events Package

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

Media Package

Table C-23 lists each JTAPI interface in the JTAPI Media Package and the support provided by the Cisco JTAPI implementation.

Table C-23. JTAPI Media Package Support

Class Name

Method Name

Cisco JTAPI Support

MediaCallObserver

 

Yes

MediaTerminalConnection

generateDtmf

Yes

getMediaAvailability

No

getMediaState

No

setDtmfDetection

Yes

startPlaying

No

startRecording

No

stopPlaying

No

stopRecording

No

useDefaultMicrophone

No

useDefaultSpeaker

No

usePlayURL

No

useRecordURL

No

Media Capabilities Package

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-24. JTAPI Media Capabilities Package Support

Class Name

Method Name

MediaTerminalConnectionCapabilities

canDetectDtmf

canGenerateDtmf

canStartPlaying

canStartRecording

canStopPlaying

canStopRecording

canUseDefaultMicrophone

canUseDefaultSpeaker

canUsePlayURL

canUseRecordURL

Media Events Package

Table C-25 lists each JTAPI interface in the JTAPI Media Events Package and the support provided by the Cisco JTAPI implementation.

Table C-25. JTAPI Media Events Package Support

Class Name

Method Name

Cisco JTAPI Support

MediaEv

getMediaCause

Yes

MediaTermConnAvailableEv

 

No

MediaTermConnDtmfEv

getDtmfDigit

Yes

MediaTermConnEv

 

Yes

MediaTermConnStateEv

getMediaState

No

MediaTermConnUnavailableEv

 

No

XML Data Types

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.

Menu

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>

IconMenu

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>

Text

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>

Image

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.

Table C-26. Data Tag Digits

Pixels

1

3

2

0

Binary Value

01

11

10

00

Reordered Pairs

00

10

11

01

Hex Digits

2

 

D

 

Packed Value

2D

   

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>

ImageFile

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>

GraphicMenu

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>

GraphicFileMenu

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 >

Directory

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>

Input

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.

Note

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>

Softkeys

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.

IPPhoneStatus

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>

IPPhoneExecute

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.

Example C-11. CiscoIPPhoneExecute XML Type

<CiscoIPPhoneExecute>
  <ExecuteItemPriority ="the priority" ExecuteItem URL="the URL or URI to be executed"/>
</CiscoIPPhoneExecute>

IPPhoneResponse

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.

Example C-12. CiscoIPPhoneResponse XML Type

<CiscoIPPhoneResponse>
  <ResponseItem Status="the success or failure of the action"
  Data="the information returned with the response" URL="the URL or
  URI specified in the Execute object"/>
</CiscoIPPhoneResponse>

IPPhoneError

The error response provides a means of returning an error status to an execute request. Example C-13 shows the CiscoIPPhoneError XML type.

Example C-13. CiscoIPPhoneError XML Type

<CiscoIPPhoneError Number="X"/>

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.

Phone-Supported URIs

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

Key URI

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:VolUp

  • Key:Headset

  • Key:Speaker

  • Key:Mute

  • Key:Info

  • Key:Messages

  • Key:Services

  • Key:Directories

  • Key:Settings

  • Key:NavUp

  • Key:NavDwn

  • Key:NavLeft

  • Key:NavRight

QueryStringParam URI

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.

RTP Streaming Control URIs

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

  • RTPTx:Stop—Stop Unicast RTP stream transmit

  • 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.

Init URI

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.

Dial URI

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.

EditDial URI

The EditDial URI is identical in functionality to the Dial URI except that it allows the user the option of editing the number prior to placing the call:

  • EditDial: n

where n is the number to be dialed.

Play URI

With the Play URI, you can direct the Cisco IP Phone to download and play an audio file from the TFTP server:

  • Play: f

where f is the filename of a raw audio file in the TFTP path.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset