com.adobe.connectpro.telephony.adaptor
Interface TelephonyAdaptor


public interface TelephonyAdaptor

The TelephonyAdaptor interface defines methods that the adaptor implements in a Java module. This Java module integrates the telephony services provided by a CSP (Conferencing Services Provider) with Connect Pro.

After the adaptor is instantiated, Connect Pro calls adaptor methods to fetch the metadata for the provider represented by the adaptor. Metadata enables Connect Pro to support different levels of telephony integrations. Some of these methods are optional and depend on the integration supported by the adaptor.

After Connect Pro is finished retrieving the metadata, Connect Pro must call initAdaptor method with appropriate parameters to pass settings that have been configured by the customers for that adaptor instance, such as connection parameters.

After the adaptor instance is initialized, calls to the adaptor and callbacks to Connect Pro provide support for various audio conference integration workflows.

The telephony adaptor interface is based on predefined Java method calls and is primarily driven by Connect Pro. The adaptor cannot make Connect Pro API calls through the adaptor interface. If you are developing a custom telephony integration that requires specific customization and control over Connect Pro defaults, use the XML API calls that are supported through the Connect Pro HTTP interface

Except for the metadata inquiry calls and certain other calls (such as the validateTelephonyProfile method), the telephony adaptor interface is asynchronous; that is, Connect Pro submits commands to the adaptor but doesn’t get return values to indicate the successful completion. For these commands, Connect Pro indicates in the UI for a meeting that a command is in process, but it doesn't change the option value in the UI until the adaptor gives a callback to indicate the actual information change on the bridge. The javadocs mention the asynchronous behavior where applicable. For these methods the adaptor returns immediately after successfully submitting the request to the bridge. Asynchronous responses in these cases are returned to Connect Pro using the TelephonyCallback interface methods.

In addition to the asynchronous commands and responses mentioned above, the adaptor can also use the TelephonyCallback interface to send other notifications, such as when a new telephony user joins the meeting. These notifications are generally generated by the CSP bridge and sent to the adaptor.

In general, adaptors implement their own logic to receive notifications from the CSP bridge. For example, an adaptor may have logic to maintain a live TCP connection with the bridge on which it may receive callbacks. For another example, the adaptor may be using long polling HTTP calls to retrieve the notifications from the bridge. Alternatively adaptor may be using the HTTP callbacks sent by bridge to the Connect Pro Telephony Server by configuring an Axis service on the Telephony Server.


Nested Class Summary
static class TelephonyAdaptor.StopRecordingCause
          Possible reasons for which Connect Pro would invoke the stopRecording call.
 
