|
Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions | |
The QPhoneCall class provides an interface for managing individual incoming and outgoing phone calls. More...
#include <QPhoneCall>
The QPhoneCall class provides an interface for managing individual incoming and outgoing phone calls.
QPhoneCall is the primary interface for managing a phone call that is in progress. Outgoing calls are created in client applications by a call to QPhoneCallManager::create(), and incoming calls are advertised to client applications via the QPhoneCallManager::newCall() signal, with the phone call's state set to Incoming.
Client applications can see all of the calls in the system, even those created by other client applications. The QPhoneCallManager::calls() method provides access to the complete call list, and the QPhoneCallManager::newCall() signal can be used to receive notification of when another client application creates a call.
QPhoneCall instances act as identifiers for the actual call objects. The actual call object will persist until the call ends, either due to explicit hangup(), remote disconnection, or some form of network failure.
Outgoing phone calls are created by QPhoneCallManager::create() and start in the Idle state. They then transition to the Dialing state when the dial() method is called. The following example demonstrates how to dial a voice call to the phone number 1234567:
QPhoneCallManager mgr;
QPhoneCall call = mgr.create( "Voice" );
QDialOptions dialOptions;
dialOptions.setNumber( "1234567" );
call.dial( dialOptions );
Once an outgoing call enters the Dialing state, it may transition to one of the following states, as reported by state():
| Alerting | The network is alerting the other party that they have an incoming call. Not all networks support alerting, so an outgoing call may never enter this state. For most client applications, Alerting can be considered identical to Dialing. |
| Connected | The call was accepted by the other party and is now connected. |
| HangupLocal | This client application, or some other application, called hangup() to abort the outgoing call before it could be accepted by the other party. |
| HangupRemote | The other party rejected the call, the party was busy, or it timed out without some kind of response. |
| OtherFailure | The dial attempt could not start because of a local problem; usually because there is another call already dialing, or there are insufficient resources to complete the request. |
| ServiceHangup | The dial attempt was for a supplementary service number starting with * or #. The request has been sent, but there is no actual call from this point onwards. While supplementary service requests can be sent with dial(), it is better to use QSupplementaryServices::sendSupplementaryServiceData() as it has better error reporting for failed supplementary service requests. |
Changes in state() are advertised to client applications with the stateChanged() signal. The client application must use connectStateChanged() to connect to this signal.
Once connected, the call can be terminated locally with hangup(), put on hold with hold(), released from hold or split from a multi-party conversation with activate(), joined with another call for a multi-party conversation with join(), and sent DTMF tones with tone().
Voice-Over-IP calls are initiated in a similar manner to GSM voice calls:
QPhoneCallManager mgr;
QPhoneCall call = mgr.create( "VoIP" );
QDialOptions dialOptions;
dialOptions.setNumber( "sip:jane@random.com" );
call.dial( dialOptions );
In this case, the phone number is replaced with the URI corresponding to the called party, and the call type is set to VoIP. The system locates the relevant Voice-Over-IP telephony service and forwards the request to it. The complete list of active call types and services can be obtained from the QPhoneCallManager::callTypes() and QPhoneCallManager::services() methods.
Incoming calls are advertised to client applications via the QPhoneCallManager::newCall() signal. They can be distinguished from outgoing calls made by other client applications by checking the state() for Incoming. The number() method will return the phone number of the calling party, if caller identification is available.
An incoming call can be rejected by calling hangup(), and will transition to the HangupLocal state.
Calls in the Incoming state can be transferred to a different number with transfer(). If the call has already been accepted, then to transfer the call requires the following steps be taken:
Normally this process is performed by the dialer as part of the multi-party conversation logic in the user interface.
Once connected, the call can be terminated locally with hangup(), put on hold with hold(), released from hold or split from a multi-party conversation with activate(), joined with another call for a multi-party conversation with join(), and sent DTMF tones with tone(); just as for outgoing calls.
For a larger example that demonstrates the use of QPhoneCall for managing incoming and outgoing calls, see Making Phone Calls.
Phone call functionality is provided by back-end telephony services in their QPhoneCallProvider implementation. Each call is associated with with a QPhoneCallImpl object, whose functions mirror those in QPhoneCall.
The Qt Extended telephony API automatically routes requests from client applications to the appropriate QPhoneCallProvider, based on the callType(). State changes in the provider are routed back to client applications and appear as stateChanged() signals (use connectStateChanged() to access these signals).
See QPhoneCallProvider for more information on implementing phone call providers within telephony services.
See also QPhoneCallManager, QDialOptions, QPhoneCallProvider, and QPhoneCallImpl.
This enum lists the flags that may be returned from QPhoneCall::parseDataState()
| Constant | Value | Description |
|---|---|---|
| QPhoneCall::PPPdStarted | 0x0001 | The pppd daemon has been started. Usually combined with DataActive or DataInactive. |
| QPhoneCall::PPPdStopped | 0x0002 | The pppd daemon stopped in response to an explicit call on QPhoneCall::hangup() |
| QPhoneCall::PPPdFailed | 0x0004 | The pppd daemon stopped for some other reason. |
| QPhoneCall::DataActive | 0x0008 | A data session is currently active. |
| QPhoneCall::DataInactive | 0x0010 | No data session is currently active. |
| QPhoneCall::Connecting | 0x0020 | The pppd daemon is attempting to connect. Usually combined with PPPdStarted and DataInactive. |
| QPhoneCall::ConnectFailed | 0x0040 | The pppd daemon failed in its connection attempt. |
Defines auxiliary value notifications that may be associated with a phone call.
| Constant | Value | Description |
|---|---|---|
| QPhoneCall::CallingName | 0 | The name of the calling party. |
| QPhoneCall::DataStateUpdate | 1 | Notification that is sent when the GPRS data state changes. Use QPhoneCall::parseDataState() to decode this value. |
| QPhoneCall::RemoteHold | 2 | Notification that is sent when the remote party requests that the call be held or unheld. This is used with VoIP implementations where either party can place a call on hold. This notification may have one of the values hold or unhold indicating whether the remote party is requesting a hold or an unhold. |
| QPhoneCall::ConnectedLineId | 3 | Full phone number of the other party, according to the connected line identification presentation (COLP) service. This notification may be emitted on outgoing calls where COLP is available. May be an empty string if the COLP service is available but the other party is blocking the provision of their phone number. |
Defines the request types, for reporting failures.
| Constant | Value | Description |
|---|---|---|
| QPhoneCall::HoldFailed | 0 | A call to QPhoneCall::hold() failed and the call could not be put on hold. |
| QPhoneCall::JoinFailed | 1 | A call to QPhoneCall::join() failed and the specified calls could not be joined. |
| QPhoneCall::TransferFailed | 2 | A call to QPhoneCall::transfer() failed and the call was not transferred. |
| QPhoneCall::ActivateFailed | 3 | A call to QPhoneCall::activate() failed and the call was not activated. |
Defines the scope of a QPhoneCall::hangup() or QPhoneCall::activate() operation.
| Constant | Value | Description |
|---|---|---|
| QPhoneCall::CallOnly | 0 | Only the referenced call. |
| QPhoneCall::Group | 1 | All calls in the same active/held group. |
This enum defines the different states a QPhoneCall can have. For discussion on the state transitions see the class overview.
| Constant | Value | Description |
|---|---|---|
| QPhoneCall::Idle | 0 | New outgoing call, not dialed yet. |
| QPhoneCall::Incoming | 1 | Incoming connection from remote party. |
| QPhoneCall::Dialing | 2 | Dialing, but not yet connected. |
| QPhoneCall::Alerting | 3 | Alerting other party during outgoing dial. This state will appear between Dialing and Connected only if the network and call type supports alerting notifications. |
| QPhoneCall::Connected | 4 | Connected to the other party, but currently not on hold. |
| QPhoneCall::Hold | 5 | Connected to the other party, but currently on hold. |
| QPhoneCall::HangupLocal | 6 | Local side hung up the call. |
| QPhoneCall::HangupRemote | 7 | Remote side hung up the call, or call lost. |
| QPhoneCall::Missed | 8 | Incoming call that was missed. |
| QPhoneCall::NetworkFailure | 9 | Network has failed in some way. |
| QPhoneCall::OtherFailure | 10 | Unknown failure. |
| QPhoneCall::ServiceHangup | 11 | Supplementary service request caused the call to "hangup", notifying higher layers that the request has been sent. |
Constructs a new phone call object, initially in the Idle state.
Constructs a copy of call.
Destroys this phone call object. This will not destroy or hangup the actual underlying phone call, which will persist until hung up by the user or some other action.
Accepts an incoming call. All active calls are automatically put on hold. Note that this object must be in the Incoming state for this to succeed. If the call is not currently in the Incoming state, the request is ignored.
To reject an incoming call, use hangup().
See also canAccept(), dial(), and hangup().
Activates this call and takes it off hold. The scope indicates whether the activation relates to this call only (CallOnly), or the entire call group (Group).
See also hold() and canActivate().
Returns the type of call (Voice, Data, etc).
See also QPhoneCallManager::callTypes().
Returns true if the accept() action is valid in the call's current state.
See also accept().
Returns true if the activate() action is valid in the call's current state and for the specified scope.
See also activate().
Returns true if the hold() action is valid in the call's current state.
See also hold().
Returns true if the join() action is valid in the call's current state and for the specified detachSubscriber state.
See also join().
Returns true if DTMF tones can be sent with tone() in the call's current state.
See also tone().
Returns true if the transfer() action is valid in the call's current state.
See also transfer().
Registers a specified slot on object to receive notification of changes in the floor. The signal prototype is "floorChanged( const QPhoneCall& call )".
See also floorAvailable().
Registers the specified slot on object to receive notification of auxiliary values that are associated with a call. The signal prototype is notification( const QPhoneCall& call, QPhoneCall::Notification type, const QString& value ).
See also QPhoneCall::Notification and disconnectNotification().
Registers a specified slot on object to receive notification of pending tone changes. The signal prototype is pendingTonesChanged( const QPhoneCall& call ).
See also pendingTones().
Registers a specified slot on object to receive notification of QPhoneCall::Request request failures. The signal prototype is requestFailed( const QPhoneCall& call, QPhoneCall::Request request ).
See also join(), transfer(), and disconnectRequestFailed().
Registers a specified slot on object to receive notification of QPhoneCall::State state changes. The signal prototype is stateChanged( const QPhoneCall& call ).
More than one call may be affected by a state change in cases where an entire group of calls are hung up, put on hold, or swapped with an active call group. The connectStateChanged() method does not allow such group operations to be tracked atomically. The QPhoneCallManager::statesChanged() signal does allow atomic tracking of group operations across all calls that are active in the system.
See also state(), disconnectStateChanged(), and QPhoneCallManager::statesChanged().
Returns the date and time that this call last entered the QPhoneCall::Connected state. Returns a null QDateTime instance if the call has never connected.
See also startTime() and endTime().
Returns true if the phone call is currently in the QPhoneCall::Connected state; false otherwise.
See also state(), onHold(), and established().
Returns the unique identifier of the contact of the remote party. Returns a null QUniqueId if the remote party's unique identifier is unknown.
Returns an I/O device for accessing the raw data of a non-voice call. When a data, fax or video call is made and the state() transitions to Connected, this device can be used to read or write data during the call. The returned device will already be open in ReadWrite mode.
Returns null if the call does not support access to the raw data of the call, or the call has not connected yet.
The returned device object is guaranteed to have at least two signals: readyRead() and closed(). The readyRead() signal indicates when data is available to be read, and the closed() signal indicates that the call has ended and the device is no longer valid.
The returned device object will be deleted automatically when the phone call terminates. The caller should not delete this object.
Dials a number on this call. The QPhoneCall object must be in the Idle state.
If a contact is specified, it is used to display information on the party being called, and will be stored as part of the call history.
If sendcallerid is true, the caller ID is enabled (on the assumption that it is normally disabled).
If the call is not in the Idle state, the request will be quietly ignored.
See also hangup() and accept().
This is an overloaded member function, provided for convenience.
Dials a call according to the specified options. The QPhoneCall object must be in the Idle state.
If the call is not in the Idle state, the request will be quietly ignored.
See also QDialOptions, hangup(), and accept().
Returns true if this call was dialed, false otherwise.
See also hasBeenConnected().
Returns true if the phone call is currently in the QPhoneCall::Dialing or QPhoneCall::Alerting states; false otherwise.
See also state().
Deregisters a specified slot on object to receive notification of changes in the floor. The signal prototype is "floorChanged( const QPhoneCall& call )".
See also floorAvailable().
Deregisters the specified slot on object to receive notification of auxiliary values. The signal prototype is notification( const QPhoneCall& call, QPhoneCall::Notification type, const QString& value ).
See also QPhoneCall::Notification and connectNotification().
Deregisters a specified slot on object to receive notification of request failures. The signal prototype is requestFailed( const QPhoneCall& call, QPhoneCall::Request request ).
See also join(), transfer(), and connectRequestFailed().
Deregisters a specified slot on object to receive notification of QPhoneCall::States changes. The signal prototype is stateChanged( const QPhoneCall& call ).
See also state() and connectStateChanged().
Returns true if the phone call is currently "dropped"; false otherwise. A "dropped" phone call is no longer connected due to normal call termination, network error, etc. Use QPhoneCall::state() to determine the precise reason why the call was dropped.
See also state().
Returns the date and time this call ended. If the call never ended a null QDateTime is returned.
See also startTime() and connectTime().
Returns true if the phone call is currently in the QPhoneCall::Connected or QPhoneCall::Hold states; false otherwise.
See also state(), connected(), and onHold().
Returns true if the floor is available in a voice group call. The "floor" is available if no one else is currently talking.
If it isn't possible to detect whether or not the floor is available, even if the call type supports floors, this method will return true; however, calls to requestFloor() might not succeed.
If this call type does not support the floor, this method will return false.
Returns the full number of the remote party. This is the literal number that was dialed including affixes. Returns a null QString if the number is unknown.
See also number().
Hangs up this call and/or all other calls of its type that are active or held. The scope indicates whether the hangup relates to this call only (CallOnly), or the entire call group (Group).
Returns true if this call has been in the state QPhoneCall::Connected at some stage, otherwise false.
See also dialed().
Returns true if this object currently has the floor in a voice group call.
See also floorAvailable().
Puts this active call and all other active calls on hold. Also activates any calls that are on hold or waiting.
See also activate() and canHold().
Returns the globally-unique identifier for this call.
Returns true if the phone call is currently in the QPhoneCall::Idle state; false otherwise.
See also state().
Returns true if the phone call is currently in the QPhoneCall::Incoming state; false otherwise.
See also state() and missed().
Returns true if this QPhoneCall object is null.
Joins the active and held calls together and makes them all active. If detachSubscriber is true, the current subscriber is detached from the conversation.
Join requests may fail and cause the requestFailed() signal to be emitted.
See also connectRequestFailed() and canJoin().
Returns true if the phone call is currently in the QPhoneCall::Missed state.
See also state() and incoming().
Returns the number that the modem uses to identify the call, or -1 if the number is unknown or the call has terminated.
Modem identifiers usually range between 1 and 9. Once a call terminates, its identifier will be reused for another call.
Modem identifiers are used with AT commands like AT+CHLD to identify specific calls. They may also be used in GCF key sequences such as 1x SEND to hang up the call with modem identifier x.
See also QPhoneCallManager::fromModemIdentifier().
Returns the phone number of the remote party, or a null QString if the number is unknown.
See also fullNumber().
Returns true if the phone call is currently in the QPhoneCall::Hold state; false otherwise.
See also state(), connected(), and established().
Parses the value from a DataStateUpdate notification into a set of QPhoneCall::DataState flags.
See also connectNotification().
Returns the pending tones for this call. Pending tones are accumulated when the call is dialed with dial(), or new tones are added with tone(). As the tones are sent, they are removed from the pendingTones() list.
Use connectPendingTonesChanged() to be notified of changes in the pending tones.
See also connectPendingTonesChanged().
Releases the floor in a voice group call.
See also floorAvailable().
Requests the floor in a voice group call for secs seconds. After the timeout, the floor will be automatically released.
If secs is -1, requests the floor until explicitly released by a call to releaseFloor().
See also floorAvailable().
Returns the date and time that this call started. Usually this is the first time it enters the Dialing or Incoming state.
See also connectTime() and endTime().
Returns the state of this call.
See also connectStateChanged(), idle(), incoming(), dialing(), established(), connected(), onHold(), dropped(), and missed().
Sends a sequence of DTMF tones over the call. Ignored if the call is not connected, or it is on hold.
See also pendingTones() and canTone().
Transfers the call to a new number and then discontinues this call.
Transfer requests may fail and cause the requestFailed() signal to be emitted.
See also connectRequestFailed() and canTransfer().
Copies call object to this object.
| Copyright © 2009 Trolltech | Trademarks | Qt Extended 4.4.3 |