6 Conference call control Service Interface Classes

29.198-04-53GPPOpen Service Access (OSA) Application Programming Interface (API)Part 4: Call controlSubpart 5: Conference call control Service Capability Feature (SCF)TS

The Conference call control Service enhances the multi-media call control service. The conference call control service gives the application the ability to manipulate subconferences within a conference. A subconference defines the grouping of legs within the overall conference call. Only parties in the same subconference have a bearer connection (or media channel connection) to each other (e.g. can speak to each other). The application can:

– create new subconferences within the conference, either as an empty subconference or by splitting an existing subconference in two subconferences;

– move legs between subconferences;

– merge subconferences;

– get a list of all subconferences in the call;

The generic conference also gives the possibility to manipulate typical multi-media conference details, such as:

– interworking with network signalled conference protocols (e.g. H.323);

– manipulation of the media in the MCU, e.g., broadcasting of video;

– handling of multi-media conference policies, e.g., how video should be handled, voice controlled switched or chair controlled.

Furthermore the conference call control service adds support for the reservation of resources needed for conferencing. The application can:

– reserve resources for a predefined time period;

– free reserved resources;

– search for the availability of conference resources based on a number of criteria.

There are two ways to initiate a conference:

– the conferences can be started on the pre-arranged time by the service, at the start time indicated in the reservation. The application is notified about this. The application can then add parties to the conference and/or parties can dial-in to the conference using the address provided during reservation;

– the conference can be created directly on request of the application using the createConference method in the IpConfCallControlManager interface.

Each Conference call control interface inherits from a Multi Media Call Control interface, which in turn inherits from Multi Party Call Control. It is possible to implement conference call control without any multi-media features, using only those inherited methods which come from Multi Party Call Control, in addition to the Conference call control methods. The minimum required method set for each Conference call control interface reflects this possibility, by not requiring the Multi Media Call Control methods.

6.1 Interface Class IpConfCallControlManager

Inherits from: IpMultiMediaCallControlManager;

The conference Call Control Manager is the factory interface for creating conferences. Additionally it takes care of resource management. This interface shall be implemented by a Conference call control SCF. As a minimum requirement, either the createConference() method shall be implemented, or the reserveResources() and freeResources() methods shall be implemented. The minimum required methods from IpMultiPartyCallControlManager are also required.

<<Interface>>

IpConfCallControlManager

createConference (appConferenceCall : in IpAppConfCallRef, numberOfSubConferences : in TpInt32, conferencePolicy : in TpConfPolicy, numberOfParticipants : in TpInt32, duration : in TpDuration) : TpConfCallIdentifier

checkResources (searchCriteria : in TpConfSearchCriteria) : TpConfSearchResult

reserveResources (appInterface : in IpAppConfCallControlManagerRef, startTime : in TpDateAndTime, numberOfParticipants : in TpInt32, duration : in TpDuration, conferencePolicy : in TpConfPolicy) : TpResourceReservation

freeResources (resourceReservation : in TpResourceReservation) : void

6.1.1 Method createConference()

This method is used to create a new conference. If the specified resources are not available for the indicated duration the creation is rejected with P_RESOURCES_UNAVAILABLE.

Returns conference : Specifies the interface reference and sessionID of the created conference.

Parameters

appConferenceCall : in IpAppConfCallRef

Specifies the callback interface for the conference created.

numberOfSubConferences : in TpInt32

Specifies the number of subconferences that the user wants to create automatically. The references to the interfaces of the subconferences can later be requested with getSubConferences.

The number of subconferences should be at least 1.

conferencePolicy : in TpConfPolicy

Specifies the policy to be applied for the conference, e.g. are parties allowed to join (call into) the conference?

Note that if parties are allowed to join the conference, the application can expect partyJoined() messages on the IpAppConfCall interface.

numberOfParticipants : in TpInt32

Specifies the number of participants in the conference. The actual number of participants may exceed this, but these resources are not guaranteed, i.e. anything exceeding this will be best effort only and the conference service may drop or reject participants in order to fulfil other committed resource requests. By specifying 0, the application can request a best effort conference.

duration : in TpDuration