Method Summary
 java.lang.String adaptorCallback(java.util.Map<java.lang.String,java.lang.String[]> callbackParameters)
          This method is not supported in Connect Pro 7.5 SP1.
 java.lang.String addPendingAudioDownload(java.lang.String[] downloadURLs, java.lang.String[] headers, java.lang.String downloadPath)
          Adds a pending audio file download.
 void destroyAdaptor()
          The adaptor closes all open sessions and/or connections and release all resources.
 void destroyConferenceSession(java.lang.String conferenceId)
          Closes the session for the specified conference.
 java.lang.String dialOut(java.lang.String conferenceId, java.lang.String phoneNumber, TelephonyUserInfo.UserType userType, java.lang.String userName, boolean isVideo)
          Dials outs to the phone user with the specified information.
 void endConference(java.lang.String conferenceId)
          Stops the audio conference on the bridge.
 ConferenceInfo getConferenceInfo(java.lang.String conferenceId)
          Gets conference-wide options such as music, talkernotify, entry/exit announcements.
 java.util.List<DialInStep> getDialInSteps()
          Gets the Universal Voice dial-in steps for telephony profiles of the Provider represented by this adaptor for the purpose of UV integration.
 java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.String>> getLocalizationStrings()
          This method is not supported in Connect Pro 7.5 SP1.
 java.util.List<java.lang.String> getSubConferenceIds(java.lang.String conferenceId, int connectBreakoutRoomCount)
          Gets a list of sub-conference IDs assigned to break-out rooms for the specified conference.
 java.util.List<AdaptorField> getTelephonyFieldInfo()
          Gets the metadata for telephony profiles of the provider represented by this adaptor instance.
 java.util.List<TelephonyUserInfo> getUserList(java.lang.String conferenceId)
          Gets information about conference users for the specified conference.
 void hangUp(java.lang.String conferenceId, java.lang.String telephonyUserId)
          Disconnects the specified phone user from the conference.
 void initAdaptor(TelephonyCallback callback, java.util.Map<java.lang.String,java.lang.String> telephonySettings, java.lang.String adaptorInstanceId)
          After the adaptor is instantiated, Connect Pro calls this method to let the adaptor perform initialization tasks.
 java.lang.String initConferenceSession(java.util.Map<java.lang.String,java.lang.String> telephonyProfileInfo)
          Passes telephony profile parameters to the adaptor for a conference when a Connect Pro meeting is initialized with specified telephony profile.
 void moveAllToMainConference(java.lang.String conferenceId)
          Moves all phone users in all the audio sub-conferences to the main audio conference room.
 void moveUserToSubConference(java.lang.String conferenceId, java.lang.String telephonyUserId, java.lang.String subConferenceId)
          Moves individual phone user to the audio sub-conference room.
 void muteAll(java.lang.String conferenceId)
          Mutes all the participants in the main conference room.
 void onConnectRoomEmpty(java.lang.String conferenceId)
          This method is not supported in Connect Pro 7.5 SP1.
 void onConnectUserLeft(java.lang.String conferenceId, java.lang.String telephonyUserId)
          This method is not supported in Connect Pro 7.5 SP1.
 java.lang.String reconnectConference(java.util.Map<java.lang.String,java.lang.String> telephonyProfileInfo, java.util.List<TelephonyUserInfo> lastKnownUserList)
          Reconnects to a specified conference.
 void setAnnouncementOption(java.lang.String conferenceId, AnnouncementOption optionName, java.lang.String optionValue)
          Sets an announcement option for the specified conference.
 void setConferenceOption(java.lang.String conferenceId, ConferenceOption optionName, java.lang.String optionValue)
          Sets an option for the specified conference.
 void setCustomConferenceOption(java.lang.String conferenceId, java.lang.String optionName, java.lang.String optionValue)
          Sets a custom option (specific to an individual adaptor) for the specified conference.
 void setCustomUserOption(java.lang.String conferenceId, java.lang.String telephonyUserId, java.lang.String optionName, java.lang.String optionValue)
          To set a custom option (specific to an individual adaptor) , for a phone user for the specified conference.
 void setUserOption(java.lang.String conferenceId, java.lang.String telephonyUserId, UserOption optionName, java.lang.String optionValue)
          To set an option for a phone user for specified conference.
 void startConference(java.lang.String conferenceId)
          Starts the audio conference on the bridge.
 void startRecording(java.lang.String conferenceId, java.lang.String fileName)
          Starts a conference recording on the bridge.
 void stopRecording(java.lang.String conferenceId, TelephonyAdaptor.StopRecordingCause cause)
          Stop a conference recording on the audio bridge.
 java.util.List<ConferenceNumber> validateTelephonyProfile(java.util.Map<java.lang.String,java.lang.String> telephonyProfileInfo)
          This method performs three functions.
 

Method Detail

adaptorCallback

java.lang.String adaptorCallback(java.util.Map<java.lang.String,java.lang.String[]> callbackParameters)
This method is not supported in Connect Pro 7.5 SP1. This is kept for future use to support HTTP callbacks through Connect Pro Telephony Server's HTTP connector.


addPendingAudioDownload

java.lang.String addPendingAudioDownload(java.lang.String[] downloadURLs,
                                         java.lang.String[] headers,
                                         java.lang.String downloadPath)
                                         throws AdaptorException
