5. API Reference

module TurretApi

Cpp

osxpert.turret.api

Java

com.unify.osx.turret.api

5.1. Constants

constantOk: i32

Action performed successfully

constantInvalidArgument: i32

One of the provided arguments has invalid value. Please refer to the description of the called function for more information.

constantInvalidSpeechUnit: i32

No speech unit exists with the provided id.

constantWrongLoginState: i32

The requested action can not be performed in the current login state.

constantCannotSendRequest: i32

The request could not be forwarded to an external component (System Manager or MLC)

constantLineUnavailable: i32

The provided line is not available at the moment. Check connection to MLC.

constantLineBusy: i32

The provided line is already in use for another call.

constantSpeechUnitBusy: i32

The provided speech unit is already in use for another call.

constantInvalidLine: i32

There is no line available with the provided line name.

constantNoIncomingCall: i32

There are no incoming calls on any line on the profile.

constantLineIsNotRinging: i32

No call can be picked up from the requested line as it is in idle state.

constantSpeechUnitHasNoCall: i32

The requested action can not be performed because there is no call on the provided speech unit.

constantNoFreeLineAvailable: i32

There are no free lines available to perform the requested action.

constantFunctionUnavailable: i32

The specified action can not be performed

constantNoConsultation: i32

There is no consultation

constantLoginSuccessful: i32

The provided login data is correct, the login process has been finished, the software is ready for use.

constantNoConnectionToSm: i32

Connection to the System Manager has been lost.

constantAuthenticationFailed: i32

The provided username and/or password is incorrect.

constantDatabaseError: i32

The requested action failed due to a System Manager database operation error.

constantUnknownProfile: i32

No profile could be found with the specified name.

constantLdapError: i32

There was an error during the ldap authentication.

constantLicenseNotAvailable: i32

The request was refused by the License Server.

constantLoadTLSCertError: i32

There was an error loading the certificate files for Thrift TLS notifications.

constantInvalidRingTransfer: i32

No ring transfer could be found with the provided identifier.

constantRingTransferIsOnlyForSignalization: i32

The specified ring transfer is only for signalization, state can not be changed.

constantRingTransferIsAlreadyInThatState: i32

The specified ring transfer is already in the requested state.

constantRingTransferIsMissingOnServer: i32

The specified ring transfer not exists on the server. Try refreshing the config or contacting the system administrator.

constantRingTransferHasNoLocalInstance: i32

The specified ring transfer could not be activated because there this ring transfer is not configured on the controlled profile. Contact the system administrator.

constantRingTransferControlledProfileLoggedOut: i32

The specified ring transfer could not be activated because the controlled profile is logged out.

constantRingTransferKagConflict: i32

The specified ring transfer could not be deactivated because it is the last active ring transfer in a keep active group.

constantRingTransferStateChangeTimeout: i32

The ring transfer state change request timed out.

constantInvalidRingTransferSequence: i32

No ring transfer sequence could be found with the provided identifier.

constantRingTransferSequenceIsOnlyForSignalization: i32

The specified ring transfer sequence is only for signalization, state can not be changed.

constantRingTransferSequenceIsAlreadyInThatState: i32

The specified ring transfer sequence is already in the requested state.

constantRingTransferSequenceIsNotInverting: i32

The specified ring transfer sequence cannot be deactivated directly because it is not configured for inverting behavior.

constantRingTransferSequenceIsMissingOnServer: i32

The specified ring transfer sequence not exists on the server. Try refreshing the config or contacting the system administrator.

constantRingTransferSequenceStateChangeTimeout: i32

The ring transfer sequence state change request timed out.

constantInvalidInterfaceAction: i32

No interface action could be found with the provided api name.

constantInterfaceActionIsOnlyForSignalization: i32

The specified interface action is only for signalization, state can not be changed.

constantInterfaceActionIsAlreadyInThatState: i32

The specified interface action is already in the requested state.

constantInvalidInterfaceActionState: i32

The requested state can not be set for the specified interface action.

constantUnknown: i32

Unexpected error has occured

5.2. Type aliases

typedefLineName = string

typedefSpeechUnitId = i16

typedefTurretErrorCode = i32

5.3. Enumerations

enumTurretState

TurretState.Logout = 0

The turret is logged out

TurretState.ReceiveCallsOnly = 1

The turret is in Receive Calls Only mode

TurretState.Login = 2

The turret is logged in with a profile

TurretState.Unknown = 255

enumBasicLineState

BasicLineState.Idle = 0

No activity on the line

BasicLineState.Ringing = 1

