QSMSMessage Class Reference
[QtTelephonyModule]

Detailed Description

The QSMSMessage class specifies the contents of an SMS message.

This class is intended for use with QSMSReader and QSMSSender to process SMS messages according to 3GPP TS 03.40 and 23.040.

An incoming SMS message from QSMSReader will typically have text() and sender() set. Other fields such as destinationPort() and applicationData() may be set if the message is a WAP Push or SMS datagram message rather than plain text.

An outgoing SMS message sent via QSMSSender will need to have at least recipient() and text() set. If the message is a WAP Push or SMS datagram message rather than plain text, then destinationPort() and applicationData() should also be set.

Special header fields in SMS messages can be accessed with serviceCenter(), replyRequest(), statusReportRequested(), validityPeriod(), timestamp(), dataCodingScheme(), and protocol().

Member Type Documentation

enum QSMSMessage::MessageType

Defines the type of an SMS message.

Member Function Documentation

QSMSMessage::QSMSMessage ()

Constructs an empty QSMSMessage.

QSMSMessage::QSMSMessage ( const QSMSMessage & msg )

Constructs an QSMSMessage that is a copy of msg.

QSMSMessage::~QSMSMessage ()

Destructs the QSMSMessage.

void QSMSMessage::addPart ( const QSMSMessagePart & part )

Add a new body part to this SMS message.

See also clearParts(), addParts(), and parts().

void QSMSMessage::addParts ( const QList<QSMSMessagePart> & parts )

Add a list of body parts to this SMS message.

See also clearParts(), addPart(), and parts().

QByteArray QSMSMessage::applicationData () const

Returns the data if this SMS message contains an application datagram. Returns an empty byte array if this message is not a datagram.

See also setApplicationData().

QSMSDataCodingScheme QSMSMessage::bestScheme () const

Returns the best SMS data coding scheme to use for this message, determined by an inspection of the plain text body parts.

See also setBestScheme().

void QSMSMessage::clearParts ()

Clear all body parts from this SMS message.

See also addPart(), addParts(), and parts().

void QSMSMessage::computeSize ( uint & numMessages, uint & spaceLeftInLast ) const

Compute an estimate for the number of messages that will need to be used to send this SMS message (numMessages), and the number of spare characters that are left in the last message before it overflows (spaceLeftInLast).

This function may be useful in user interfaces to indicate to the user that an SMS message needs to be sent in multiple pieces, costing the user more money.

int QSMSMessage::dataCodingScheme () const

Returns the data coding scheme to use within an SMS message. If the value is -1, then the system chooses the best data coding scheme based on the content.

This method is mainly of use with application datagrams, not text SMS messages.

See also setDataCodingScheme().

int QSMSMessage::destinationPort () const

Returns the destination port number if this SMS message contains an application datagram, or -1 if not an application datagram.

When an SMS message is received that has a destination port number, Qt Extended will attempt to find a QDS service that can handle it. Qt Extended first looks for a QDS service named push for the MIME type T from the WAP push header. Next, it looks for a service named push for the MIME type application/x-smsapp-N where N is the port number in decimal.

If a matching service is found, then the SMS message is sent to the corresponding application via QDS. The QCop message is that specified in the QDS service definition. Thus, applications can register to receive special SMS messages.

The following QDS definition, in etc/qds/ContactsPhone will direct vcard's that are received via WAP to the ContactsPhone service. The ContactsPhone service is normally implemented by the addressbook program.

    [Translation]
    File=QtopiaServices
    Context=ContactsPhone
    [pushVCard]
    RequestDataType=text/x-vcard
    ResponseDataType=
    Attributes="push"
    Description[]=Receive a vcard via WAP push

The Attributes must contain push and the RequestDataType must be the MIME type to be dispatched. The QCop message that is delivered to the application will have the name pushVCard(QDSActionRequest). The data in the action request will be the payload of the push message.

The auxilary data in the action request will be a QByteArray containing the full QSMSMessage object, from which the application can extra header information if it needs it. Use the QSMSMessage datastream operators to extract the QSMSMessage object.

