de.siemens.icn.hipath.dls.apiv100
Interface DlsAPIv100


public interface DlsAPIv100

The DlsAPI Interface.

Method deleted since DLS version
getTemplateNames .HI-DLS.10.211.00.


Method Summary
 DlsAPIout addUser(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164User, java.lang.String e164UserPin, java.lang.String userDataProfile, java.lang.String ppData)
           THIS METHOD IS NOT YET IMPLEMEMNTED AND RETURNS DlsAPIout.DLSAPI_ERROR_NOT_IMPLEMENTED.
 DlsAPIout closeSession(java.lang.String sessionRef)
          Close a DlsAPI session.
 DlsAPIout createClientSessionID(java.lang.String user, java.lang.String password)
           Type: synchronous Get a DLS client session ID for a single usage.
 DlsAPIout deviceIdModifyE164(java.lang.String sessionRef, java.lang.String orderID, java.lang.String deviceId, java.lang.String newE164)
           THIS METHOD IS NOT YET IMPLEMEMNTED AND RETURNS DlsAPIout.DLSAPI_ERROR_NOT_IMPLEMENTED.
 DlsAPIout deviceIdModifyHfaSubscriber(java.lang.String sessionRef, java.lang.String orderID, java.lang.String deviceId, java.lang.String deviceProfile, java.lang.String subscriberNumber, java.lang.String subscriberPassword, java.lang.String gatekeeperAddress, java.lang.String gatekeeperPort)
          Modify a HFA subscriber based on its deviceId.
 DlsAPIout deviceIdModifyMacAddress(java.lang.String sessionRef, java.lang.String orderID, java.lang.String deviceId, java.lang.String newMacAddress)
          Change the mac address of a virtual device with an explicitely given mac address .
 DlsAPIout deviceIdModifySipSubscriber(java.lang.String sessionRef, java.lang.String orderID, java.lang.String deviceId, java.lang.String deviceProfile, java.lang.String terminalName, java.lang.String sipUserID, java.lang.String sipPassword, java.lang.String sipRealm)
          Modify a SIP subscriber based on its deviceId.
 DlsAPIout deviceIDQuerySubscribers(java.lang.String sessionRef, java.lang.String orderID, java.lang.String queryType, java.lang.String deviceIDPattern)
          Query DLS inventory DB based on device ID (search pattern).
 SipSubscriberList deviceIDQuerySubscribersType02(java.lang.String sessionRef, java.lang.String orderID, java.lang.String deviceIDPattern)
           
 DlsAPIout e164AddHfaSubscriber(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164, java.lang.String deviceProfile, java.lang.String subscriberNumber, java.lang.String subscriberPassword, java.lang.String gatekeeperAddress, java.lang.String gatekeeperPort, java.lang.String macAddress)
          Add a HFA subscriber based on its e164 number.
 DlsAPIout e164AddSipSubscriber(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164, java.lang.String deviceProfile, java.lang.String terminalName, java.lang.String sipUserID, java.lang.String sipPassword, java.lang.String sipRealm, java.lang.String macAddress)
          Add a SIP subscriber based on its e164 number.
 DlsAPIout e164AddSipSubscriberType02(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164, java.lang.String deviceProfile, java.lang.String terminalName, java.lang.String sipUserID, java.lang.String sipPassword, java.lang.String sipRealm, java.lang.String sipServerAddress, java.lang.String sipServerPort, java.lang.String macAddress)
          Add a SIP subscriber based on its e164 number.
 DlsAPIout e164DeleteSubscriber(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164)
          Delete a subscriber based on its e164 number.
 DlsAPIout e164DeleteSubscriberList(java.lang.String sessionRef, java.lang.String orderID, java.lang.String[] e164List)
          Delete a list of subscribers based on their e164 numbers.
 DeviceProfileAPIout e164GetDeviceProfile(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164)
          Reads the last device profile which was applied to the device identifed by e164.
 DeviceAPIout e164GetKeyLayout(java.lang.String sessionRef, java.lang.String e164)
          Provides information about key layout and key functions configured for the device.
 DlsAPIout e164ModifyE164(java.lang.String sessionRef, java.lang.String orderID, java.lang.String oldE164, java.lang.String newE164)
           THIS METHOD IS NOT YET IMPLEMEMNTED AND RETURNS DlsAPIout.DLSAPI_ERROR_NOT_IMPLEMENTED.
 DlsAPIout e164ModifyHfaSubscriber(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164, java.lang.String deviceProfile, java.lang.String subscriberNumber, java.lang.String subscriberPassword, java.lang.String gatekeeperAddress, java.lang.String gatekeeperPort)
          Modify a HFA subscriber based on its e164 number.
 DeviceAPIout e164ModifyKeyLayout(java.lang.String sessionRef, java.lang.String orderId, Device device)
          Key layout and key functions for the device are configured based on the e164 number.
 DlsAPIout e164ModifyMacAddress(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164, java.lang.String newMacAddress)
           Type: synchronous
