QtopiaSystemTestModem Class Reference
[QtUiTestModule]

Detailed Description

The QtopiaSystemTestModem class provides functionality for simulating modem events from within a system test.

The QtopiaSystemTestModem class encapsulates a simulated AT modem. This allows phone events to be simulated, such as an incoming call or network handover.

Note that creating or destroying a QtopiaSystemTestModem causes Qt Extended to restart, as this is the only way to change the modem used by Qtopia.

An instance of this class can be obtained using the QtopiaSystemTest::testModem() function. It is recommended to call this function in initTestCase to prevent Qt Extended restarting during a test.

See also QSystemTest.

Member Function Documentation

Boolean QtopiaSystemTestModem::activateWillFail () const

Returns the activate request failure setting from the phone simulator.

Example:

    // Retrieve the ACTIVATE failure status from the simulator
    testModem().setActivateWillFail(true);
    QVERIFY( testModem().activateWillFail() );         // returns 'true'

See also setActivateWillFail().

void QtopiaSystemTestModem::destroy ()

Deletes the test modem and restarts Qtopia.

void QtopiaSystemTestModem::expectCommand ( String key, String command )

Adds an expected AT command to the list. Set before the action prompting the command takes place. key is a reference to the command item, can be an arbitrary string. command is the expected command text.

Example:

    // Test enabling Voice Call Waiting feature sends the correct AT command
    testModem().expectCommand("enable_voice", "AT+CCWA=1,1,1");
    // Enable Voice CF checkbox
    keyClick( Qt.Key_Select );
    QVERIFY( testModem().waitCommand("enable_voice", 5000) );

See also waitCommand(), expectResponse(), and waitResponse().

void QtopiaSystemTestModem::expectResponse ( String key, String response )

Adds an expected AT response to the list. Set before the action prompting the response takes place. key is a reference to the response, can be an arbitrary string. response is the expected response text.

Example:

    // Test enabling Voice Call Waiting receives the expected modem response
    testModem().expectResponse("enable_voice", "+CCWA=1,1");
    // Enable Voice CF checkbox
    keyClick( Qt.Key_Select );
    QVERIFY( testModem().waitResponse("enable_voice", 5000) );

See also waitResponse(), expectCommand(), and waitCommand().

String QtopiaSystemTestModem::getVariable ( String name ) const

Returns the value of a specified phone simulator variable. name is the name of the variable to obtain the value from.

Example:

    // Change operator name from within a system test, verify the result
    testModem().setVariable("OP", "Qt Extended Comms");
    var op = testModem().getVariable("OP");   // Returns "Qt Extended Comms"

See also send() and setVariable().

void QtopiaSystemTestModem::hangupAll ()

Prompts the modem to 'remotely' end all calls, simulating a hang up event from all callers.

Example:

    // Simulate a universal remote hangup event
    testModem().startIncomingCall(12345);  // Initiate an incoming call
    keyClick( Qt.Key_Call );
    testModem().startIncomingCall(67890);  // Initiate an second incoming call
    keyClick( Qt.Key_Call );
    testModem().hangupAll();               // All calls are ended

See also hangupConnected(), hangupHeld(), hangupConnectedAndHeld(), and hangupCall().

void QtopiaSystemTestModem::hangupCall ( Number id )

Prompts the modem to 'remotely' end a specified call, simulating a hang up event from the specified caller. id is the 'call id' of the target call item, where activated calls in a call manager begin at '1' and are incremented on each activated call. Example:

    // Simulate a remote hangup event from a specified caller
    testModem().startIncomingCall(12345);  // Initiate an incoming call (Call 1)
    keyClick( Qt.Key_Call );
    testModem().startIncomingCall(67890);  // Initiate an second incoming call (Call 2)
    keyClick( Qt.Key_Call );
    testModem().hangupCall(1);             // Call 1 is ended

See also hangupAll(), hangupConnected(), hangupHeld(), and hangupConnectedAndHeld().

void QtopiaSystemTestModem::hangupConnected ()

Prompts the modem to 'remotely' end all active calls, simulating a hang up event from the active callers.

Example:

    // Simulate an active calls remote hangup event
    testModem().startIncomingCall(12345);  // Initiate an incoming call (call 1)
    keyClick( Qt.Key_Call );
    testModem().startIncomingCall(67890);  // Initiate an second incoming call (call 2)
    testModem().hangupConnected();         // Only call 1 is ended