If the application fails to process an SMS message that is sent to it via QCop, then it will be lost. It is important that such applications take steps to save the message if necessary.

If a matching service is not found, then the SMS message will be delivered to the qtmail application normally, and then saved by that application.

See also setDestinationPort() and sourcePort().

bool QSMSMessage::forceGsm () const

Returns true if the 7-bit GSM encoding has been forced.

See also setForceGsm().

QSMSMessage QSMSMessage::fromPdu ( const QByteArray & pdu )   [static]

Convert a binary pdu into an SMS message, according to 3GPP TS 03.40 and 3GPP TS 23.040.

See also toPdu().

uint QSMSMessage::gsmValidityPeriod () const

Returns the GSM validity period value, between 0 and 255, inclusive.

See also setGsmValidityPeriod() and setValidityPeriod().

const QByteArray & QSMSMessage::headers () const

Returns the SMS message's user data headers.

See also setHeaders().

int QSMSMessage::messageClass () const

Get the message class for this message, or -1 if the system should choose a default message class. The message class should otherwise be 0, 1, 2, or 3, according to 3GPP TS 03.38.

See also setMessageClass().

MessageType QSMSMessage::messageType () const

Returns the SMS message type.

See also setMessageType().

QList<QSMSMessagePart> QSMSMessage::parts () const

Returns a list of all body parts in this SMS message.

See also clearParts(), addParts(), and addPart().

int QSMSMessage::pduAddressLength ( const QByteArray & pdu )   [static]

Returns the length of the service center address on the start of pdu. This is typically used with AT-based GSM modems that need to transmit the length of the pdu, excluding the service center address, along with the AT+CMGS command.

int QSMSMessage::protocol () const

Returns the SMS message's protocol field.

See also setProtocol().

QString QSMSMessage::recipient () const

Returns the recipient's telephone number. Normally QString() for an incoming message.

See also setRecipient().

bool QSMSMessage::replyRequest () const

Returns the "reply request" flag.

See also setReplyRequest().

QString QSMSMessage::sender () const

Returns the sender's telephone number. Normally QString() for an outgoing message.

See also setSender().

QString QSMSMessage::serviceCenter () const

Returns the service center.

See also setServiceCenter().

void QSMSMessage::setApplicationData ( const QByteArray & value )

Sets the data within an SMS message that contains an application datagram to value.

See also applicationData().

void QSMSMessage::setBestScheme ( QSMSDataCodingScheme scheme )

Sets the SMS data coding scheme to use for this message. Normally you won't need to call this unless the user has somehow explicitly requested an override. By default, the QSMSMessage class will choose the best scheme for you. Should be set to one of QSMS_DefaultAlphabet, QSMS_8BitAlphabet, or QSMS_UCS2Alphabet.

See also bestScheme().

void QSMSMessage::setDataCodingScheme ( int value )

Sets the data coding scheme to use within an SMS message to value. If value is -1, then the system chooses the best data coding scheme based on the content.

This method is mainly of use with application datagrams, not text SMS messages.

See also dataCodingScheme().

void QSMSMessage::setDestinationPort ( int value )

Sets the destination port number for an SMS message that contains an application datagram to value.

See also destinationPort() and sourcePort().

void QSMSMessage::setForceGsm ( bool force )

If force is true, then the codec set by QSMSMessage::setTextCodec is ignored and the 7-bit GSM encoding is always used. Setting this flag increases the number of characters that can be sent in any given SMS message, but may lose information.

See also forceGsm().

void QSMSMessage::setGsmValidityPeriod ( uint value )

Sets the GSM validity period to value, which must be between 0 and 255, inclusive. The setValidity() method is a friendlier way to set the validity value.

0 to 143 indicates 0 to 12 hours in 5 minute increments (0 = 5 minutes). 144 to 167 indicates 12 hrs 30 min to 24 hrs in 30 minute increments. 168 to 196 indicates 2 days to 30 days in 1 day increments. 197 to 255 indicates 5 weeks to 63 weeks in 1 week increments.

See also gsmValidityPeriod() and validityPeriod().

void QSMSMessage::setHeaders ( const QByteArray & value )

