com.cisco.ipphone.sdk
Class Phone

java.lang.Object
  com.cisco.ipphone.sdk.Phone

public class Phone
extends java.lang.Object

This class encapsulates the attributes and functions of a Cisco IP Phone. The primary purpose of this class is to provide a convenient mechanism for finding relationships between IP Phones and other system components such as Users, Extensions, and PCs. Methods implemented in this class allow simple, efficient access to that information using service Providers, such as an LDAP Directory Provider.

Method Summary

User[]	getControllingUsers(LDAPProviderIF lp, java.lang.String[] excludedUsers) Queries the specified LDAP Provider for a list of Users who are allowed to Control this device (phone).
User	getCurrentExtMobUser(EMProviderIF ep) Queries the specified Extension Mobility Provider to determine if this Phone currently has an EM USer logged into it.
java.lang.String	getDeviceName()
Extension[]	getExtensions() This method returns an Array of Extension objects which are currently configured for this phone.
java.lang.String	getIPAddress(IPAddressProviderIF ipProv)
static Phone	getPhone(java.lang.String deviceName) The getPhone method is used to obtain a reference to a Phone object which has the specified, unique deviceName.
SpeedDial[]	getSpeedDials() This method returns an Array of SpeedDial objects which are currently configured for this phone.
boolean	loadAttributes(AXLProviderIF ap) Equivalent to calling loadAttributes(ap, false)
boolean	loadAttributes(AXLProviderIF ap, boolean loadExtensions) The loadAttributes method queries the specified AXL Provider for Phone configuration info.
boolean	login(EMProviderIF ep, User loginUser) Uses the specified Extension Mobility Provider to log the specified User into this Phone
boolean	logout(EMProviderIF ep) Uses the specified Extension Mobility Provider to logout the current EM User of this Phone
java.lang.String	push(java.lang.String[] uris, IPAddressProviderIF ipProv, java.lang.String pushUserId, java.lang.String pushPassword, boolean getResult) This method PUSHes commands to the Phone.
static java.lang.String	push(java.lang.String[] uris, java.lang.String phoneIP, java.lang.String pushUserId, java.lang.String pushPassword, boolean getResult) This method PUSHes a command to the Phone.
java.lang.String	push(java.lang.String uri, IPAddressProviderIF ipProv, java.lang.String pushUserId, java.lang.String pushPassword, boolean getResult) This method PUSHes a command to the Phone.
static java.lang.String	push(java.lang.String uri, java.lang.String phoneIP, java.lang.String pushUserId, java.lang.String pushPassword, boolean getResult) This method PUSHes a command to the Phone.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getPhone

public static Phone getPhone(java.lang.String deviceName)

The getPhone method is used to obtain a reference to a Phone object which has the specified, unique deviceName. Phone objects cannot be directly instantiated with a new command since there are no public constructors - instead a reference is obtained to a given Phone by calling this method. This architecture has the added benefit of being able to directly compare Phone objects for equality - since there is guaranteed to be only one object in existence with a given, unique deviceName. This also has the effect of minimizing memory utilization since only a single instance of a given Phone object exists within the JVM.

Parameters:

deviceName - the unique deviceName of the requested Phone

Returns:

the requested Phone object. If the Phone with this deviceName does not exist, it is created and returned.

loadAttributes

public boolean loadAttributes(AXLProviderIF ap)

Equivalent to calling loadAttributes(ap, false)

Parameters:

ap - the AXLProvider to be queried for configuration information

Returns:

boolean value indicating whether or not the query was successful

loadAttributes

public boolean loadAttributes(AXLProviderIF ap,
                              boolean loadExtensions)

The loadAttributes method queries the specified AXL Provider for Phone configuration info. The method currently only loads the SpeedDial settings into the object, but it could be easily extended to load other device configuration settings and make them available via new getter methods (as was done for the SpeedDials). If the optional loadExtensions flag is included and true, then AXL will also be queried for detailed information about the Phone's line appearances and this information can be subsequently retrieved by a call to getExtensions(). Since this creates multiple AXL queries, this parameter should only be used when Extension information is needed.

Parameters:

ap - the AXLProvider to be queried for configuration information

loadExtensions - boolean value specifying whether or not the Phone's Extension information should also be loaded from AXL

Returns:

boolean value indicating whether or not the query was successful

getDeviceName

public java.lang.String getDeviceName()

Returns:

the String deviceName of the Phone

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

Returns:

the String deviceName of the Phone

getSpeedDials

public SpeedDial[] getSpeedDials()

This method returns an Array of SpeedDial objects which are currently configured for this phone. The SpeedDial class is a simple structure which contains all relevant info for a SpeedDial - index, label, and number. The SpeedDials attributes MUST first be loaded by a call to loadAttributes prior to calling this method - otherwise this method will simply return an empty Array.

Returns:

the Array of SpeedDials. Returns an empty Array (length=0) if no SpeedDials are configured.

See Also:

SpeedDial

getExtensions

public Extension[] getExtensions()

This method returns an Array of Extension objects which are currently configured for this phone. The Extension class contains the key attributes of an extension: pattern (number), label, display (internal CallerId display), and MWI status. The Extension attributes MUST first be loaded by a call to loadAttributes(ap, true) prior to calling this method - otherwise this method will simply return an empty Array.

Returns:

the Array of Extensions. Returns an empty Array (length=0) if no Extensions are configured.

See Also:

Extension

getControllingUsers

public User[] getControllingUsers(LDAPProviderIF lp,
                                  java.lang.String[] excludedUsers)

Queries the specified LDAP Provider for a list of Users who are allowed to Control this device (phone).

Parameters:

lp - the LDAPProvider

