Messages: Creating and Sending SMS and MMS Messages

This tutorial demonstrates how you can send SMS and MMS messages, and fetch messages from a specified message box.

Warm-up

Become familiar with the Messages API basics by learning about:

Initializing the Messages Service
Initialize the Messages service for use.
Fetching Messages from a Specified Message Box
Fetch all SMS or MMS messages from a given message box (such as Inbox or the sent items).
Sending SMS or MMS Messages
Create and send a message, and add attachments to MMS messages.

Initializing the Messages Service

To initialize the Messages service:

To use the functions and data types of the Messages API (in mobile and wearable applications), include the <messages.h> header file in your application:
```
#include <messages.h>
```
The Messages service works like a client-service architecture. In this architecture, a Tizen application is the client side and has to connect to the service before using the Messages API.

Establish a connection using the messages_open_service(messages_service_h *service) function:
```
static messages_service_h service_handle = NULL;
int error_code;

error_code = messages_open_service(&service_handle);

if (error_code != MESSAGES_ERROR_NONE) 
{
   // Error handling
}
```
When a connection with the Messages service is no longer needed (or the application is exiting), call the messages_close_service() function for proper connection closing:
```
messages_close_service(service_handle);
service_handle = NULL;
```

Fetching Messages from a Specified Message Box

To fetch messages from a message box, use the messages_foreach_message() function with the appropriate parameters. One of these parameters is the callback function called for each message matching the search criteria.

Define the message searching callback function.

The callback function signature has to match the following typedef:

typedef bool(* messages_search_cb)(messages_message_h msg, int index, int result_count, int total_count, void *user_data)

Within the callback, to print the message content (or to show it to the user in any other way), extract its text, address, and type as below:

char *message = NULL, *address = NULL;
messages_recipient_type_e rtype;
int error_code = MESSAGES_ERROR_NONE;

error_code = messages_get_text(msg, &message);
if (error_code != MESSAGES_ERROR_NONE) 
{
   dlog_print(DLOG_DEBUG, LOG_TAG, "Failed to get message content");
}

error_code = messages_get_address(msg, 0, &address, &rtype);
if (error_code != MESSAGES_ERROR_NONE) 
{
   dlog_print(DLOG_DEBUG, LOG_TAG, "Failed to get recipient address");
}

messages_message_type_e mtype = MESSAGES_TYPE_UNKNOWN;
messages_get_message_type(msg, &mtype);

For MMS messages, the subject and attachments attributes exist and can be extracted from the found message:

if (MESSAGES_TYPE_MMS == mtype) 
{
   char *subject = NULL;
   error_code = messages_mms_get_subject(msg, &subject);
   if (error_code != MESSAGES_ERROR_NONE) 
   {
      dlog_print(DLOG_DEBUG, LOG_TAG, "Failed to get MMS subject");
   }
   int atcount = 0;
   messages_mms_get_attachment_count(msg, &atcount);
}

The memory allocated for the message given to the callback function and for all string variables extracted from the message have to be explicitly released before leaving their visibility scope:
```
free(subject);
free(message);
free(address);
```

Call the search function.

With a connection opened and callback prepared, the messages_foreach_message() function can be called to retrieve all existing messages stored in different mailboxes. The function arguments allow to select only a subset of all available messages based on:

Message box type (inbox, outbox, sent items, drafts, or all of them)
Message type (such as SMS, MMS)
Keyword (for searching based on text and subject)
Address (message recipient address)

The following example shows a simple search for all SMS messages in all message boxes with a callback function named message_search_callback:

int error_code;
error_code = messages_open_service(&service_handle);
if (error_code != MESSAGES_ERROR_NONE) 

{
   dlog_print(DLOG_DEBUG, LOG_TAG, "Failed to open connection");
}

error_code = messages_foreach_message(service_handle, MESSAGES_MBOX_ALL,
                                      MESSAGES_TYPE_SMS, NULL, NULL, 0, 0,
                                      messages_search_callback, NULL);
if (error_code != MESSAGES_ERROR_NONE) 
{
   dlog_print(DLOG_DEBUG, LOG_TAG, "Messages searching failed");
}

messages_close_service(service_handle);

Sending SMS or MMS Messages

The Messaging API provides functions to send SMS (Short Message Service) messages and MMS (Multimedia Message Service) messages with attachments (image or video files):

Create a message.
Before sending a message, open a connection to the messaging service.

To create an SMS or an MMS message, use the messages_create_message() function. Specify the message type (MESSAGES_TYPE_SMS or MESSAGES_TYPE_MMS) when creating the message. The following example creates an SMS message:
```
int error_code;
messages_message_h msg_hndl = NULL;

// Create an SMS message handle
error_code = messages_create_message(MESSAGES_TYPE_SMS, &msg_hndl);
if (error_code != MESSAGES_ERROR_NONE) 
{
   dlog_print(DLOG_DEBUG, LOG_TAG, "Failed to create message");
}
```

Define the recipients and message body.

Functions for setting the recipient address and the message body (the message text) are the same for SMS and MMS, but in this case the message type specification is not needed:

error_code = messages_add_address(msg_hndl, "123456789", MESSAGES_RECIPIENT_TO);
if (error_code != MESSAGES_ERROR_NONE) 
{
   dlog_print(DLOG_DEBUG, LOG_TAG, "Failed to add recipient address");
}

error_code = messages_set_text(msg_hndl, __PRETTY_FUNCTION__);
if (error_code != MESSAGES_ERROR_NONE) 
{
   dlog_print(DLOG_DEBUG, LOG_TAG, "Failed to set message text");
}

Set a subject and add an attachment (note that sending MMS is not supported on the Emulator).

You can set a message subject and add attachments to MMS messages. Set the subject:

error_code = messages_mms_set_subject(msg_hndl, "MMS test");
if (error_code != MESSAGES_ERROR_NONE) 
{
   dlog_print(DLOG_DEBUG, LOG_TAG, "Failed to set MMS subject");
}

Add attachments to the MMS message with their absolute path in the device file system. When adding the attachment, give the attachment type. Possible attachment types are image, audio, and video:

error_code = messages_mms_add_attachment(g_message, MESSAGES_MEDIA_IMAGE, "/path/to/image/file");
if (error_code != MESSAGES_ERROR_NONE) 
{
   dlog_print(DLOG_DEBUG, LOG_TAG, "Failed to add attachment to MMS");
}

Send the message.

SMS and MMS sending is an asynchronous operation, and a callback function is needed to receive the sending operation status. This function has to match the following typedef:
```
typedef void(* messages_sent_cb)(messages_sending_result_e result, void *user_data)
```

Using the first parameter in the callback (result), the messaging service informs you about the sending status. It can be used to determine whether the sending succeeded:

static void sent_msg_cb(messages_sending_result_e result, void *user_data)
{
   if (MESSAGES_SENDING_SUCCEEDED == result) 
   {
      dlog_print(DLOG_DEBUG, LOG_TAG, "Message sending succeeded");
   }
   else 
   {
      dlog_print(DLOG_DEBUG, LOG_TAG, "Message sending failed");
   }
}

If the connection to the messaging service is open (service_handle) and the message itself is successfully created (msg_hndl), send it using the messages_send_message() function:

error_code = messages_send_message(service_handle, msg_hndl, true, sent_msg_cb, NULL);
if (error_code != MESSAGES_ERROR_NONE) 
{
   dlog_print(DLOG_DEBUG, LOG_TAG, "Failed to send message");
}