src/include/mobile/utils_i18n_uenumeration.h

   1 /*
   2  * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  *    Licensed under the Apache License, Version 2.0 (the "License");
   5  *    you may not use this file except in compliance with the License.
   6  *    You may obtain a copy of the License at
   7  *
   8  *        http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  *    Unless required by applicable law or agreed to in writing, software
  11  *    distributed under the License is distributed on an "AS IS" BASIS,
  12  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  *    See the License for the specific language governing permissions and
  14  *    limitations under the License.
  15  */
  16
  17 #ifndef __UTILS_I18N_UENUMERATION_PRODUCT_H__
  18 #define __UTILS_I18N_UENUMERATION_PRODUCT_H__
  19
  20 #include <utils_i18n_types.h>
  21
  22 /**
  23  * @file utils_i18n_uenumeration.h
  24  * @version 0.1
  25  * @brief utils_i18n_uenumeration
  26  */
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /**
  33  * @ingroup CAPI_BASE_UTILS_I18N_MODULE
  34  * @defgroup CAPI_BASE_UTILS_I18N_UENUMERATION_MODULE UEnumeration
  35  * @brief UEnumeration defines functions for handling String Enumeration.
  36  *
  37  * @section CAPI_BASE_UTILS_I18N_UENUMERATION_MODULE_HEADER Required Header
  38  *  \#include <utils_i18n.h>
  39  *
  40  * @section CAPI_BASE_UTILS_I18N_UENUMERATION_MODULE_OVERVIEW Overview
  41  * @details The UEnumeration module allows to create String Enumeration
  42  *          from chars and uchars.
  43  *
  44 */
  45
  46 /**
  47  * @addtogroup CAPI_BASE_UTILS_I18N_UENUMERATION_MODULE
  48  * @{
  49  */
  50
  51 /**
  52  * @brief Disposes of resources in use by the iterator.
  53  * @details If @c enumeration is <code>NULL</code>, does nothing. After this call, any <code>char*</code> or <code>i18n_uchar*</code> returned
  54  *          by i18n_uenumeration_unext() or i18n_uenumeration_next() is invalid.
  55  * @remarks Error codes are described in #i18n_error_code_e description.
  56  * @since_tizen 2.3.1
  57  *
  58  * @param[in] enumeration    An #i18n_uenumeration_h to destroy
  59  *
  60  * @return The obtained error code.
  61  * @retval #I18N_ERROR_NONE Successful
  62  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
  63  */
  64 int i18n_uenumeration_destroy ( i18n_uenumeration_h enumeration );
  65
  66 /**
  67  * @brief Returns the number of elements that the iterator traverses.
  68  * @details If the iterator is out-of-sync with its service, error code is set to #I18N_ERROR_ENUM_OUT_OF_SYNC.
  69  *          This is a convenience function. It can end up being very expensive as all the items might have to be pre-fetched
  70  *          (depending on the type of data being traversed).
  71  *          Use with caution and only when necessary.
  72  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
  73  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
  74  * @since_tizen 2.3.1
  75  *
  76  * @param[in] enumeration      An #i18n_uenumeration_h to count
  77  *
  78  * @return The number of elements in the iterator
  79  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
  80  * @exception #I18N_ERROR_ENUM_OUT_OF_SYNC The iterator is out of sync
  81  */
  82 int32_t i18n_uenumeration_count ( i18n_uenumeration_h enumeration );
  83
  84 /**
  85  * @brief Returns the next element in the iterator's list.
  86  * @details If there are no more elements, returns <code>NULL</code>.
  87  *          If the iterator is out-of-sync with its service, error code is set to #I18N_ERROR_ENUM_OUT_OF_SYNC and <code>NULL</code> is returned.
  88  *          If the native service string is a <code>char*</code> string, it is converted to <code>i18n_uchar*</code> with the invariant converter.
  89  *          The result is terminated by <code>(i18n_uchar)0</code>.
  90  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
  91  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
  92  * @since_tizen 2.3.1
  93  *
  94  * @param[in] enumeration       An #i18n_uenumeration_h
  95  * @param[out] result_length    A pointer to receive the length of the result (not including the terminating \\0).
  96  *                              If the pointer is <code>NULL</code> it is ignored.
  97  *
  98  * @return A pointer to the string. The string will be zero-terminated.
  99  *         The return pointer is owned by this iterator and must not be deleted by the caller.
 100  *         The pointer is valid until the next call to any i18n_uenumeration_... method, including i18n_uenumeration_next() or i18n_uenumeration_unext().
 101  *         When all strings have been traversed, returns <code>NULL</code>.
 102  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 103  * @exception #I18N_ERROR_ENUM_OUT_OF_SYNC The iterator is out of sync
 104  */
 105 const i18n_uchar *i18n_uenumeration_unext ( i18n_uenumeration_h enumeration, int32_t *result_length );
 106
 107 /**
 108  * @brief Returns the next element in the iterator's list.
 109  * @details If there are no more elements, returns NULL. If the iterator is out-of-sync with its service,
 110  *          the #I18N_ERROR_ENUM_OUT_OF_SYNC error code is set and <code>NULL</code> is returned.
 111  *          If the native service string is a <code>i18n_uchar*</code> string, it is converted to <code>char*</code> with the invariant converter.
 112  *          The result is terminated by <code>(char)0</code>. If the conversion fails (because a character cannot be converted)
 113  *          then the error code is set to #I18N_ERROR_INVARIANT_CONVERSION and the return value is undefined (but non-NULL).
 114  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
 115  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 116  * @since_tizen 2.3.1
 117  *
 118  * @param[in] enumeration       An #i18n_uenumeration_h
 119  * @param[out] result_length    A pointer to receive the length of the result (not including the terminating \\0).
 120  *                              If the pointer is <code>NULL</code> it is ignored.
 121  *
 122  * @return A pointer to the string. The string will be zero-terminated.
 123  *         The return pointer is owned by this iterator and must not be deleted by the caller.
 124  *         The pointer is valid until the next call to any i18n_uenumeration_... method, including i18n_uenumeration_next() or i18n_uenumeration_unext().
 125  *         When all strings have been traversed, returns <code>NULL</code>.
 126  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 127  * @exception #I18N_ERROR_ENUM_OUT_OF_SYNC The iterator is out of sync
 128  * @exception #I18N_ERROR_INVARIANT_CONVERSION The underlying native string is <code>i18n_uchar*</code> and conversion to <code>char*</code> with the invariant converter fails.
 129  *                                             This error pertains only to current string, so iteration might be able to continue successfully.
 130  */
 131 const char *i18n_uenumeration_next ( i18n_uenumeration_h enumeration, int32_t *result_length );
 132
 133 /**
 134  * @brief Resets the iterator to the current list of service IDs.
 135  * @details This re-establishes sync with the service and rewinds the iterator to start at the first element.
 136  * @remarks Error codes are described in #i18n_error_code_e description.
 137  * @since_tizen 2.3.1
 138  *
 139  * @param[in] enumeration      An #i18n_uenumeration_h
 140  *
 141  * @return The obtained error code.
 142  * @retval #I18N_ERROR_NONE Successful
 143  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 144  */
 145 int i18n_uenumeration_reset ( i18n_uenumeration_h enumeration );
 146
 147 /**
 148  * @brief Given an array of <code>const i18n_uchar*</code> strings, return an #i18n_uenumeration_h.
 149  * @details String pointers from 0..count-1 must not be <code>NULL</code>.
 150  *          Do not free or modify either the string array or the characters it points to until this object has been destroyed with i18n_uenumeration_destroy().
 151  * @remarks Error codes are described in #i18n_error_code_e description.
 152  * @since_tizen 2.3.1
 153  *
 154  * @param[in] strings     An array of const <code>i18n_uchar*</code> strings (each null terminated). All storage is owned by the caller.
 155  * @param[in] count       The length of the array
 156  * @param[out] enumeration A pointer to the new #i18n_uenumeration_h. Caller is responsible for calling i18n_uenumeration_destroy() to free memory.
 157  *
 158  * @return The obtained error code.
 159  * @retval #I18N_ERROR_NONE Successful
 160  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 161  *
 162  * @see i18n_uenumeration_destroy()
 163  */
 164 int i18n_uenumeration_uchar_strings_enumeration_create(const i18n_uchar *const strings[], int32_t count, i18n_uenumeration_h *enumeration );
 165
 166 /**
 167  * @brief Given an array of <code>const char*</code> strings (invariant chars only), return an #i18n_uenumeration_h.
 168  * @details String pointers from 0..count-1 must not be <code>NULL</code>.
 169  *          Do not free or modify either the string array or the characters it points to until this object has been destroyed with i18n_uenumeration_destroy().
 170  * @remarks Error codes are described in #i18n_error_code_e description.
 171  * @since_tizen 2.3.1
 172  *
 173  * @param[in] strings     A array of <code>char*</code> strings (each null terminated). All storage is owned by the caller.
 174  * @param[in] count       The length of the array
 175  * @param[out] enumeration A pointer to the new #i18n_uenumeration_h. Caller is responsible for calling i18n_uenumeration_destroy() to free memory
 176  *
 177  * @return The obtained error code.
 178  * @retval #I18N_ERROR_NONE Successful
 179  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 180  *
 181  * @see i18n_uenumeration_destroy()
 182  */
 183 int i18n_uenumeration_char_strings_enumeration_create(const char* const strings[], int32_t count, i18n_uenumeration_h *enumeration );
 184
 185 /**
 186  * @}
 187  * @}
 188  */
 189
 190 #ifdef __cplusplus
 191 }
 192 #endif
 193
 194 #endif  /* __UTILS_I18N_UENUMERATION_PRODUCT_H__*/