Specifies the duration for which the conference resources are reserved. The duration of the conference may exceed this, but after the duration, the resources are no longer guaranteed, i.e. parties may be dropped or rejected by the service in order to satisfy other committed resource requests. When the conference is released before the allocated duration, the reserved resources are released and can be used to satisfy other resource requests. By specifying 0, the application requests a best effort conference.

Returns

TpConfCallIdentifier

Raises

TpCommonExceptions

6.1.2 Method checkResources()

This method is used to check for the availability of conference resources.

The input is the search period (start and stop time and date) – mandatory.

Furthermore, a conference duration and number of participants can be specified – optional.

The search algorithm will search the specified period for availability of conference resources and tries to find an optimal solution.

When a match is found the actual number of available resources, the actual start and the actual duration for which these are available is returned. These values can exceed the requested values.

When no match is found a best effort is returned, still the actual start time, duration, number of resources are returned, but these values now indicate the best that the conference bridge can offer, e.g. one or more of these values will not reach the requested values.

Returns result : Specifies the result of the search. It indicates if a match was found. If no exact match was found the best attempt is returned.

Parameters

searchCriteria : in TpConfSearchCriteria

Specifies the boundary conditions of the search. E.g. the time period that should be searched, the number of participants.

Returns

TpConfSearchResult

Raises

TpCommonExceptions

6.1.3 Method reserveResources()

This method is used to reserve conference resources for a given time period. Conferences can be created without first reserving resources, but in that case no guarantees can be made.

Returns resourceReservation : Specifies a structured data type which contains two fields:

ResourceID: The address with which the conference can be addressed, both in the methods of the interface and in the network, i.e. if joinAllowed is TRUE, parties can use this address to join the conference.

If no match is found the ResourceID contains an empty address.

ReservationID: Specifies the reservation made. It should be unique in a particular resource.

Parameters

appInterface : in IpAppConfCallControlManagerRef

Specifies the callback interface to be used when the conference is created in the network. The application will receive the conferenceCreated message when a conference is created in the network.

startTime : in TpDateAndTime

Specifies the time at which the conference resources should be reserved, i.e. the start time of the conference.

numberOfParticipants : in TpInt32

Specifies the number of participants in the conference. The actual number of participants may exceed this, but these resources are not guaranteed, i.e. anything exceeding this will be best effort only and the conference service may drop or reject participants in order to fulfil other committed resource requests.

duration : in TpDuration

Specifies the duration for which the conference resources are reserved. The duration of the conference may exceed this, but after the duration, the resources are no longer guaranteed, i.e. parties may be dropped or rejected by the service in order to satisfy other committed resource requests. When the conference is released before the allocated duration, the reserved resources are released and can be used to satisfy other resource requests.

conferencePolicy : in TpConfPolicy

The policy to be applied for the conference, e.g. are parties allowed to join (call into) the conference? Note that if parties are allowed to join the conference, the application can expect partyJoined() messages on the appConfCall.

Returns

TpResourceReservation

Raises

TpCommonExceptions

6.1.4 Method freeResources()

This method can be used to cancel an earlier made reservation of conference resources.

This also means that no ConferenceCreated events will be received for this conference.

Parameters

resourceReservation : in TpResourceReservation

Specifies the ResourceID and the ReservationID that were received during the reservation.

Raises

TpCommonExceptions

6.2 Interface Class IpAppConfCallControlManager

Inherits from: IpAppMultiMediaCallControlManager;

The conference call control manager application interface provides the application with additional callbacks when a conference is created by the network (based on an earlier reservation).

<<Interface>>

IpAppConfCallControlManager

conferenceCreated (conferenceCall : in TpConfCallIdentifier) : IpAppConfCallRef

6.2.1 Method conferenceCreated()

This method is called when a conference is created from an earlier resource reservation. If the application has previously explicitly passed a reference to the callback using a setCallbackWithSessionID() invocation, this parameter may be null, or if supplied must be the same as that provided during the setCallbackWithSessionID().

Returns appInterface : Specifies a reference to the application interface which implements the callback interface for the new conference.

Parameters

conferenceCall : in TpConfCallIdentifier

Specifies the reference to the conference call interface to which the notification relates and the associated sessionID.

Returns

IpAppConfCallRef

6.3 Interface Class IpConfCall

Inherits from: IpMultiMediaCall;