excludedUsers - an Array of Strings containing UserIds which should NOT be returned in the result. If excludedUsers is either null or an empty Array, all matching Users will be returned. This easily filters out "application" UserIds which are Controlling groups of devices. For example, many of the sample applications will filter out the "sdkapps" userId which is associated with all devices for PUSH control and other purposes.

Returns:

an Array of Users who are Controlling this Phone. If no Users were found or the query fails, an empty Array (length=0) will be returned.

getCurrentExtMobUser

public User getCurrentExtMobUser(EMProviderIF ep)

Queries the specified Extension Mobility Provider to determine if this Phone currently has an EM USer logged into it.

Parameters:

ep - the EMProvider

Returns:

the User currently logged into this Phone, or null if no User is currently logged in

login

public boolean login(EMProviderIF ep,
                     User loginUser)

Uses the specified Extension Mobility Provider to log the specified User into this Phone

Parameters:

ep - the EMProvider

loginUser - the User to be logged into this Phone

Returns:

boolean value indicated the success (true) or failure (false) of the login request. Note that the request will fail if another User is currently logged into the Phone.

logout

public boolean logout(EMProviderIF ep)

Uses the specified Extension Mobility Provider to logout the current EM User of this Phone

Parameters:

ep - the EMProvider

Returns:

boolean value indicating the success (true) or failure (false) of this request Note that the request will fail if no User is currently logged into this Phone

getIPAddress

public java.lang.String getIPAddress(IPAddressProviderIF ipProv)

push

public java.lang.String push(java.lang.String uri,
                             IPAddressProviderIF ipProv,
                             java.lang.String pushUserId,
                             java.lang.String pushPassword,
                             boolean getResult)

This method PUSHes a command to the Phone. A PUSH to the phone is performed by HTTP POSTing a CiscoIPPhoneExecute object.

Parameters:

uri - the URI to be executed by the Phone

ipProv - the IPAddressProvider to be used to obtain the IP address of this Phone in order to perform the PUSH

pushUserId - the UserId of a user with permissions to PUSH to this Phone

pushPassword - the password for the above UserId

getResult - indicates whether or not the HTTP redirect to the CiscoIPPhoneResponse object should be followed. Unless the application requires verification of the PUSH success, this parameter should be set to false, otherwise performance will be degraded.

Returns:

the XML PUSH response returned by the Phone which indicates the success of PUSH

push

public java.lang.String push(java.lang.String[] uris,
                             IPAddressProviderIF ipProv,
                             java.lang.String pushUserId,
                             java.lang.String pushPassword,
                             boolean getResult)

This method PUSHes commands to the Phone. A PUSH to the phone is performed by HTTP POSTing a CiscoIPPhoneExecute object.

Parameters:

uris - an Array of String URIs (maximum of 3) to be executed by the Phone If an Array larger than 3 is passed, the method will fail and return null

ipProv - the IPAddressProvider to be used to obtain the IP address of this Phone in order to perform the PUSH

pushUserId - the UserId of a user with permissions to PUSH to this Phone

pushPassword - the password for the above UserId

getResult - indicates whether or not the HTTP redirect to the CiscoIPPhoneResponse object should be followed. Unless the application requires verification of the PUSH success, this parameter should be set to false, otherwise performance will be degraded.

Returns:

the XML PUSH response returned by the Phone which indicates the success of PUSH

push

public static java.lang.String push(java.lang.String uri,
                                    java.lang.String phoneIP,
                                    java.lang.String pushUserId,
                                    java.lang.String pushPassword,
                                    boolean getResult)

This method PUSHes a command to the Phone. A PUSH to the phone is performed by HTTP POSTing a CiscoIPPhoneExecute object. This method takes the IP address of this phone as a parameter - this is generally a better approach if an application is PUSHing to multiple Phones at the same time because a single query can be made to the IPAddressProvider to get the entire list of IP addresses and then the PUSH method can be called for each Phone - this avoids a call to the IPAddressProvider for each Phone.

Parameters:

uri - the URI to be executed by the Phone

phoneIP - the IP address of this Phone

pushUserId - the UserId of a user with permissions to PUSH to this Phone

pushPassword - the password for the above UserId

getResult - indicates whether or not the HTTP redirect to the CiscoIPPhoneResponse object should be followed. Unless the application requires verification of the PUSH success, this parameter should be set to false, otherwise performance will be degraded.

Returns:

the XML PUSH response returned by the Phone which indicates the success of PUSH

push

public static java.lang.String push(java.lang.String[] uris,
                                    java.lang.String phoneIP,
                                    java.lang.String pushUserId,
                                    java.lang.String pushPassword,
                                    boolean getResult)

This method PUSHes a command to the Phone. A PUSH to the phone is performed by HTTP POSTing a CiscoIPPhoneExecute object. This method takes the IP address of this phone as a parameter - this is generally a better approach if an application is PUSHing to multiple Phones at the same time because a single query can be made to the IPAddressProvider to get the entire list of IP addresses and then the PUSH method can be called for each Phone - this avoids a call to the IPAddressProvider for each Phone.

Parameters:

uris - an Array of String URIs (maximum of 3) to be executed by the Phone. If an Array larger than 3 is passed, the method will fail and return null

phoneIP - the IP address of this Phone

pushUserId - the UserId of a user with permissions to PUSH to this Phone

pushPassword - the password for the above UserId

getResult - indicates whether or not the HTTP redirect to the CiscoIPPhoneResponse object should be followed. Unless the application requires verification of the PUSH success, this parameter should be set to false, otherwise performance will be degraded.

Returns:

the XML PUSH response returned by the Phone which indicates the success of PUSH.