An application uses the BridgeFactory.getImpl() method to connect to the Bridge. The BridgeFactory requires a set of bridge parameters. Bridge parameters may be passed in a hashtable or defined in a properties file with the filename passed to the factory.

To connect to a MX Enterprise 5.0 bridge, the following properties are required:

• -IMPL_TYPE=
  IMPL_MODAPI_FOR_BCAPI_1_6_OR_HIGHER (Release 5.0) or
  IMPL_MODAPI (backward compatibility w/previous releases)
• -BRIDGE_NAME=domain_name or ip address of the bridge
• -USER_NAME=valid_user_account
• -PASSWORD=valid_password_for_user_account
• -OPER_NUM=operator_channel (if set to 0 - next available channel is used)

Optional bridge parameters may be also be set. The programmer's guide 'Meeting Exchange 5.0 Bridge Control API (BCAPI) Guide' contains details on all bridge parameters.

Yes - there are three new bridge parameters for Meeting Exchange 5.0.

The new parameters are:

• - XML_LOGGER_PROPERTIES - identifies a specific log4j.xml file, if not set the Java CLASSPATH is used to find the log4j.xml file
• - DATABASE_URL - defaults to value of BRIDGE_NAME.
• - DATABASE_DRIVER_NAME- defaults to "com.informix.jdbc.IfxDriver"

BCAPI is designed for persistent connections from an application server to the bridge. Applications should login once and keep the connection. It can take 12-50 or more seconds to log into a fully loaded bridge. A single BCAPI connection can control all conferences on the bridge simultaneously.

There is a bridge limit to the number of conferences a bridge supports. A fully loaded 1152 port bridge supports 800 user-conference rooms. Care must be taken to not open up more than the maximum number of supported rooms. Current results from doing this will cause a Bridge Exception, and possibly an API disconnect.

Most of the time a bridge service provider does not overbook the number of possible conferences. For instance, an 1152 port bridge supports up to 800 conferences, yet mathematically speaking it would be reasonable to expect 576 2-person conferences max. If the application is opening conference rooms and not closing them, the CONFERENCE_ID number will increment and the lower number rooms will not be re-used. When this happens it is possible to cause a catastrophic denial of service condition. See other FAQs related to openConference() for more information on opening conferences.

Operator logins are mutually exclusive. An operator login can be used only once on any bridge. For every active API login, there must be an FDAPI port configured to reserve an audio path for each persistent API connection. As a rule of thumb the bridge can support about 5% of the total number of ports as FDAPI login associations. For example, on a 1000 port bridge you should plan on having no more than 50 API connections (operator logins) to the bridge.

See the programmer's guide 'Meeting Exchange 5.0 Bridge Control API (BCAPI) Guide' and the 'Meeting Exchange 5.0 Administration and Maintenance S6200/S6800 Media Server' for detailed information on configuring operator logins and FDAPI ports.

No, but you can. See the FAQ question on 'What ports are required for the API?' for more details.

Listed below are the set of ports used by the client API to communicate with the bridge and the ports used by the bridge to communicate to the client API.

NOTE: The delta messages port on the API client increments from the base value in the table when more than one bridge is being monitored. For instance, an application connects to 5 bridges from a PC using the same jar file; the first one connects from the bridge to the API client at 5040, the second at 5041, third at 5042, fourth at 5043 and fifth at 5044. If ports 5040-5044 are already in use, then the API will attempt the connection starting at 5045 and so on.

NOTE: See the programmer's guide 'Meeting Exchange 5.0 Bridge Control API (BCAPI) Guide' for a description of the properties that allow developers to suggest the appropriate port connection.

The API requires an operator login on the bridge. The operator login can be created using the 'dcbmaint' login on the bridge. You will also need at least one reserved FDAPI port for each active operator login. Count the number of concurrent API applications, and Bridgetalk or Workstation logins, and add two or more for good measure - that should be the number of reserved FDAPI ports.

NOTE: The API does not dial out of the reserved FDAPI port; however, the bridge does require this association as a result of the legacy origins of the API being derived from an operator login type. The call handler on certain functions requires the FDAPI port to be available even though it is not being used explicitly for the API.

The number of reserved FDAPI ports should be understood when installing an application for an enterprise. Most service providers have 20 or more reserved FDAPI ports so the API connection does not usually require more ports to be allocated.

See the programmer's guide 'Meeting Exchange 5.0 Bridge Control API (BCAPI) Guide' and the 'Meeting Exchange 5.0 Administration and Maintenance S6200/S6800 Media Server' for detailed information on configuring operator logins and FDAPI ports.

The BridgeListener.onEvent(Event) callback method notifies listeners of events that have occurred on the bridge. Care must be taken to implement event handling correctly. The event supplied in the callback should be placed into a queue such that the queue gets serviced by a separate thread in the application.

No calls using BCAPI should be made from inside the onEvent(Event) method. This includes calls to benign BCAPI methods that only read from the cache such as Participant.getParameters().