See also hangupAll(), hangupHeld(), hangupConnectedAndHeld(), and hangupCall().

void QtopiaSystemTestModem::hangupConnectedAndHeld ()

Prompts the modem to 'remotely' end all active and held calls, simulating a hang up event from all callers active and on hold.

Example:

    // Simulate an active and held calls remote hangup event
    testModem().startIncomingCall(12345);  // Initiate an incoming call (call 1)
    keyClick( Qt.Key_Call );
    testModem().startIncomingCall(67890);  // Initiate an second incoming call (call 2)
    keyClick( Qt.Key_Call );                // Call 2 is active, Call 1 is placed on hold
    testModem().startIncomingCall(54321);  // Initiate an incoming call (call 3)
    testModem().hangupConnectedAndHeld();  // Calls 1 and 2 are ended, Call 3 is still waiting

See also hangupAll(), hangupConnected(), hangupHeld(), and hangupCall().

void QtopiaSystemTestModem::hangupHeld ()

Prompts the modem to 'remotely' end all held calls, simulating a hang up event from all callers on hold.

Example:

    // Simulate a held calls remote hangup event
    testModem().startIncomingCall(12345);  // Initiate an incoming call (call 1)
    keyClick( Qt.Key_Call );
    testModem().startIncomingCall(67890);  // Initiate an second incoming call (call 2)
    keyClick( Qt.Key_Call );                // Call 2 is active, Call 1 is placed on hold
    testModem().hangupHeld();              // Call 1 is ended

See also hangupAll(), hangupConnected(), hangupConnectedAndHeld(), and hangupCall().

Boolean QtopiaSystemTestModem::holdWillFail () const

Returns the hold request failure setting from the phone simulator.

Example:

    // Retrieve the HOLD failure status from the simulator
    testModem().setHoldWillFail(true);
    QVERIFY( testModem().holdWillFail() );

See also setHoldWillFail().

void QtopiaSystemTestModem::incomingSMS ( const Number type, String sender, String serviceCenter, String text )

Initiates an incoming short message. type indicates the message class (0 - 3) sender is the phone number of the sending party serviceCenter is the SMS forwarding service text is the short message text.

Example:

    // Initiate an incoming SMS
    expectMessageBox( "New Message", "Do you wish to view", "Yes", 5000 ){
        testModem().incomingSMS( "12345", "67090", "Hello" );
    }

void QtopiaSystemTestModem::installToolkitApp ( SimApplication app )

Installs app as the SIM toolkit application in the simulated modem. If app is null, return to the default SIM toolkit application.

The previous SIM toolkit application will be deleted if it is not the default.

Boolean QtopiaSystemTestModem::joinWillFail () const

Returns the join request failure setting from the phone simulator.

Example:

    // Retrieve the JOIN failure status from the simulator
    testModem().setJoinWillFail(true);
    QVERIFY( testModem().joinWillFail() );             // returns 'true'

See also setJoinWillFail().

Number QtopiaSystemTestModem::multipartyLimit () const

Returns the maximum number of concurrent parties currently allowed in the test modem.

Example:

    // Retrieve the maximum number of allowed participants in a multiparty call
    testModem().setMultipartyLimit(5);
    var lim = testModem().multipartyLimit();         // returns 5

See also setMultipartyLimit().

void QtopiaSystemTestModem::resetPersistentVariables ()

Forget all persistent values set through setVariable(). The next time Qt Extended is restarted, all variables which were previously persistent will be set to their default values.

void QtopiaSystemTestModem::send ( String string )

Make the simulated modem emit arbitrary unsolicited data. string is the string emitted by the modem.

Example:

    // Change operator name from within a system test
    testModem().setVariable("OP", "Qt Extended Comms");
    testModem().send("+CREG: 5");

void QtopiaSystemTestModem::setActivateWillFail ( Boolean value )

Enables a simulated failure response on ACTIVATE requests eg. alternate between an active and held call. value is the desired setting.

Example:

    // Simulate a failed ACTIVATE request within a system test
    testModem().setActivateWillFail(true); // Activate failures enabled
    testModem().startIncomingCall(12345);  // Initiate an incoming call
    keyClick( Qt.Key_Call );
    testModem().startIncomingCall(67890);  // Initiate an second incoming call
    keyClick( Qt.Key_Call ) );
    selectContext( "Swap" );       // Request ACTIVATE on held call, modem will respond with "ERROR"