There is an incoming call on the line

BasicLineState.Connected = 2

The line is considered as connected

BasicLineState.Conversation = 3

There is an ongoing call on the line on this device

BasicLineState.ConversationByAnother = 4

There is an ongoing call on the line on another device

BasicLineState.PrivateHold = 5

The call on this line is put on hold by this device, and the conversation partner isn’t notified about this

BasicLineState.PrivateHoldByAnother = 6

The call on this line is put on hold by another device, and the conversation partner isn’t notified about this

BasicLineState.CommonHold = 7

The call on this line is put on hold by this device

BasicLineState.CommonHoldByAnother = 8

The call on this line is put on hold by another device

BasicLineState.Privacy = 9

The call is private for this device, and cannot be accessed by other devices

BasicLineState.PrivacyByAnother = 10

The call is private for another device, and cannot be accessed by this device

BasicLineState.SpeechMonitoring = 11

The line is assigned to a speech monitoring channel by this device, and is not present on any speech unit

BasicLineState.ConferenceHold = 12

This line is hosting a conference that is put on hold

BasicLineState.Inactive = 13

The line is unavailable due to connection error

BasicLineState.SpeechMonitoringByAnother = 14

The line is assigned to a speech monitoring channel by another device

BasicLineState.Announcement = 15

There is an active announcement on the line

BasicLineState.Preseized = 16

The line is reserved to be used by this device, and cannot be accessed by other devices

BasicLineState.PreseizedByAnother = 17

The line is reserved to be used by another device, and cannot be accessed by this device

BasicLineState.HostingQuickConference = 18

The line is the host of a quick conference

BasicLineState.HostingConsultation = 19

The line is the host of a consultation

BasicLineState.HostingPbxConference = 20

The line is the host of a PBX conference

BasicLineState.Unknown = 255

enumRingTransferState

RingTransferState.Active = 0

The ring transfer state is active

RingTransferState.Inactive = 1

The ring transfer state is inactive

enumRingTransferSequenceState

RingTransferSequenceState.Active = 0

The ring transfer sequence state is active

RingTransferSequenceState.Inactive = 1

The ring transfer sequence state is inactive

RingTransferSequenceState.PartiallyActive = 2

The ring transfer sequence state is partially (some of the ring transfers are in the required state, but not all of them)

enumInterfaceActionStateValue

InterfaceActionStateValue.Active = 0

The interface action state is active

InterfaceActionStateValue.Inactive = 1

The interface action state is inactive

InterfaceActionStateValue.State_A = 2

The interface action state is ‘A’

InterfaceActionStateValue.State_B = 3

The interface action state is ‘B’

InterfaceActionStateValue.State_C = 4

The interface action state is ‘C’

InterfaceActionStateValue.State_D = 5

The interface action state is ‘D’

InterfaceActionStateValue.State_E = 6

The interface action state is ‘E’

InterfaceActionStateValue.State_F = 7

The interface action state is ‘F’

InterfaceActionStateValue.State_G = 8

The interface action state is ‘G’

InterfaceActionStateValue.State_H = 9

The interface action state is ‘H’

InterfaceActionStateValue.State_I = 10

The interface action state is ‘I’

InterfaceActionStateValue.State_J = 11

The interface action state is ‘J’

InterfaceActionStateValue.State_K = 12

The interface action state is ‘K’

InterfaceActionStateValue.State_L = 13

The interface action state is ‘L’

InterfaceActionStateValue.State_M = 14

The interface action state is ‘M’

InterfaceActionStateValue.State_N = 15

The interface action state is ‘N’

InterfaceActionStateValue.State_O = 16

The interface action state is ‘O’

InterfaceActionStateValue.State_P = 17

The interface action state is ‘P’

InterfaceActionStateValue.State_Q = 18

The interface action state is ‘Q’

InterfaceActionStateValue.State_R = 19

The interface action state is ‘R’

InterfaceActionStateValue.State_S = 20

The interface action state is ‘S’

InterfaceActionStateValue.State_T = 21

The interface action state is ‘T’

InterfaceActionStateValue.State_U = 22

The interface action state is ‘U’

InterfaceActionStateValue.State_V = 23

The interface action state is ‘V’

InterfaceActionStateValue.State_W = 24

The interface action state is ‘W’

InterfaceActionStateValue.State_X = 25

The interface action state is ‘X’

InterfaceActionStateValue.State_Y = 26

The interface action state is ‘Y’

InterfaceActionStateValue.State_Z = 27

The interface action state is ‘Z’

enumInterfaceActionKeyState

