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.
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 &) |
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 |
RMobileConferenceCall | ( | const RMobileConferenceCall & | ) | [private] |
const RMobileConferenceCall & |
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.
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. |
IMPORT_C void | ConstructL | ( | ) | [protected] |
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.
TRequestStatus & aReqStatus | On return, KErrNone if successful, a system wide error code if not. |
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.
TInt & aCount | On return, the number of calls - will be equal to 0 or >=2. |
IMPORT_C TInt | GetCaps | ( | TUint32 & | aCaps | ) | const |
Gets the current capabilities of the conference call.
TUint32 & aCaps | On completion, a descriptor that will contain the conference call capabilities; this consists of the sum of the TMobileConferenceCallCaps constants. |
IMPORT_C TInt | GetConferenceStatus | ( | TMobileConferenceStatus & | aStatus | ) | const |
Allows clients to retrieve the current status of the conference call.
TMobileConferenceStatus & aStatus | On completion, the new conference status. |
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.
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.
TRequestStatus & aReqStatus | On return, KErrNone if successful, a system wide error code if not. |
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.
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. |
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.
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. |
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.
TRequestStatus & aReqStatus | On return, KErrNone if successful, a system wide error code if not. |
TMobileConferenceStatus & aStatus | On return, the conference status. |
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.
RMobilePhone & aPhone | The phone sub-session used to open the conference call. |
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.
TRequestStatus & aReqStatus | On return, KErrNone if successful, a system wide error code if not. |
Conference call capabilities.
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). |
Conference events.
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. |
Conference call status.
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. |
CMobileConferenceCallPtrHolder * | iMmPtrHolder | [private] |
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.