26.2. Using the
+CMGR AT Command to Read an SMS Message from a Message Storage Area
The
AT command +CMGR (command name in text: Read Message) is used to read
a message from a message storage area. The location of the message to
be read from the message storage area is specified by an index
number. The message to be retrieved by the AT command +CMGR does not
necessarily have to be an SMS message. It can be of other message
types such as status reports and cell broadcast messages, but we will
only focus on SMS messages here.
In
SMS text mode, you can retrieve the following information about an
SMS message with the AT command +CMGR:
Status
of the SMS message ("received unread", "received
read", "stored unsent",
"stored sent", etc).
Originator/recipient
phone number stored in the SMS message header and the type of the
phone number.
Text
associated to the originator/recipient phone number in the
phonebook.
Time
and date at which the SMS message arrived at the SMSC (available to
incoming SMS messages only).
The
first octet (1 octet = 8 bits) of the TPDU (Transport Protocol Data
Unit) of the SMS message.
The
protocol identifier value in the TPDU of the SMS message.
The
data coding scheme value in the TPDU of the SMS message.
SMSC
number stored with the SMS message and the type of the SMSC number.
Validity
period of the SMS message (available to outgoing SMS messages only).
Body
of the SMS message and its length.
In
SMS PDU mode, the list becomes:
Status
of the SMS message ("received unread", "received
read", "stored unsent",
"stored sent", etc).
Text
associated to the originator/recipient phone number in the
phonebook.
SMSC
number stored with the SMS message and the type of the SMSC number.
TPDU
of the SMS message and its length.
After
using the +CMGR AT command to read an SMS message with the "received
unread" status, the status will be changed to "received
read".
The
message storage area from which SMS messages are read is specified by
the +CPMS AT command (command name in text: Preferred Message
Storage). Details about the +CPMS AT command can be found in the
earlier section "Preferred
Message Storage (AT+CPMS)" of this SMS tutorial.
26.2.1. Syntax of
the +CMGR AT Command in SMS Text Mode
The
syntax of the +CMGR AT command in SMS text mode is:
+CMGR=index
index
is an integer specifying the location of the SMS message to be read
from the message storage area.
26.2.2. Format of
the Information Response of the +CMGR AT Command in SMS Text Mode
If
the GSM/GPRS modem or mobile phone successfully reads the SMS message
from message storage, it will return an information response to the
computer / PC. In SMS text mode, the format of the information
response of the +CMGR AT command is different for different message
types. In the sections that follow, we assume the message to be read
is an SMS message but not of other message types like status reports
and cell broadcast messages.
26.2.2.1. Incoming
SMS Messages and Outgoing SMS Messages
If
the SMS message retrieved is an SMS message received from the SMS
center (i.e. incoming SMS message), the information response of the
+CMGR AT command in SMS text mode has the following format: (Optional
fields are enclosed in square brackets.)
+CMGR:
message_status,address,[address_text],service_center_time_stamp[,address_type,TPDU_first_octet,protocol_identifier,data_coding_scheme,service_center_address,service_center_address_type,sms_message_body_length]<CR><LF>sms_message_body
If
the SMS message retrieved is an SMS message that you wrote to the
message storage area for sending out (i.e. outgoing SMS message), the
format is: (Optional fields are enclosed in square brackets.)
+CMGR:
message_status,address,[address_text][,address_type,TPDU_first_octet,protocol_identifier,data_coding_scheme,[validity_period],service_center_address,service_center_address_type,sms_message_body_length]<CR><LF>sms_message_body
As
you can see above, the format of the +CMGR information response for
incoming SMS messages and for outgoing SMS messages is slightly
different. The differences are:
Before
we discuss each of the fields that appear in the +CMGR information
response, let's see two examples that give you some idea of how an
actual +CMGR information response should look like:
For
incoming SMS messages:
+CMGR:
"REC
READ","+85291234567",,"07/04/20,10:08:02+32",145,4,0,0,"+85290000000",145,49 It
is easy to read text messages via AT commands.
For
outgoing SMS messages:
+CMGR:
"STO
SENT","+85291234567",,145,17,0,0,167,"+85290000000",145,36 A
simple demo of SMS text messaging.
26.2.2.2. Details
of the Fields that Appear in the +CMGR Information Response
The
message_status Field
The
first field of the information response of the +CMGR AT command,
message_status, is a
string that indicates the status of the SMS message. It can be one of
the following four values:
REC
UNREAD. It refers to the message status "received unread".
REC
READ. It refers to the message status "received read".
STO
UNSENT. It refers to the message status "stored unsent".
STO
SENT. It refers to the message status "stored sent".
The
address Field
The
second field of the information response of the +CMGR AT command,
address, is a string
that contains the address/phone number stored in the SMS message
header. If the SMS message read is an incoming SMS message, the
address field contains
the originator address. If the SMS message read is an outgoing SMS
message, the address
field contains the recipient address. Usually the address
field value is a phone number formatted using the typical ISDN /
telephony numbering plan (ITU E.164/E.163). For example,
"+85291234567".
The
address_text Field
The
third field of the information response of the +CMGR AT command,
address_text, is a
string that contains the text associated to address
in the phonebook. For example, if the text "Alice" is
associated to the phone number "91234567" in the phonebook,
address_text will be
"Alice". The AT command +CSCS (command name in text: Select
TE Character Set) can be used to specify the character set for
displaying address_text.
Note that address_text
is an optional field. Some GSM/GPRS modems and mobile phones
(examples: most Nokia products, including my Nokia 6021) leave this
field empty.
The
service_center_time_stamp Field
The
fourth field of the +CMGR information response for incoming SMS
messages, service_center_time_stamp,
is a string that contains the time and date at which the SMS
message arrived at the service center (i.e. SMSC). The time stamp
format is "yy/MM/dd,hh:mm:ss±zz"
(yy = year, MM = month, dd = day, hh = hour, mm = minute, ss =
second, zz = time zone [Note: the unit of time zone is a quarter of
an hour]). For example, "07/02/05,08:30:45+32"
represents 5 February 2007, 8:30:45 GMT+8 hours. (+32 means GMT+8
hours, since 32 quarters of an hour = 8 hours.)
Note
that service_center_time_stamp is an optional field. This
field is available to incoming SMS messages but not to outgoing SMS
messages since outgoing SMS messages have not gone through an SMSC.
The
address_type Field
The
fifth (fourth) field of the +CMGR information response for incoming
SMS messages (outgoing SMS messages), address_type,
is an integer that indicates the type of the address contained in the
address field. Usually
it is one of the following two values:
129.
Meaning: The value of address
is formatted using the typical ISDN / telephony numbering plan (ITU
E.164/E.163) but it is not sure whether the value of address
is an international number, a national number or a number of other
types. Example addresses: "85291234567", "91234567".
145.
Meaning: The value of address
is formatted using the typical ISDN / telephony numbering plan (ITU
E.164/E.163) and it is an international number. Example address:
"+85291234567".
Note
that address_type is
an optional field and it is not shown by default. The AT command
+CSDH (command name in text: Show Text Mode Parameters) can be
used to control whether the field address_type
will be shown in the information response of the +CMGR AT command.
The
TPDU_first_octet Field
The
sixth (fifth) field of the +CMGR information response for incoming
SMS messages (outgoing SMS messages), TPDU_first_octet,
contains the first octet (expressed as an integer) of the TPDU of the
SMS message.
Note
that TPDU_first_octet
is an optional field and it is not shown by default. The AT command
+CSDH (command name in text: Show Text Mode Parameters) can be used
to control whether the field TPDU_first_octet
will be shown in the information response of the +CMGR AT command.
The
protocol_identifier Field
The
seventh (sixth) field of the +CMGR information response for incoming
SMS messages (outgoing SMS messages), protocol_identifier,
contains the value (expressed as an integer) of the
TP-Protocol-Identifier parameter in the TPDU of the SMS message.
Note
that protocol_identifier
is an optional field and it is not shown by default. The AT command
+CSDH (command name in text: Show Text Mode Parameters) can be used
to control whether the field protocol_identifier
will be shown in the information response of the +CMGR AT command.
The
data_coding_scheme Field
The
eighth (seventh) field of the +CMGR information response for incoming
SMS messages (outgoing SMS messages), data_coding_scheme,
contains the value (expressed as an integer) of the
TP-Data-Coding-Scheme parameter in the TPDU of the SMS message.
Note
that data_coding_scheme
is an optional field and it is not shown by default. The AT command
+CSDH (command name in text: Show Text Mode Parameters) can be used
to control whether the field data_coding_scheme
will be shown in the information response of the +CMGR AT command.
The
validity_period Field
The
eighth field of the +CMGR information response for outgoing SMS
messages, validity_period,
contains the validity period assigned to the SMS message. There are
three possible validity period formats: relative format, absolute
format and enhanced format. To find out the format of
validity_period,
examine the value of the TP-Validity-Period-Format parameter in the
TPDU of the SMS message. It is located at bit 4 and bit 3 of the
first octet of the TPDU. (Note: Bit 0 is the rightmost bit.) For
example, let's say the value of the TPDU_first_octet
Field is 17. Its binary representation is 00010001. As you can see,
bit 4 is 1 and bit 3 is 0.
If
the relative format is used (bit 4 = 1, bit 3 = 0), validity_period
will be an integer in the range from 0 to 255 that indicates the
period after which the SMSC should delete the SMS message, counted
from the time at which the SMSC receives the SMS message. The
validity period can be calculated by the following formulae:
If
validity_period is in the
range from 0 to 143, validity period = (validity_period
+ 1) x 5 minutes.
If
validity_period is in
the range from 144 to 167, validity period = 12 hours +
((validity_period -
143) x 0.5 hours).
If
validity_period is in
the range from 168 to 196, validity period = (validity_period
- 166) x 1 day.
If
validity_period is in
the range from 197 to 255, validity period = (validity_period
- 192) x 1 week.
If
the absolute format is used (bit 4 = 1, bit 3 =1), validity_period
will be a string that contains the time and date at which the SMSC
should delete the SMS message. The time/date format is
"yy/MM/dd,hh:mm:ss±zz"
(yy = year, MM = month, dd = day, hh = hour, mm = minute, ss =
second, zz = time zone [Note: the unit of time zone is a quarter of
an hour]). For example, "07/02/05,08:30:45+32"
represents 5 February 2007, 8:30:45 GMT+8 hours. (+32 means GMT+8
hours, since 32 quarters of an hour = 8 hours.)
If
the enhanced format is used (bit 4 = 0, bit 3 = 1), validity_period
will be a hexadecimal coded string. Since the enhanced format is not
commonly used, we do not discuss the details here.
Note
that validity_period
is an optional field and it is not shown by default. The AT command
+CSDH (command name in text: Show Text Mode Parameters) can be used
to control whether the field validity_period
will be shown in the information response of the +CMGR AT command.
Also, note that validity_period
is available to outgoing SMS messages but not to incoming SMS
messages, since there is no such value stored in the headers of
incoming SMS messages.
The
service_center_address Field
The
ninth field of the information response of the +CMGR AT command,
service_center_address,
is a string that contains the SMSC address stored with the SMS
message. Usually it is a phone number formatted using the typical
ISDN / telephony numbering plan (ITU E.164/E.163). For example,
"+85291234567".
Note
that service_center_address
is an optional field and it is not shown by default. The AT command
+CSDH (command name in text: Show Text Mode Parameters) can be used
to control whether the field service_center_address
will be shown in the information response of the +CMGR AT command.
The
service_center_address_type Field
The
tenth field of the information response of the +CMGR AT command,
service_center_address_type,
is an integer that indicates the type of the SMSC address contained
in the service_center_address
field. Usually it is one of the following two values:
129.
Meaning: The SMSC address, service_center_address,
is formatted using the typical ISDN / telephony numbering plan (ITU
E.164/E.163) but it is not sure whether service_center_address
is an international number, a national number or a number of other
types. Example addresses: "85291234567" and "91234567".
145.
Meaning: The SMSC address, service_center_address,
is formatted using the typical ISDN / telephony numbering plan (ITU
E.164/E.163) and it is an international number. Example address:
"+85291234567".
Note
that service_center_address_type
is an optional field and it is not shown by default. The AT command
+CSDH (command name in text: Show Text Mode Parameters) can be used
to control whether the field service_center_address_type
will be shown in the information response of the +CMGR AT command.
The
sms_message_body_length Field
The
eleventh field of the information response of the +CMGR AT command,
sms_message_body_length,
is an integer that indicates the number of characters contained in
the sms_message_body
field. For example, there are 48 characters in "It is easy to
read text messages via AT commands". If the value of the
sms_message_body field
is "It is easy to read text messages via AT commands", the
value of the sms_message_body_length
field will be 48.
Note
that sms_message_body_length
is an optional field and it is not shown by default. The AT command
+CSDH (command name in text: Show Text Mode Parameters) can be used
to control whether the field sms_message_body_length
will be shown in the information response of the +CMGR AT command.
The
sms_message_body Field
The
twelfth field of the information response of the +CMGR AT command,
sms_message_body,
contains the body of the SMS message.
Feedback Form (ExpandCollapse)
|
|