History of change: DLS version Change .HI-DLS.10.300.00.
 DlsAPIout e164ModifySipSubscriber(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164, java.lang.String deviceProfile, java.lang.String terminalName, java.lang.String sipUserID, java.lang.String sipPassword, java.lang.String sipRealm)
          Modify a SIP subscriber based on its e164 number.
 DlsAPIout e164ModifySipSubscriberType02(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164, java.lang.String deviceProfile, java.lang.String terminalName, java.lang.String sipUserID, java.lang.String sipPassword, java.lang.String sipRealm, java.lang.String sipServerAddress, java.lang.String sipServerPort)
           THIS METHOD IS NOT YET IMPLEMEMNTED AND RETURNS DlsAPIout.DLSAPI_ERROR_NOT_IMPLEMENTED.
 DlsAPIout e164QuerySubscribers(java.lang.String sessionRef, java.lang.String orderID, java.lang.String queryType, java.lang.String e164Pattern)
          Query DLS inventory DB based on e164 number (search pattern).
 SipSubscriberList e164QuerySubscribersType01(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164Pattern)
          This method does essentialy the same as e164QuerySubscribers(String, String, String, String) with queryType=01.
 SipSubscriberList e164QuerySubscribersType02(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164Pattern)
          This method does essentialy the same as e164QuerySubscribers(String, String, String, String) with queryType=02.
 DlsAPIout gatewayStartupNotification(java.lang.String sessionRef, java.lang.String orderID, java.lang.String gatewayIpAddress)
          Notify DLS about gateway startup.
 java.lang.String getApiServerVersionString()
          Get the version of the DlsAPI.
 DeviceDescriptionAPIout getDeviceDescriptions(java.lang.String sessionRef)
          This method returns master data of devices suported by DLS (i.e. device type, modules, level and keys).
 java.lang.String getDlsServerVersionString()
          Get the version of the DLS server.
 FunctionDescriptionAPIout getFunctionDescriptions(java.lang.String sessionRef, java.lang.String deviceType, int level, java.lang.String softwareType, java.lang.String softwareVersion)
          
Key function descriptions are stable throughout a DLS release.
 LayoutDescriptionAPIout getLayoutDescription(java.lang.String sessionRef, java.lang.String deviceType, java.lang.String softwareType, java.lang.String softwareVersion)
          
Key layout descriptions are stable throughout a DLS release.
 DlsAPIout getStatusOfRequestID(java.lang.String sessionRef, java.lang.String orderID, java.lang.String requestID)
          Get status of an asynchronously started request (i.e. a request that returned DlsAPIout.DLSAPI_OK_RUNNING).
 DlsAPIout getStatusOfRequestIDs(java.lang.String sessionRef, java.lang.String orderID, java.lang.String whatOrderID, java.lang.String whatUser, java.lang.String whatStatus)
          Get status of asynchronously started requests (i.e. all requests that returned DlsAPIout.DLSAPI_OK_RUNNING) including their current status.
 DlsAPIout listDeviceProfiles(java.lang.String sessionRef, java.lang.String orderID, java.lang.String pattern)
          List all device profiles names currently configured in DLS.
 DlsAPIout mobileUserLogoff(java.lang.String sessionRef, java.lang.String orderID, java.lang.String timeout, java.lang.String e164User, java.lang.String e164UserPin)
           Logoff a mobile user from a mobility-enabled phone.
 DlsAPIout mobileUserLogon(java.lang.String sessionRef, java.lang.String orderID, java.lang.String timeout, java.lang.String e164User, java.lang.String e164UserPin, java.lang.String e164Basic)
           Logon a mobile user to a mobility-enabled phone.
 DlsAPIout mobileUserModifyTerminalName(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164User, java.lang.String terminalName)
           Modify the terminal name of a mobile user.
 DlsAPIout mobileUserSearch(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164User)
           Return mobility-enabled phone(s), the mobile user is currently logged on.
 DlsAPIout mobileUserStatus(java.lang.String sessionRef, java.lang.String orderID, java.lang.String e164Basic)
           Return current mobility status of a mobility-enabled phone.
 DlsAPIout openSession(java.lang.String user, java.lang.String password)
          Open a DlsAPI session.
 

Method Detail

getApiServerVersionString

java.lang.String getApiServerVersionString()
Get the version of the DlsAPI.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.196.00. history started

Returns:
Currently returns "100" as the version string of the DlsAPI.

getDlsServerVersionString

java.lang.String getDlsServerVersionString()
Get the version of the DLS server.

History of change: DLS version Change
.HI-DLS.10.196.00. history started

Type: synchronous

Returns:
Returns a string that contains the DLS server version, incl. load and subversion number - surrounded by '.'
Sample: ".V1R2.0.0-203.00."

openSession

DlsAPIout openSession(java.lang.String user,
                      java.lang.String password)
Open a DlsAPI session. Most of the DlsAPI methods can only be performed within a valid session. For all these methods the session identifier returned by this method as DlsAPIout.result is a required input parameter ('sessionRef').

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.196.00. history started

Parameters:
user - The user name.
password - The user password.
Returns:
DlsAPIout.status can have one of the following values:

closeSession

DlsAPIout closeSession(java.lang.String sessionRef)
Close a DlsAPI session.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.196.00. history started

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
Returns:
DlsAPIout.status can have one of the following values:

createClientSessionID

DlsAPIout createClientSessionID(java.lang.String user,
                                java.lang.String password)

Type: synchronous

Get a DLS client session ID for a single usage. The ID is valid only for 100 seconds. The DLS client session ID can be used to start a DLS client via URL

http://[DLS_HOST]:[DLS_PORT]/DeploymentService/index.html?session=[CLIENT_SESSION_ID]&e164=4989722987654.

DLS client then automatically logs on to DLS server with user and password passed to this method.

