Detailed Description
The QAtChat class provides communication with AT-command-based modems.
QAtChat is used for sending AT commands to modems and retrieving the responses to those commands. It can be preferable to manually processing the raw binary data from a serial device.
QAtChat objects are obtained by calling QSerialIODevice::atchat() on the serial device that you wish to communicate with. The following example sends the command AT+CGMI on device. Once the command completes, the result is sent to the cgmi(bool,QAtResult) slot on the calling object:
QAtChat *atchat = device->atchat();
atchat->chat("AT+CGMI", this, SLOT(cgmi(bool,QAtResult)));
Results from an AT command are reported in two parameters. The first parameter is a simple boolean parameter that allows the slot to quickly determine if the command succeeded (true) or failed (false). The second parameter is a QAtResult object that contains detailed information about the command response, or the reason for command failure. The QAtResultParser class can be used to assist in parsing complex responses to AT commands.
QAtChat objects can also be used to receive unsolicited notifications from the modem device. The caller registers a slot with registerNotificationType() which is invoked whenever a particular unsolicited notification prefix is encountered in the device's input stream. The following example registers for unsolicited +CSSI: notifications from device:
QAtChat *atchat = device->atchat();
atchat()->registerNotificationType("+CSSI:", this, SLOT(cssi(QString)));
When the corresponding slot is invoked for an unsolicited notification, the entire notification, including the prefix, is passed to the slot as a QString parameter. The QAtResultParser class can be used to assist in parsing complex unsolicited notification strings.
See also QSerialIODevice, QAtResult, and QAtResultParser.
Member Function Documentation
void QAtChat::abortDial ()
Aborts an ATD command. Usually just sends and empty line to the modem, but some modems need to use ATH instead.
This method calls QSerialIODevice::abortDial() to perform the abort, which by default sends an empty line to the modem.
Modem-specific multiplexer plug-ins can override QSerialIODevice::abortDial() to implement alternative abort strategies. The send() method may be useful to implement such strategies.
See also send().
void QAtChat::callNotification ( const QString & type ) [signal]
This signal is emitted when a call-related notification such as CONNECT, NO CARRIER, BUSY, etc occurs, but which was not associated with a corresponding ATD command. The type parameter is the text of the notification.
void QAtChat::chat ( const QString & command )
Sends command to the underlying device. If the command fails, the caller will not be notified.
This version of chat() is useful for commands that the caller is reasonably certain will be understood by the modem, or it is not a serious problem if the command is not understood.
The following example turns on unsolicited +CRING notifications for device:
QAtChat *atchat = device->atchat();
atchat->chat("AT+CRC=1");
void QAtChat::chat ( const QString & command, QObject * target, const char * slot, QAtResult::UserData * data = 0 )
This is an overloaded member function, provided for convenience.
Sends command to the underlying device. When the command finishes, notify slot on target.
The optional data parameter can be used to pass extra user data that will be made available to the target slot in the QAtResult::userData() field.
The following example sends the command AT+CGMI on device. Once the command completes, the result is sent to the cgmi(bool,QAtResult) slot on the current object:
QAtChat *atchat = device->atchat();
atchat->chat("AT+CGMI", this, SLOT(cgmi(bool,QAtResult)));
Results from an AT command are reported to slot in two parameters. The first parameter is a simple boolean parameter that allows the slot to quickly determine if the command succeeded (true) or failed (false). The second parameter is a QAtResult object that contains detailed information about the command response, or the reason for command failure. The QAtResultParser class can be used to assist in parsing complex responses to AT commands.
See also QAtResult and QAtResultParser.
void QAtChat::chatPDU ( const QString & command, const QByteArray & pdu, QObject * target, const char * slot, QAtResult::UserData * data = 0 )
Sends command to the underlying device, followed by pdu on the next line. When the command finishes, notify slot on target.
The pdu will be transmitted in hexadecimal, followed by a CTRL-Z.
The optional data parameter can be used to pass extra user data that will be made available to the target slot in the QAtResult::userData() field.
The chatPDU() command is intended for AT commands such as AT+CMGS which need additional information in the form of a binary PDU.
See also chat().
void QAtChat::dead () [signal]
This signal is emitted when the link is detected to be dead.
See also deadTimeout() and setDeadTimeout().
int QAtChat::deadTimeout () const
Returns the current link dead detection timeout in milliseconds. If this object sends a command to the link and it does not receive a response within the specified time, it will emit the dead() signal. If the value is -1 (the default), the link dead detection timeout will be disabled.
When the link dead detection timeout expires, all pending commands will fail with QAtResult::Dead as the result code.
See also setDeadTimeout() and dead().
void QAtChat::pduNotification ( const QString & type, const QByteArray & pdu ) [signal]
This signal is emitted when a PDU notification such as +CMT, +CDS, or +CBM arrives. The type parameter contains the type and PDU length (e.g. +CBM: 88), and the pdu parameter contains the binary data for the PDU.
void QAtChat::registerErrorPrefix ( const QString & type )
Registers type as a prefix for error strings. Any line of data from the modem that starts with type will be recorded as a synonym for ERROR. This is to support modems that have non-standard error strings.
This function was introduced in Qtopia 4.2.1
void QAtChat::registerNotificationType ( const QString & type, QObject * target, const char * slot, bool mayBeCommand = false )
Registers type as an unsolicited notification on this object. Whenever a line is received from the modem that starts with type, the indicated slot on target will be called. The slot has the signature notification(const QString&). The entire notification, including the type prefix, will be passed to the slot.
If mayBeCommand is true, then the notification type may sometimes appear as a command result. When it does, the command's completion slot should be called, not the unsolicited notification slot. An example is +CREG:, which can appear in response to an AT+CREG command, or as an unsolicited notification.
The following example registers for unsolicited +CSSI: notifications from device:
QAtChat *atchat = device->atchat();
atchat()->registerNotificationType("+CSSI:", this, SLOT(cssi(QString)));
When the cssi() slot is invoked for the +CSSI: unsolicited notification, the entire notification, including the prefix, is passed to the slot as a QString parameter. The QAtResultParser class can be used to assist in parsing complex unsolicited notification strings.
See also QAtResultParser.
void QAtChat::registerWakeupCommand ( const QString & cmd, int wakeupTime )
Registers cmd as a command to be sent to wake up the modem if no commands have been sent in the last wakeupTime milliseconds.
This function was introduced in Qtopia 4.3.1.
void QAtChat::requestNextLine ( QObject * target, const char * slot )
Requests that the next line from the modem be delivered to slot on target. This is used to collect up extra lines of data on an unsolicited response. The slot takes a single QString parameter.
void QAtChat::resume ()
Resumes the AT chat process after a suspension. Any data that is currently in the buffer will be processed for unsolicited notifications.
See also suspend().
int QAtChat::retryOnNonEcho () const
Returns the retry on non-echo timeout. The default is -1.
See also setRetryOnNonEcho().
void QAtChat::send ( const QString & command )
Sends command directly to the modem without waiting for a response, and without waiting for any existing commands to complete. This is typically used by modem-specific multiplexer plug-ins that have overridden QSerialIODevice::abortDial() to send ATH or some other command that is different from the default abortDial() behavior.
See also abortDial().
void QAtChat::setCPINTerminator ()
Sets +CPIN as a terminator for the AT+CPIN? command. Needed on some modems that do not send OK.
void QAtChat::setDeadTimeout ( int msec )
Sets the link dead detection timeout to msec milliseconds. If this object sends a command to the link and it does not receive a response within the specified time, it will emit the dead() signal. If msec is -1, the link dead detection timeout will be disabled.
When the link dead detection timeout expires, all pending commands will fail with QAtResult::Dead as the result code.
See also deadTimeout() and dead().
void QAtChat::setDebugChars ( char from, char to, char notify, char unknown )
Sets the characters to use in debug output to from, to, notify, and unknown. The defaults are F, T, N, and ?. The caller may wish to use different sets on separate channels so that it is clear from the debug output which channel is being used.
void QAtChat::setRetryOnNonEcho ( int msec )
Sets the retry on non-echo timeout to msec. If msec is not -1, then if an AT command is not echoed by the modem within the time period, the command will be automatically retried. This is sometimes necessary to restart chat operations after a modem stall.
See also retryOnNonEcho().
void QAtChat::suspend ()
Suspends the AT chat process from the underlying device so that read() and write() can be used to process binary data. Call resume() to restart the AT chat process after the binary data.
See also resume().