• At login time, BCAPI caches a complete image of the bridge state in the client and then receives delta messages that notify the BCAPI client when the cache has changed due to changes occurring on the bridge.
• BCAPI methods that throw a BridgeException send command information to the bridge and receive acknowledgement of the command request before returning.
• Methods that do not throw a BridgeException retrieve information from the BCAPI client cache and do not cause network traffic. Examples of methods that retrieve information from the cache are Participant.getParameters() or Bridge.getConferenceIds().

When a BCAPI client sends a command request to the bridge, the request is acknowledged prior to the command being executed by the bridge. After the bridge executes the command, delta messages are sent to the BCAPI client to update the client cache with the changed attributes. Client applications must be sure the cache has received the delta message from the bridge before retrieving the attribute values from the cache.

Yes - there are multiple points of conference control. Conference and participant states can be changed through participant DTMF key entry on the telephone or by commands invoked by other client applications. Commands to change state do not necessarily change the desired state. The bridge's call handler looks on the stack to determine if there are redundant commands. For example - mute (), unmute() , mute() can result in no event occurring for the unmute() request since the next command on the stack is mute().

The only way to accurately detect state change is to listen for events through the BridgeListener interface or to poll for attribute states. A good example of this is the Bridge.openConference("","1234") method. This method does not return a conference. If the conference is opened with this command, registered BridgeListeners will detect the conference being opened when they receive the appropriate event. If the conference was already open, no event will arrive, but the conference will appear in the list of active conferences retrieved from Bridge.getConferenceIds().

The confereeCode must be in the schedule database. The schedule database contains unattended, attended and on-demand conference codes. BCAPI will NOT open conferences that are not in the schedule database.

If a conference is already open on the bridge, there will be no CONFERENCE_OPEN event returned from a openConference("",confereeCode) call.

A conference opened by the API calling Bridge.openConference() will stay open until:

• A participant enters and leaves the room
• The API client requests a Bridge.conferenceClose() or
• The scheduled end time of the conference passes and total participants is equal to zero.

Not all conferences have a scheduled end time. This means a conference opened by the API can stay open indefinitely and thus result in a denial of service.

There are a limited number of conference rooms on any bridge. If an application or operator opens a room, the call handler will ignore the room until the entire bridge becomes full or until a bridge reboot. This generally means that a room should only be opened if there is a request to dial people into the conference. If there is no impending request to actually use the room no conferenceOpen() should occur.

The dial method returns a participant prior to the dialing request completing. The dialed participant is not associated with a conference room until after the PARTICIPANT_USER_ENTER event for that participant arrives. If the conference closes before the arrival of this event, the dialing will continue and the participant(s) will wind up in an ad-hoc room on the bridge.

In some applications, like click-to-dial, there is also a click-to-close-conference button. When the user clicks to dial, followed by an immediate decision to abort, and then clicks to close conference, the API client is responsible for disconnecting the in-progress dialed participants.

Applications should always maintain a list of dialed out participants until the PARTICIPANT_USER_ENTER event arrives for each participant. After the PARTICIPANT_USER_ENTER event arrives, the Bridge.closeConference() command will disconnect that participant.

The BCAPI dial method returns a participant before the dial request is completed. The participant has entered a conference when the PARTICIPANT_USER_ENTER event for that participant is received from the bridge.

Applications and conference participants and moderators can mute and un-mutes lines in several ways. A line can be in a muted state as a result of participant actions or applications invoking BCAPI methods.

• operatorMute - the line stays muted until operatorUnMute() is called or the line is disconnected. Equivalent to silencing a participant or moderator. Invoked through the BCAPI operatorMute() and operatorUnMute() methods.
• applicationMute - the line is muted as a result of lecture-mode or the application calling mute().
• selfMute - participants may mute themselves using DTMF keys or an application can mute a participant using the BCAPI selfMute(), selfUnMute() methods.
• annunciatorMute - when a line is being played a message, the line is muted while the message is being played.

The mute state of a participant - is the combined (logical OR) of the mute states: application-mute, operator-mute and self-mute.

Check the Participant.STATE attribute. The STATE_CHANGE_EVENT fires for any changes to Participant.STATE value. When the Participant.STATE attribute changes from STATE_BEING_DIALED to any other state it implies that the phone has been picked up or disconnected by the far end. It does not mean that a person is on the other end.

Yes. This is normal behavior. The PARTICIPANT_USER_ENTER event means the dialed out line has been associated with a user conference. A user conference is a main-conference, sub-conference or intercept-conference. A non-user conference is an operator-conference or an annunciator conference, and possibly other conferences like the hold-conference or enter-conference. The PARTICIPANT_USER_ENTER also means the conference can hear the phone ringing if the participant is not muted in that conference. The PARTICIPANT_ENTER event is an enter event for any type of conference, for example the client API will see these when annunciators are played, and when entering user conferences.