It is not guaranteed that the returned client session ID is valid. Even if e.g. user or password are invalid a client session ID will be created (so that it is not to easy to find out the password for a known user by brute force). But then calling DLS client with this client session ID will fail and DLS client will present its login screen so that the user can submit correct data.

The client session ID expires in following cases:

History of change: DLS version Change
.HI-DLS.10.216.00. created and impelemented
.HI-DLS.10.218.00. parameter sessionRef removed

Parameters:
user - DLS client user.
password - DLS client password.
Returns:
DlsAPIout.status can have one of the following values: DlsAPIout.result contains the client session id. Note that it is not guaranteed that a logon to the DLS client will be successful, even if a client session id is created.

getStatusOfRequestIDs

DlsAPIout getStatusOfRequestIDs(java.lang.String sessionRef,
                                java.lang.String orderID,
                                java.lang.String whatOrderID,
                                java.lang.String whatUser,
                                java.lang.String whatStatus)
Get status of asynchronously started requests (i.e. all requests that returned DlsAPIout.DLSAPI_OK_RUNNING) including their current status.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.196.00. history started

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
whatOrderID - optional - if given, only requests associated with this orderID are listed
whatUser - optional - if given, only requests started by this user are listed
whatStatus - optional - if given, only requests whose current status matches with whatStatus are listed
Returns:
DlsAPIout.status can have one of the following values: DlsAPIout.result is formatted as follows:
one line per returned request; each line consists of: <requestID>;<Status>;<orderID>

getStatusOfRequestID

DlsAPIout getStatusOfRequestID(java.lang.String sessionRef,
                               java.lang.String orderID,
                               java.lang.String requestID)
Get status of an asynchronously started request (i.e. a request that returned DlsAPIout.DLSAPI_OK_RUNNING).

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.196.00. history started

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
requestID - a single requestID as returned by a previous DlsAPI request.
Note: does NOT support comma-separated list of requestIDs
Returns:
The status of the request which returned 'requestID'.
DlsAPIout.status can have one of the following values:

listDeviceProfiles

DlsAPIout listDeviceProfiles(java.lang.String sessionRef,
                             java.lang.String orderID,
                             java.lang.String pattern)
List all device profiles names currently configured in DLS.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.196.00. created and implemented
.HI-DLS.10.212.00. Name changed from 'listTemplateNames' to 'listDeviceProfiles'.

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
pattern - if given, restricts the list of returned device profile names to those that match 'pattern'
Returns:
DlsAPIout.status can have one of the following values: DlsAPIout.result contains all device profile names, separated by newline characters, i.e.:
<deviceProfileName1>\n<deviceProfileName2>\n...<deviceProfileNameN>

e164AddSipSubscriber

DlsAPIout e164AddSipSubscriber(java.lang.String sessionRef,
                               java.lang.String orderID,
                               java.lang.String e164,
                               java.lang.String deviceProfile,
                               java.lang.String terminalName,
                               java.lang.String sipUserID,
                               java.lang.String sipPassword,
                               java.lang.String sipRealm,
                               java.lang.String macAddress)
Add a SIP subscriber based on its e164 number.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.196.00. history started

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
e164 - The e164 number of the device to be added. A device with given e164 number must not yet exist.
deviceProfile - The device profile containing the PnP data.
terminalName - Terminal name of the device. This is the name of the phone as it registers with the SIP registrar server. If not set, the phone uses its E164 number for registration.
sipUserID - User ID to be used by the device to register at the SIP server
sipPassword - Password to be used by the device to register at the SIP server
sipRealm - Realm to be used by the device to register at the SIP server
macAddress - Mac address of the device to be added. If not empty, a device with this mac address must not yet exists.
Returns:
DlsAPIout.status can have one of the following values:

e164AddSipSubscriberType02

DlsAPIout e164AddSipSubscriberType02(java.lang.String sessionRef,
                                     java.lang.String orderID,
                                     java.lang.String e164,
                                     java.lang.String deviceProfile,
                                     java.lang.String terminalName,
                                     java.lang.String sipUserID,
                                     java.lang.String sipPassword,
                                     java.lang.String sipRealm,
                                     java.lang.String sipServerAddress,
                                     java.lang.String sipServerPort,
                                     java.lang.String macAddress)
Add a SIP subscriber based on its e164 number.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.246.00. method added, not yet implemented
.HI-DLS.10.246.00. method name changed from e164AddSipSubscriber to e164AddSipSubscriberType02

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
e164 - The e164 number of the device to be added. A device with given e164 number must not yet exist.
deviceProfile - The device profile containing the PnP data.
terminalName - Terminal name of the device. This is the name of the phone as it registers with the SIP registrar server. If not set, the phone uses its E164 number for registration.
sipUserID - User ID to be used by the device to register at the SIP server
sipPassword - Password to be used by the device to register at the SIP server
sipRealm - Realm to be used by the device to register at the SIP server
sipServerAddress - SIP server IP address or hostname
sipServerPort - SIP server port
macAddress - Mac address of the device to be added. If not empty, a device with this mac address must not yet exists.
Returns:
DlsAPIout.status can have one of the following values:

e164AddHfaSubscriber

DlsAPIout e164AddHfaSubscriber(java.lang.String sessionRef,
                               java.lang.String orderID,
                               java.lang.String e164,
                               java.lang.String deviceProfile,
                               java.lang.String subscriberNumber,
                               java.lang.String subscriberPassword,
                               java.lang.String gatekeeperAddress,
                               java.lang.String gatekeeperPort,
                               java.lang.String macAddress)
