2 * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __UTILS_I18N_UENUMERATION_PRODUCT_H__
18 #define __UTILS_I18N_UENUMERATION_PRODUCT_H__
20 #include <utils_i18n_types.h>
23 * @file utils_i18n_uenumeration.h
25 * @brief utils_i18n_uenumeration
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.
37 * @section CAPI_BASE_UTILS_I18N_UENUMERATION_MODULE_HEADER Required Header
38 * \#include <utils_i18n.h>
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.
47 * @addtogroup CAPI_BASE_UTILS_I18N_UENUMERATION_MODULE
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.
58 * @param[in] enumeration An #i18n_uenumeration_h to destroy
60 * @return The obtained error code.
61 * @retval #I18N_ERROR_NONE Successful
62 * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
64 int i18n_uenumeration_destroy ( i18n_uenumeration_h enumeration );
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.
76 * @param[in] enumeration An #i18n_uenumeration_h to count
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
82 int32_t i18n_uenumeration_count ( i18n_uenumeration_h enumeration );
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.
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.
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
105 const i18n_uchar *i18n_uenumeration_unext ( i18n_uenumeration_h enumeration, int32_t *result_length );
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.
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.
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.
131 const char *i18n_uenumeration_next ( i18n_uenumeration_h enumeration, int32_t *result_length );
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.
139 * @param[in] enumeration An #i18n_uenumeration_h
141 * @return The obtained error code.
142 * @retval #I18N_ERROR_NONE Successful
143 * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
145 int i18n_uenumeration_reset ( i18n_uenumeration_h enumeration );
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.
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.
158 * @return The obtained error code.
159 * @retval #I18N_ERROR_NONE Successful
160 * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
162 * @see i18n_uenumeration_destroy()
164 int i18n_uenumeration_uchar_strings_enumeration_create(const i18n_uchar *const strings[], int32_t count, i18n_uenumeration_h *enumeration );
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.
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
177 * @return The obtained error code.
178 * @retval #I18N_ERROR_NONE Successful
179 * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
181 * @see i18n_uenumeration_destroy()
183 int i18n_uenumeration_char_strings_enumeration_create(const char* const strings[], int32_t count, i18n_uenumeration_h *enumeration );
194 #endif /* __UTILS_I18N_UENUMERATION_PRODUCT_H__*/