The Messages API provides functions to create, set properties, and send a SMS/MMS message.

Required Header

#include <messages.h>

Overview

The Messages API provides the following functionalities:

Creating a message
Setting the text of the message
Setting the message recipient(s)
Sending a message
Searching for messages
Registering/Unregistering a callback function to check whether a message is sent successfully or not
Registering/Unregistering a callback function to receive notifications when an incoming message is received

Related Features

This API is related with the following features:

http://tizen.org/feature/network.telephony
http://tizen.org/feature/network.telephony.sms
http://tizen.org/feature/network.telephony.mms
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.

Functions
int	messages_open_service (messages_service_h *service)
	Opens a handle for the messaging service.
int	messages_close_service (messages_service_h service)
	Closes a handle for the messaging service.
int	messages_create_message (messages_message_type_e type, messages_message_h *msg)
	Creates a message handle.
int	messages_destroy_message (messages_message_h msg)
	Destroys a message handle and releases all its resources.
int	messages_add_message (messages_service_h service, messages_message_h msg, int *msg_id)
	Adds the message to message database.
int	messages_get_message_id (messages_message_h msg, int *msg_id)
	Gets the message ID of the message.
int	messages_set_sim_id (messages_message_h msg, int sim_id)
	Sets the SIM ID of the sending message.
int	messages_get_sim_id (messages_message_h msg, int *sim_id)
	Gets the SIM ID of the message.
int	messages_set_mbox_type (messages_message_h msg, messages_message_box_e mbox)
	Sets the message box type of the message.
int	messages_get_mbox_type (messages_message_h msg, messages_message_box_e *mbox)
	Gets the message box type of the message.
int	messages_get_message_port (messages_message_h msg, int *port)
	Gets the destination port of the message.
int	messages_get_message_type (messages_message_h msg, messages_message_type_e *type)
	Gets the type of the message.
int	messages_add_address (messages_message_h msg, const char *address, messages_recipient_type_e type)
	Adds an recipient's address(phone number) to the message.
int	messages_get_address_count (messages_message_h msg, int *count)
	Gets the total number of recipients in the message.
int	messages_get_address (messages_message_h msg, int index, char *address, messages_recipient_type_e type)
	Gets a recipient's address with specified index.
int	messages_remove_all_addresses (messages_message_h msg)
	Removes all recipients in the message.
int	messages_set_text (messages_message_h msg, const char *text)
	Sets the text of the message.
int	messages_get_text (messages_message_h msg, char **text)
	Gets the text of the message.
int	messages_set_time (messages_message_h msg, time_t time)
	Sets the time of the message.
int	messages_get_time (messages_message_h msg, time_t *time)
	Gets the time of the message.
int	messages_send_message (messages_service_h service, messages_message_h msg, bool save_to_sentbox, messages_sent_cb callback, void *user_data)
	Sends the message to all recipients.
int	messages_get_message_count (messages_service_h service, messages_message_box_e mbox, messages_message_type_e type, int *count)
	Gets the message count in the specific message box.
int	messages_search_message (messages_service_h service, messages_message_box_e mbox, messages_message_type_e type, const char keyword, const char address, int offset, int limit, messages_message_h *message_array, int length, int *total)
	Searches for messages.
int	messages_search_message_by_id (messages_service_h service, int msg_id, messages_message_h *msg)
	Searches a message with the given message ID.
int	messages_free_message_array (messages_message_h *message_array)
	Frees the message array.
int	messages_foreach_message (messages_service_h service, messages_message_box_e mbox, messages_message_type_e type, const char keyword, const char address, int offset, int limit, messages_search_cb callback, void *user_data)
	Retrieves the searched messages by invoking the given callback function iteratively.
int	messages_set_message_incoming_cb (messages_service_h service, messages_incoming_cb callback, void *user_data)
	Registers a callback to be invoked when an incoming message is received.
int	messages_unset_message_incoming_cb (messages_service_h service)
	Unregisters the callback function.
int	messages_add_sms_listening_port (messages_service_h service, int port)
	Adds an additional listening port for the incoming SMS messages.
Typedefs
typedef struct messages_service_s *	messages_service_h
	The messaging service handle.
