/*
 * 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_RELATEDGROUP_H__
#define __TIZEN_SOCIAL_CONTACTS_RELATEDGROUP_H__


#include <contacts_types.h>

#ifdef __cplusplus
extern "C"
{
#endif


/**
 * @addtogroup CAPI_SOCIAL_CONTACTS_RELATEDGROUP_MODULE
 * @{
 */

/**
 * @brief       Gets the related group name from the contacts group handle.  
 *
 * @remarks     @a name must be released with free() by you. 
 *
 * @param[in]   relatedgroup    The contacts group handle
 * @param[out]  name            The fetched related group name \n
 * 						If @a name 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
 */
int contact_relatedgroup_get_name(contact_relatedgroup_h relatedgroup, char **name);

/**
 * @brief       Gets the ringtone path from the contacts group handle.
 *
 * @remarks @a ringtone_path must be released with free() by you. 
 *
 * @param[in]   relatedgroup            The contacts group handle
 * @param[out]  ringtone_path           The ringtone path \n
 * 							If @a ringtone_path 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
 */
int contact_relatedgroup_get_ringtonepath(contact_relatedgroup_h relatedgroup, char **ringtone_path);

/**
 * @brief       Gets the group database ID from contacts group handle. 
 *
 *
 * @param[in]   relatedgroup        The contacts group handle
 * @param[out]  group_db_id        The group ID fetched from contacts group handle
 *
 * @return      0 on success, otherwise a negative error value.
 * @retval      #CONTACTS_ERROR_NONE                Successful
 * @retval      #CONTACTS_ERROR_INVALID_PARAMETER   Invalid parameter
 * 
 * @see contacts_group_get_from_db()
 */
int contact_relatedgroup_get_group_db_id(contact_relatedgroup_h relatedgroup, int *group_db_id);

/**
 * @brief       Moves the related group list iterator to the next position and gets the contacts group handle.
 *
 * @details   If the next element for the current related group list exists, then the iterator is moved to the next position
 * on the list and the contacts related group 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 relatedgroup will remain unchanged.
 *
 * @param[in]   relatedgroup_iterator   The handle to the related group list 
 * @param[out]  relatedgroup            The contacts group 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_ITERATOR_END            List reached end
 *
 * @see contact_relatedgroup_iterator_has_next()
 */
int contact_relatedgroup_iterator_next(contact_relatedgroup_iterator_h *relatedgroup_iterator, contact_relatedgroup_h *relatedgroup);

/**
 * @brief   Checks whether the next element of the related group iterator exists or not.
 *
 *
 * @param[in]   relatedgroup_iterator   The handle to the related group list 
 *
 * @return  @c true If the next element exists or @c false If the next element doesn't exist  
 * @see contact_relatedgroup_iterator_next()
 */
bool contact_relatedgroup_iterator_has_next(contact_relatedgroup_iterator_h relatedgroup_iterator);

/**
 * @}
 */

#ifdef __cplusplus
}
#endif


#endif /* __TIZEN_SOCIAL_CONTACTS_RELATEDGROUP_H__ */