1/*
2 * Copyright (c) 2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup UDMF
18 * @{
19 *
20 * @brief The Unified Data Management Framework(UDMF) aims to define various standards
21 * for data across applications, devices, and platforms, providing a unified OpenHarmony
22 * data language and standardized data access and reading paths.
23 *
24 * @syscap SystemCapability.DistributedDataManager.UDMF.Core
25 * @since 12
26 */
27
28/**
29 * @file utd.h
30 *
31 * @brief Provides uniform type descriptor(UTD) related functions and struct.
32 *
33 * @kit ArkData
34 * @library libudmf.so
35 * @syscap SystemCapability.DistributedDataManager.UDMF.Core
36 * @since 12
37 */
38
39#ifndef UTD_H
40#define UTD_H
41
42#include <stdbool.h>
43
44#ifdef __cplusplus
45extern "C" {
46#endif
47
48/**
49 * @brief Describes the unified data type descriptor.
50 *
51 * @since 12
52 */
53typedef struct OH_Utd OH_Utd;
54
55/**
56 * @brief Prouct a pointer to the instance of the {@link OH_Utd}.
57 *
58 * @param typeId Represents type of UTD, reference udmf_meta.h.
59 * @return If the operation is successful, a pointer to the instance of the {@link OH_Utd}
60 * structure is returned.If the operation is failed, nullptr is returned.
61 * Must be destroyed with {@link OH_Utd_DestroyTypeDescriptor} when not needed.
62 * @see OH_Utd.
63 * @since 12
64 */
65OH_Utd* OH_Utd_Create(const char* typeId);
66
67/**
68 * @brief Destroy a pointer that points to the {@link OH_Utd} instance.
69 *
70 * @param pThis Represents a pointer to an instance of {@link OH_Utd}.
71 * @see OH_Utd.
72 * @since 12
73 */
74void OH_Utd_Destroy(OH_Utd* pThis);
75
76/**
77 * @brief Get type id from the {@link OH_Utd}.
78 *
79 * @param pThis Represents a pointer to an instance of {@link OH_Utd}.
80 * @return Returns a string pointer when input args normally, otherwise return nullptr.
81 * @see OH_Utd.
82 * @since 12
83 */
84const char* OH_Utd_GetTypeId(OH_Utd* pThis);
85
86/**
87 * @brief Get description from the {@link OH_Utd}.
88 *
89 * @param pThis Represents a pointer to an instance of {@link OH_Utd}.
90 * @return Returns a string pointer when input args normally, otherwise return nullptr.
91 * @see OH_Utd.
92 * @since 12
93 */
94const char* OH_Utd_GetDescription(OH_Utd* pThis);
95
96/**
97 * @brief Get url from the {@link OH_Utd}.
98 *
99 * @param pThis Represents a pointer to an instance of {@link OH_Utd}.
100 * @return Returns a string pointer when input args normally, otherwise return nullptr.
101 * @see OH_Utd.
102 * @since 12
103 */
104const char* OH_Utd_GetReferenceUrl(OH_Utd* pThis);
105
106/**
107 * @brief Get icon file from the {@link OH_Utd}.
108 *
109 * @param pThis Represents a pointer to an instance of {@link OH_Utd}.
110 * @return Returns a string pointer when input args normally, otherwise return nullptr.
111 * @see OH_Utd.
112 * @since 12
113 */
114const char* OH_Utd_GetIconFile(OH_Utd* pThis);
115
116/**
117 * @brief Get belong to type id of the current {@link OH_Utd}.
118 *
119 * @param pThis Represents a pointer to an instance of {@link OH_Utd}.
120 * @param count Represents the return types count.
121 * @return Returns string array when input args normally, otherwise return nullptr.
122 * @see OH_Utd.
123 * @since 12
124 */
125const char** OH_Utd_GetBelongingToTypes(OH_Utd* pThis, unsigned int* count);
126
127/**
128 * @brief Get filename extensions of the current {@link OH_Utd}.
129 *
130 * @param pThis Represents a pointer to an instance of {@link OH_Utd}.
131 * @param count Represents the return file extensions count.
132 * @return Returns string array when input args normally, otherwise return nullptr.
133 * @see OH_Utd.
134 * @since 12
135 */
136const char** OH_Utd_GetFilenameExtensions(OH_Utd* pThis, unsigned int* count);
137
138/**
139 * @brief Get mime types of the current {@link OH_Utd}.
140 *
141 * @param pThis Represents a pointer to an instance of {@link OH_Utd}.
142 * @param count Represents the mime types count.
143 * @return Returns string array when input args normally, otherwise return nullptr.
144 * @see OH_Utd.
145 * @since 12
146 */
147const char** OH_Utd_GetMimeTypes(OH_Utd* pThis, unsigned int* count);
148
149/**
150 * @brief Get type id by file name extension.
151 *
152 * @param extension Represents file name extension.
153 * @param count Represents the types count.
154 * @return Returns string list of types. Must be destroyed with {@link OH_Utd_DestroyStringList} when not needed.
155 * @since 12
156 */
157const char** OH_Utd_GetTypesByFilenameExtension(const char* extension, unsigned int* count);
158
159/**
160 * @brief Get type id by mime type.
161 *
162 * @param mimeType Represents mime type
163 * @param count Represents the types count.
164 * @return Returns string list of types. Must be destroyed with {@link OH_Utd_DestroyStringList} when not needed.
165 * @since 12
166 */
167const char** OH_Utd_GetTypesByMimeType(const char* mimeType, unsigned int* count);
168
169/**
170 * @brief Calculate relationships of two types.
171 *
172 * @param srcTypeId Represents source type id.
173 * @param destTypeId Represents target type id.
174 * @return Returns the status code of the execution.
175 *         {@code false} Represents srcTypeId not belongs to destTypeId.
176 *         {@code true} Represents srcTypeId belongs to destTypeId.
177 * @since 12
178 */
179bool OH_Utd_BelongsTo(const char* srcTypeId, const char* destTypeId);
180
181/**
182 * @brief Calculate relationships of two types.
183 *
184 * @param srcTypeId Represents source type id.
185 * @param destTypeId Represents target type id.
186 * @return Returns the status code of the execution.
187 *         {@code false} Represents srcTypeId not lower level to destTypeId.
188 *         {@code true} Represents srcTypeId lower level to destTypeId.
189 * @since 12
190 */
191bool OH_Utd_IsLower(const char* srcTypeId, const char* destTypeId);
192
193/**
194 * @brief Calculate relationships of two types.
195 *
196 * @param srcTypeId Represents source type id.
197 * @param destTypeId Represents target type id.
198 * @return Returns the status code of the execution.
199 *         {@code false} Represents srcTypeId not higher level to destTypeId.
200 *         {@code true} Represents srcTypeId higher level to destTypeId.
201 * @since 12
202 */
203bool OH_Utd_IsHigher(const char* srcTypeId, const char* destTypeId);
204
205/**
206 * @brief Calculate two {@link OH_Utd}s are equal.
207 *
208 * @param utd1 Represents a pointer to {@link OH_Utd} instance.
209 * @param utd2 Represents a pointer to {@link OH_Utd} instance.
210 * @return Returns the status code of the execution.
211 *         {@code false} Represents utd1 and utd2 are not equal.
212 *         {@code true} Represents utd1 and utd2 are equal.
213 * @since 12
214 */
215bool OH_Utd_Equals(OH_Utd* utd1, OH_Utd* utd2);
216
217/**
218 * @brief Destroy string list memory.
219 *
220 * @param list Represents a point to string list.
221 * @param count Represents string count in list.
222 * @since 12
223 */
224void OH_Utd_DestroyStringList(const char** list, unsigned int count);
225
226#ifdef __cplusplus
227};
228#endif
229
230/** @} */
231#endif