Add a HFA subscriber based on its e164 number.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.203.00. created, not yet implemented
.HI-DLS.10.300.00. implemented
.HI-DLS.10.301.00. Parameter gatekeeperPort added

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
e164 - The e164 number of the device to be added.
deviceProfile - The device profile containing the PnP data.
subscriberNumber - Subscriber number of the device used to register at the gatekeeper.
subscriberPassword - Password to be used by the device to register at the gatekeeper.
gatekeeperAddress - IP address of the gatekeeper (equal to gateway IP address).
gatekeeperPort - Port of the gatekeeper
macAddress - Mac address of the device to be added. If not empty, a device with this mac address must not yet exists.
Returns:
DlsAPIout.status can have one of the following values:

e164ModifyE164

DlsAPIout e164ModifyE164(java.lang.String sessionRef,
                         java.lang.String orderID,
                         java.lang.String oldE164,
                         java.lang.String newE164)

THIS METHOD IS NOT YET IMPLEMEMNTED AND RETURNS DlsAPIout.DLSAPI_ERROR_NOT_IMPLEMENTED.

Change the e164 number of a subscriber.

Type: asynchronous & synchronous

History of change: DLS version Change
.HI-DLS.10.203.00. created

Parameters:
sessionRef - A valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - Transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
oldE164 - All devices with old e164 number will be given the new e164 number, with one restriction: The resulting set of devices with new e164 number must not contain more than one virtual device without mac address.
newE164 - The new e164 number for the given subscriber(s).
Returns:
DlsAPIout.status can have one of the following values:

deviceIdModifyE164

DlsAPIout deviceIdModifyE164(java.lang.String sessionRef,
                             java.lang.String orderID,
                             java.lang.String deviceId,
                             java.lang.String newE164)

THIS METHOD IS NOT YET IMPLEMEMNTED AND RETURNS DlsAPIout.DLSAPI_ERROR_NOT_IMPLEMENTED.

Change the e164 number of a subscriber.

Type: asynchronous & synchronous

History of change: DLS version Change
.HI-DLS.10.203.00. created

Parameters:
sessionRef - A valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - Transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
deviceId - The deviceId of the device which should be given the new e164.
newE164 - The new e164 number for the given subscriber(s).
Returns:
DlsAPIout.status can have one of the following values:

e164ModifyMacAddress

DlsAPIout e164ModifyMacAddress(java.lang.String sessionRef,
                               java.lang.String orderID,
                               java.lang.String e164,
                               java.lang.String newMacAddress)

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.300.00. created and implemented

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
e164 - The e164 number of the device to modify. 'e164' must identify a single virtual sip or hfa device.
newMacAddress - The new mac address for the given subscriber.
Returns:
DlsAPIout.status can have one of the following values:

deviceIdModifyMacAddress

DlsAPIout deviceIdModifyMacAddress(java.lang.String sessionRef,
                                   java.lang.String orderID,
                                   java.lang.String deviceId,
                                   java.lang.String newMacAddress)
Change the mac address of a virtual device with an explicitely given mac address .

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.300.00. created and implemented

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
deviceId - The deviceId of the device to modify. 'deviceId' must be a mac-address and it must identify a virtual sip or hfa device.
newMacAddress - The new mac address for the given subscriber.
Returns:
DlsAPIout.status can have one of the following values:

e164ModifySipSubscriber

DlsAPIout e164ModifySipSubscriber(java.lang.String sessionRef,
                                  java.lang.String orderID,
                                  java.lang.String e164,
                                  java.lang.String deviceProfile,
                                  java.lang.String terminalName,
                                  java.lang.String sipUserID,
                                  java.lang.String sipPassword,
                                  java.lang.String sipRealm)
Modify a SIP subscriber based on its e164 number.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.239.00. Support for multiple devices with identical e164.
.HI-DLS.10.196.00. history started

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
e164 - e164 of the SIP subscriber to modify. e164 has to be the basic e164 of one ore more SIP IP Phones.
deviceProfile - - add/update in inventory
terminalName - Terminal name of the device
sipUserID - User ID to be used by the device to register at the SIP server
sipPassword - Password to be used by the device to register at the SIP server
sipRealm - Realm to be used by the device to register at the SIP server
Returns:
DlsAPIout.status can have one of the following values: In case of DlsAPIout.status = DlsAPIout.DLSAPI_OK_RUNNING:

e164ModifySipSubscriberType02

DlsAPIout e164ModifySipSubscriberType02(java.lang.String sessionRef,
                                        java.lang.String orderID,
                                        java.lang.String e164,
                                        java.lang.String deviceProfile,
                                        java.lang.String terminalName,
                                        java.lang.String sipUserID,
                                        java.lang.String sipPassword,
                                        java.lang.String sipRealm,
                                        java.lang.String sipServerAddress,
                                        java.lang.String sipServerPort)

THIS METHOD IS NOT YET IMPLEMEMNTED AND RETURNS DlsAPIout.DLSAPI_ERROR_NOT_IMPLEMENTED.

Modify a SIP subscriber based on its e164 number.

Type: asynchronous & synchronous

