diff options
Diffstat (limited to 'include/messages.h')
| -rw-r--r-- | include/messages.h | 761 |
1 files changed, 287 insertions, 474 deletions
diff --git a/include/messages.h b/include/messages.h index 4ba0fb2..4995ebc 100644 --- a/include/messages.h +++ b/include/messages.h @@ -14,6 +14,7 @@ * limitations under the License. */ + #ifndef __TIZEN_MESSAGING_H__ #define __TIZEN_MESSAGING_H__ @@ -22,11 +23,13 @@ #include <messages_types.h> #include <messages_error.h> + #ifdef __cplusplus extern "C" { #endif + /* * @file messages.h * @brief This file contains the messages API. @@ -41,25 +44,19 @@ extern "C" /** * @brief Opens a handle for the messaging service. - * * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/message.read - * * @remarks You must release @a service using messages_close_service(). - * * @param[out] service The message service handle - * * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_SERVER_NOT_READY Server is not read + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_SERVER_NOT_READY Server is not ready * @retval #MESSAGES_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed - * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_close_service() */ int messages_open_service(messages_service_h *service); @@ -67,22 +64,17 @@ int messages_open_service(messages_service_h *service); /** * @brief Closes a handle for the messaging service. - * * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/message.read - * * @param[in] service The message service handle - * * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MESSAGES_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed - * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_open_service() */ int messages_close_service(messages_service_h service); @@ -90,23 +82,17 @@ int messages_close_service(messages_service_h service); /** * @brief Creates a message handle. - * * @since_tizen 2.3 - * * @remarks You must release @a msg using messages_destroy_message(). - * - * @param[in] type The message type (#MESSAGES_TYPE_SMS or #MESSAGES_TYPE_MMS) \n - * If @a type is #MESSAGES_TYPE_UNKNOWN, #MESSAGES_ERROR_INVALID_PARAMETER occurs. - * @param[out] msg The message handle that is newly created if successful - * + * @param[in] type The message type (#MESSAGES_TYPE_SMS or #MESSAGES_TYPE_MMS) \n + * If @a type is #MESSAGES_TYPE_UNKNOWN, #MESSAGES_ERROR_INVALID_PARAMETER occurs + * @param[out] msg The message handle that is newly created if successful * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_destroy_message() */ int messages_create_message(messages_message_type_e type, messages_message_h *msg); @@ -114,18 +100,13 @@ int messages_create_message(messages_message_type_e type, messages_message_h *ms /** * @brief Destroys a message handle and releases all its resources. - * * @since_tizen 2.3 - * * @param[in] msg The message handle to destroy - * * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_create_message() */ int messages_destroy_message(messages_message_h msg); @@ -133,45 +114,35 @@ int messages_destroy_message(messages_message_h msg); /** * @brief Adds the message to message database. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/message.write - * - * @param[in] service The message service handle - * @param[in] msg The message handle - * @param[out] msg_id The message ID of added message - * + * @param[in] service The message service handle + * @param[in] msg The message handle + * @param[out] msg_id The message ID of added message * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed + * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_create_message() - * */ int messages_add_message(messages_service_h service, messages_message_h msg, int *msg_id); + /** * @brief Gets the message ID of the message. - * * @since_tizen 2.3 - * - * @param[in] msg The message handle - * @param[out] msg_id The message ID - * + * @param[in] msg The message handle + * @param[out] msg_id The message ID * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_search_message_by_id() */ int messages_get_message_id(messages_message_h msg, int *msg_id); @@ -179,20 +150,15 @@ int messages_get_message_id(messages_message_h msg, int *msg_id); /** * @brief Sets the SIM ID of the sending message. - * * @since_tizen 2.3 - * - * @param[in] msg The message handle - * @param[in] sim_id The SIM id to send message - * + * @param[in] msg The message handle + * @param[in] sim_id The SIM ID to send message * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_get_sim_id() */ int messages_set_sim_id(messages_message_h msg, int sim_id); @@ -200,113 +166,90 @@ int messages_set_sim_id(messages_message_h msg, int sim_id); /** * @brief Gets the SIM ID of the message. - * * @since_tizen 2.3 - * - * @param[in] msg The message handle - * @param[out] sim_id The SIM id of message - * + * @param[in] msg The message handle + * @param[out] sim_id The SIM ID of message * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_set_sim_id() */ int messages_get_sim_id(messages_message_h msg, int *sim_id); + /** * @brief Sets the message box type of the message. - * * @since_tizen 3.0 - * - * @param[in] msg The message handle - * @param[in] mbox The message box type - * + * @param[in] msg The message handle + * @param[in] mbox The message box type * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported */ int messages_set_mbox_type(messages_message_h msg, messages_message_box_e mbox); + /** * @brief Gets the message box type of the message. - * * @since_tizen 2.3 - * - * @param[in] msg The message handle - * @param[out] mbox The message box type - * + * @param[in] msg The message handle + * @param[out] mbox The message box type * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported */ int messages_get_mbox_type(messages_message_h msg, messages_message_box_e *mbox); + /** * @brief Gets the destination port of the message. - * * @since_tizen 2.3 - * - * @param[in] msg The message handle - * @param[out] port The destination port of the message - * + * @param[in] msg The message handle + * @param[out] port The destination port of the message * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_add_sms_listening_port() */ int messages_get_message_port(messages_message_h msg, int *port); + /** * @brief Gets the type of the message. - * * @since_tizen 2.3 - * - * @param[in] msg The message handle + * @param[in] msg The message handle * @param[out] type The message type - * * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported */ int messages_get_message_type(messages_message_h msg, messages_message_type_e *type); /** * @brief Adds an recipient's address(phone number) to the message. - * @details The maximum number of recipients per a message is 10. - * + * @details The maximum number of recipients per message is 10. * @since_tizen 2.3 - * - * @param[in] msg The message handle - * @param[in] address The recipient's address to receive a message \n - * The maximum length of @a address is @c 254. - * @param[in] type The recipient's type of the @a address - * + * @param[in] msg The message handle + * @param[in] address The recipient's address to receive a message \n + * The maximum length of @a address is @c 254. + * @param[in] type The recipient's type of the @a address * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_get_address() * @see messages_remove_all_addresses() */ @@ -315,19 +258,14 @@ int messages_add_address(messages_message_h msg, const char *address, messages_r /** * @brief Gets the total number of recipients in the message. - * * @since_tizen 2.3 - * - * @param[in] msg The message handle - * @param[out] count The total number of recipients - * + * @param[in] msg The message handle + * @param[out] count The total number of recipients * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_add_address() * @see messages_remove_all_addresses() */ @@ -336,24 +274,18 @@ int messages_get_address_count(messages_message_h msg, int *count); /** * @brief Gets a recipient's address with specified index. - * * @since_tizen 2.3 - * * @remarks You must release @a address using free(). - * - * @param[in] msg The message handle - * @param[in] index The zero-based index of an address to receive a message. - * @param[out] address The recipient's address with specified index - * @param[out] type The recipient's type of the @a address - * + * @param[in] msg The message handle + * @param[in] index The zero-based index of an address to receive a message + * @param[out] address The recipient's address with specified index + * @param[out] type The recipient's type of the @a address * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_add_address() * @see messages_remove_all_addresses() */ @@ -362,18 +294,13 @@ int messages_get_address(messages_message_h msg, int index, char **address, mess /** * @brief Removes all recipients in the message. - * * @since_tizen 2.3 - * * @param[in] msg The message handle - * * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_add_address() * @see messages_get_address() */ @@ -382,21 +309,16 @@ int messages_remove_all_addresses(messages_message_h msg); /** * @brief Sets the text of the message. - * * @since_tizen 2.3 - * - * @param[in] msg The message handle + * @param[in] msg The message handle * @param[in] text The text of the message \n - * The maximum length of @a text is @c 1530. - * + * The maximum length of @a text is @c 1530 * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_get_text() */ int messages_set_text(messages_message_h msg, const char *text); @@ -404,151 +326,123 @@ int messages_set_text(messages_message_h msg, const char *text); /** * @brief Gets the text of the message. - * * @since_tizen 2.3 - * * @remarks You must release @a text using free(). - * - * @param[in] msg The message handle - * @param[out] text The text of the message - * + * @param[in] msg The message handle + * @param[out] text The text of the message * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_set_text() */ int messages_get_text(messages_message_h msg, char **text); + /** * @brief Sets the time of the message. - * * @since_tizen 3.0 - * - * @param[in] msg The message handle - * @param[in] time The time of the message - * + * @param[in] msg The message handle + * @param[in] time The time of the message * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported */ int messages_set_time(messages_message_h msg, time_t time); + /** * @brief Gets the time of the message. - * * @since_tizen 2.3 - * - * @param[in] msg The message handle - * @param[out] time The time of the message - * + * @param[in] msg The message handle + * @param[out] time The time of the message * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful - * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful + * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported */ int messages_get_time(messages_message_h msg, time_t *time); + /** * @brief Sends the message to all recipients. - * * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/message.write - * - * @param[in] service The message service handle - * @param[in] msg The message handle + * @param[in] service The message service handle + * @param[in] msg The message handle * @param[in] save_to_sentbox Set to @c true to save the message in the sentbox, * otherwise set to @c false to not save the message in the sentbox - * @param[in] callback The callback function - * @param[in] user_data The user data to be passed to the callback function - * + * @param[in] callback The callback function + * @param[in] user_data The user data to be passed to the callback function * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_SENDING_FAILED Sending a message failed - * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed + * @retval #MESSAGES_ERROR_SENDING_FAILED Sending message failed + * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_sent_cb() */ int messages_send_message(messages_service_h service, messages_message_h msg, bool save_to_sentbox, messages_sent_cb callback, void *user_data); + /** * @brief Gets the message count in the specific message box. * @since_tizen 2.3 - * * @privlevel public * @privilege %http://tizen.org/privilege/message.read - * - * @param[in] service The message service handle - * @param[in] mbox The message box type - * @param[in] type The message type \n - * If @a type is #MESSAGES_TYPE_UNKNOWN, all SMS and MMS messages are counted. - * @param[out] count The number of messages - * + * @param[in] service The message service handle + * @param[in] mbox The message box type + * @param[in] type The message type \n + * If @a type is #MESSAGES_TYPE_UNKNOWN, all SMS and MMS messages are counted + * @param[out] count The number of messages * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed + * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #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); +int messages_get_message_count(messages_service_h service, messages_message_box_e mbox, messages_message_type_e type, int *count); /** * @brief Searches for messages. - * * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/message.read - * * @remarks You must release @a message_array using messages_free_message_array(). - * - * @param[in] service The message service handle - * @param[in] mbox The message box type - * @param[in] type The message type \n - * If @a type is #MESSAGES_TYPE_UNKNOWN, all SMS and MMS messages are searched. - * @param[in] keyword The keyword search in the text and subject - * @param[in] address The recipient address - * @param[in] offset The start position (base @c 0) - * @param[in] limit The maximum amount of messages to get \n - * In case of @c 0, this method passes to the callback all searched messages. - * @param[out] message_array The array of the message handle - * @param[out] length The number of messages of the @a message_array - * @param[out] total The count of the messages that have been retrieved as a result without applying @a limit and @a offset\ n - * The value can be used to calculate the total number of page views for the searched messages\ n - * For example, if the count of message search is @c 50 and the limit is @c 20, then using this value, you can notice the total page is @c 3. - * - * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * @param[in] service The message service handle + * @param[in] mbox The message box type + * @param[in] type The message type \n + * If @a type is #MESSAGES_TYPE_UNKNOWN, all SMS and MMS messages are searched + * @param[in] keyword The keyword search in the text and subject + * @param[in] address The recipient address + * @param[in] offset The start position (base @c 0) + * @param[in] limit The maximum amount of messages to get \n + * In case of @c 0, this method passes to the callback all searched messages + * @param[out] message_array The array of the message handle + * @param[out] length The number of messages of the @a message_array + * @param[out] total The count of the messages that have been retrieved as a result without applying @a limit and @a offset \n + * The value can be used to calculate the total number of page views for the searched messages \n + * For example, if the count of message search is @c 50 and the limit is @c 20, then using this value, you can notice the total page is @c 3 + * @return @c 0 on success, + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory - * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed + * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory + * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_free_message_array() */ int messages_search_message(messages_service_h service, @@ -558,28 +452,23 @@ int messages_search_message(messages_service_h service, int offset, int limit, messages_message_h **message_array, int *length, int *total); + /** * @brief Searches a message with the given message ID. - * * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/message.read - * * @remarks You must release @a msg using messages_destroy_message(). - * - * @param[in] service The message service handle - * @param[in] msg_id The message ID - * @param[out] msg The message handle that is newly created if successful - * + * @param[in] service The message service handle + * @param[in] msg_id The message ID + * @param[out] msg The message handle that is newly created if successful * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory + * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_get_message_id() */ int messages_search_message_by_id(messages_service_h service, int msg_id, messages_message_h *msg); @@ -587,18 +476,13 @@ int messages_search_message_by_id(messages_service_h service, int msg_id, messag /** * @brief Frees the message array. - * * @since_tizen 2.3 - * * @param[in] message_array The array of the message handle - * * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_search_message() */ int messages_free_message_array(messages_message_h *message_array); @@ -606,35 +490,29 @@ int messages_free_message_array(messages_message_h *message_array); /** * @brief Retrieves the searched messages by invoking the given callback function iteratively. - * * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/message.read - * - * @param[in] service The message service handle - * @param[in] mbox The message box type - * @param[in] type The message type \n - * If @a type is #MESSAGES_TYPE_UNKNOWN, all SMS and MMS messages are searched. - * @param[in] keyword The keyword search in the text and subject - * @param[in] address The recipient address - * @param[in] offset The start position (base 0) - * @param[in] limit The maximum amount of messages to get \n - * In case of @c 0, this method passes to the callback all searched messages. - * @param[in] callback The callback function to get a message + * @param[in] service The message service handle + * @param[in] mbox The message box type + * @param[in] type The message type \n + * If @a type is #MESSAGES_TYPE_UNKNOWN, all SMS and MMS messages are searched + * @param[in] keyword The keyword search in the text and subject + * @param[in] address The recipient address + * @param[in] offset The start position (base 0) + * @param[in] limit The maximum amount of messages to get \n + * In case of @c 0, this method passes to the callback all searched messages + * @param[in] callback The callback function to get a message * @param[in] user_data The user data to be passed to the callback function - * * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory - * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed + * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory + * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @post It invokes messages_search_cb(). - * * @see messages_search_cb() */ int messages_foreach_message(messages_service_h service, @@ -644,28 +522,23 @@ int messages_foreach_message(messages_service_h service, int offset, int limit, messages_search_cb callback, void *user_data); + /** * @brief Registers a callback to be invoked when an incoming message is received. - * * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/message.read - * - * @param[in] service The message service handle - * @param[in] callback The callback function + * @param[in] service The message service handle + * @param[in] callback The callback function * @param[in] user_data The user data to be passed to the callback function - * * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed + * @retval #MESSAGES_ERROR_OPERATION_FAILED Messaging operation failed * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @post It will invoke messages_incoming_cb(). - * * @see messages_unset_message_incoming_cb() * @see messages_incoming_cb() */ @@ -674,44 +547,35 @@ int messages_set_message_incoming_cb(messages_service_h service, messages_incomi /** * @brief Unregisters the callback function. - * * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/message.write - * * @param[in] service The message service handle - * * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_set_message_incoming_cb() * @see messages_incoming_cb() */ int messages_unset_message_incoming_cb(messages_service_h service); + /** * @brief Adds an additional listening port for the incoming SMS messages. - * * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/message.read - * * @param[in] service The message service handle - * @param[in] port The listening port for the SMS messages - * + * @param[in] port The listening port for the SMS messages * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @see messages_set_message_incoming_cb() * @see messages_get_message_port() */ @@ -722,24 +586,20 @@ int messages_add_sms_listening_port(messages_service_h service, int port); * @addtogroup CAPI_MESSAGING_MESSAGES_MMS_MODULE * @{ */ + + /** * @brief Sets the subject of the message. - * * @since_tizen 2.3 - * - * @param[in] msg The message handle + * @param[in] msg The message handle * @param[in] subject The subject of the message \n - * The maximum length of @a subject is @c 120. - * + * The maximum length of @a subject is @c 120 * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @pre @a msg is created as a #MESSAGES_TYPE_MMS. - * * @see messages_mms_get_subject() */ int messages_mms_set_subject(messages_message_h msg, const char *subject); @@ -747,24 +607,17 @@ int messages_mms_set_subject(messages_message_h msg, const char *subject); /** * @brief Gets the subject of the message. - * * @since_tizen 2.3 - * * @remarks You must release @a subject using free(). - * - * @param[in] msg The message handle + * @param[in] msg The message handle * @param[out] subject The subject of the message - * * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @pre @a msg is created as a #MESSAGES_TYPE_MMS. - * * @see messages_mms_set_subject() */ int messages_mms_get_subject(messages_message_h msg, char **subject); @@ -772,24 +625,18 @@ int messages_mms_get_subject(messages_message_h msg, char **subject); /** * @brief Adds the attachment to the MMS message. - * * @since_tizen 2.3 - * - * @param[in] msg The message handle + * @param[in] msg The message handle * @param[in] type The attachment type * @param[in] path The file path to attach \n - * The maximum length of @a path is @c 1024. - * + * The maximum length of @a path is @c 1024 * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @pre @a msg is created as a #MESSAGES_TYPE_MMS. - * * @see messages_mms_get_attachment() * @see messages_mms_get_attachment_count() * @see messages_mms_remove_all_attachments() @@ -799,26 +646,19 @@ int messages_mms_add_attachment(messages_message_h msg, messages_media_type_e ty /** * @brief Gets the file path of the attachment with the specified index. - * * @since_tizen 2.3 - * * @remarks You must release @a path using free(). - * - * @param[in] msg The message handle - * @param[in] index The zero-based index of the attachment - * @param[out] type The attachment type - * @param[out] path The file path to attach - * + * @param[in] msg The message handle + * @param[in] index The zero-based index of the attachment + * @param[out] type The attachment type + * @param[out] path The file path to attach * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_OUT_OF_MEMORY Out of memory + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @pre @a msg is created as a #MESSAGES_TYPE_MMS. - * * @see messages_mms_add_attachment() * @see messages_mms_get_attachment_count() * @see messages_mms_remove_all_attachments() @@ -828,21 +668,15 @@ int messages_mms_get_attachment(messages_message_h msg, int index, messages_medi /** * @brief Gets the attachment with the specified index. - * * @since_tizen 2.3 - * - * @param[in] msg The message handle + * @param[in] msg The message handle * @param[out] count The total number of attachments - * * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @pre @a msg is created as a #MESSAGES_TYPE_MMS. - * * @see messages_mms_add_attachment() * @see messages_mms_get_attachment() * @see messages_mms_remove_all_attachments() @@ -852,53 +686,47 @@ int messages_mms_get_attachment_count(messages_message_h msg, int *count); /** * @brief Removes all attachments to the MMS message. - * * @since_tizen 2.3 - * * @param[in] msg The message handle - * * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported * @pre @a msg is created as a #MESSAGES_TYPE_MMS. - * * @see messages_mms_add_attachment() * @see messages_mms_get_attachment() * @see messages_mms_get_attachment_count() */ int messages_mms_remove_all_attachments(messages_message_h msg); + + /** * @} */ + /** * @addtogroup CAPI_MESSAGING_MESSAGES_PUSH_MODULE * @{ */ + /** * @brief Registers a callback to be invoked when an WAP Push message is received. - * * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/message.read - * - * @param[in] service The message service handle - * @param[in] app_id The "X-WAP-Application-ID" to indicate a destination WAP Push application ID - * @param[in] callback The callback function + * @param[in] service The message service handle + * @param[in] app_id The "X-WAP-Application-ID" to indicate a destination WAP Push application ID + * @param[in] callback The callback function * @param[in] user_data The user data to be passed to the callback function - * * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported */ int messages_push_add_incoming_cb(messages_service_h service, const char *app_id, messages_push_incoming_cb callback, void *user_data); @@ -906,97 +734,82 @@ int messages_push_add_incoming_cb(messages_service_h service, const char *app_id /** * @brief Unregisters the WAP push incoming callback function. - * * @since_tizen 2.3 - * * @param[in] service The message service handle - * @param[in] app_id The "X-WAP-Application-ID" to indicate a destination WAP Push application ID - * + * @param[in] app_id The "X-WAP-Application-ID" to indicate a destination WAP Push application ID * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported */ int messages_push_remove_incoming_cb(messages_service_h service, const char *app_id); /** * @brief Registers an application to the mapping table of the WAP Push service. - * * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/message.write - * - * @param[in] service The message service handle + * @param[in] service The message service handle * @param[in] content_type The MIME content type of the content - * @param[in] app_id The "X-WAP-Application-ID" to indicate a destination WAP Push application ID - * + * @param[in] app_id The "X-WAP-Application-ID" to indicate a destination WAP Push application ID * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported */ int messages_push_register(messages_service_h service, const char *content_type, const char *app_id); /** * @brief De-registers an application from the mapping table of the WAP Push service. - * * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/message.write - * - * @param[in] service The message service handle + * @param[in] service The message service handle * @param[in] content_type The MIME content type of the content - * @param[in] app_id The "X-WAP-Application-ID" to indicate a destination WAP Push application ID - * + * @param[in] app_id The "X-WAP-Application-ID" to indicate a destination WAP Push application ID * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported */ int messages_push_deregister(messages_service_h service, const char *content_type, const char *app_id); /** * @brief Re-registers an application to the mapping table of the WAP Push service. - * * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/message.write - * - * @param[in] service The message service handle - * @param[in] content_type An element of the composite key for searching registered entry \n - * The MIME content type of the content. - * @param[in] app_id The composite key for searching mapping information \n - * The "X-WAP-Application-ID" to indicate a destination WAP Push application ID. + * @param[in] service The message service handle + * @param[in] content_type An element of the composite key for searching registered entry \n + * The MIME content type of the content + * @param[in] app_id The composite key for searching mapping information \n + * The "X-WAP-Application-ID" to indicate a destination WAP Push application ID * @param[in] dst_content_type The MIME content type of the content - * @param[in] dst_app_id The "X-WAP-Application-ID" to indicate a destination WAP Push application ID - * + * @param[in] dst_app_id The "X-WAP-Application-ID" to indicate a destination WAP Push application ID * @return @c 0 on success, - * otherwise a negative error value - * - * @retval #MESSAGES_ERROR_NONE Successful + * otherwise a negative error value + * @retval #MESSAGES_ERROR_NONE Successful * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method - * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported - * + * @retval #MESSAGES_ERROR_NOT_SUPPORTED Not supported */ int messages_push_reregister(messages_service_h service, const char *content_type, const char *app_id, const char *dst_content_type, const char *dst_app_id); + /** * @} */ + /** * @} */ |