InterfaceActionKeyState.Pressed = 0

A push type key is pressed

InterfaceActionKeyState.Released = 1

A push type key is released

InterfaceActionKeyState.Clicked = 2

A switch type key is pressed

5.4. Structs

structLineStatesData

Contains the name of a line and the composite state of the line. Used for snapshots about lines, and notification about state changes of the line.

fieldlineName: TurretApi.LineName

Unique name of the line

fieldbasicLineStates: set<TurretApi.BasicLineState>

Set of BasicLineStates of the line (as they are not all mutually exclusive)

structSubscriberInfo

Contains information required to be able to subscribe for notifications.

fieldipAddress: string

Specifies the notification receiver’s IP address

fieldport: i32

Specifies the port the receiver is listening on

fieldturretName: string

Notifications will contain this name for turret identification if the connecting client has to handle multiple turrets at the same time. This parameter is optional. If no turretName is provided, the notifications will be sent with an empty string as the name.

structRingTransferId

Contains information required to identify a ring transfer or a ring transfer sequence

fieldapiName: string

The API name of the ring transfer

fieldcontrolledProfileName: string

The name of the controlled profile

structInterfaceActionState

Contains information about an interface action’s state and the texts displayed on its button

fieldstate: TurretApi.InterfaceActionStateValue

The state of the ring transfer

fieldlabelText: string

The overriding text for ‘label’. Overriding means that it is an empty string in case of default text. It is optional only when used in setInterfaceActionState.

fieldfirstLineText: string

The text displayed on the first line. Overriding means that it is an empty string in case of default text. It is optional only when used in setInterfaceActionState.

fieldsecondLineText: string

The text displayed on the second line. Overriding means that it is an empty string in case of default text. It is optional only when used in setInterfaceActionState.

exceptionTurretApiException

Exception type used to indicate that an error has occured.

fieldErrorCode: TurretApi.TurretErrorCode

Unique number indicating the error

fieldErrorAsString: string

Short description of the problem, useful for logging

5.5. Services

serviceTurretRequestService

void requestNotifications(TurretApi.SubscriberInfo subscriberInfo) throws (TurretApi.TurretApiException ex)

Parameters

subscriberInfo – SubscriberInfo IP address and port of the requesting client; Optionally contains turret display name

Exceptions

ex –

Requests notifications about line state change, login state change, login errors and change on top of call queue.

list<TurretApi.LineName> getAvailableLines() throws (TurretApi.TurretApiException ex)

Exceptions

ex –

Requests and returns a list about the identifiers of the available lines. TurretApi.TurretApiException is thrown if the turret is logged out.

TurretApi.LineStatesData snapshotLineRequest(TurretApi.LineName lineName) throws (TurretApi.TurretApiException ex)

Parameters

lineName – Identifier of the requested line

Exceptions

ex –

Requests the state of the line specified by lineName. TurretApi.TurretApiException is thrown if the turret is logged out or line name is invalid.

void login(string profileName, string password) throws (TurretApi.TurretApiException ex)

Parameters

• profileName – Name of the profile

• password – Profile’s password

Exceptions

ex –

Requests the turret to log in with the specified profile name and password. TurretApi.TurretApiException is thrown if the turret is already logged in. A successful call of this function only means that the request is forwarded to the System Manager; The actual response will arrive in a login response notification (see onLoginResponse)

void logout() throws (TurretApi.TurretApiException ex)

Exceptions

ex –

Requests the turret to log out of the currently logged in profile. TurretApi.TurretApiException is thrown if the turret is already logged out.

void makeCall(TurretApi.SpeechUnitId suId, string number) throws (TurretApi.TurretApiException ex)

Parameters

• suId – Speech unit identifier

• number – Telephone number to call

Exceptions

ex –

Requests the turret to dial the given number from the specified speech unit. TurretApi.TurretApiException is thrown if speech unit id is invalid, the speech unit is busy or there is no free line to initiate a call from.

void makeCallFromSpecificLine(TurretApi.SpeechUnitId suId, TurretApi.LineName lineName, string number) throws (TurretApi.TurretApiException ex)

Parameters

• suId – Speech unit identifier

• lineName – Line identifier from which the call will be initiated

• number – Telephone number to call

Exceptions

ex –

Requests the turret to dial the given number from the specified speech unit using a certain line. TurretApi.TurretApiException is thrown if speech unit id or lineName is invalid, the speech unit or line is busy or the line is unavailable.

void createConsultation(TurretApi.SpeechUnitId suId, string number) throws (TurretApi.TurretApiException ex)