Adds a pending audio file download. When the download is finished, the adaptor reports the completion by calling audioDownloadComplete method in TelephonyCallback interface.

Parameters:
downloadURLs - URLs of the files to be downloaded.
headers - The headers required to download the files.
downloadPath - The path to the folder in which the downloaded file is to be stored.
Returns:
downloadId An identifier issued by the adaptor for later reference by either Connect Pro or the adaptor. When the download is finished, the adaptor reports the completion with this identifier
Throws:
AdaptorException - If an internal error occurs.

destroyAdaptor

void destroyAdaptor()
The adaptor closes all open sessions and/or connections and release all resources.


destroyConferenceSession

void destroyConferenceSession(java.lang.String conferenceId)
Closes the session for the specified conference. After this call, the conference identifier is no longer available for communication between Connect Pro and adaptor. This method is usually called by Connect Pro when the meeting associated with the Conference is no longer active.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.

dialOut

java.lang.String dialOut(java.lang.String conferenceId,
                         java.lang.String phoneNumber,
                         TelephonyUserInfo.UserType userType,
                         java.lang.String userName,
                         boolean isVideo)
                         throws AdaptorException
Dials outs to the phone user with the specified information. This returns the identifier for the phone user that the adaptor creates when dial out is complete. Connect Pro uses this generated identifier for merging the user on userOnline callback, and for later communication for the phone user using telephonyUserId parameter.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
phoneNumber - The phone number to be dialed.
userType - Added user type.
userName - Connect Pro display name of the Connect counterpart. Optional parameter. May be ignored by the adaptor. Parameter value may also be null.
isVideo - Optional attribute indicating if the phone user is a video end-point. Optional parameter. May be ignored by the adaptor.
Throws:
AdaptorException - If dial out can not be completed due to invalid number.

endConference

void endConference(java.lang.String conferenceId)
                   throws AdaptorException
Stops the audio conference on the bridge.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
Throws:
AdaptorException - If the specified conference is not active on the bridge, or if an error occurs while communicating to the bridge.

getConferenceInfo

ConferenceInfo getConferenceInfo(java.lang.String conferenceId)
                                 throws AdaptorException
Gets conference-wide options such as music, talkernotify, entry/exit announcements. This method may be called by Connect Pro to refresh conference state. State refresh may be needed due to an internal system problem or inconsistency within the Connect Pro meeting.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
Returns:
Detailed conference information.
Throws:
AdaptorException - If an internal error occurs.

getDialInSteps

java.util.List<DialInStep> getDialInSteps()
                                          throws AdaptorException
Gets the Universal Voice dial-in steps for telephony profiles of the Provider represented by this adaptor for the purpose of UV integration. If the provider doesn't support UV integration, returns null. The response includes the list of dial-in steps in the order of execution. The first step represents the conference number, and it can be followed by multiple delay and dtmf steps.

Returns:
The list of dial-in steps for UV integration. See DialInStep
Throws:
AdaptorException - If an internal error occurs.

getLocalizationStrings

java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.String>> getLocalizationStrings()
                                                                                                        throws AdaptorException
This method is not supported in Connect Pro 7.5 SP1. This is kept for future use to support adaptor Strings localization without the need to edit language files on Connect Pro server.

Throws:
AdaptorException

getSubConferenceIds

java.util.List<java.lang.String> getSubConferenceIds(java.lang.String conferenceId,
                                                     int connectBreakoutRoomCount)
                                                     throws AdaptorException
Gets a list of sub-conference IDs assigned to break-out rooms for the specified conference. The list doesn't include sub-conference ID for main meeting room. Main room is referred to by the original conferenceId of the conference (generated by adaptor on initConferenceSession). Connect Pro maps the returned identifiers to the internal breakout rooms as per the order of elements in the list. All telephony user movement commands refer to these IDs.

