4 * @defgroup MESSAGE MessagingFW
6 <h1 class="pg">Introduction</h1>
7 <h2 class="pg">Purpose</h2>
8 The purpose of this document is to describe how applications can use the Messaging Framework APIs to send and receive SMS and MMS messages. This document gives programming guidelines to application engineers.
10 <h2 class="pg">Scope</h2>
11 The scope of this document is limited to Messaging Framework APIs usage.
13 <h2 class="pg">Abbreviations</h2>
15 <tr><td>API</td><td>Application Programming Interface</td></tr>
19 @defgroup Message_Architecture 1.Archtecture
22 <h1>Messaging Framework Architecture</h1>
23 The Messaging framework supports various messaging services such as SMS, MMS, Cell Broadcast, WAP Push, and Provisioning message. The Messaging framework architecture consists of a Messaging daemon and a library. The messaging library works on application process and provides various APIs to support transport, control, storage, filter and setting services for application. The messaging daemon has three components (transaction manager, transaction handler, and plug-in manager) to provide message services. The socket IPC is used to communicate (request & event) between Messaging daemon and library.
24 @image html messaging_image001.png
27 - Receive the IPC message (request) on socket.
28 - Manage list of pairs (request ID, transaction proxy) for synchronous return.
29 - Determine the transaction flow based on request/event information. (Mapping the request to one of the handlers)
30 - Store the transaction information for asynchronous events (Find which transaction proxy want to receive SMS)
32 - Submit handler deals with submit requests.
33 - Deliver handler deals with the incoming message from plug-ins.
34 - Storage handler deals with the messages, accounts and folder requests
35 - Filter handler deals with the filter requests
36 - Setting handler deals with the service-specific attributes
38 - Initialize all plug-ins after loading plug-in configuration files
39 - Holding the list of plug-ins and the state of plug-ins
40 - Providing the interface between handlers and plug-ins
41 - Transaction Handlers
42 - Initialize all plug-ins after loading plug-in configuration files
43 - Receiving IPC messages from messaging daemon.
44 - Handling synchronous calls
45 - Condition variable is used for waiting the return from msg. server)
46 - Handling asynchronous calls or events
47 - Proxy listener is a component of transaction proxy
48 - Proxy listener is waiting for the event
49 - Invoking callback function in the msg. handle list
50 - i.e. calling incoming callback function of MSG APP handle, when incoming msg
51 - Holding list of message handles
52 - Message handle is created by MsgOpenMsgHandle(msgHandle)
53 - Message handle holds some info such as callback func
55 - Transport & control API
61 @defgroup Message_Feature 2.Feature
64 <h2 class="pg">Messaging Framework Features</h2>
65 -# Message Control Features:
66 -# Open/Close message handle
67 -# Message Transport Features:
68 -# Submit request to send, forward, reply, retrieve message.
69 -# Register callback functions to listen to invoked events from messaging daemon. (message status callback, incoming message callback)
70 -# Message Storage Features:
71 -# Add / Update / Move / Delete / Count / Get message or message list.
72 -# Add / Update / Delete / Get folder or folder list.
73 -# Message Filter Features:
74 -# Add / Update / Delete filter or filter list.
75 -# Message Setting Features:
76 -# Set / Get various message setting (i.e. whether to send read/delivery report or not)
79 @defgroup MESSAGE_USECASES_1 Initialize/Finalization
80 @ingroup MESSAGE_USECASES
82 <h2 class="pg">Messaging Framework Functions</h2>
84 <h3 class="pg">Initialization / Finalization to use Messaging Service </h3>
85 - int msg_open_msg_handle(MSG_HANDLE_T *handle);
86 @n msg_open_msg_handle() should be called before using the messaging service. This function opens a channel between the application and the messaging framework.
87 - int msg_close_msg_handle(MSG_HANDLE_T *handle);
88 @n msg_close_msg_handle() should be called after using the messaging service. This function closes a channel between the application and the messaging framework.
89 - int msg_reg_sent_status_callback(MSG_HANDLE_T handle, msg_sent_status_cb cb);
90 @n Application should implement a msg_sent_status_cb function and register it into message handle. If the application sends a message, this callback function will be called to report its sending status. msg_reg_set_status_callback function should be called after creation of message handle.
91 - int msg_reg_sms_message_callback(MSG_HANDLE_T handle, msg_sms_incoming_cb cb, unsigned short port);
92 @n Application should implement a msg_sms_incoming_cb function and register it into message handle. It’s used to listen to the SMS incoming event invoked by messaging daemon. The incoming message information structure (MSG_MESSAGE_S) can be delivered as a parameter of the callback function.
93 - int msg_reg_mms_conf_message_callback(MSG_HANDLE_T handle, msg_mms_conf_msg_incoming_cb cb, char *app_id);
94 @n Application should implement a msg_mms_conf_msg_incoming_cb function and register it into message handle. It’s used to listen to the MMS incoming event invoked by messaging daemon. The incoming message information structure (MSG_MESSAGE_S) can be delivered as a parameter of the callback function.
98 #include <MapiControl.h>
99 #include <MapiTransport.h>
101 void sentStatusCB(MSG_HANDLE_T hMsgHandle, MSG_SENT_STATUS_S *pMsgStatus, void *user_param)
103 // Application can handle message sent status event
106 void incomingSmsMessageCB (MSG_HANDLE_T hMsgHandle, msg_message_t msg, void *user_param)
108 // Application can handle SMS incoming message.
111 void incomingMmsConfMessageCB(MSG_HANDLE_T hMsgHandle, msg_message_t msg, void *user_param)
113 // Application can handle MMS incoming message.
118 MSG_HANDLE_T msgHandle = NULL;
120 err = msg_open_msg_handle(&msgHandle);
122 if (err != MSG_SUCCESS)
124 printf("msg_open_msg_handle() Fail [%d]", err);
128 // Register sent status handler
129 err = msg_reg_sent_status_callback(msgHandle, &sentStatusCB, NULL);
131 if (err != MSG_SUCCESS)
133 printf("msg_reg_sent_status_callback() Fail [%d]", err);
137 // Register SMS incoming message handler
138 err = msg_reg_sms_message_callback(msgHandle, &incomingSmsMessageCB, 0, NULL);
140 if (err != MSG_SUCCESS)
142 printf("msg_reg_sms_message_callback() Fail [%d]", err);
146 // Register MMS incoming message handler
147 err = msg_reg_mms_conf_message_callback(msgHandle, &incomingMmsConfMessageCB, NULL, NULL);
149 if (err != MSG_SUCCESS)
151 printf("msg_reg_mms_conf_message_callback() Fail [%d]", err);
155 // g_main_loop should be used to listen CB event from messaging daemon
156 mainloop = g_main_loop_new(NULL, FALSE);
157 g_main_loop_run(mainloop);
159 msg_close_msg_handle(&msgHandle);
166 @defgroup MESSAGE_USECASES_2 Adding a SMS Message
167 @ingroup MESSAGE_USECASES
169 <h3 class="pg">Adding a SMS Message</h3>
170 - msg_message_t msg_new_message();
171 @n msg_new_message() is a function to create a message object which can store the message information. You should call this function to set the message that you want to add or send.
172 - int msg_set_message_type(msg_message_t msg, MSG_MESSAGE_TYPE_T msg_type);
173 @n msg_set_message_type() is a function to set the message type such as SMS or MMS. The first parameter is the message object which is created by msg_new_message(). The second parameter is the message type you want to set. It should be one of enum type ( _MSG_MESSAGE_TYPE_E). If setting is successful, the function returns MSG_SUCCESS. Otherwise it returns an error in enum type (_MSG_ERROR_E).
174 - int msg_sms_set_message_body(msg_message_t msg, const char* mdata, int size);
175 @n msg_sms_set_message_body() is a function to set the SMS body data. The first parameter is the message object which is created by msg_new_message(). The second parameter is the SMS body data you want to set. The third parameter is the length of SMS body data. If setting is successful, the function returns MSG_SUCCESS. Otherwise it returns an error in enum type (_MSG_ERROR_E).
176 - int msg_add_address(msg_message_t msg, const char* phone_num_list, MSG_RECIPIENT_TYPE_T to_type);
177 @n msg_add_address() is a function to add the phone numbers for the message. The first parameter is the message object which is created by msg_new_message(). The second parameter is the list of phone number you want to set. You can add several phone numbers at once. The phone numbers should be separated by ','. The third parameter is the recipient type of phone number. It should be one of enum type (_MSG_RECIPIENT_TYPE_E). If setting is successful, the function returns MSG_SUCCESS. Otherwise it returns an error in enum type (_MSG_ERROR_E).
178 - int msg_add_message(MSG_HANDLE_T handle, const msg_message_t msg, const MSG_SENDINGOPT_S *send_opt);
179 @n msg_add_message() is a function to add a composed message into the database of messaging framework. Before calling this function, the application should set the message object and the sending option structure and then pass them as parameters. If you don't want to change the current sending option, set the variable 'bSetting' to false. If saving a message is successful, the function returns MSG_SUCCESS. Otherwise it returns an error in enum type (_MSG_ERROR_E).
180 - int msg_release_message(msg_message_t *msg);
181 @n msg_release_message() is a function to free the memory of a message object which is create by msg_new_message(). If freeing the memory is successful, the function returns MSG_SUCCESS. Otherwise it returns an error in enum type (_MSG_ERROR_E).
184 #include <MapiStorage.h>
185 #include <MapiMessage.h>
187 void test_add_sms_message(MSG_HANDLE_T hMsgHandle)
189 MSG_ERROR_T err = MSG_SUCCESS;
191 MSG_SENDINGOPT_S sendOpt = {0, };
192 sendOpt.bSetting = false;
194 msg_message_t msgInfo = msg_new_message();
197 err = msg_set_message_type(msgInfo, MSG_TYPE_SMS);
199 if (err != MSG_SUCCESS) goto free_memory;
203 memset(msgText, 0x00, 1024);
204 strncpy(msgText, "Test SMS Message", sizeof(msgText)-1);
205 int dataSize = strlen(msgText);
208 err = msg_sms_set_message_body(msgInfo, msgText, dataSize);
210 if (err != MSG_SUCCESS) goto free_memory;
212 char number[MAX_ADDRESS_VAL_LEN];
214 memset(number, 0x00, MAX_ADDRESS_VAL_LEN);
215 strncpy(number, "+821030011234", sizeof(number)-1);
217 // Set Recipient Address
218 err = msg_add_address(msgInfo, number, MSG_RECIPIENTS_TYPE_TO);
220 if (err != MSG_SUCCESS) goto free_memory;
222 err = msg_add_message(hMsgHandle, msgInfo, &sendOpt);
224 if (err == MSG_SUCCESS)
225 printf("Saving Message is OK!");
227 printf("Saving Message is failed!");
230 msg_release_message(&msgInfo);
235 @defgroup MESSAGE_USECASES_3 Adding a MMS Message
236 @ingroup MESSAGE_USECASES
238 <h3 class="pg">Adding a MMS Message</h3>
239 - int msg_set_subject(msg_message_t msg, const char* subject);
240 @n msg_set_subject() is a function to set the subject of MMS. The first parameter is the message object which is created by msg_new_message(). The second parameter is the subject you want to set. If setting is successful, the function returns MSG_SUCCESS. Otherwise it returns an error in enum type (_MSG_ERROR_E).
242 - MMS_MESSAGE_DATA_S* msg_mms_create_message(void);
243 @n msg_mms_create_message() allocates a MMS_MESSAGE_DATA_S structure and returns it’s address. MMS_MESSAGE_DATA_S is needed to represent mms specific data and transfer it to the messaging daemon in the pData parameter of the MSG_MESSAGE_S structure.
245 - MMS_SMIL_ROOTLAYOUT* msg_mms_set_rootlayout(MMS_MESSAGE_DATA_S* msg, const int width, const int height, const int bgcolor);
246 @n msg_mms_set_rootlayout() is a function to set smil root layout. The parameters representing the size and background color of smil root layout should be set.
248 - MMS_SMIL_REGION* msg_mms_add_region(MMS_MESSAGE_DATA_S *msg_data, const char* szID, const int x, const int y, const int width, const int height, const int bgcolor);
249 @n msg_mms_add_region() is a function to add a smil region. Smil region is needed to display text message, image, and video data (Each content has its own region). This function is called to allocate a region for each contents.
251 - MMS_PAGE_S* msg_mms_add_page(MMS_MESSAGE_DATA_S *msg_data, const int duration);
252 @n msg_mms_add_page() is a function to add a smil page.
254 - MMS_MEDIA_S* msg_mms_add_media(MMS_PAGE_S *page, const MmsSmilMediaType mediatype, const char* regionid, char* filepath);
255 @n msg_mms_add_media() is a function to add multimedia content to a mms message. If some content should be played with smil player, this function can be used.
257 - MMS_ATTACH_S* msg_mms_add_attachment(MMS_MESSAGE_DATA_S *msg_data, char *filepath);
258 @n msg_mms_add_attachment() is a function to add a content as an attached file. With this function a content might be attached as a multipart mixed type.
260 - int msg_mms_set_message_body(msg_message_t msg, const MMS_MESSAGE_DATA_S *msg_data);
261 @n msg_mms_set_message_body() is a function to set the MMS body data. The first parameter is the message object which is created by msg_new_message(). The second parameter is the structure which is allocated by msg_mms_create_message() and is set by the APIs for MMS.
263 - int msg_mms_destroy_message(MMS_MESSAGE_DATA_S* msg);
264 @n msg_mms_destroy_message() should be called to deallocate the MMS_MESSAGE_DATA_S structure and internal region, page, media, and attach list.
267 #include <MapiStorage.h>
268 #include <MapiMessage.h>
270 void test_add_mms_message(MSG_HANDLE_T hMsgHandle)
272 MSG_ERROR_T err = MSG_SUCCESS;
274 MSG_SENDINGOPT_S sendOpt = {0, };
275 sendOpt.bSetting = false;
277 msg_message_t msgInfo = msg_new_message();
280 err = msg_set_message_type(msgInfo, MSG_TYPE_MMS);
282 if (err != MSG_SUCCESS) goto free_memory;
284 MMS_MESSAGE_DATA_S* data;
286 MMS_MEDIA_S* media[3];
287 MMS_ATTACH_S* attach;
291 char subject[MAX_SUBJECT_LEN];
293 memset(subject, 0x00, MAX_SUBJECT_LEN);
294 strncpy(subject, "hello mms", sizeof(subject)-1);
296 err = msg_set_subject(msgInfo, subject);
298 if (err != MSG_SUCCESS) goto free_memory;
301 data = msg_mms_create_message();
302 msg_mms_set_rootlayout(data, 100, 100, 0xffffff);
303 msg_mms_add_region(data, "Image", 0, 50, 100, 50, 0xffffff);
304 msg_mms_add_region(data, "Text", 0, 0, 100, 50, 0xffffff);
305 page = msg_mms_add_page(data, 5000);
306 media[0] = msg_mms_add_media(page, MMS_SMIL_MEDIA_IMG, "Image", "/tmp/image.jpg");
307 media[1] = msg_mms_add_media(page, MMS_SMIL_MEDIA_AUDIO, NULL, "/tmp/audio.amr");
308 media[2] = msg_mms_add_media(page, MMS_SMIL_MEDIA_TEXT, "Text", "/tmp/message.txt");
309 attach = msg_mms_add_attachment(data, "attachment.3gp");
311 err = msg_mms_set_message_body(msgInfo, data);
313 if (err != MSG_SUCCESS)
315 msg_mms_destroy_message(data);
319 msg_mms_destroy_message(data);
321 // Set Recipient Address
322 char number[MAX_ADDRESS_VAL_LEN];
324 memset(number, 0x00, MAX_ADDRESS_VAL_LEN);
325 strncpy(number, "+821030011234", sizeof(number)-1);
327 err = msg_add_address(msgInfo, number, MSG_RECIPIENTS_TYPE_TO);
329 if (err != MSG_SUCCESS) goto free_memory;
331 err = msg_add_message(hMsgHandle, msgInfo, &sendOpt);
333 if (err == MSG_SUCCESS)
334 printf("Saving Message is OK!");
336 printf("Saving Message is failed!");
339 msg_release_message(&msgInfo);
344 @defgroup MESSAGE_USECASES_4 Sending a SMS/MMS Message
345 @ingroup MESSAGE_USECASES
347 <h3 class="pg">Sending a SMS/MMS Message</h3>
349 - bool msg_is_sms(msg_message_t msg);
350 @n msg_is_sms() is a function to check whether the message type of message object is SMS or not. The first parameter is the message object which is created by msg_new_message(). The function returns true if the message object is a SMS message. Otherwise, it returns false.
352 - bool msg_is_mms(msg_message_t msg);
353 @n msg_is_mms() is a function to check whether the message type of message object is MMS or not. The first parameter is the message object which is created by msg_new_message(). The function returns true if the message object is a MMS message. Otherwise, it returns false.
355 - int msg_sms_send_message(MSG_HANDLE_T handle, MSG_REQUEST_S* req);
356 @n msg_sms_send_message() is a function to send SMS through messaging framework. The first parameter is the handle which is created by msg_open_msg_handle (). The second parameter is the structure that includes the message information to send. You can get the result of sending on sent status callback.
358 - int msg_mms_send_message(MSG_HANDLE_T handle, MSG_REQUEST_S* req);
359 @n msg_sms_send_message() is a function to send SMS through messaging framework. The first parameter is the handle which is created by msg_open_msg_handle (). The second parameter is the structure that includes the message information to send. You can get the result of sending on sent status callback.
361 #include <MapiTransport.h>
362 #include <MapiMessage.h>
364 int MsgTestSendMsg(MSG_HANDLE_T hMsgHandle, msg_message_t pMsg)
366 if (hMsgHandle == NULL)
368 printf("Handle is NULL\n");
369 return MSG_ERR_NULL_MSGHANDLE;
372 MSG_ERROR_T err = MSG_SUCCESS;
374 MSG_REQUEST_S req = {0};
378 printf("Message is NULL\n");
379 return MSG_ERR_NULL_MESSAGE;
384 if (msg_is_sms(req.msg))
385 err = msg_sms_send_message(hMsgHandle, &req);
386 else if (msg_is_mms(req.msg))
387 err = msg_mms_send_message(hMsgHandle, &req);
389 if (err == MSG_SUCCESS)
390 printf("Request to Send Message is successful!!!");
392 printf("Request to Send Message is failed!!!");
399 @defgroup MESSAGE_USECASES_5 Sending Simple SMS Message
400 @ingroup MESSAGE_USECASES
402 <h3 class="pg">Simple SMS Sending</h3>
403 - int msg_sms_send(const char *phone_num_list, const char *sms_text, msg_simple_sent_status_cb cb, void *user_param);
404 @n msg_sms_send() is a simple function to send an SMS message. Without this API, in order to send a message the application should allocate a channel with messaging daemon for IPC, register sent-status callback function to monitor the sending result, and fulfill many member variables of MSG_MESSAGE_S. This function implicitly makes a connection with messaging daemon and registers the callback function. In addition, member variables of the MSG_MESSAGE_S structure are filled with default values except for the recipient phone_number and sms_text.
409 #include <MapiTransport.h>
419 void sent_status_cb(MSG_SENT_STATUS_S *pMsgStatus, void *userData)
421 if (pMsgStatus->status == MSG_NETWORK_SEND_SUCCESS)
422 printf("reqId : %d MSG SENT SUCCESS !!!\n", pMsgStatus->reqId);
424 printf("reqId : %d MSG SENT FAIL !!! [%d]\n", pMsgStatus->reqId, pMsgStatus->status);
428 gboolean send_func(gpointer data)
430 send_data* sms_input = (send_data*)data;
432 printf("Begin to send [%s] to [%s]\n", sms_input->number, sms_input->text);
433 MSG_ERROR_T err = msg_sms_send(sms_input->number, sms_input->text, &sent_status_cb, (void*)sms_input->userdata);
435 if (err != MSG_SUCCESS)
436 printf("Send failed [%d]\n", err);
442 int main(int argc, char* argv[])
444 if (argc != 3 && argc != 4)
446 printf("Usage: %s {phone_num_list} {sms_text} [user_data]\n", argv[0]);
447 printf("phone_num_list: phone_num1, phone_num2, ..., phone_numN\n");
451 // Set sms input parameters : phone numbers and text
452 send_data sms_input = {};
453 strncpy(sms_input.number, argv[1], sizeof(sms_input.number)-1);
454 strncpy(sms_input.text, argv[2], sizeof(sms_input.text)-1);
456 strncpy(sms_input.userdata, argv[3], sizeof(sms_input.userdata)-1);
458 // Add Sending Function to GMainLoop
459 g_idle_add(&send_func, (gpointer) &sms_input);
462 mainloop = g_main_loop_new(NULL, FALSE);
464 printf("Entering GMain Loop to Receive Notifications in Thread...\n");
466 g_main_loop_run(mainloop);
468 printf("==== End Test App. Bye...===\n");
475 @defgroup MESSAGE_USECASES_6 Retrieving a MMS Message
476 @ingroup MESSAGE_USECASES
478 <h3 class="pg">Retrieving a MMS Message</h3>
479 - int msg_mms_retrieve_message(MSG_HANDLE_T handle, MSG_REQUEST_S* req);
480 @n msg_mms_retrieve_message() is a function to submit a retrieve MMS request.
482 void MsgTestRetrieveMessage(MSG_HANDLE_T hMsgHandle, MSG_MESSAGE_ID_T nMsgId)
484 if (hMsgHandle == NULL)
486 printf("Handle is NULL");
490 MSG_ERROR_T err = MSG_SUCCESS;
492 msg_message_t msg = msg_new_message();
493 MSG_SENDINGOPT_S sendOpt = {0, };
495 err = msg_get_message(hMsgHandle, (MSG_MESSAGE_ID_T)nMsgId, msg, &sendOpt);
497 if (err != MSG_SUCCESS)
498 printf("Get Message Failed!");
500 MSG_REQUEST_S req = {0, msg, sendOpt};
502 err = msg_mms_retrieve_message(hMsgHandle, &req);
504 if (err != MSG_SUCCESS)
505 printf("Retrieve MMS Message Failed!");
507 msg_release_message(&msg);
512 @defgroup MESSAGE_USECASES_7 Getting a SMS Message
513 @ingroup MESSAGE_USECASES
515 <h3 class="pg">Getting a SMS Message</h3>
516 - int msg_get_message(MSG_HANDLE_T handle, MSG_MESSAGE_ID_T msg_id, msg_message_t msg, MSG_SENDINGOPT_S *send_opt);
517 @n msg_get_message() is a function to get a message. The first parameter is the handle which is created by msg_open_msg_handle (). The second parameter is the message ID you want to get. The third parameter is the message object to receive the message information. The last parameter is the structure to receive the message sending options.
519 - int msg_get_message_id(msg_message_t msg);
520 @n msg_get_message_id() is a function to get the message ID. The parameter is the message object. If the function is successful, it returns the message ID. Otherwise it returns an error in enum type (_MSG_ERROR_E).
522 - int msg_get_folder_id(msg_message_t msg);
523 @n msg_get_folder_id() is a function to get the ID of the folder that the message is saved within. The parameter is the message object. If the function is successful, it returns one of the enum type in (_MSG_FOLDER_ID_E) . Otherwise it returns an error in enum type (_MSG_ERROR_E).
525 - int msg_get_message_type(msg_message_t msg);
526 @n msg_get_message_type() is a function to get the message type. The parameter is the message object. If the function is successful, it returns one of the enum type in (_MSG_MESSAGE_TYPE_E). Otherwise it returns an error in enum type (_MSG_ERROR_E).
528 - int msg_get_address_count(msg_message_t msg);
529 @n msg_get_address_count() is a function to get the number of addresses. The parameter is the message object. If the function is successful, it returns the number of addresses. Otherwise it returns an error in enum type (_MSG_ERROR_E).
531 - const char* msg_get_ith_address(msg_message_t msg, int ith);
532 @n msg_get_ith_address() is a function to get the ith address of message. The first parameter is the message object. The second parameter is the index of address you want to get. If the function is successful, it returns the address string. Otherwise it returns NULL.
534 - time_t* msg_get_time(msg_message_t msg);
535 @n msg_get_time() is a function to get the time value of message. The parameter is the message object. If the function is successful, it returns the time value. Otherwise it returns NULL.
537 - int msg_get_network_status(msg_message_t msg);
538 @n msg_get_network_status() is a function to get the network status of message. The parameter is the message object. If the function is successful, it returns one of the enum type in (_MSG_NETWORK_STATUS_E). Otherwise it returns an error in enum type (_MSG_ERROR_E).
540 - bool msg_is_read(msg_message_t msg);
541 @n msg_is_read() is a function to check whether the message was read or not. The parameter is the message object. If the message was read, it returns true. Otherwise it returns false.
543 - bool msg_is_protected(msg_message_t msg);
544 @n msg_is_protected() is a function to check whether the message is protected or not. The parameter is the message object. If the the message was protected, it returns true. Otherwise it returns false.
546 - int msg_get_message_body_size(msg_message_t msg);
547 @n msg_get_message_body_size() is a function to get the byte size of message. The parameter is the message object. If the function is successful, it returns the byte size of message. Otherwise it returns an error in enum type (_MSG_ERROR_E).
549 - const char* msg_sms_get_message_body(msg_message_t msg);
550 @n msg_sms_get_message_body() is a function to get the body data of message. The first parameter is the message object. If the function is successful, it returns the body data. Otherwise it returns NULL.
552 void MsgTestGetSmsMessage(MSG_HANDLE_T hMsgHandle, int MsgId)
554 if (hMsgHandle == NULL)
556 printf("Handle is NULL\n");
560 MSG_ERROR_T err = MSG_SUCCESS;
562 msg_message_t msg = msg_new_message();
563 MSG_SENDINGOPT_S sendOpt = {0, };
566 err = msg_get_message(hMsgHandle, (MSG_MESSAGE_ID_T)MsgId, msg, &sendOpt);
568 if (err != MSG_SUCCESS) goto free_memory;
570 printf("msgId = %d\n", msg_get_message_id(msg));
571 printf("folderId = %d\n", msg_get_folder_id(msg));
572 printf("msgType = %d\n", msg_get_message_type(msg));
573 printf("phone number = %s\n", msg_get_ith_address(msg, 0));
574 printf("displayTime = %s\n", ctime(msg_get_time(msg)));
575 printf("networkStatus = %d\n", msg_get_network_status(msg));
576 printf("bRead = %d\n", msg_is_read(msg));
577 printf("bProtected = %d\n", msg_is_protected(msg));
578 printf("dataSize = %d\n", msg_get_message_body_size(msg));
579 printf("msgData = %s\n", msg_sms_get_message_body(msg));
582 msg_release_message(&msg);
587 @defgroup MESSAGE_USECASES_8 Getting a MMS Message
588 @ingroup MESSAGE_USECASES
590 <h3 class="pg">Getting a MMS Message</h3>
591 - int msg_mms_get_message_body(msg_message_t msg, MMS_MESSAGE_DATA_S *body);
592 @n msg_get_address_count. The parameter is the message object. The second parameter is the structure to receive MMS data as output. If the function is successful, it returns MSG_SUCCESS. Otherwise it returns an error in enum type (_MSG_ERROR_E).
593 - MMS_SMIL_REGION* msg_mms_get_smil_region(MMS_MESSAGE_DATA_S msgBody, int region_idx);
594 @n msg_mms_get_smil_region() is a function to get a SMIL region information. The first parameter is the structure of MMS data. The second parameter is the index of SMIL region you want to get. If the function is successful, it returns the structure which contains the SMIL region information. Otherwise it returns NULL.
595 - MMS_PAGE_S* msg_mms_get_page(MMS_MESSAGE_DATA_S msgBody, int page_idx);
596 @n msg_mms_get_page() is a function to get a SMIL page information. The first parameter is the structure of MMS data. The second parameter is the index of SMIL page you want to get. If the function is successful, it returns the structure which contains the SMIL page information. Otherwise it returns NULL.
597 - MMS_MEDIA_S* msg_mms_get_media(MMS_PAGE_S *page, int media_idx);
598 @n msg_mms_get_media() is a function to get a media information in a SMIL page. The first parameter is the structure of SMIL page you want to get the media from. The second parameter is the index of media you want to get. If the function is successful, it returns the structure which contains the media information. Otherwise it returns NULL.
599 - MMS_ATTACH_S* msg_mms_get_attachment(MMS_MESSAGE_DATA_S msgBody, int attach_idx);
600 @n msg_mms_get_attachment() is a function to get the file information of an attachment. The first parameter is the structure of MMS data. The second parameter is the index of attachment you want to get. If the function is successful, it returns the structure which contains the attachment file information. Otherwise it returns NULL.
601 - const char* msg_get_subject(msg_message_t msg);
602 @n msg_get_subject() is a function to get the subject of MMS. The parameter is the message object. If the function is successful, it returns the subject string. Otherwise it returns NULL.
604 void MsgTestGetMmsMessage(MSG_HANDLE_T hMsgHandle, int MsgId)
606 if (hMsgHandle == NULL)
608 printf("Handle is NULL\n");
612 MSG_ERROR_T err = MSG_SUCCESS;
614 msg_message_t msg = msg_new_message();
615 MSG_SENDINGOPT_S sendOpt = {0, };
618 err = msg_get_message(hMsgHandle, (MSG_MESSAGE_ID_T)MsgId, msg, &sendOpt);
620 if (err != MSG_SUCCESS) goto free_memory;
622 if (msg_is_mms(msg) == false)
624 printf("It is not MMS Message!");
628 MMS_MESSAGE_DATA_S* msgBody = msg_mms_create_message();
631 msg_mms_get_message_body(msg, msgBody);
633 //Print root-layout info
637 msgBody->rootlayout.width.value,
638 msgBody->rootlayout.height.value,
639 msgBody->rootlayout.bgColor);
642 for (int i = 0; i < msgBody->regionCnt; ++i)
644 MMS_SMIL_REGION* pRegion = msg_mms_get_smil_region(msgBody, i);
646 printf("region id: %s\n
651 region bgColor : %x\n
653 pRegion->szID,pRegion->nLeft.value,
654 pRegion->nTop.value,pRegion->width.value,
655 pRegion->height.value, pRegion->bgColor,
660 for (int i = 0; i< msgBody->pageCnt; ++i)
662 MMS_PAGE_S* pPage = msg_mms_get_page(msgBody, i);
664 printf("page's duration: %d msec\n
665 page's media count: %d\n",
666 pPage->nDur, pPage->mediaCnt);
668 // Print Contents Info
669 for(int j = 0; j < pPage->mediaCnt; ++j)
671 MMS_MEDIA_S* pMedia = msg_mms_get_media(pPage, j);
672 printf("media's filename: %s\n
673 media's filepath: %s\n
674 media's regionId: %s\n
675 Bold: %d Italic: %d\n",
679 pMedia->sMedia.sText.bBold,
680 pMedia->sMedia.sText.bItalic);
682 if(pMedia->drmType != MSG_DRM_TYPE_NONE)
684 printf("media's drmtype: %d\n
685 media's drmpath: %s\n",
686 pMedia->drmType, pMedia->szDrm2FullPath);
691 for (int i = 0; i < msgBody->attachCnt; ++i)
693 MMS_ATTACH_S* pAttach = msg_mms_get_attachment(msgBody, i);
695 printf("Attachment file Name: %s\n
696 Attachment file Path: %s\n
697 Attached file size: %d\n",
702 if(pAttach->drmType != MSG_DRM_TYPE_NONE)
703 printf("media's drmtype: %d\n
704 media's drmpath: %s\n",
705 pAttach->drmType, pAttach->szDrm2FullPath);
708 printf("Subject: %s\n", msg_get_subject(pMsg));
710 printf("msgId = %d", msg_get_message_id(msg));
711 printf("folderId = %d", msg_get_folder_id(msg));
712 printf("phone number = %s", msg_get_ith_address(msg, 0));
713 printf("displayTime = %s", ctime(msg_get_time(msg)));
714 printf("networkStatus = %d", msg_get_network_status(msg));
715 printf("bRead = %d", msg_is_read(msg));
716 printf("bProtected = %d", msg_is_protected(msg));
719 msg_mms_destroy_message(msgBody);
721 msg_release_message(&msg);
726 @defgroup MESSAGE_USECASES_9 Delete a Message
727 @ingroup MESSAGE_USECASES
729 <h3 class="pg">Delete a Message</h3>
730 - int msg_delete_message(MSG_HANDLE_T handle, MSG_MESSAGE_ID_T msg_id);
731 @n msg_delete_message() is a function to delete a message from message box by msg_id.
733 void MsgTestDeleteMessage(MSG_HANDLE_T hMsgHandle, MSG_MESSAGE_ID_T nMsgId)
737 if (msg_delete_message(hMsgHandle, nMsgId) != MSG_SUCCESS)
738 printf("Failed to delete Message");
744 @defgroup MESSAGE_USECASES_10 Set/Get Message Setting
745 @ingroup MESSAGE_USECASES
747 <h3 class="pg">Set / Get Message setting</h3>
748 msg_set_config() and msg_get_cofig() is used to set or to get the message setting options. MSG_SETTING_S structure includes various setting information and is shared between message application and messaging daemon.
750 - int msg_set_config(MSG_HANDLE_T handle, const MSG_SETTING_S *setting);
751 @n msg_set_config() sets a message option.
752 - int msg_get_config(MSG_HANDLE_T handle, MSG_SETTING_S *setting);
753 @n msg_get_config() gets a message option.
755 void MsgTestSetGeneralOpt(MSG_HANDLE_T hMsgHandle)
757 MSG_ERROR_T err = MSG_SUCCESS;
758 MSG_SETTING_S setting = {0, };
760 setting.type = MSG_GENERAL_OPT;
762 setting.option.generalOpt.bKeepCopy = true;
763 setting.option.generalOpt.alertTone = MSG_ALERT_TONE_ONCE;
765 err = msg_set_config(hMsgHandle, &setting);
767 if (err == MSG_SUCCESS)
768 printf("Setting Config Data is OK!");
770 printf("Setting Config Data is failed!");
773 void MsgTestGetGeneralOpt(MSG_HANDLE_T hMsgHandle)
775 MSG_ERROR_T err = MSG_SUCCESS;
776 MSG_SETTING_S setting = {0, };
778 err = msg_get_config(hMsgHandle, &setting);
780 if (err == MSG_SUCCESS)
782 printf("Setting Config Data is OK!\n");
783 printf("bKeepCopy : [%d], AlertTone : [%d]\n", setting.option.generalOpt.bKeepCopy, setting.option.generalOpt.alertTone);
786 printf("Setting Config Data is failed!\n");
791 @defgroup MESSAGE_USECASES_11 Filtering a Message
792 @ingroup MESSAGE_USECASES
794 <h3 class="pg">Filtering a Message</h3>
795 Messaging framework provides a filtering function for incoming message. New incoming message can be blocked (Move to spam-box or discard) by adding a filtering rule. A incoming message can be blocked by its originating address or by subject matching. If address matching filter rule is applied, only messages with exactly the same phone number can be blocked. Whereas, if a subject matching filter rule is applied, all messages that include the registered subject string might be blocked. An application can add or remove a filtering rule by calling msg_add_filter() or msg_delete_filter().
797 - int msg_add_filter(MSG_HANDLE_T handle, const MSG_FILTER_S *filter);
798 @n msg_add_filter() inserts a filtering rule to filter list and returns filter id.
799 - int msg_delete_filter(MSG_HANDLE_T handle, MSG_FILTER_ID_T filter_id);
800 @n msg_delete_filter()removes a filtering rule from filter list by filter id
802 void MsgTestAddFilter(MSG_HANDLE_T hMsgHandle)
804 if (hMsgHandle == NULL)
806 printf("Handle is NULL");
810 MSG_ERROR_T err = MSG_SUCCESS;
811 MSG_FILTER_S filter[2]= {0, };
813 // Add filter by address
814 filter[0].filterType = MSG_FILTER_BY_ADDRESS;
815 strncpy(filter[0].filterValue, "+821234567890", MAX_FILTER_VALUE_LEN);
817 err = msg_add_filter(hMsgHandle, &filter[0]);
819 if (err == MSG_SUCCESS)
820 printf("msg_add_filter success");
822 printf("msg_add_filter fail - err [%d]", err);
824 // Add filter by subject
825 filter[1].filterType = MSG_FILTER_BY_SUBJECT;
826 strncpy(filter[1].filterValue, "test filter", MAX_FILTER_VALUE_LEN);
828 err = msg_add_filter(hMsgHandle, &filter[1]);
830 if (err == MSG_SUCCESS)
831 printf("msg_add_filter success");
833 printf("msg_add_filter fail - err [%d]", err);
838 void MsgTestDeleteFilter(MSG_HANDLE_T hMsgHandle, MSG_FILTER_ID_T filterId)
840 if (hMsgHandle == NULL)
842 printf("Handle is NULL");
846 MSG_ERROR_T err = MSG_SUCCESS;
847 err = msg_delete_filter(hMsgHandle, filterId);
849 if (MSG_SUCCESS == err)
851 printf("msg_delete_filter success");
855 printf("msg_delete_filter fail - err [%d]", err);
867 @defgroup MESSAGE_USECASES Use Cases