History of change: DLS version Change
.HI-DLS.10.246.00. created, not yet implemented. method name changed from e164ModifySipSubscriber to e164ModifySipSubscriberType02

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
e164 - e164 of the SIP subscriber to modify. e164 has to be the basic e164 of one ore more SIP IP Phones.
deviceProfile - - add/update in inventory
terminalName - Terminal name of the device
sipUserID - User ID to be used by the device to register at the SIP server
sipPassword - Password to be used by the device to register at the SIP server
sipRealm - Realm to be used by the device to register at the SIP server
sipServerAddress - SIP server IP address or hostname
sipServerPort - SIP server port
Returns:
DlsAPIout.status can have one of the following values: In case of DlsAPIout.status = DlsAPIout.DLSAPI_OK_RUNNING:

deviceIdModifySipSubscriber

DlsAPIout deviceIdModifySipSubscriber(java.lang.String sessionRef,
                                      java.lang.String orderID,
                                      java.lang.String deviceId,
                                      java.lang.String deviceProfile,
                                      java.lang.String terminalName,
                                      java.lang.String sipUserID,
                                      java.lang.String sipPassword,
                                      java.lang.String sipRealm)
Modify a SIP subscriber based on its deviceId.

Type: asynchronous & synchronous

History of change: DLS version Change
.HI-DLS.10.238.00. created

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
deviceId - deviceId of the device to modify. deviceId must identify a sip device. If no device with given deviceId is found, no modification is done.
deviceProfile - - add/update in inventory
terminalName - Terminal name of the device
sipUserID - User ID to be used by the device to register at the SIP server
sipPassword - Password to be used by the device to register at the SIP server
sipRealm - Realm to be used by the device to register at the SIP server
Returns:
DlsAPIout.status can have one of the following values: DlsAPIout.result contains the (comma-separated list of) requestID(s) that is associated with the job(s) created by DLS for that device. The current status of these jobs can be retrieved using getStatusOfRequestID(java.lang.String, java.lang.String, java.lang.String).

getDeviceDescriptions

DeviceDescriptionAPIout getDeviceDescriptions(java.lang.String sessionRef)
This method returns master data of devices suported by DLS (i.e. device type, modules, level and keys). The information about the devices is restricted to 'hardware' topis, which do not depend on software type or software version (e.g. key functions).
The device master data are stable throughout a DLS release. It is therefore recommended that DLSApi clients request device descriptions only once on start-up and store the data locally in memory or on disk.

History of change: DLS version Change
.HI-DLS.10.206.00. created
.HI-DLS.10.208.00. implemented

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
Returns:
A description of all devices supported by DLS. See DeviceDescription for a detailled description.

getFunctionDescriptions

FunctionDescriptionAPIout getFunctionDescriptions(java.lang.String sessionRef,
                                                  java.lang.String deviceType,
                                                  int level,
                                                  java.lang.String softwareType,
                                                  java.lang.String softwareVersion)

Key function descriptions are stable throughout a DLS release. For clients which always need key function descriptions for the same set of parameters it is therefore recommended to request those key function descriptions only once on start-up and store the data locally in memory or on disk.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.206.00. created
.HI-DLS.10.208.00. implemented

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
deviceType - The devic type, e.g. "optiPoint 420 economy plus". The device type has to be equal to DeviceDescription.getDeviceType() for one of the device descriptions returned by getDeviceDescriptions(String).
level - The level number.
softwareType - The software type, e.g. "Siemens HFA". Software type has to be equal one of the software types given by DeviceDescription.getSoftwareTypes().
softwareVersion - The software version must have the form x.y.z where x, y and z are non-negative numbers. If software version '0.0.0' is supplied all functions for the given 'softwareType' will be returned. If x,y or z are positive numbers only the functions supported by the given software version are returned.
Returns:
A description of all functions which can be configured for a device with the given parameter.

getLayoutDescription

LayoutDescriptionAPIout getLayoutDescription(java.lang.String sessionRef,
                                             java.lang.String deviceType,
                                             java.lang.String softwareType,
                                             java.lang.String softwareVersion)

Key layout descriptions are stable throughout a DLS release. For clients which always need key layout descriptions for the same set of parameters it is therefore recommended to request those key layout descriptions only once on start-up and store the data locally in memory or on disk.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.211.00. created and implemented

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
deviceType - The devic type, e.g. "optiPoint 420 economy plus". The device type has to be equal to DeviceDescription.getDeviceType() for one of the device descriptions returned by getDeviceDescriptions(String).
softwareType - The software type, e.g. "Siemens HFA". Software type has to be equal one of the software types given by DeviceDescription.getSoftwareTypes().
softwareVersion - The software version must have the form x.y.z where x, y and z are non-negative numbers. If software version '0.0.0' is supplied all functions for the given 'softwareType' will be returned. If x,y or z are positive numbers only the functions supported by the given software version are returned.
Returns:
A description of the key layout which can be configured for a device with the given parameter.

e164GetKeyLayout

DeviceAPIout e164GetKeyLayout(java.lang.String sessionRef,
                              java.lang.String e164)
Provides information about key layout and key functions configured for the device.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.206.00. created
.HI-DLS.10.208.00. implemented

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
e164 - The e164 number identifying a registered device, a virtual device or a mobile user.
Returns:
Returns a 'Device' containing the information about so far configured key layout and functions.

e164ModifyKeyLayout

DeviceAPIout e164ModifyKeyLayout(java.lang.String sessionRef,
                                 java.lang.String orderId,
                                 Device device)
Key layout and key functions for the device are configured based on the e164 number. Following situations can occur:

Type: asynchronous & synchronous

History of change: DLS version Change
.HI-DLS.10.206.00. created
.HI-DLS.10.208.00. implemented
.HI-DLS.10.210.00. Name changed from 'setSipKeys' to 'e164ModifyKeyLayout'.

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderId - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
device - The device which should be configured. The device is identifed by its e164 number.
Returns:
The device contained in the return value is equal to the submitted device, except:
  • softwareType, softwareVersion and deviceType are set to the values of the device identified by e164 number.
  • A negatively validated attribute contains as validation state the cause why validation failed.
  • Missing mandatory attributes are added with validaton state set accordingly.

e164ModifyHfaSubscriber

DlsAPIout e164ModifyHfaSubscriber(java.lang.String sessionRef,
                                  java.lang.String orderID,
                                  java.lang.String e164,
                                  java.lang.String deviceProfile,
                                  java.lang.String subscriberNumber,
                                  java.lang.String subscriberPassword,
                                  java.lang.String gatekeeperAddress,
                                  java.lang.String gatekeeperPort)
Modify a HFA subscriber based on its e164 number.

Type: asynchronous & synchronous

History of change: DLS version Change
.HI-DLS.10.203.00. created, not yet implemented
.HI-DLS.10.300.00. implemented
.HI-DLS.10.301.00. Parameter gatekeeperPort added

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
e164 - error if more than one wp in inventory; if not exists in inventory, pnp data is updated only (incl. set of pnp flags) - note that templateName is ignored in this case
if not exists neither in inventory nor in pnp -> return error
deviceProfile - - add/update in inventory
subscriberNumber - Subscriber number of the device used to register at the gatekeeper
subscriberPassword - Password to be used by the device to register at the gatekeeper
gatekeeperAddress - IP address of the gatekeeper
gatekeeperPort - Port of the gatekeeper
Returns:
DlsAPIout.status can have one of the following values: DlsAPIout.result contains the (comma-separated list of) requestID(s) that is associated with the job(s) created by DLS for that device. The current status of these jobs can be retrieved using getStatusOfRequestID(java.lang.String, java.lang.String, java.lang.String).

deviceIdModifyHfaSubscriber

DlsAPIout deviceIdModifyHfaSubscriber(java.lang.String sessionRef,
                                      java.lang.String orderID,
                                      java.lang.String deviceId,
                                      java.lang.String deviceProfile,
                                      java.lang.String subscriberNumber,
                                      java.lang.String subscriberPassword,
                                      java.lang.String gatekeeperAddress,
                                      java.lang.String gatekeeperPort)
Modify a HFA subscriber based on its deviceId.

Type: asynchronous & synchronous

History of change: DLS version Change
.HI-DLS.10.238.00. created, not yet implemented
.HI-DLS.10.300.00. implemented
.HI-DLS.10.301.00. Parameter gatekeeperPort added

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
deviceId - deviceId of the device to modify. deviceId must identify an hfa device. If no device with given deviceId is found, no modification is done.
deviceProfile - - add/update in inventory
subscriberNumber - Subscriber number of the device used to register at the gatekeeper
subscriberPassword - Password to be used by the device to register at the gatekeeper
gatekeeperAddress - IP address of the gatekeeper
gatekeeperPort - Port of the gatekeeper
Returns:
DlsAPIout.status can have one of the following values: DlsAPIout.result contains the (comma-separated list of) requestID(s) that is associated with the job(s) created by DLS for that device. The current status of these jobs can be retrieved using getStatusOfRequestID(java.lang.String, java.lang.String, java.lang.String).

e164DeleteSubscriber

DlsAPIout e164DeleteSubscriber(java.lang.String sessionRef,
                               java.lang.String orderID,
                               java.lang.String e164)
Delete a subscriber based on its e164 number.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.196.00. history started
.HI-DLS.10.203.00. Parameter 'ppOnly' added.
.HI-DLS.10.212.00. Parameter 'ppOnly' removed.

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
e164 - All entries of the given e164 number are deleted in DLS
Returns:
DlsAPIout.status can have one of the following values:
  • ≥ 0: number of entries in inventory DB that have been deleted
    Note: number of entries deleted in pp data is ignored
  • DlsAPIout.DLSAPI_ERROR_NOT_FOUND: e164 not found in inventory DB

e164DeleteSubscriberList

DlsAPIout e164DeleteSubscriberList(java.lang.String sessionRef,
                                   java.lang.String orderID,
                                   java.lang.String[] e164List)
Delete a list of subscribers based on their e164 numbers.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.211.00. created and implemented
.HI-DLS.10.212.00. Parameter 'ppOnly' removed.

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
e164List - All entries of the given e164 numbers are deleted in DLS
Returns:
DlsAPIout.getStatus() can have one of the following values: DlsAPIout.getResult() is a comma-separated list with one entry for each supplied e164 number. Each entry has the form 'e164:message', where 'message' contains information about the deletion status of the respective sip subscriber.

e164GetDeviceProfile

DeviceProfileAPIout e164GetDeviceProfile(java.lang.String sessionRef,
                                         java.lang.String orderID,
                                         java.lang.String e164)