Parameters

• suId – Speech unit identifier

• number – Telephone number to call

Exceptions

ex –

Request the turret to create a Consultation on suId by calling number. It is prerequisite that there is a line on suId and it is Connected.

void transfer(TurretApi.SpeechUnitId suId) throws (TurretApi.TurretApiException ex)

Parameters

suId – Speech unit identifier

Exceptions

ex –

Request the turret to execute Transfer on the given suId. The line seized on suId must have the HostingConsultation state.

void toggle(TurretApi.SpeechUnitId suId) throws (TurretApi.TurretApiException ex)

Parameters

suId – Speech unit identifier

Exceptions

ex –

Request the turret to execute Toggle on the given suId. The line seized on suId must have the HostingConsultation state.

void pbxConference(TurretApi.SpeechUnitId suId) throws (TurretApi.TurretApiException ex)

Parameters

suId – Speech unit identifier

Exceptions

ex –

Request the turret to create a PBX Conference (max. 3 participants) on the given suId. The line seized on suId must have the HostingConsultation state. If the request was successful, the line on the given suId will have the HostingPbxConference state.

void answerCall(TurretApi.SpeechUnitId suId) throws (TurretApi.TurretApiException ex)

Parameters

suId – Receiver speech unit’s identifier

Exceptions

ex –

Answers the incoming call with the highest priority in the call queue. TurretApi.TurretApiException is thrown if speech unit id is invalid or the speech unit is busy.

void answerSpecificCall(TurretApi.SpeechUnitId suId, TurretApi.LineName lineName) throws (TurretApi.TurretApiException ex)

Parameters

• suId – Receiver speech unit’s identifier

• lineName – Ringing line’s identifier which will be picked up

Exceptions

ex –

Answers the incoming call on the line specified by lineName. TurretApi.TurretApiException is thrown if speech unit id or lineName is invalid, the speech unit is busy or there is no incoming call on the specified line.

void disconnectCall(TurretApi.SpeechUnitId suId) throws (TurretApi.TurretApiException ex)

Parameters

suId – Receiver speech unit’s identifier

Exceptions

ex –

Disconnects the call present on the speech unit specified by suId TurretApi.TurretApiException is thrown if the speech unit id is invalid, there is no ongoing call on the speech unit, or the turret is not logged in.

TurretApi.TurretState getLoginState()

Requests the current login state of the turret

string getVersion()

Requests the version of the turret software.

list<TurretApi.RingTransferId> getAvailableRingTransfers() throws (TurretApi.TurretApiException ex)

Exceptions

ex –

Requests the list of available ring transfers

TurretApi.RingTransferState snapshotRingTransfer(TurretApi.RingTransferId id) throws (TurretApi.TurretApiException ex)

Parameters

id –

Exceptions

ex –

Requests the current state of the ring transfer

void setRingTransferActive(TurretApi.RingTransferId id, bool active) throws (TurretApi.TurretApiException ex)

Parameters

• id –

• active –

Exceptions

ex –

Sets the ring transfer’s state

list<TurretApi.RingTransferId> getAvailableRingtransferSequences() throws (TurretApi.TurretApiException ex)

Exceptions

ex –

Requests the list of available ring transfer sequences

TurretApi.RingTransferSequenceState snapshotRingTransferSequence(TurretApi.RingTransferId id) throws (TurretApi.TurretApiException ex)

Parameters

id –

Exceptions

ex –

Requests the current state of the ring transfer sequence

void setRingTransferSequenceActive(TurretApi.RingTransferId id, bool active) throws (TurretApi.TurretApiException ex)

Parameters

• id –

• active –

Exceptions

ex –

Sets the ring transfer sequence’s state

list<string> getAvailableInterfaceActions() throws (TurretApi.TurretApiException ex)

Exceptions

ex –

Requests the list of available interface actions

TurretApi.InterfaceActionState snapshotInterfaceAction(string apiName) throws (TurretApi.TurretApiException ex)

Parameters

apiName –

Exceptions

ex –

Requests the current state of the interface action including the displayed texts

void setInterfaceActionState(string apiName, TurretApi.InterfaceActionState state) throws (TurretApi.TurretApiException ex)

Parameters

• apiName –

• state –

Exceptions

ex –

Sets the interface action’s state The texts within InterfaceActionState are optional. The texts are not changed if they are not specified. The texts can be reset to their original value by setting an empty string.

serviceTurretNotificationService

onewayvoid onLineStatesChanged(string turretName, TurretApi.LineStatesData states)

Parameters