Connect Pro 7.5 SP1 supports a maximum of 10 subconferences.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
connectBreakoutRoomCount - Maximum breakout rooms Connect Pro supports and expects subconference identifier for. In case adaptor/bridge supports less return less number of identifiers.
Returns:
A list of sub-conference IDs.
Throws:
AdaptorException - If an internal error occurs. This means that breakout rooms will not be integrated with audio sub conferences.

getTelephonyFieldInfo

java.util.List<AdaptorField> getTelephonyFieldInfo()
                                                   throws AdaptorException
Gets the metadata for telephony profiles of the provider represented by this adaptor instance.

The response should include the list of telephony field information. For example if the field value is required to be input from user, should it be displayed in Connect Pro meeting UI or not etc. Connect Pro can call this method immediately after the adaptor is initialized. That is, this method may be called before initAdaptor method is called since it expects only metadata for the provider.

Returns:
The list of profile field meta-data. See AdaptorField
Throws:
AdaptorException - If an internal error occurs.

getUserList

java.util.List<TelephonyUserInfo> getUserList(java.lang.String conferenceId)
                                              throws AdaptorException
Gets information about conference users for the specified conference. This method may be called by Connect Pro in case it needs to refresh conference state. State refresh may be needed in case of some internal system problem or inconsistency within Connect Pro meeting.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
Returns:
List containing details of all the telephony users in the conference.
Throws:
AdaptorException - If an internal error occurs.

hangUp

void hangUp(java.lang.String conferenceId,
            java.lang.String telephonyUserId)
            throws AdaptorException
Disconnects the specified phone user from the conference.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
telephonyUserId - Identifier generated by the adaptor for phone user.
Throws:
AdaptorException - If the phone user is inactive or unknown.

initAdaptor

void initAdaptor(TelephonyCallback callback,
                 java.util.Map<java.lang.String,java.lang.String> telephonySettings,
                 java.lang.String adaptorInstanceId)
                 throws AdaptorException
After the adaptor is instantiated, Connect Pro calls this method to let the adaptor perform initialization tasks. Adaptor settings are given in the form of name-value pairs, such as the connection parameters, which the administrator defines in Connect Pro for this adaptor instance.

The TelephonyCallback object parameter enables the adaptor to send asynchronous responses and notifications. The adaptor stores this TelephonyCallback object internally so that it can be used later for communication with Connect Pro.

Parameters:
callback - Callback object for asynchronous responses and notifications.
telephonySettings - Adaptor settings such as connection parameters.
adaptorInstanceId - Unique identifier generated by Connect Pro for this adaptor instance. This identifier needs to be cached and used by adaptor/bridge if the bridge needs to make API callbacks to the adaptor. For details look for CallBacks in TelephonyAdaptor javadocs.
Throws:
AdaptorException - If an internal error occurs. This means the adaptor instance is not available to serve any other telephony requests and may be destroyed.

initConferenceSession

java.lang.String initConferenceSession(java.util.Map<java.lang.String,java.lang.String> telephonyProfileInfo)
                                       throws AdaptorException
Passes telephony profile parameters to the adaptor for a conference when a Connect Pro meeting is initialized with specified telephony profile. The adaptor caches this information in case it needs it for later reference.

Adaptor may Initialize a connection to the bridge at this time. This gives adaptor a chance to connect early so that the conference requires less time to start up later. Also in case the conference is already active on the bridge, adaptor may inform Connect Pro about the same regardless of the startConference call.

The method should returns a conference identifier for later reference to the conference. All other telephony calls only communicate with the returned conference identifier.

Parameters:
telephonyProfileInfo - Information about the telephony profile required to start the conference. It is a set of name value pairs, where names are the field-id and values are user profile value of those fields.
Returns:
A Conference identifier, which is unique for this running instance of the adaptor.
Throws:
AdaptorException - If profile is expired or some internal error occurs. This means the UI to start the conference would be disabled in Connect Pro meeting. Adaptor may choose to do nothing in this call and instead may throw error for expired profile or invalid profile on startConference call.

moveAllToMainConference