The conference call manages the subconferences. It also provides some convenience methods to hide the fact of multiple subconferences from the applications that do not need it. Note that the conference call always contains one subconference. The following inherited call methods apply to the conference as a whole, with the specified semantics: – setCallback; changes the callback interface reference. – release; releases the entire conference, including all the subconferences and detached legs. – deassignCall; de-assigns the complete conference. No callbacks will be received by the application, either on the conference, or on any of the contained subconferences or call legs. – getInfoReq; request information over the complete conference. The conference duration is defined as the time when the first party joined the conference until when the last party leaves the conference or the conference is released. – setChargePlan; set the chargeplan for the conference. This chargeplan will apply to all the subconferences, unless another chargeplan is explicitly overridden on the subconference. – superviseReq; supervise the duration of the complete conference. – getCallLegs; return all the call legs used within the conference. – superviseVolumeReq; supervises and sets a granted data volume for the conference. Other methods apply to the default subconference. When using multiple subconferences, it is recommended that the application calls these methods directly on the subconference since this makes it more explicit what the effect of the method is: – createAndRouteCallLegReq. – createCallLeg. This interface shall be implemented by a Conference call control SCF. As a minimum requirement, the getSubConferences(), getConferenceAddress() and createSubConference() methods shall be implemented. The minimum required methods from IpMultiPartyCall are also required.

<<Interface>>

IpConfCall

getSubConferences (conferenceSessionID : in TpSessionID) : TpSubConfCallIdentifierSet

createSubConference (conferenceSessionID : in TpSessionID, appSubConference : in IpAppSubConfCallRef, conferencePolicy : in TpConfPolicy) : TpSubConfCallIdentifier

leaveMonitorReq (conferenceSessionID : in TpSessionID) : void

getConferenceAddress (conferenceSessionID : in TpSessionID) : TpAddress

6.3.1 Method getSubConferences()

This method returns all the subconferences of the conference.

Returns subConferenceList : Specifies the list of all the subconferences of the conference.

Parameters

conferenceSessionID : in TpSessionID

Specifies the sessionID of the conference.

Returns

TpSubConfCallIdentifierSet

Raises

TpCommonExceptions, P_INVALID_SESSION_ID

6.3.2 Method createSubConference()

This method is used to create a new subconference. Note that one subconference is already created together with the conference.

Returns subConference : Specifies the created subconference (interface and sessionID).

Parameters

conferenceSessionID : in TpSessionID

Specifies the sessionID of the conference.

appSubConference : in IpAppSubConfCallRef

Specifies the call back interface for the created subconference.

conferencePolicy : in TpConfPolicy

Conference Policy to be used in the subconference. Optional; if undefined, the policy of the conference is used. Note that not all policy elements have to be applicable for subconferences.

Returns

TpSubConfCallIdentifier

Raises

TpCommonExceptions, P_INVALID_SESSION_ID

6.3.3 Method leaveMonitorReq()

This method is used to request a notification when a party leaves the conference.

Parameters

conferenceSessionID : in TpSessionID

Specifies the session ID of the conference.

Raises

TpCommonExceptions, P_INVALID_SESSION_ID

6.3.4 Method getConferenceAddress()

This method returns the conference address that specifies the address with which the conference can be addressed in case parties are allowed to join the conference.

Parameters

conferenceSessionID : in TpSessionID

Specifies the sessionID of the conference.

Returns

TpAddress

Raises

TpCommonExceptions, P_INVALID_SESSION_ID

6.4 Interface Class IpAppConfCall

Inherits from: IpAppMultiMediaCall;

The Conference Call application interface allows the application to handle call responses and state reports. Additionally it allows the application to handle parties entering and leaving the conference.

<<Interface>>

IpAppConfCall

partyJoined (conferenceSessionID : in TpSessionID, callLeg : in mpccs::TpCallLegIdentifier, eventInfo : in TpJoinEventInfo) : mpccs::IpAppCallLegRef

leaveMonitorRes (conferenceSessionID : in TpSessionID, callLeg : in TpSessionID) : void

6.4.1 Method partyJoined()

This asynchronous method indicates that a new party (leg) has joined the conference. This can be used in, e.g. a meetme conference where the participants dial in to the conference using the address returned during reservation of the conference.

The Leg will be assigned to the default subconference object and will be in a detached state. The application may move the call Leg to a different subconference before attaching the media.

The method will only be called when joinAllowed is indicated in the conference policy.

Returns appCallLeg : Specifies the call back interface that should be used for callbacks from the new call Leg.

Parameters

conferenceSessionID : in TpSessionID

Specifies the session ID of the conference that the party wants to join.

callLeg : in mpccs::TpCallLegIdentifier

Specifies the interface and sessionID of the call leg that joined the conference.

eventInfo : in TpJoinEventInfo

Specifies the address information of the party that wants to join the conference.

Returns

mpccs::IpAppCallLegRef

6.4.2 Method leaveMonitorRes()

This asynchronous method indicates that a party (leg) has left the conference.

Parameters

conferenceSessionID : in TpSessionID

Specifies the session ID of the conference that the party wants to leaves.

callLeg : in TpSessionID

Specifies the sessionID of the call leg that left the conference.

6.5 Interface Class IpSubConfCall

Inherits from: IpMultiMediaCall;

The subconference is an additional grouping mechanism within a conference. Parties (legs) that are in the same subconference have a speech connection with each other. The following inherited call methods apply to the subconference as a whole, with the specified semantics: – setCallback; changes the callback interface reference. – release; releases the subconference, including all currently attached legs. When the last subconference in the conference is released, the conference is implicitly released as well. – deassignCall; de-assigns the subconference. No callbacks will be received by the application on this subconference, nor will the gateway accept any methods on this subconference or accept any methods using the subconference as a parameter (e.g., merge). When the subconference is the last subconference in the conference, the conference is deassigned as well. In general it is recommended to only use deassignCall for the complete conference. – getInfoReq; request information over the subconference. The subconference duration is defined as the time when the first party joined the subconference until when the last party leaves the subconference or the subconference is released. – setChargePlan; set the charge plan for the subconference. – superviseReq; supervise the duration of the subconference. It is recommended that this method is only used on the complete conference. – superviseVolumeReq; supervises and sets a granted data volume for the subconference. – getCallLegs; return all the call legs in the subconference. – createCallLeg; create a call leg. – createAndRouteCallLegReq; implicitly create a leg and route the leg to the specified destination. This interface shall be implemented by a Conference call control SCF. As a minimum requirement, either the moveCallLeg() method shall be implemented, or the splitSubConference() and mergeSubConference() methods shall be implemented. The minimum required methods from IpMultiPartyCall are also required.

<<Interface>>

IpSubConfCall

splitSubConference (subConferenceSessionID : in TpSessionID, callLegList : in TpSessionIDSet, appSubConferenceCall : in IpAppSubConfCallRef) : TpSubConfCallIdentifier

mergeSubConference (subConferenceCallSessionID : in TpSessionID, targetSubConferenceCall : in TpSessionID) : void

moveCallLeg (subConferenceCallSessionID : in TpSessionID, targetSubConferenceCall : in TpSessionID, callLeg : in TpSessionID) : void

inspectVideo (subConferenceSessionID : in TpSessionID, inspectedCallLeg : in TpSessionID) : void

inspectVideoCancel (subConferenceSessionID : in TpSessionID) : void

appointSpeaker (subConferenceSessionID : in TpSessionID, speakerCallLeg : in TpSessionID) : void

chairSelection (subConferenceSessionID : in TpSessionID, chairCallLeg : in TpSessionID) : void

changeConferencePolicy (subConferenceSessionID : in TpSessionID, conferencePolicy : in TpConfPolicy) : void

6.5.1 Method splitSubConference()

This method is used to create a new subconference and move some of the legs to it.

Returns newSubConferenceCall : Specifies the new subconference that is implicitly created as a result of the method.

Parameters

subConferenceSessionID : in TpSessionID

Specifies the session ID of the subconference.

callLegList : in TpSessionIDSet

Specifies the sessionIDs of the legs that will be moved to the new subconference.

appSubConferenceCall : in IpAppSubConfCallRef

Specifies the application call back interface for the new subconference.

Returns

TpSubConfCallIdentifier

Raises

TpCommonExceptions, P_INVALID_SESSION_ID

6.5.2 Method mergeSubConference()

This method is used to merge two subconferences, i.e. move all our legs from this subconference to the other subconference followed by a release of this subconference.

