26.3. Using the
+CMGL AT Command to List SMS Messages of a Certain Status from a
Message Storage Area
The
AT command +CMGL (command name in text: List Messages) is used to
list messages of a certain status (for example, "received
unread" and "received read") from a message storage
area. The messages listed by the AT command +CMGL do not necessarily
have to be SMS messages. They 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 +CMGL:
The
index specifying the location of the SMS message in the message
storage area.
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).
Body
of the SMS message and its length.
In
SMS PDU mode, the list becomes:
The
index specifying the location of the SMS message in the message
storage area.
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.
If
the status of a message is "received unread", after being
retrieved by the +CMGL AT command, the status is 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.3.1. Syntax of
the +CMGL AT Command in SMS Text Mode
The
syntax of the +CMGL AT command in SMS text mode is: (Optional
parameter is enclosed in square brackets.)
+CMGL[=message_status]
The
message_status
parameter takes a string that specifies the message status to be used
to find messages to return. The SMS specification has defined five
message status values, which are shown below. You can perform a test
operation to find the actual values supported by your GSM/GPRS modem
or mobile phone. See the "Finding
the Message Status Values Supported by the +CMGL AT Command in SMS
Text Mode" section
for the details. Usually all five status values are supported.
REC
UNREAD. It refers to the message status "received unread".
It is the default value.
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".
ALL.
It tells the +CMGL AT command to list all messages.
For
example, if "REC READ" is specified to the message_status
parameter, the +CMGL AT command will list all messages that have the
"received read" status from the message storage area.
Note
that message_status is
an optional parameter. If it is omitted, the +CMGL AT command will
use the default value "REC UNREAD".
26.3.2. Format of
the Information Response of the +CMGL AT Command in SMS Text Mode
If
the GSM/GPRS modem or mobile phone reads the SMS messages from
message storage successfully, it will return an information response
to the computer / PC. Suppose the messages to be listed are SMS
messages (not of other message types like status reports and cell
broadcast messages), the information response of the +CMGL AT command
in SMS text mode has the following format: (Optional fields are
enclosed in square brackets.)
+CMGL:
index,message_status,address,[address_text],[service_center_time_stamp][,address_type,sms_message_body_length]<CR><LF>sms_message_body[<CR><LF>+CMGL:
...]
Before
we discuss each of the fields that appear in the +CMGL information
response, let's see an example that gives you some idea of how an
actual +CMGL information response should look like:
+CMGL:
1,"REC READ","+85291234567",,"07/05/01,08:00:15+32",145,37 It
is easy to list SMS text messages.
The
index Field
The
first field of the information response of the +CMGL AT command,
index, is an integer
that specifies the location of the SMS message in the message storage
area.
The
message_status Field
The
second field of the information response of the +CMGL 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
third field of the information response of the +CMGL 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
fourth field of the information response of the +CMGL 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
fifth field of the information response of the +CMGL AT command,
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
sixth field of the information response of the +CMGL AT command,
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 +CMGL AT command.
The
sms_message_body_length Field
The
seventh field of the information response of the +CMGL 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 36 characters in "It is easy to
list SMS text messages". If the value of the sms_message_body
field is "It is easy to list SMS text messages", the value
of the sms_message_body_length
field will be 36.
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 +CMGL AT command.
The
sms_message_body Field
The
eighth field of the information response of the +CMGL AT command,
sms_message_body,
contains the body of the SMS message.
Multiple
SMS Messages in the Information Response
If
there are multiple SMS messages to be returned, the information
response of the +CMGL AT command will contain more than one "+CMGL:
...". Two characters, <CR><LF>, are
used to delimit two "+CMGL: ...". Here is an example for
illustration. Suppose the command line 'AT+CMGL="ALL"' is
executed and three SMS messages are listed. If all characters are
shown, the command line and the response returned will be displayed
like this:
AT+CMGL="ALL"<CR> <CR><LF>+CMGL:
...<CR><LF>+CMGL: ...<CR><LF>+CMGL:
...<CR><LF> <CR><LF>OK<CR><LF>
In
a terminal program such as HyperTerminal of Microsoft Windows, a
carriage return character causes the cursor to be moved to the
beginning of the current line, and a linefeed character causes the
cursor to be moved to the same position on the next line. Hence, the
above result will be displayed like this in a terminal program such
as HyperTerminal of Microsoft Windows:
AT+CMGL="ALL" +CMGL:
... +CMGL: ... +CMGL: ...
OK
Feedback Form (ExpandCollapse)
|
|