void moveAllToMainConference(java.lang.String conferenceId)
                             throws AdaptorException
Moves all phone users in all the audio sub-conferences to the main audio conference room.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
Throws:
AdaptorException - If an internal error occurs.

moveUserToSubConference

void moveUserToSubConference(java.lang.String conferenceId,
                             java.lang.String telephonyUserId,
                             java.lang.String subConferenceId)
                             throws AdaptorException
Moves individual phone user to the audio sub-conference room.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
telephonyUserId - The user telephony identifier generated by adaptor.
subConferenceId - sub-conference room identifier generated by the adaptor on getSubConferenceIds call.
Throws:
AdaptorException - If an internal error occurs.

muteAll

void muteAll(java.lang.String conferenceId)
             throws AdaptorException
Mutes all the participants in the main conference room.

This method is different from the setOption() method. The muteAll method applies to the entire conference, whereas setOption only applies to a selected phone user.

If muteAll succeeds, each participant mute event is returned to Connect Pro using userInfoUpdated callback.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
Throws:
AdaptorException - If an internal error occurs.

onConnectRoomEmpty

void onConnectRoomEmpty(java.lang.String conferenceId)
This method is not supported in Connect Pro 7.5 SP1. This is kept for future use to support event passing to adaptor when all the users in the Connect Pro meeting room have left. Adaptor may choose to end the audio conference on the bridge in this scenario.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.

onConnectUserLeft

void onConnectUserLeft(java.lang.String conferenceId,
                       java.lang.String telephonyUserId)
This method is not supported in Connect Pro 7.5 SP1. This is kept for future use to support event passing to adaptor when the Connect Pro meeting user associated with specified phone user leaves the meeting room. Adaptor may choose to disconnect the telephony user as well in such a scenario. Please note that this event is sent only for those Connect Pro users who had an associated telephony user. The telephony user may still be shown as phone only user in Connect Pro meeting room.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
telephonyUserId - The user telephony identifier generated by adaptor.

reconnectConference

java.lang.String reconnectConference(java.util.Map<java.lang.String,java.lang.String> telephonyProfileInfo,
                                     java.util.List<TelephonyUserInfo> lastKnownUserList)
                                     throws AdaptorException
Reconnects to a specified conference. May be used by Connect Pro when a conference session fails over from one server running an adaptor instance to another server running other adaptor instance. Please note that neither initConferenceSession nor startConference is called if this method is called. Also please note that the parameter lastKnownUserList is only for information to the adaptor in case it helps it re-align the new telephony user identifiers with existing ones, so that users remain merged with Connect Pro meeting user counterparts. Adaptor may completely ignore this parameter in its reconnect logic.

Once the reconnect is successful the adaptor should user the conferenceReconnected callback to inform Connect Pro about the event as well as the latest information about the conference.

Parameters:
lastKnownUserList - The user details known to Connect Pro before the failover. This is an optional parameter in the sense that adaptor may choose to ignore this.
Returns:
A Conference identifier, which is unique for this running instance of the adaptor.
Throws:
AdaptorException - If the communication to the bridge fails, or if conference does not exist, or if profile fields values are invalid. See error code constants in exception javadocs.

setAnnouncementOption

void setAnnouncementOption(java.lang.String conferenceId,
                           AnnouncementOption optionName,
                           java.lang.String optionValue)
                           throws AdaptorException
Sets an announcement option for the specified conference.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
optionValue - The value of the option being set.
optionName - The option being set. See AnnouncementOption
Throws:
AdaptorException - If an internal error occurs.
See Also:
AnnouncementOption

setConferenceOption

void setConferenceOption(java.lang.String conferenceId,
                         ConferenceOption optionName,
                         java.lang.String optionValue)
                         throws AdaptorException
Sets an option for the specified conference.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
optionName - The option being set. See ConferenceOption
optionValue - The value of the option being set.
Throws:
AdaptorException - If an internal error occurs.
See Also:
ConferenceOption

setCustomConferenceOption