• turretName – Identifier of the turret specified at notification subscription. It’s an empty string if no name was specified at subscription.

• states – Contains the name and the new state of the line.

Notifies about the change of state of the specified line.

onewayvoid onCallDataChanged(string turretName, TurretApi.LineName lineName, string partyNumber, string partyName, string contactName)

Parameters

• turretName – Identifier of the turret specified at notification subscription. It’s an empty string if no name was specified at subscription.

• lineName – Name of the line.

• partyNumber – Line number of the other party.

• partyName – Name of the line as provided by the PBX, encoded in UTF-8.

• contactName – Name of the calling party resolved from the contact list, encoded in UTF-8.

Notifies about the change of the possibly displayed name(s) of the line. Note: The turret’s GUI shows this information in the following way:

1. If contactName is not empty, then it is displayed.

2. If partyName is not empty, then "{partyNumber} {partyName}" is displayed.

3. In other cases, the partyNumber is diplayed.

onewayvoid onLoginStateChanged(string turretName, TurretApi.TurretState state)

Parameters

• turretName – Identifier of the turret specified at notification subscription. It’s an empty string if no name was specified at subscription.

• state – New login state of the turret.

Notifies about the login state change of the turret software.

onewayvoid onLoginResponse(string turretName, TurretApi.TurretErrorCode errorCode, string errorDescription)

Parameters

• turretName – Identifier of the turret specified at notification subscription. It’s an empty string if no name was specified at subscription.

• errorCode – Error code (see Constants)

• errorDescription – Short text description of the error

Notifies about an error during the login process

onewayvoid onTopOfCallQueueChanged(string turretName, TurretApi.LineName lineName)

Parameters

• turretName – Identifier of the turret specified at notification subscription. It’s an empty string if no name was specified at subscription.

• lineName – Name of the line at the top of the call queue or an empty string if there is none.

Notifies a new incoming call having higher priority than the ones before, or if all incoming calls have been removed from the call queue

onewayvoid onRingTransferStateChanged(string turretName, TurretApi.RingTransferId id, TurretApi.RingTransferState state)

Parameters

• turretName – Identifier of the turret specified at notification subscription. It’s an empty string if no name was specified at subscription.

• id – Identifier of the ring transfer

• state – The new state of the ring transfer

Notifies a ring transfer state change.

onewayvoid onRingTransferStateChangeError(string turretName, TurretApi.RingTransferId id, TurretApi.TurretErrorCode errorCode, string errorDescription)

Parameters

• turretName – Identifier of the turret specified at notification subscription. It’s an empty string if no name was specified at subscription.

• id – Identifier of the ring transfer

• errorCode – Error code (see TurretApi.TurretErrorCode)

• errorDescription – Short text description of the error

Notifies that a previous request to change the activation of a ring transfer has failed. (See TurretApi.TurretRequestService.setRingTransferActive.)

onewayvoid onRingTransferSequenceStateChanged(string turretName, TurretApi.RingTransferId id, TurretApi.RingTransferSequenceState state)

Parameters

• turretName – Identifier of the turret specified at notification subscription. It’s an empty string if no name was specified at subscription.

• id – Identifier of the ring transfer sequence

• state – The new state of the ring transfer sequence

Notifies a ring transfer sequence state change.

onewayvoid onRingTransferSequenceStateChangeError(string turretName, TurretApi.RingTransferId id, TurretApi.TurretErrorCode errorCode, string errorDescription)

Parameters

• turretName – Identifier of the turret specified at notification subscription. It’s an empty string if no name was specified at subscription.

• id – Identifier of the ring transfer sequence

• errorCode – Error code (see TurretApi.TurretErrorCode)

• errorDescription – Short text description of the error

Notifies that a previous request to change the activation of a ring transfer sequence has failed. (See TurretApi.TurretRequestService.setRingTransferSequenceActive.)

onewayvoid onInterfaceActionStateChanged(string turretName, string apiName, TurretApi.InterfaceActionState state)

Parameters

• turretName – Identifier of the turret specified at notification subscription. It’s an empty string if no name was specified at subscription.

• apiName – Identifier of the interface action

• state – The new state of the interface action

Notifies a interface action state change (including changes in the overriding texts).

onewayvoid onInterfaceActionKeyChanged(string turretName, string apiName, TurretApi.InterfaceActionKeyState keyState)

Parameters

• turretName – Identifier of the turret specified at notification subscription. It’s an empty string if no name was specified at subscription.

• apiName – Identifier of the interface action

• keyState – The key event

Notifies an interface action key event (press/release).