Sets the SMS message's user data headers to value.

See also headers().

void QSMSMessage::setMessageClass ( int value )

Sets the message class for this message to value. The

See also messageClass().

void QSMSMessage::setMessageType ( MessageType m )   [protected]

Sets the SMS message type to m. There is rarely any need to set this to something other than QSMSMessage::Normal.

See also messageType().

void QSMSMessage::setProtocol ( int value )

Sets the SMS message's protocol field to value.

See also protocol().

void QSMSMessage::setRecipient ( const QString & txt )

Sets the recipient's telephone number to txt.

See also recipient().

void QSMSMessage::setReplyRequest ( bool on )

Enable or disable the "reply request" flag for this SMS message, according to the value of on.

See also replyRequest().

void QSMSMessage::setSender ( const QString & txt )

Sets the sender's telephone number to txt.

See also sender().

void QSMSMessage::setServiceCenter ( const QString & str )

Sets the service center to use for transmitting this SMS message, or QString() for the default service center, to str.

See also serviceCenter().

void QSMSMessage::setSourcePort ( int value )

Sets the source port number for an SMS message that contains an application datagram to value.

See also sourcePort() and destinationPort().

void QSMSMessage::setStatusReportRequested ( bool on )

Sets the status report requested flag to on.

See also statusReportRequested().

void QSMSMessage::setText ( const QString & str )

Sets the contents of this QSMSMessage to a single plain text body containing str. This is for simple messages only. Complex messages should be constructed part by part using the addPart() method.

See also text().

void QSMSMessage::setTextCodec ( QTextCodec * codec )

If the message consists solely of characters in the 7-bit GSM encoding, then the message will be transmitted that way. Otherwise codec is used to convert the characters into an appropriate language-specific 8-bit encoding. If codec is set to NULL, then the default UCS-2 encoding for GSM messages is used.

See also textCodec().

void QSMSMessage::setTimestamp ( const QDateTime & timestamp )

Sets the SMS message's timestamp.

See also timestamp().

void QSMSMessage::setValidityPeriod ( uint minutes )

Sets the validity period to minutes. The default is 2 days. If the value is set to (uint)(-1), it indicates that the message should have no validity period specified.

See also validityPeriod() and gsmValidityPeriod().

bool QSMSMessage::shouldSplit () const

Returns true if this message needs to be split into multiple messages before being transmitted over a GSM network; otherwise returns false.

See also split().

int QSMSMessage::sourcePort () const

Returns the source port number if this SMS message contains an application datagram, or -1 if not an application datagram.

See also setSourcePort() and destinationPort().

QList<QSMSMessage> QSMSMessage::split () const

Split this message into several messages of smaller size for transmission over a GSM network.

See also shouldSplit().

bool QSMSMessage::statusReportRequested () const

Returns true if status report requested flag is currently set;otherwise returns false.

See also setStatusReportRequested().

QString QSMSMessage::text () const

Returns the contents of this QSMSMessage as a single plain text string. If the message contains binary parts, they will not appear in the result. This is for simple message viewers only. Complex message viewers should iterate over the list returned by parts().

See also setText().

QTextCodec * QSMSMessage::textCodec () const

Returns the current 8-bit text codec, or NULL if none has been set.

See also setTextCodec().

QDateTime QSMSMessage::timestamp () const

Returns the SMS message's timestamp, which will be null if the message does not have a timestamp.

See also setTimestamp().

QByteArray QSMSMessage::toPdu () const

Convert this SMS message into its binary PDU form, according to 3GPP TS 03.40 and 3GPP TS 23.040. If the message has a recipient, then a SUBMIT message will be constructed. If the message does not have a recipient, then a DELIVER message will be constructed.

See also fromPdu().

uint QSMSMessage::validityPeriod () const

Returns the validity period in minutes for this message. The default is 2 days. If the value is (uint)(-1), it indicates that the message should have no validity period specified.

See also setValidityPeriod() and setGsmValidityPeriod().

QSMSMessage & QSMSMessage::operator= ( const QSMSMessage & msg )

Assigns a copy of msg to this object.