typedef struct messages_message_s *	messages_message_h
	The message handle.
typedef void(*	messages_sent_cb )(messages_sending_result_e result, void *user_data)
	Called when the process of sending a message to all recipients finishes.
typedef void(*	messages_incoming_cb )(messages_message_h incoming_msg, void *user_data)
	Called when an incoming message is received.
typedef bool(*	messages_search_cb )(messages_message_h msg, int index, int result_count, int total_count, void *user_data)
	Called when a message is retrieved from a search request.

Typedef Documentation

typedef void(* messages_incoming_cb)(messages_message_h incoming_msg, void *user_data)

Called when an incoming message is received.

Since :: 2.3

Parameters:

[in]	incoming_msg	The incoming message
[in]	user_data	The user data passed from the callback registration function

Precondition:: You register this callback using messages_set_message_incoming_cb() for getting an incoming message.

See also:: messages_set_message_incoming_cb(); messages_unset_message_incoming_cb()

typedef struct messages_message_s* messages_message_h

The message handle.

Since :: 2.3

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

Called when a message is retrieved from a search request.

Since :: 2.3

Remarks:: You should not call messages_destroy_message() with msg.

Parameters:

[in]	msg	The message handle It can be `NULL` if nothing is found
[in]	user_data	The user data passed from the foreach function
[in]	index	The index of a message from the messages that have been retrieved as a search result
[in]	result_count	The count of the messages that have been retrieved as a result applying limit and offset If the search has a limit, then this value is always equal or less than the limit
[in]	total_count	The count of the messages that have been retrieved as a result without applying limit and offset The value can be used to calculate the total number of page views for the searched messages. For example, if the count of message search is `50` and the limit is `20`, then using this value, you can notice the total page is `3`

Returns:: true to continue with the next iteration of the loop, otherwise return false to break out of the loop

Precondition:: messages_foreach_message() will invoke this callback function.

See also:: messages_foreach_message()

typedef void(* messages_sent_cb)(messages_sending_result_e result, void *user_data)

Called when the process of sending a message to all recipients finishes.

Since :: 2.3

Parameters:

[in]	result	The result of message sending
[in]	user_data	The user data passed from the callback registration function

Precondition:: messages_send_message() will invoke this callback function.

See also:: messages_send_message()

typedef struct messages_service_s* messages_service_h

The messaging service handle.

Since :: 2.3

Enumeration Type Documentation

enum messages_error_e

Enumeration for Messaging of error code.

Enumerator:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_SERVER_NOT_READY	Server is not read
MESSAGES_ERROR_COMMUNICATION_WITH_SERVER_FAILED	Communication with server failed
MESSAGES_ERROR_OUT_OF_RANGE	Index out of range
MESSAGES_ERROR_SENDING_FAILED	Sending a message failed
MESSAGES_ERROR_OPERATION_FAILED	Messaging operation failed
MESSAGES_ERROR_NO_SIM_CARD	No SIM Card
MESSAGES_ERROR_NO_DATA	No data available
MESSAGES_ERROR_PERMISSION_DENIED	Permission denied
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

enum messages_media_type_e

Enumeration for the attachment type for MMS messaging.

Since :: 2.3

Enumerator:

MESSAGES_MEDIA_UNKNOWN	Unknown
MESSAGES_MEDIA_IMAGE	The image
MESSAGES_MEDIA_AUDIO	The audio
MESSAGES_MEDIA_VIDEO	The video

enum messages_message_box_e

Enumeration for the message box type.

Since :: 2.3

Enumerator:

MESSAGES_MBOX_ALL	All message box type
MESSAGES_MBOX_INBOX	Inbox type
MESSAGES_MBOX_OUTBOX	Outbox type
MESSAGES_MBOX_SENTBOX	Sentbox type
MESSAGES_MBOX_DRAFT	Draft type

enum messages_message_type_e

Enumeration for the message type.

Since :: 2.3

Enumerator:

MESSAGES_TYPE_UNKNOWN	Unknown type
MESSAGES_TYPE_SMS	SMS type
MESSAGES_TYPE_MMS	MMS type
MESSAGES_TYPE_SMS_CB	CB(Cell Broadcast) Type
MESSAGES_TYPE_SMS_PUSH	WAP Push Type
MESSAGES_TYPE_SMS_ETWS_PRIMARY	ETWS(Earthquake and Tsunami Warning System) Primary Type
MESSAGES_TYPE_SMS_ETWS_SECONDARY	ETWS(Earthquake and Tsunami Warning System) Secondary Type

enum messages_recipient_type_e

Enumeration for the recipient type of a message.

Since :: 2.3

Enumerator:

MESSAGES_RECIPIENT_UNKNOWN	Unknown
MESSAGES_RECIPIENT_TO	The 'To' recipient
MESSAGES_RECIPIENT_CC	The 'Cc' (carbon copy) recipient
MESSAGES_RECIPIENT_BCC	The 'Bcc' (blind carbon copy) recipient

enum messages_sending_result_e

Enumeration for the result of sending a message.

Since :: 2.3

Enumerator:

MESSAGES_SENDING_FAILED	Message sending failed
MESSAGES_SENDING_SUCCEEDED	Message sending succeeded

enum messages_sim_index_e

Enumeration for the SIM index of a message.

Since :: 2.3

Enumerator:

MESSAGES_SIM_INDEX_UNKNOWN	Unknown SIM Index
MESSAGES_SIM_INDEX_1	SIM Index 1
MESSAGES_SIM_INDEX_2	SIM Index 2

Function Documentation

int messages_add_address	(	messages_message_h	msg,
		const char *	address,
		messages_recipient_type_e	type
	)

Adds an recipient's address(phone number) to the message.

The maximum number of recipients per message is 10.

Since :: 2.3

Parameters:

[in]	msg	The message handle
[in]	address	The recipient's address to receive a message The maximum length of address is `254`.
[in]	type	The recipient's type of the address

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_get_address(); messages_remove_all_addresses()

int messages_add_message	(	messages_service_h	service,
		messages_message_h	msg,
		int *	msg_id
	)

Adds the message to message database.

Since :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/message.write

Parameters:

[in]	service	The message service handle
[in]	msg	The message handle
[out]	msg_id	The message ID of added message

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_OPERATION_FAILED	Messaging operation failed
MESSAGES_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_create_message()

int messages_add_sms_listening_port	(	messages_service_h	service,
		int	port
	)

Adds an additional listening port for the incoming SMS messages.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/message.read

Parameters:

[in]	service	The message service handle
[in]	port	The listening port for the SMS messages

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_set_message_incoming_cb(); messages_get_message_port()

int messages_close_service ( messages_service_h service )

Closes a handle for the messaging service.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/message.read

Parameters:

[in] service The message service handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_COMMUNICATION_WITH_SERVER_FAILED	Communication with server failed
MESSAGES_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_open_service()

int messages_create_message	(	messages_message_type_e	type,
		messages_message_h *	msg
	)

Creates a message handle.

Since :: 2.3

Remarks:: You must release msg using messages_destroy_message().

Parameters:

[in]	type	The message type (MESSAGES_TYPE_SMS or MESSAGES_TYPE_MMS) If type is MESSAGES_TYPE_UNKNOWN, MESSAGES_ERROR_INVALID_PARAMETER occurs
[out]	msg	The message handle that is newly created if successful

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_destroy_message()

int messages_destroy_message ( messages_message_h msg )

Destroys a message handle and releases all its resources.

Since :: 2.3

Parameters:

[in] msg The message handle to destroy

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_create_message()

int messages_foreach_message	(	messages_service_h	service,
		messages_message_box_e	mbox,
		messages_message_type_e	type,
		const char *	keyword,
		const char *	address,
		int	offset,
		int	limit,
		messages_search_cb	callback,
		void *	user_data
	)

Retrieves the searched messages by invoking the given callback function iteratively.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/message.read

Parameters:

[in]	service	The message service handle
[in]	mbox	The message box type
[in]	type	The message type If type is MESSAGES_TYPE_UNKNOWN, all SMS and MMS messages are searched
[in]	keyword	The keyword search in the text and subject
[in]	address	The recipient address
[in]	offset	The start position (base 0)
[in]	limit	The maximum amount of messages to get In case of `0`, this method passes to the callback all searched messages
[in]	callback	The callback function to get a message
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGES_ERROR_OPERATION_FAILED	Messaging operation failed
MESSAGES_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

