GSM - Arduino Sketches: Tools and Techniques for Programming Wizardry - page 280

The message parameter is again a char array and contains the message to
be sent. Note that SMS messages are limited to 160 characters. This function
returns the amount of bytes sent, expressed as an int .
To complete an SMS message and to instruct the modem to send the message,
use endSMS() :
sms .endSMS();
This function does not take any parameters.
When the SMS message has been assembled, the SIM card is told to send
the message as soon as possible. The SIM card coupled with the modem make
an autonomous unit which acts independently from the Arduino. Assembling
and sending a message through the Arduino API does not guarantee that the
message is sent; it is queued to be sent.
Because the device is autonomous, it also receives SMS messages without
warning; there is no callback and no interruption. The sketch must periodically
poll the GSM shield to see if a message is present. This is done with available() :
result = sms .available();
This function returns an int , the number of messages waiting on the SIM
card. To begin reading a text message, you must i rst retrieve the number of the
sender, which is done with remoteNumber() :
sms .remoteNumber(number, size);
The number parameter is a char array, a memory location where the sender
ID will be stored. The size parameter is the size of the char array.
When the sender ID has been retrieved, the next thing you must do is to
retrieve the message body. You can do this with read() , which works the same
way as with i le functions and serial buffers. It reads one character at a time.
result = sms .read();
You can read the entire content of a message with the following code:
// Read message bytes and print them
while(c=sms.read())
Serial.print(c);
SMS messages that have been previously read are marked with a hashtag.
To see if a message has been read without actually fetching the i rst character,
you can use peek() . Just like with serial buffers, this function returns the i rst
character but does not increment the index. Subsequent calls to peek() or even
read() will return the same character.