Reads the last device profile which was applied to the device identifed by e164.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.212.00. created
.HI-DLS.10.216.00. implemented
.HI-DLS.10.219.00. Returns time when last plug & play was performed.

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
e164 - e164 of the device for which the device profiel should be read.
Returns:
DlsAPIout.getStatus() can have one of the following values: DeviceProfileAPIout.getDeviceProfileName() is the last device profile name which was applied to the device. DeviceProfileAPIout.getTimeInMillis()() is the date and time when the plug & play for the device was performed (as number of milliseconds since the Epoch '1970-01-01 0:00 GMT'). If no device profile was applied to the given device, device profile name is empty and time in millis is '0'.

e164QuerySubscribers

DlsAPIout e164QuerySubscribers(java.lang.String sessionRef,
                               java.lang.String orderID,
                               java.lang.String queryType,
                               java.lang.String e164Pattern)
Query DLS inventory DB based on e164 number (search pattern).

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.196.00. history started

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
queryType - Defines what device attributes are to be returned in DlsAPIout.result.
Currently supported queryTypes are: "01"
Their individual output format is listed below.
e164Pattern - if given, restricts the list of returned devices to those that match 'e164pattern'
Returns:
DlsAPIout.status can have one of the following values: DlsAPIout.result is formatted as follows:
one line per found entry; each line consists of:
<queryType>;<further device attributes according to queryType>
I.e.,
  • If queryType was set to "01", each line consists of:
    01;<E.164>;<Device ID>;<Device Type>; <SW Type>;<SW Version>;<Last Registration>
  • If queryType was set to "02", each line consists of:
    02;<E.164>;<Device ID>;<IP Address>; <Display ID>
Note: Strings that contain a time and/or date (e.g.: Last Registration) are returned as number of milliseconds since the Epoch (1970-01-01 0:00 GMT)

e164QuerySubscribersType01

SipSubscriberList e164QuerySubscribersType01(java.lang.String sessionRef,
                                             java.lang.String orderID,
                                             java.lang.String e164Pattern)
This method does essentialy the same as e164QuerySubscribers(String, String, String, String) with queryType=01. The main difference is the return type: This method returns a list of typed sip subscriber data. Note that (for large lists) this method is slower than e164QuerySubscribers(String, String, String, String).

History of change: DLS version Change
.HI-DLS.10.202.00. created and implemented

Parameters:
sessionRef - see e164QuerySubscribers(String, String, String, String)
orderID - see e164QuerySubscribers(String, String, String, String)
e164Pattern - see e164QuerySubscribers(String, String, String, String)
Returns:
List containing the found sip subscribers. Following SipSubscriberData values will be set for each result in the list: e164, deviveId, deviceType, swType, swVersion, lastRegistration. Since the list is also of type DlsAPIout refer to e164QuerySubscribers(String, String, String, String) for a decription of DlsAPIout values (except DlsAPIout.result).

e164QuerySubscribersType02

SipSubscriberList e164QuerySubscribersType02(java.lang.String sessionRef,
                                             java.lang.String orderID,
                                             java.lang.String e164Pattern)
This method does essentialy the same as e164QuerySubscribers(String, String, String, String) with queryType=02. The main difference is the return type: This method returns a list of typed sip subscriber data. Note that (for large lists) this method is slower than e164QuerySubscribers(String, String, String, String).

History of change: DLS version Change
.HI-DLS.10.202.00. created and implemented

Parameters:
sessionRef - see e164QuerySubscribers(String, String, String, String)
orderID - see e164QuerySubscribers(String, String, String, String)
e164Pattern - see e164QuerySubscribers(String, String, String, String)
Returns:
List containing the found sip subscribers. Following SipSubscriberData values will be set for each result in the list: e164, deviveId, ipAddress, displayId. Since the list is also of type DlsAPIout refer to e164QuerySubscribers(String, String, String, String) for a decription of DlsAPIout values (except DlsAPIout.result).

deviceIDQuerySubscribers

DlsAPIout deviceIDQuerySubscribers(java.lang.String sessionRef,
                                   java.lang.String orderID,
                                   java.lang.String queryType,
                                   java.lang.String deviceIDPattern)
Query DLS inventory DB based on device ID (search pattern).

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.200.00. created and implemented

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
queryType - Defines what device attributes are to be returned in DlsAPIout.result.
Currently supported queryTypes are: "01"
Their individual output format is listed below.
deviceIDPattern - if given, restricts the list of returned devices to those that match 'deviceIDpattern'
Returns:
DlsAPIout.status can have one of the following values: DlsAPIout.result is formatted as follows:
one line per found entry; each line consists of:
<queryType>;<further device attributes according to queryType>
I.e.,
  • If queryType was set to "01", each line consists of:
    01;<E.164>;<Device ID>;<Device Type>; <SW Type>;<SW Version>;<Last Registration>
  • If queryType was set to "02", each line consists of:
    02;<E.164>;<Device ID>;<IP Address>; <Display ID>

deviceIDQuerySubscribersType02

SipSubscriberList deviceIDQuerySubscribersType02(java.lang.String sessionRef,
                                                 java.lang.String orderID,
                                                 java.lang.String deviceIDPattern)

gatewayStartupNotification

DlsAPIout gatewayStartupNotification(java.lang.String sessionRef,
                                     java.lang.String orderID,
                                     java.lang.String gatewayIpAddress)
Notify DLS about gateway startup.
This method is used by gateways (HG1500, HG3550, HG3530/70/75) to inform DLS when they start up. This notification triggers actions at the DLS, e.g. distribution of current preshared secret for SRTP to the gateway.

Type: asynchronous