Postcondition:: It invokes messages_search_cb().

See also:: messages_search_cb()

int messages_free_message_array ( messages_message_h * message_array )

Frees the message array.

Since :: 2.3

Parameters:

[in] message_array The array of the message handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_search_message()

int messages_get_address	(	messages_message_h	msg,
		int	index,
		char **	address,
		messages_recipient_type_e *	type
	)

Gets a recipient's address with specified index.

Since :: 2.3

Remarks:: You must release address using free().

Parameters:

[in]	msg	The message handle
[in]	index	The zero-based index of an address to receive a message
[out]	address	The recipient's address with specified index
[out]	type	The recipient's type of the address

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_add_address(); messages_remove_all_addresses()

int messages_get_address_count	(	messages_message_h	msg,
		int *	count
	)

Gets the total number of recipients in the message.

Since :: 2.3

Parameters:

[in]	msg	The message handle
[out]	count	The total number of recipients

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_add_address(); messages_remove_all_addresses()

int messages_get_mbox_type	(	messages_message_h	msg,
		messages_message_box_e *	mbox
	)

Gets the message box type of the message.

Since :: 2.3

Parameters:

[in]	msg	The message handle
[out]	mbox	The message box type

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

int messages_get_message_count	(	messages_service_h	service,
		messages_message_box_e	mbox,
		messages_message_type_e	type,
		int *	count
	)

Gets the message count in the specific message box.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/message.read

Parameters:

[in]	service	The message service handle
[in]	mbox	The message box type
[in]	type	The message type If type is MESSAGES_TYPE_UNKNOWN, all SMS and MMS messages are counted
[out]	count	The number of messages

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_OPERATION_FAILED	Messaging operation failed
MESSAGES_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

int messages_get_message_id	(	messages_message_h	msg,
		int *	msg_id
	)

Gets the message ID of the message.

Since :: 2.3

Parameters:

[in]	msg	The message handle
[out]	msg_id	The message ID

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_OPERATION_FAILED	Messaging operation failed
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_search_message_by_id()

int messages_get_message_port	(	messages_message_h	msg,
		int *	port
	)

Gets the destination port of the message.

Since :: 2.3

Parameters:

[in]	msg	The message handle
[out]	port	The destination port of the message

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_add_sms_listening_port()

int messages_get_message_type	(	messages_message_h	msg,
		messages_message_type_e *	type
	)

Gets the type of the message.

Since :: 2.3

Parameters:

[in]	msg	The message handle
[out]	type	The message type

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

int messages_get_sim_id	(	messages_message_h	msg,
		int *	sim_id
	)

Gets the SIM ID of the message.

Since :: 2.3

Parameters:

[in]	msg	The message handle
[out]	sim_id	The SIM ID of message

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_OPERATION_FAILED	Messaging operation failed
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_set_sim_id()

int messages_get_text	(	messages_message_h	msg,
		char **	text
	)

Gets the text of the message.

Since :: 2.3

Remarks:: You must release text using free().

Parameters:

[in]	msg	The message handle
[out]	text	The text of the message

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_set_text()

int messages_get_time	(	messages_message_h	msg,
		time_t *	time
	)

Gets the time of the message.

Since :: 2.3

Parameters:

[in]	msg	The message handle
[out]	time	The time of the message

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

int messages_open_service ( messages_service_h * service )

Opens a handle for the messaging service.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/message.read

Remarks:: You must release service using messages_close_service().

Parameters:

[out] service The message service handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_SERVER_NOT_READY	Server is not ready
MESSAGES_ERROR_COMMUNICATION_WITH_SERVER_FAILED	Communication with server failed
MESSAGES_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_close_service()

int messages_remove_all_addresses ( messages_message_h msg )

Removes all recipients in the message.

Since :: 2.3

Parameters:

[in] msg The message handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_add_address(); messages_get_address()

