diff options
Diffstat (limited to 'include/contacts_messenger.h')
| -rwxr-xr-x | include/contacts_messenger.h | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/include/contacts_messenger.h b/include/contacts_messenger.h new file mode 100755 index 0000000..4720d73 --- /dev/null +++ b/include/contacts_messenger.h @@ -0,0 +1,162 @@ +/* + * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the License); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an AS IS BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + +#ifndef __TIZEN_SOCIAL_CONTACTS_MESSENGER_H__ +#define __TIZEN_SOCIAL_CONTACTS_MESSENGER_H__ + +#include <contacts_types.h> + +#ifdef __cplusplus +extern "C" +{ +#endif + +/** + * @addtogroup CAPI_SOCIAL_CONTACTS_MESSENGER_MODULE + * @{ + */ + +/** + * @brief Creates a handle to contacts messenger. + * + * @remarks @a messenger must be released with contact_messenger_destroy() by you. + * @remarks @a messenger is not added to contacts database until contact_insert_to_db() is called. + * + * @param[out] messenger A new contacts messenger handle + * + * @return 0 on success, otherwise a negative error value. + * @retval #CONTACTS_ERROR_NONE Successful + * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory + * + * @see contact_messenger_destroy() + */ +int contact_messenger_create(contact_messenger_h *messenger); + +/** + * @brief Destroys the handle to contacts messenger handle. + * + * @param[in] messenger The contacts messenger handle + * + * @return 0 on success, otherwise a negative error value. + * @retval #CONTACTS_ERROR_NONE Successful + * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see contact_messenger_create() + */ +int contact_messenger_destroy(contact_messenger_h messenger); + + +/** + * @brief Gets the messenger ID from the contacts messenger handle. + * + * @remarks @a id must be released with free() by you. + * + * @param[in] messenger The contacts messenger handle + * @param[out] id The ID returned as string. \n + * If @a id does not exist, it is NULL + * + * @return 0 on success, otherwise a negative error value. + * @retval #CONTACTS_ERROR_NONE Successful + * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see contact_messenger_set_id() + */ +int contact_messenger_get_id(contact_messenger_h messenger, char **id); + +/** + * @brief Sets a messenger ID to the contacts messenger handle. + * + * @remarks @a id must be released with free() by you. + * + * @param[in] messenger The contacts messenger handle + * @param[in] id The ID to set + * + * @return 0 on success, otherwise a negative error value. + * @retval #CONTACTS_ERROR_NONE Successful + * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter + * @see contact_messenger_get_id() + */ +int contact_messenger_set_id(contact_messenger_h messenger, const char *id); + +/** + * @brief Gets the messenger type from the contacts messenger handle. + * + * + * @param[in] messenger The contacts messenger handle + * @param[out] type The messenger type + * + * @return 0 on success, otherwise a negative error value. + * @retval #CONTACTS_ERROR_NONE Successful + * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter + * @see contact_messenger_set_type() + */ +int contact_messenger_get_type(contact_messenger_h messenger, contact_messenger_type_e *type); + +/** + * @brief Sets a messenger type to the contacts messenger handle. + * + * @param[in] messenger The contacts messenger handle + * @param[in] type The messenger type + * + * @return 0 on success, otherwise a negative error value. + * @retval #CONTACTS_ERROR_NONE Successful + * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter + * @see contact_messenger_get_type() + */ +int contact_messenger_set_type(contact_messenger_h messenger, contact_messenger_type_e type); + +/** + * @brief Moves the messenger iterator to the next position and gets a contacts messenger handle. + * + * @details If the next element for the current messenger list exists, then the iterator is moved to the next + * position on the list and the contacts messenger handle for this position is returned. When the iterator reaches the last + * element of the list, all further calls will return #CONTACTS_ERROR_ITERATOR_END and @a messenger will + * remain unchanged. + * + * @param[in] messenger_iterator The handle to the contacts messenger list + * @param[in] messenger The handle to a contacts messenger, fetched from new iterator position + * + * @return 0 on success, otherwise a negative error value. + * @retval #CONTACTS_ERROR_NONE Successful + * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CONTACTS_ERROR_ITERATOR_END List reached end + * @see contact_messenger_iterator_has_next() + */ +int contact_messenger_iterator_next(contact_messenger_iterator_h *messenger_iterator, contact_messenger_h *messenger); + +/** + * @brief Checks whether there is a next contacts messenger handle on the list. + * + * + * @param[in] messenger_iterator The contacts message list handle + * + * @return Return @c true If next element exists or @c false If nest element doesn't exist + * @see contact_messenger_iterator_next() + */ +bool contact_messenger_iterator_has_next(contact_messenger_iterator_h messenger_iterator); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* __TIZEN_SOCIAL_CONTACTS_MESSENGER_H__ */ + |