See also activateWillFail().

void QtopiaSystemTestModem::setHoldWillFail ( Boolean value )

Enables a simulated failure response on HOLD requests. value is the desired setting.

Example:

    // Simulate a failed HOLD request within a system test
    testModem().setHoldWillFail(true);     // Hold failures enabled
    testModem().startIncomingCall(12345);  // Initiate an incoming call
    keyClick( Qt.Key_Call );
    selectContext("Hold");                  // Modem will respond with "ERROR"

See also holdWillFail().

void QtopiaSystemTestModem::setJoinWillFail ( Boolean value )

Enables a simulated failure response on JOIN requests ie. creating a multiparty call. value is the desired setting.

Example:

    // Simulate a failed JOIN request within a system test
    testModem().setJoinWillFail(true);     // Join failures enabled
    testModem().startIncomingCall(12345);  // Initiate an incoming call
    keyClick( Qt::Key_Call );
    testModem().startIncomingCall(67890);  // Initiate an second incoming call
    keyClick( Qt::Key_Call );
    selectContext( "Join" );       // Request JOIN on calls, modem will respond with "ERROR"

See also joinWillFail().

void QtopiaSystemTestModem::setMultipartyLimit ( Number value )

Sets the maximum number of concurrent parties in the test modem. value is the target maximum number of parties.

Example:

    // Sets the maximum number of participants in a multiparty call
    testModem().setMultipartyLimit(2);     // Set maximum participants to '2'
    testModem().startIncomingCall(12345);  // Initiate an incoming call (Call 1)
    keyClick( Qt.Key_Call );
    testModem().startIncomingCall(67890);  // Initiate an second incoming call (Call 2)
    keyClick( Qt.Key_Call );
    selectContext( "Join" );
    testModem().startIncomingCall(54321);  // Initiate an incoming call (Call 3)
    keyClick( Qt.Key_Call );
    selectContext( "Join" );                  // Maximum participants reached, join will fail

See also multipartyLimit().

void QtopiaSystemTestModem::setVariable ( String name, String value, Boolean persistent = false )

Change the value of a specified phone simulator variable. name is the name of the variable to change, value is the new value of the variable. If persistent is true, the value of the variable will be retained when Qt Extended is restarted. Otherwise the variable will be reset to its default value.

Example:

    // Change operator name from within a system test
    testModem().setVariable("OP", "Qt Extended Comms");
    testModem().send("+CREG: 5");

See also send() and getVariable().

void QtopiaSystemTestModem::startIncomingCall ( String number )

Initiates an incoming call. number is the phone number of the calling party (can be empty).

Example:

    // Initiate an incoming call
    testModem().startIncomingCall(12345);  // Initiate an incoming call (Call 1)
    keyClick( Qt.Key_Call );   // Call 1 now active

Boolean QtopiaSystemTestModem::waitCommand ( String key, Number timeout = 10000 )

Verifies an expected command has been sent. Will fail if not set with expectedCommand(). key is a reference to the command item as set in expectCommand(). timeout indicates time to verification failure.

Returns true if the specified command occurs within the given timeout.

Example:

    // Test enabling Voice Call Waiting feature sends the correct AT command
    testModem().expectCommand("enable_voice", "AT+CCWA=1,1,1");
    // Enable Voice CF checkbox
    keyClick( Qt.Key_Select );
    QVERIFY( testModem().waitCommand("enable_voice", 5000) );

See also expectCommand(), expectResponse(), and waitResponse().

Boolean QtopiaSystemTestModem::waitResponse ( String key, Number timeout = 10000 )

Verifies an expected response has been received. Will fail if not set with expectedResponse(). key is a reference to the response item as set in expectResponse(). timeout indicates time to verification failure.

Returns true if the specified response is received within the given timeout.

Example:

    // Test enabling Voice Call Waiting feature prompts the correct AT response
    testModem().expectResponse("enable_voice", "+CCWA=1,1");
    // Enable Voice CF checkbox
    keyClick( Qt.Key_Select );
    QVERIFY( testModem().waitResponse("enable_voice", 5000) );

See also expectResponse(), expectCommand(), and waitCommand().