int messages_search_message	(	messages_service_h	service,
		messages_message_box_e	mbox,
		messages_message_type_e	type,
		const char *	keyword,
		const char *	address,
		int	offset,
		int	limit,
		messages_message_h **	message_array,
		int *	length,
		int *	total
	)

Searches for messages.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/message.read

Remarks:: You must release message_array using messages_free_message_array().

Parameters:

[in]	service	The message service handle
[in]	mbox	The message box type
[in]	type	The message type If type is MESSAGES_TYPE_UNKNOWN, all SMS and MMS messages are searched
[in]	keyword	The keyword search in the text and subject
[in]	address	The recipient address
[in]	offset	The start position (base `0`)
[in]	limit	The maximum amount of messages to get In case of `0`, this method passes to the callback all searched messages
[out]	message_array	The array of the message handle
[out]	length	The number of messages of the message_array
[out]	total	The count of the messages that have been retrieved as a result without applying limit and offset The value can be used to calculate the total number of page views for the searched messages For example, if the count of message search is `50` and the limit is `20`, then using this value, you can notice the total page is `3`

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGES_ERROR_OPERATION_FAILED	Messaging operation failed
MESSAGES_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_free_message_array()

int messages_search_message_by_id	(	messages_service_h	service,
		int	msg_id,
		messages_message_h *	msg
	)

Searches a message with the given message ID.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/message.read

Remarks:: You must release msg using messages_destroy_message().

Parameters:

[in]	service	The message service handle
[in]	msg_id	The message ID
[out]	msg	The message handle that is newly created if successful

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGES_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_get_message_id()

int messages_send_message	(	messages_service_h	service,
		messages_message_h	msg,
		bool	save_to_sentbox,
		messages_sent_cb	callback,
		void *	user_data
	)

Sends the message to all recipients.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/message.write

Parameters:

[in]	service	The message service handle
[in]	msg	The message handle
[in]	save_to_sentbox	Set to `true` to save the message in the sentbox, otherwise set to `false` to not save the message in the sentbox
[in]	callback	The callback function
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_SENDING_FAILED	Sending message failed
MESSAGES_ERROR_OPERATION_FAILED	Messaging operation failed
MESSAGES_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_sent_cb()

int messages_set_mbox_type	(	messages_message_h	msg,
		messages_message_box_e	mbox
	)

Sets the message box type of the message.

Since :: 3.0

Parameters:

[in]	msg	The message handle
[in]	mbox	The message box type

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

int messages_set_message_incoming_cb	(	messages_service_h	service,
		messages_incoming_cb	callback,
		void *	user_data
	)

Registers a callback to be invoked when an incoming message is received.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/message.read

Parameters:

[in]	service	The message service handle
[in]	callback	The callback function
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_OPERATION_FAILED	Messaging operation failed
MESSAGES_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

Postcondition:: It will invoke messages_incoming_cb().

See also:: messages_unset_message_incoming_cb(); messages_incoming_cb()

int messages_set_sim_id	(	messages_message_h	msg,
		int	sim_id
	)

Sets the SIM ID of the sending message.

Since :: 2.3

Parameters:

[in]	msg	The message handle
[in]	sim_id	The SIM ID to send message

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_OPERATION_FAILED	Messaging operation failed
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_get_sim_id()

int messages_set_text	(	messages_message_h	msg,
		const char *	text
	)

Sets the text of the message.

Since :: 2.3

Parameters:

[in]	msg	The message handle
[in]	text	The text of the message The maximum length of text is `1530`

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_OUT_OF_MEMORY	Out of memory
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_get_text()

int messages_set_time	(	messages_message_h	msg,
		time_t	time
	)

Sets the time of the message.

Since :: 3.0

Parameters:

[in]	msg	The message handle
[in]	time	The time of the message

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

int messages_unset_message_incoming_cb ( messages_service_h service )

Unregisters the callback function.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/message.write

Parameters:

[in] service The message service handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MESSAGES_ERROR_NONE	Successful
MESSAGES_ERROR_INVALID_PARAMETER	Invalid parameter
MESSAGES_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
MESSAGES_ERROR_NOT_SUPPORTED	Not supported

See also:: messages_set_message_incoming_cb(); messages_incoming_cb()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation