Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD