Viadeo Twitter Google Bookmarks ! Facebook Digg del.icio.us MySpace Yahoo MyWeb Blinklist Netvouz Reddit Simpy StumbleUpon Bookmarks Windows Live Favorites 
Logo Documentation Qt ·  Page d'accueil  ·  Toutes les classes  ·  Toutes les fonctions  ·  Vues d'ensemble  · 

QPhoneCall Class Reference
[QtTelephonyModule]

The QPhoneCall class provides an interface for managing individual incoming and outgoing phone calls. More...

    #include <QPhoneCall>

Public Types

  • enum DataState { PPPdStarted, PPPdStopped, PPPdFailed, DataActive, ..., ConnectFailed }
  • enum Notification { CallingName, DataStateUpdate, RemoteHold, ConnectedLineId }
  • enum Request { HoldFailed, JoinFailed, TransferFailed, ActivateFailed }
  • enum Scope { CallOnly, Group }
  • enum State { Idle, Incoming, Dialing, Alerting, ..., ServiceHangup }

Public Functions

Static Public Members

Detailed Description

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 calls

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():

AlertingThe 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.
ConnectedThe call was accepted by the other party and is now connected.
HangupLocalThis client application, or some other application, called hangup() to abort the outgoing call before it could be accepted by the other party.
HangupRemoteThe other party rejected the call, the party was busy, or it timed out without some kind of response.
OtherFailureThe 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.
ServiceHangupThe 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

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:

  • Create a new outgoing QPhoneCall with QPhoneCall::dial().
  • Join the two calls together with join(), passing true as the detachSubscriber parameter.

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 providers

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.

Member Type Documentation

enum QPhoneCall::DataState

This enum lists the flags that may be returned from QPhoneCall::parseDataState()

ConstantValueDescription
QPhoneCall::PPPdStarted0x0001The pppd daemon has been started. Usually combined with DataActive or DataInactive.
QPhoneCall::PPPdStopped0x0002The pppd daemon stopped in response to an explicit call on QPhoneCall::hangup()
QPhoneCall::PPPdFailed0x0004The pppd daemon stopped for some other reason.
QPhoneCall::DataActive0x0008A data session is currently active.
QPhoneCall::DataInactive0x0010No data session is currently active.
QPhoneCall::Connecting0x0020The pppd daemon is attempting to connect. Usually combined with PPPdStarted and DataInactive.
QPhoneCall::ConnectFailed0x0040The pppd daemon failed in its connection attempt.

enum QPhoneCall::Notification

Defines auxiliary value notifications that may be associated with a phone call.

ConstantValueDescription
QPhoneCall::CallingName0The name of the calling party.
QPhoneCall::DataStateUpdate1Notification that is sent when the GPRS data state changes. Use QPhoneCall::parseDataState() to decode this value.
QPhoneCall::RemoteHold2Notification 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::ConnectedLineId3Full 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.

enum QPhoneCall::Request

Defines the request types, for reporting failures.

ConstantValueDescription
QPhoneCall::HoldFailed0A call to QPhoneCall::hold() failed and the call could not be put on hold.
QPhoneCall::JoinFailed1A call to QPhoneCall::join() failed and the specified calls could not be joined.
QPhoneCall::TransferFailed2A call to QPhoneCall::transfer() failed and the call was not transferred.
QPhoneCall::ActivateFailed3A call to QPhoneCall::activate() failed and the call was not activated.

enum QPhoneCall::Scope

Defines the scope of a QPhoneCall::hangup() or QPhoneCall::activate() operation.

ConstantValueDescription
QPhoneCall::CallOnly0Only the referenced call.
QPhoneCall::Group1All calls in the same active/held group.

enum QPhoneCall::State

This enum defines the different states a QPhoneCall can have. For discussion on the state transitions see the class overview.

ConstantValueDescription
QPhoneCall::Idle0New outgoing call, not dialed yet.
QPhoneCall::Incoming1Incoming connection from remote party.
QPhoneCall::Dialing2Dialing, but not yet connected.
QPhoneCall::Alerting3Alerting other party during outgoing dial. This state will appear between Dialing and Connected only if the network and call type supports alerting notifications.
QPhoneCall::Connected4Connected to the other party, but currently not on hold.
QPhoneCall::Hold5Connected to the other party, but currently on hold.
QPhoneCall::HangupLocal6Local side hung up the call.
QPhoneCall::HangupRemote7Remote side hung up the call, or call lost.
QPhoneCall::Missed8Incoming call that was missed.
QPhoneCall::NetworkFailure9Network has failed in some way.
QPhoneCall::OtherFailure10Unknown failure.
QPhoneCall::ServiceHangup11Supplementary service request caused the call to "hangup", notifying higher layers that the request has been sent.

Member Function Documentation

QPhoneCall::QPhoneCall ()

Constructs a new phone call object, initially in the Idle state.

QPhoneCall::QPhoneCall ( const QPhoneCall & call )

Constructs a copy of call.

QPhoneCall::~QPhoneCall ()

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.

void QPhoneCall::accept ()

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().

void QPhoneCall::activate ( QPhoneCall::Scope scope = Group )

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().

QString QPhoneCall::callType () const

Returns the type of call (Voice, Data, etc).

See also QPhoneCallManager::callTypes().

bool QPhoneCall::canAccept () const

Returns true if the accept() action is valid in the call's current state.

See also accept().

bool QPhoneCall::canActivate ( QPhoneCall::Scope scope = Group ) const

Returns true if the activate() action is valid in the call's current state and for the specified scope.

See also activate().

bool QPhoneCall::canHold () const

Returns true if the hold() action is valid in the call's current state.

See also hold().

bool QPhoneCall::canJoin ( bool detachSubscriber = false ) const

Returns true if the join() action is valid in the call's current state and for the specified detachSubscriber state.

See also join().

bool QPhoneCall::canTone () const

Returns true if DTMF tones can be sent with tone() in the call's current state.

See also tone().

bool QPhoneCall::canTransfer () const

Returns true if the transfer() action is valid in the call's current state.

See also transfer().

void QPhoneCall::connectFloorChanged ( QObject * object, const char * slot ) const

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().

void QPhoneCall::connectNotification ( QObject * object, const char * slot ) const

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().

void QPhoneCall::connectPendingTonesChanged ( QObject * object, const char * slot ) const

Registers a specified slot on object to receive notification of pending tone changes. The signal prototype is pendingTonesChanged( const QPhoneCall& call ).

See also pendingTones().

void QPhoneCall::connectRequestFailed ( QObject * object, const char * slot ) const

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().

void QPhoneCall::connectStateChanged ( QObject * object, const char * slot ) const

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().

QDateTime QPhoneCall::connectTime () const

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().

bool QPhoneCall::connected () const

Returns true if the phone call is currently in the QPhoneCall::Connected state; false otherwise.

See also state(), onHold(), and established().

QUniqueId QPhoneCall::contact () const

Returns the unique identifier of the contact of the remote party. Returns a null QUniqueId if the remote party's unique identifier is unknown.

QIODevice * QPhoneCall::device () const

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.

void QPhoneCall::dial ( const QString & number, bool sendcallerid, const QUniqueId & contact = QUniqueId() )

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().

void QPhoneCall::dial ( const QDialOptions & options )

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().

bool QPhoneCall::dialed () const

Returns true if this call was dialed, false otherwise.

See also hasBeenConnected().

bool QPhoneCall::dialing () const

Returns true if the phone call is currently in the QPhoneCall::Dialing or QPhoneCall::Alerting states; false otherwise.

See also state().

void QPhoneCall::disconnectFloorChanged ( QObject * object, const char * slot ) const

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().

void QPhoneCall::disconnectNotification ( QObject * object, const char * slot ) const

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().

void QPhoneCall::disconnectRequestFailed ( QObject * object, const char * slot ) const

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().

void QPhoneCall::disconnectStateChanged ( QObject * object, const char * slot ) const

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().

bool QPhoneCall::dropped () const

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().

QDateTime QPhoneCall::endTime () const

Returns the date and time this call ended. If the call never ended a null QDateTime is returned.

See also startTime() and connectTime().

bool QPhoneCall::established () const

Returns true if the phone call is currently in the QPhoneCall::Connected or QPhoneCall::Hold states; false otherwise.

See also state(), connected(), and onHold().

bool QPhoneCall::floorAvailable () const

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.

QString QPhoneCall::fullNumber () const

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().

void QPhoneCall::hangup ( QPhoneCall::Scope scope = Group )

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).

See also dial() and accept().

bool QPhoneCall::hasBeenConnected () const

Returns true if this call has been in the state QPhoneCall::Connected at some stage, otherwise false.

See also dialed().

bool QPhoneCall::haveFloor () const

Returns true if this object currently has the floor in a voice group call.

See also floorAvailable().

void QPhoneCall::hold ()

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().

QString QPhoneCall::identifier () const

Returns the globally-unique identifier for this call.

bool QPhoneCall::idle () const

Returns true if the phone call is currently in the QPhoneCall::Idle state; false otherwise.

See also state().

bool QPhoneCall::incoming () const

Returns true if the phone call is currently in the QPhoneCall::Incoming state; false otherwise.

See also state() and missed().

bool QPhoneCall::isNull () const

Returns true if this QPhoneCall object is null.

void QPhoneCall::join ( bool detachSubscriber = false )

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().

bool QPhoneCall::missed () const

Returns true if the phone call is currently in the QPhoneCall::Missed state.

See also state() and incoming().

int QPhoneCall::modemIdentifier () const

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().

QString QPhoneCall::number () const

Returns the phone number of the remote party, or a null QString if the number is unknown.

See also fullNumber().

bool QPhoneCall::onHold () const

Returns true if the phone call is currently in the QPhoneCall::Hold state; false otherwise.

See also state(), connected(), and established().

QPhoneCall::DataState QPhoneCall::parseDataState ( const QString & value )   [static]

Parses the value from a DataStateUpdate notification into a set of QPhoneCall::DataState flags.

See also connectNotification().

QString QPhoneCall::pendingTones () const

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().

void QPhoneCall::releaseFloor ()

Releases the floor in a voice group call.

See also floorAvailable().

void QPhoneCall::requestFloor ( int secs = -1 )

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().

QDateTime QPhoneCall::startTime () const

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().

State QPhoneCall::state () const

Returns the state of this call.

See also connectStateChanged(), idle(), incoming(), dialing(), established(), connected(), onHold(), dropped(), and missed().

void QPhoneCall::tone ( const QString & tones )

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().

void QPhoneCall::transfer ( const QString & number )

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().

QPhoneCall & QPhoneCall::operator= ( const QPhoneCall & call )

Copies call object to this object.
Cette page est une traduction d'une page de la documentation de Qt, écrite par Nokia Corporation and/or its subsidiary(-ies). Les éventuels problèmes résultant d'une mauvaise traduction ne sont pas imputables à Nokia. Qt qtextended4.4
Copyright © 2012 Developpez LLC. Tous droits réservés Developpez LLC. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents et images sans l'autorisation expresse de Developpez LLC. Sinon, vous encourez selon la loi jusqu'à 3 ans de prison et jusqu'à 300 000 E de dommages et intérêts. Cette page est déposée à la SACD.
Vous avez déniché une erreur ? Un bug ? Une redirection cassée ? Ou tout autre problème, quel qu'il soit ? Ou bien vous désirez participer à ce projet de traduction ? N'hésitez pas à nous contacter ou par MP !
 
 
Developpez.com

Nous contacter

Participez

Informations légales

 
Services

Forum Qt

Blogs

Hébergement

 
Partenaires

Hébergement Web


Warning: mysql_connect() [function.mysql-connect]: [2002] Connection refused (trying to connect via tcp://developpez.net:3306) in /home/developpez/www/developpez-com/template/connexion.php on line 7

Warning: mysql_connect() [function.mysql-connect]: Connection refused in /home/developpez/www/developpez-com/template/connexion.php on line 7

Warning: mysql_fetch_object(): supplied argument is not a valid MySQL result resource in /home/developpez/www/developpez-com/template/pied.php on line 12