RMobileConferenceCall Class Reference

class RMobileConferenceCall : public RTelSubSessionBase

Provides access to conference call functionality provided by TSY.

Conference calls allow users to conduct multi-connection voice calls, for example simultaneous communication to more than one remote party. All participants within a conference call can hear and speak to each other. There is a controlling party that initiates and manages the conference.

Conference calling is possible in both GSM and CDMA mode and the actions to initiate a 3-way conference are the same in either mode. However, GSM conference calls offer more functionality and the number of remote parties is limited in CDMA mode to 2 and in GSM mode to 5.

The Multimode ETel API uses a new sub-session called RMobileConferenceCall as a model for a conference call. The conference call object will be an aggregation of all the RMobileCall objects that are part of the conference call. It will be possible for clients to manipulate both the conference call as a whole and individual calls within a conference call depending on the dynamic capabilities of each of these objects.

Please note that RMobileConferenceCall is replacing the RCallGroup abstraction used in the GSM API. This was an optimisation decision. The call group abstraction placed a large burden on a TSY to create call groups, monitor the calls in each group and trigger notification when calls were added or moved, probably even when a conference call was not ongoing. Clients will probably only open a RMobileConferenceCall when the user has decided to make a conference call and by having just one object replace three call groups it will also reduce the number of notifications that would trigger in response to conference call events. With a view to the future, without call groups there are also no longer any restrictions to the allowed types of active calls (simultaneous, separate voice and data calls are possible).

The methods within this section must be supported if the TSY supports MobileConferenceCall functional unit.

Inherits from

Public Member Functions
RMobileConferenceCall ()
IMPORT_C void AddCall ( TRequestStatus &, const TName &)
IMPORT_C void Close ()
IMPORT_C void CreateConference ( TRequestStatus &)
IMPORT_C TInt EnumerateCalls ( TInt &)
IMPORT_C TInt GetCaps ( TUint32 &)
IMPORT_C TInt GetConferenceStatus ( TMobileConferenceStatus &)
IMPORT_C TInt GetMobileCallInfo ( TInt , TDes8 &)
IMPORT_C void HangUp ( TRequestStatus &)
IMPORT_C void NotifyCapsChange ( TRequestStatus &, TUint32 &)
IMPORT_C void NotifyConferenceEvent ( TRequestStatus &, TMobileConferenceEvent &, TName &)
IMPORT_C void NotifyConferenceStatusChange ( TRequestStatus &, TMobileConferenceStatus &)
IMPORT_C TInt Open ( RMobilePhone &)
IMPORT_C void Swap ( TRequestStatus &)
Protected Member Functions
IMPORT_C void ConstructL ()
IMPORT_C void Destruct ()
Private Member Functions
RMobileConferenceCall (const RMobileConferenceCall &)
Inherited Functions
RSubSessionBase::CloseSubSession(TInt)
RSubSessionBase::CreateAutoCloseSubSession(RSessionBase &,TInt,const TIpcArgs &)
RSubSessionBase::CreateSubSession(const RSessionBase &,TInt)
RSubSessionBase::CreateSubSession(const RSessionBase &,TInt,const TIpcArgs &)
RSubSessionBase::RSubSessionBase()
RSubSessionBase::Send(TInt)const
RSubSessionBase::Send(TInt,const TIpcArgs &)const
RSubSessionBase::SendReceive(TInt)const
RSubSessionBase::SendReceive(TInt,TRequestStatus &)const
RSubSessionBase::SendReceive(TInt,const TIpcArgs &)const
RSubSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
RSubSessionBase::Session()const
RSubSessionBase::SubSessionHandle()const
RTelSubSessionBase::Blank(const TInt,TReqPriorityType)const
RTelSubSessionBase::Blank(const TInt,TRequestStatus &,TReqPriorityType)const
RTelSubSessionBase::CancelAsyncRequest(TInt)const
RTelSubSessionBase::CancelReq(const TInt,const TInt)const
RTelSubSessionBase::CancelSubSession()const
RTelSubSessionBase::Get(const TInt,TDes16 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TDes8 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TDes8 &,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes16 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes8 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes8 &,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::RTelSubSessionBase()
RTelSubSessionBase::ResetSessionHandle()
RTelSubSessionBase::SessionHandle()const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC16 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC8 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC8 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC8 &,const TDesC8 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const RFile &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC16 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC8 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC8 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC8 &,const TDesC8 &,TReqPriorityType)const
RTelSubSessionBase::SetAndGet(const TInt,TRequestStatus &,TDes8 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::SetAndGet(const TInt,TRequestStatus &,const TDesC16 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::SetAndGet(const TInt,TRequestStatus &,const TDesC8 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::SetAndGet(const TInt,TRequestStatus &,const TDesC8 &,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::SetSessionHandle(RSessionBase &)
RTelSubSessionBase::SubSessionHandle()
Public Member Enumerations
enum TMobileConferenceCallCaps { KCapsCreate  = 0x00000001, KCapsHangUp  = 0x00000002, KCapsSwap  = 0x00000004 }
enum TMobileConferenceEvent {
EConferenceCallAdded , EConferenceCallRemoved , EConferenceBuilt , EConferenceTerminated , EConferenceSwapped , EConferenceSplit
}
enum TMobileConferenceStatus { EConferenceIdle , EConferenceActive , EConferenceHold }
Inherited Enumerations
RTelSubSessionBase:TReqPriorityType
Private Attributes
CMobileConferenceCallPtrHolder * iMmPtrHolder
Inherited Attributes
RTelSubSessionBase::iPtrHolder

Constructor & Destructor Documentation

RMobileConferenceCall()

IMPORT_C RMobileConferenceCall ( )

Default constructor.

RMobileConferenceCall(const RMobileConferenceCall &)

RMobileConferenceCall ( const RMobileConferenceCall & ) [private]

Parameters

const RMobileConferenceCall &

Member Functions Documentation

AddCall(TRequestStatus &, const TName &)

IMPORT_C void AddCall ( TRequestStatus & aReqStatus,
const TName & aCallName
) const

Adds the single voice call to an existing conference call.

Only calls whose call control capabilities include KCapsJoin can be added to a conference call.

In GSM mode, this function member will complete when the TSY has received confirmation from the network that the conference call service has been successfully invoked and the call added.

In CDMA mode, only 3-way conference calls are currently possible, so after the initial conference creation it is not possible to add further calls. Therefore single calls outside of the conference will never have the KCapsJoin capability set during CDMA mode.

Use RTelSubSessionBase::CancelAsyncRequest(EMobileConferenceCallAddCall) to cancel a previously placed asynchronous AddCall() request.

capability
NetworkServices

Parameters

TRequestStatus & aReqStatus On return, KErrNone if successful, a system wide error code if not.
const TName & aCallName The call sub-session to add to the conference call.

Close()

IMPORT_C void Close ( )
Closes a RMobileConferenceCall sub-session.
capability
None

ConstructL()

IMPORT_C void ConstructL ( ) [protected]
Constructs and initializes the RMobileConferenceCall object.
capability
None

CreateConference(TRequestStatus &)

IMPORT_C void CreateConference ( TRequestStatus & aReqStatus ) const

Allows clients to create the initial 3-way conference call.

The phone must be in a state where there are two single voice calls, one on hold and the other connected or alerting the remote, called party.

The TSY will reflect the conference creation capability by setting the KCapsJoin flags of the individual calls and the KCapsCreate flag of the conference call sub-session.

In GSM mode, this function member will complete when the TSY has received confirmation from the network that the conference call service has been successfully invoked.

In CDMA mode, this function member will complete when the TSY has sent the conference create request to the network. There is no response from CDMA networks to ascertain whether the request failed or succeeded.

Use RTelSubSessionBase::CancelAsyncRequest(EMobileConferenceCallCreateConference) to cancel a previously placed asynchronous CreateConference() request.

capability
NetworkServices

Parameters

TRequestStatus & aReqStatus On return, KErrNone if successful, a system wide error code if not.

Destruct()

IMPORT_C void Destruct ( ) [protected]
C++ destructor.
capability
None

EnumerateCalls(TInt &)

IMPORT_C TInt EnumerateCalls ( TInt & aCount ) const

Gets the number of calls (i.e. call objects) that are currently part of the conference call.

This number may be zero if a conference call is not active or equal to two or more if a conference call exists.

capability
None

Parameters

TInt & aCount On return, the number of calls - will be equal to 0 or >=2.

GetCaps(TUint32 &)

IMPORT_C TInt GetCaps ( TUint32 & aCaps ) const

Gets the current capabilities of the conference call.

capability
None

Parameters

TUint32 & aCaps On completion, a descriptor that will contain the conference call capabilities; this consists of the sum of the TMobileConferenceCallCaps constants.

GetConferenceStatus(TMobileConferenceStatus &)

IMPORT_C TInt GetConferenceStatus ( TMobileConferenceStatus & aStatus ) const

Allows clients to retrieve the current status of the conference call.

capability
None

Parameters

TMobileConferenceStatus & aStatus On completion, the new conference status.

GetMobileCallInfo(TInt, TDes8 &)

IMPORT_C TInt GetMobileCallInfo ( TInt aIndex,
TDes8 & aCallInfo
) const

Gets a current snapshot of the call information associated with the call specified by the aIndex parameter.

capability
ReadDeviceData

Parameters

TInt aIndex The index of the call = 0 to aCount-1 where aCount is the returned value from EnumerateCalls()
TDes8 & aCallInfo On completion, a RMobileCall::TMobileCallInfoV1Pckg containing the large block of call information.

HangUp(TRequestStatus &)

IMPORT_C void HangUp ( TRequestStatus & aReqStatus ) const

Terminates the whole conference.

All calls that are currently part of the conference will also be terminated. Can be called by any client that has a handle on the conference call (i.e. not necessarily the client that first created the conference).

This action is possible if the conference call capabilities include the KCapsHangUp flag. In GSM mode, this function member will complete when the TSY has received confirmation from the network that the conference call has been fully released.

In CDMA mode, this function member will complete when the TSY has sent the hang-up request to the network. There is no response from CDMA networks to ascertain whether the request failed or succeeded.

After termination, the conference call will consist of zero calls and will return to the EConferenceIdle state.

Use RTelSubSessionBase::CancelAsyncRequest(EMobileConferenceCallHangUp) to cancel a previously placed asynchronous HangUp() request.

capability
NetworkServices

Parameters

TRequestStatus & aReqStatus On return, KErrNone if successful, a system wide error code if not.

NotifyCapsChange(TRequestStatus &, TUint32 &)

IMPORT_C void NotifyCapsChange ( TRequestStatus & aReqStatus,
TUint32 & aCaps
) const

Allows clients to be notified when the conference call capabilities change.

Use RTelSubSessionBase::CancelAsyncRequest(EMobileConferenceCallNotifyCapsChange) to cancel a previously placed asynchronous NotifyCapsChange() request.

capability
None

Parameters

TRequestStatus & aReqStatus On return, KErrNone if successful, a system wide error code if not.
TUint32 & aCaps On completion, a descriptor that will contain the new conference call capabilities, this consists of the sum of the TMobileConferenceCallCaps constants.

NotifyConferenceEvent(TRequestStatus &, TMobileConferenceEvent &, TName &)

IMPORT_C void NotifyConferenceEvent ( TRequestStatus & aReqStatus,
TMobileConferenceEvent & aEvent,
TName & aCallName
) const

This notification will complete when a conference call event occurs.

Use RTelSubSessionBase::CancelAsyncRequest(EMobileConferenceCallNotifyConferenceEvent) to cancel a previously placed asynchronous NotifyConferenceEvent() request.

capability
None

Parameters

TRequestStatus & aReqStatus On return, KErrNone if successful, a system wide error code if not.
TMobileConferenceEvent & aEvent On completion, contains the conference event.
TName & aCallName On completion, contains the name of the individual call, if the event is a call added or dropped from a conference.

NotifyConferenceStatusChange(TRequestStatus &, TMobileConferenceStatus &)

IMPORT_C void NotifyConferenceStatusChange ( TRequestStatus & aReqStatus,
TMobileConferenceStatus & aStatus
) const

Allows clients to be notified of a change in the status of a conference call.

The notification completes when the TSY recognizes that a conference call has changed state.

Conference calls may change state either as a result of a direct client action on the conference call sub-session (e.g. client puts the conference on hold or terminates the whole conference) or as a result of a client action on an individual call (e.g. a private communication with one call in a conference will put the rest of the conference on hold).

Use RTelSubSessionBase::CancelAsyncRequest(EMobileConferenceCallNotifyConferenceStatusChange) to cancel a previously placed asynchronous NotifyCapsChange() request.

capability
None

Parameters

TRequestStatus & aReqStatus On return, KErrNone if successful, a system wide error code if not.
TMobileConferenceStatus & aStatus On return, the conference status.

Open(RMobilePhone &)

IMPORT_C TInt Open ( RMobilePhone & aPhone )

Opens a RMobileConferenceCall conference call sub-session from RMobilePhone .

The name of the sub-session opened in the TSY will equal the string defined by the KETelConferenceCall LIT definition.

This API currently supports only one conference call object in the TSY - so this means only one conference call can be ongoing at any one time. The conference call sub-session is opened from the phone (rather than from a line) in order not to place any restrictions on the types of call that could be added to the conference. It is up to the TSY to inform clients which calls can be added to a conference by setting each call's dynamic KCapsJoin capability.

capability
None

Parameters

RMobilePhone & aPhone The phone sub-session used to open the conference call.

Swap(TRequestStatus &)

IMPORT_C void Swap ( TRequestStatus & aReqStatus ) const

Allows a client to switch a conference call between "Active" and "Hold" states.

This function member will complete either when the conference call has successfully moved to the opposite state or if the action failed due to some reason. Can be called by any client that has a handle on the conference call (i.e. not necessarily the client that first created the conference).

This action is possible under two circumstances:

There is just a conference call. This implies that there are no single calls already in the state to which the client wishes to toggle the conference call. The client will call Swap on the conference call and if it is active it will move to the held state and if it is held it will move to the active state.

There is a conference call and a single call, one currently active and one on hold. This function member therefore swaps the conference call with the single call, simultaneously placing the active one on hold and resuming the held one.

In either circumstance, the conference call capabilities will include the KCapsSwap flag. In GSM mode, this function member will complete when the TSY has received confirmation from the network that the conference call has been successfully moved to its opposite state. In CDMA mode, this function member will complete when the TSY has sent the swap request to the network. There is no response from CDMA networks to ascertain whether the request failed or succeeded.

Use RTelSubSessionBase::CancelAsyncRequest(EMobileConferenceCallSwap) to cancel a previously placed asynchronous Swap() request.

capability
NetworkServices

Parameters

TRequestStatus & aReqStatus On return, KErrNone if successful, a system wide error code if not.

Member Enumerations Documentation

Enum TMobileConferenceCallCaps

Conference call capabilities.

Enumerators

KCapsCreate = 0x00000001

Indicates that a conference call can be created.

KCapsHangUp = 0x00000002

Indicates that a conference call can be terminated.

KCapsSwap = 0x00000004

Indicates that a conference call exists and can be swapped to the opposite state (active or hold).

Enum TMobileConferenceEvent

Conference events.

Enumerators

EConferenceCallAdded

A call has been added to the conference.

EConferenceCallRemoved

A call has been removed from the conference.

EConferenceBuilt

Names of the two calls used to build the conference call returned in aCallName.

EConferenceTerminated

No name provided

EConferenceSwapped

No name provided.

EConferenceSplit

Name of the call being seperated.

Enum TMobileConferenceStatus

Conference call status.

Enumerators

EConferenceIdle

The conference call is in the idle state.

EConferenceActive

The conference call is in the active, connected state.

EConferenceHold

The conference call is in the held, connected state.

Member Data Documentation

CMobileConferenceCallPtrHolder * iMmPtrHolder

CMobileConferenceCallPtrHolder * iMmPtrHolder [private]