Parameters

subConferenceCallSessionID : in TpSessionID

Specifies the session ID of the subconference.

targetSubConferenceCall : in TpSessionID

The session ID of target subconference with which the current subconference will be merged.

Raises

TpCommonExceptions, P_INVALID_SESSION_ID

6.5.3 Method moveCallLeg()

This method moves one leg from this subconference to another subconference.

Parameters

subConferenceCallSessionID : in TpSessionID

Specifies the session ID of the source subconference.

targetSubConferenceCall : in TpSessionID

Specifies the sessionID of the target subconference.

callLeg : in TpSessionID

Specifies the sessionID of the call leg to be moved.

Raises

TpCommonExceptions, P_INVALID_SESSION_ID

6.5.4 Method inspectVideo()

This method can be used by the application to select which video should be sent to the party that is currently selected as the chair.

Whether this method can be used depends on the selected conference policy.

Parameters

subConferenceSessionID : in TpSessionID

Specifies the session ID of the multi media subconference.

inspectedCallLeg : in TpSessionID

Specifies the sessionID of call leg of the party whose video stream should be sent to the chair.

Raises

TpCommonExceptions, P_INVALID_SESSION_ID

6.5.5 Method inspectVideoCancel()

This method cancels a previous inspectVideo. The chair will receive the broadcasted video.

Whether this method can be used depends on the selected conference policy.

Parameters

subConferenceSessionID : in TpSessionID

Specifies the session ID of the multi media subconference.

Raises

TpCommonExceptions, P_INVALID_SESSION_ID

6.5.6 Method appointSpeaker()

This method indicates which of the participants in the conference has the floor. The video of the speaker will be broadcast to the other parties.

Whether this method can be used depends on the selected conference policy.

Parameters

subConferenceSessionID : in TpSessionID

Specifies the session ID of the multi media subconference.

speakerCallLeg : in TpSessionID

Specifies the sessionID of the call leg of the party whose video stream should be broadcast.

Raises

TpCommonExceptions, P_INVALID_SESSION_ID

6.5.7 Method chairSelection()

This method is used to indicate which participant in the conference is the chair. E.g. the terminal of this participant will be the destination of the video of the inspectVideo method.

Whether this method can be used depends on the selected conference policy.

Parameters

subConferenceSessionID : in TpSessionID

Specifies the session ID of the multi media subconference.

chairCallLeg : in TpSessionID

Specifies the sessionID of the call leg of the party that will become the chair.

Raises

TpCommonExceptions, P_INVALID_SESSION_ID

6.5.8 Method changeConferencePolicy()

This method can be used to change the conference policy in an ongoing conference.

Multi media conference policy options available. E.g.:

– chair controlled video / voice switched video;

– closed conference / open conference;

– Composite video (different types) / only speaker.

Parameters

subConferenceSessionID : in TpSessionID

Specifies the session ID of the multi media subconference.

conferencePolicy : in TpConfPolicy

New Conference Policy to be used in the subconference.

Raises

TpCommonExceptions, P_INVALID_SESSION_ID

6.6 Interface Class IpAppSubConfCall

Inherits from: IpAppMultiMediaCall;

The Sub Conference Call application interface allows the application to handle call responses and state reports from a sub conference.

<<Interface>>

IpAppSubConfCall

chairSelection (subConferenceSessionID : in TpSessionID, callLegSessionID : in TpSessionID) : void

floorRequest (subConferenceSessionID : in TpSessionID, callLegSessionID : in TpSessionID) : void

6.6.1 Method chairSelection()

This method is used to inform the application about the chair selection requests from the network. The application can grant the request by calling the chairSelection method on the subconference.

Parameters

subConferenceSessionID : in TpSessionID

Specifies the session ID of the subconference where the chair request originates.

callLegSessionID : in TpSessionID

Specifies the session ID of the call leg making the chair request.

6.6.2 Method floorRequest()

This method is used to inform the application about the floor requests from the network. The application can grant the request by calling the appointSpeaker method.

Parameters

subConferenceSessionID : in TpSessionID

Specifies the session ID of the subconference where the floor request originates.

callLegSessionID : in TpSessionID

Specifies the session ID of the call leg making the floor request.