void setCustomConferenceOption(java.lang.String conferenceId,
                               java.lang.String optionName,
                               java.lang.String optionValue)
                               throws AdaptorException
Sets a custom option (specific to an individual adaptor) for the specified conference. Custom options come from capability settings for the adaptor instance.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
optionName - The option being set.
optionValue - The value of the option being set.
Throws:
AdaptorException - If an internal error occurs.

setCustomUserOption

void setCustomUserOption(java.lang.String conferenceId,
                         java.lang.String telephonyUserId,
                         java.lang.String optionName,
                         java.lang.String optionValue)
                         throws AdaptorException
To set a custom option (specific to an individual adaptor) , for a phone user for the specified conference. Custom options come from capability settings for the adaptor instance.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
telephonyUserId - Identifier generated by the adaptor for phone user.
optionName - The option being set.
optionValue - The value of the option being set.
Throws:
AdaptorException - If specified user no longer exists or some communication/internal error occurs

setUserOption

void setUserOption(java.lang.String conferenceId,
                   java.lang.String telephonyUserId,
                   UserOption optionName,
                   java.lang.String optionValue)
                   throws AdaptorException
To set an option for a phone user for specified conference.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
telephonyUserId - Identifier generated by the adaptor for phone user.
optionName - The option being set. See UserOption
optionValue - The value of the option being set.
Throws:
AdaptorException - If specified user no longer exists or some communication/internal error occurs
See Also:
UserOption

startConference

void startConference(java.lang.String conferenceId)
                     throws AdaptorException
Starts the audio conference on the bridge.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
Throws:
AdaptorException - If the communication to the bridge fails, or if conference does not exist, or the conference account is expired, or if profile fields values are invalid. See error code constants in exception javadocs.

startRecording

void startRecording(java.lang.String conferenceId,
                    java.lang.String fileName)
                    throws AdaptorException
Starts a conference recording on the bridge.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
fileName - The name of the file in which the recording is stored when merging with Connect Pro recording.
Throws:
AdaptorException - If the conference is inactive.

stopRecording

void stopRecording(java.lang.String conferenceId,
                   TelephonyAdaptor.StopRecordingCause cause)
                   throws AdaptorException
Stop a conference recording on the audio bridge.

Parameters:
conferenceId - Identifier generated by the adaptor on initConferenceSession.
cause - tells adaptor if the recording has been stopped by host, or because all the Connect Pro meeting users had left the recording. Adaptor may choose to keep recording the audio conference for other use than integration with Connect Pro recording. For cause values see TelephonyAdaptor.StopRecordingCause
Throws:
AdaptorException - If a recording is not in progress.
See Also:
TelephonyAdaptor.StopRecordingCause

validateTelephonyProfile

java.util.List<ConferenceNumber> validateTelephonyProfile(java.util.Map<java.lang.String,java.lang.String> telephonyProfileInfo)
                                                          throws AdaptorException
This method performs three functions.

First is to verify if the specified telephony information constitutes a valid telephony profile or not. If not, adaptor throws the exception containing the list of fields which are not valid or missing. See ValidateException.

Second is to generate a list of conference numbers to be displayed in Connect Pro meeting UI. This is optional but preferable choice for displaying the conference numbers. Adaptor may use some profile info field instead for display of conference numbers. However, using this method is preferred because it gives Connect Pro flexibility to display multiple numbers in a user-friendly format.

Third is to add any information to the dual (input + output) parameter telephonyProfileInfo map. This may be additional information or some modification to existing information. For example, the adaptor may want to add a More Info URL field.

Parameters:
telephonyProfileInfo - Input/Output parameter. Input includes the information provided by user for creating a telephony profile. Output includes additional information generated by the adaptor for display purpose or for later use while starting the conference.
Returns:
A list of conference numbers. Returns null if adaptor chooses to display the numbers through some profile field.
Throws:
ValidateException - If the specified profile information is not valid.
AdaptorException - If an internal error occurs.