History of change: DLS version Change
.HI-DLS.10.196.00. history started

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
gatewayIpAddress - IP Address of the affected gateway
Returns:
DlsAPIout.status can have one of the following values: DlsAPIout.result contains the requestID that is associated with the job created by DLS for that gateway. The current status of the job can be retrieved using getStatusOfRequestID(java.lang.String, java.lang.String, java.lang.String).

mobileUserLogon

DlsAPIout mobileUserLogon(java.lang.String sessionRef,
                          java.lang.String orderID,
                          java.lang.String timeout,
                          java.lang.String e164User,
                          java.lang.String e164UserPin,
                          java.lang.String e164Basic)

Logon a mobile user to a mobility-enabled phone.

Type: pseudo-synchronous or asynchronous (depending on timeout parameter)

History of change: DLS version Change
.HI-DLS.10.196.00. method added, not yet implemented

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
timeout - timeout (in seconds) if set to 0, the method is executed asynchronously (OK_RUNNING is returned and the appropriate reqestID in status) if set to value greater than 0, the method returns latest after the given timeout; if the request has not been completed, ERROR_TIMEOUT is returned
e164User - The mobile users e164 number.
e164UserPin - This parameter is for future use and is currently ignored.
e164Basic - The e164 basic number of the phone the mobile user should be logged on.
Returns:
The return value depends on the timeout parameter:
1. timeout > 0: DlsAPIout.status can have one of the following values: DlsAPIout.requestID is set if logon could not be perfomred wirthout exceeding the timeout.
2. timeout = 0: DlsAPIout.status can have one of the following values: DlsAPIout.requestID represents the job performing an asynchronous logon.

mobileUserLogoff

DlsAPIout mobileUserLogoff(java.lang.String sessionRef,
                           java.lang.String orderID,
                           java.lang.String timeout,
                           java.lang.String e164User,
                           java.lang.String e164UserPin)

Logoff a mobile user from a mobility-enabled phone.

Type: pseudo-synchronous or asynchronous (depending on timeout parameter)

History of change: DLS version Change
.HI-DLS.10.196.00. history started

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
timeout - timeout (in seconds) if set to 0, the method is executed asynchronously (OK_RUNNING is returned and the appropriate reqestID in status) if set to value greater than 0, the method returns latest after the given timeout; if the request has not been completed, ERROR_TIMEOUT is returned
e164User - The mobile users e164 number.
e164UserPin - This parameter is for future use and is currently ignored.
Returns:
refer to mobileUserLogon(String, String, String, String, String, String)

mobileUserStatus

DlsAPIout mobileUserStatus(java.lang.String sessionRef,
                           java.lang.String orderID,
                           java.lang.String e164Basic)

Return current mobility status of a mobility-enabled phone.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.196.00. history started
.HI-DLS.10.236.00. no change, but documentation added

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
e164Basic - The e164 basic number of a mobility-enabled phone.
Returns:
DlsAPIout.status can have one of the following values:

mobileUserSearch

DlsAPIout mobileUserSearch(java.lang.String sessionRef,
                           java.lang.String orderID,
                           java.lang.String e164User)

Return mobility-enabled phone(s), the mobile user is currently logged on.

Type: synchronous

History of change: DLS version Change
.HI-DLS.10.246.00. method added, but not yet implemented

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
e164User - The e164 number of a mobile user.
Returns:
DlsAPIout.status can have one of the following values:

mobileUserModifyTerminalName

DlsAPIout mobileUserModifyTerminalName(java.lang.String sessionRef,
                                       java.lang.String orderID,
                                       java.lang.String e164User,
                                       java.lang.String terminalName)

Modify the terminal name of a mobile user. If the mobile is currently logged on to a device, a job will be created to inform the device about the new terminal name. In this case the method is executed asynchronously. If the mobile is currently not logged on the mobile user data are updated synchronously.

Type: synchronous & asynchronous

History of change: DLS version Change
.HI-DLS.10.216.00. created and implemented

Parameters:
sessionRef - A valid session reference obtained through openSession(java.lang.String, java.lang.String).
orderID - Transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them).
e164User - The mobile user e164 number.
terminalName - The new terminal name.
Returns:
DlsAPIout.status can have one of the following values: If the mobile user is logged on to a device, DlsAPIout.result contains the requestID that is associated with the job created by DLS for that device. The current status of the job can be retrieved using getStatusOfRequestID(java.lang.String, java.lang.String, java.lang.String).

addUser

DlsAPIout addUser(java.lang.String sessionRef,
                  java.lang.String orderID,
                  java.lang.String e164User,
                  java.lang.String e164UserPin,
                  java.lang.String userDataProfile,
                  java.lang.String ppData)

THIS METHOD IS NOT YET IMPLEMEMNTED AND RETURNS DlsAPIout.DLSAPI_ERROR_NOT_IMPLEMENTED.

Create a mobile user.

Type: pseudo-synchronous or asynchronous (depending on timeout parameter)

History of change: DLS version Change
.HI-DLS.10.202.00. created

Parameters:
sessionRef - a valid session reference obtained through openSession(java.lang.String, java.lang.String)
orderID - transparent to DLS (used by client to separate different users - if the client application uses the same session for all of them)
e164User - The mobile users e164 number.
e164UserPin -
userDataProfile - User data rofile to use when creating the mobile user.
ppData - If set to 'true' use plug & play data when creating mobile user. This requieres plug & play data to be configured prior to adding the mobile user.