1 | /* |
2 | This file is part of the syndication library |
3 | SPDX-FileCopyrightText: 2006 Frank Osterfeld <osterfeld@kde.org> |
4 | |
5 | SPDX-License-Identifier: LGPL-2.0-or-later |
6 | */ |
7 | |
8 | #ifndef SYNDICATION_ATOM_CONTENT_H |
9 | #define SYNDICATION_ATOM_CONTENT_H |
10 | |
11 | #include <syndication/elementwrapper.h> |
12 | |
13 | #include <QString> |
14 | |
15 | class QByteArray; |
16 | class QDomElement; |
17 | |
18 | namespace Syndication |
19 | { |
20 | namespace Atom |
21 | { |
22 | /** |
23 | * The content element either contains or links the content of an entry. |
24 | * The content is usually plain text or HTML, but arbitrary XML or binary |
25 | * content are also possible. If isContained() is false, the content is |
26 | * not contained in the feed source, but linked. |
27 | * |
28 | * @author Frank Osterfeld |
29 | */ |
30 | class SYNDICATION_EXPORT Content : public ElementWrapper |
31 | { |
32 | public: |
33 | /** |
34 | * format of the content. |
35 | */ |
36 | enum Format { |
37 | PlainText, /**< the content is plain text (i.e. "<", ">" |
38 | * etc. are text, not |
39 | * markup */ |
40 | EscapedHTML, /**< the content is escaped HTML, (i.e., "<", ">" etc. |
41 | * are markup) */ |
42 | XML, /**< the content is embedded XML */ |
43 | Binary, /**< the content is base64-encoded binary content */ |
44 | }; |
45 | |
46 | /** |
47 | * maps a mimetype to Format enum according to the Atom 1.0 |
48 | * specification |
49 | * |
50 | * @param type a valid mimetype, or one of "text", "html", "xhtml" |
51 | * @param src content source, see src() for details. |
52 | * |
53 | */ |
54 | static Format mapTypeToFormat(const QString &type, const QString &src = QString()); |
55 | |
56 | /** |
57 | * creates a null content object. |
58 | */ |
59 | Content(); |
60 | |
61 | /** |
62 | * creates a Content object wrapping an atom:content element. |
63 | * @param element a DOM element, should be a atom:content element |
64 | * (although not enforced), otherwise this object will not parse |
65 | * anything useful |
66 | */ |
67 | explicit Content(const QDomElement &element); |
68 | |
69 | /** |
70 | * creates a copy of another Content object |
71 | * |
72 | * @param other the content object to copy |
73 | */ |
74 | Content(const Content &other); |
75 | |
76 | /** |
77 | * destructor |
78 | */ |
79 | ~Content() override; |
80 | |
81 | /** |
82 | * assigns another content objecct |
83 | * |
84 | * @param other the Content object to assign |
85 | */ |
86 | Content &operator=(const Content &other); |
87 | |
88 | /** |
89 | * the type of the content. This is either "text" (plain text), |
90 | * "html" (escaped HTML), "xhtml" (embedded XHTML) or a mime type |
91 | * |
92 | * @return the content type. If no type is specified, "text" (the |
93 | * default) is returned. |
94 | */ |
95 | Q_REQUIRED_RESULT QString type() const; |
96 | |
97 | /** |
98 | * If src() is set, the content of this entry is not contained in the |
99 | * feed source, but available on the net. |
100 | * src() then contains a URL (more precise: IRI reference) linking to |
101 | * remote content. |
102 | * If src is provided, type() should contain a mimetype, instead of "text", |
103 | * "html" or "xhtml". |
104 | * |
105 | * @return a null string if the content is contained in the feed |
106 | * source, or a URL linking to the remote content |
107 | */ |
108 | Q_REQUIRED_RESULT QString src() const; |
109 | |
110 | /** |
111 | * returns the content as string. If the content format is Text, the |
112 | * returned string contains the text as HTML. |
113 | * If the content is embedded XML, the XML is returned as string. |
114 | * |
115 | * @return a string representation of the content, or a null string if |
116 | * the content is either binary content or not contained but linked |
117 | * (see isContained()) |
118 | */ |
119 | |
120 | Q_REQUIRED_RESULT QString asString() const; |
121 | |
122 | /** |
123 | * returns binary content as byte array. |
124 | * |
125 | * @return byte array containing the embedded binary data, or |
126 | * an empty array if the content is not in binary format |
127 | */ |
128 | Q_REQUIRED_RESULT QByteArray asByteArray() const; |
129 | |
130 | /** |
131 | * returns the content format |
132 | */ |
133 | Q_REQUIRED_RESULT Format format() const; |
134 | |
135 | /** |
136 | * returns whether the content is contained in the feed source, |
137 | * or not. If it is not contained, src() provides a URL to the |
138 | * content. |
139 | */ |
140 | Q_REQUIRED_RESULT bool isContained() const; |
141 | |
142 | /** |
143 | * returns whether the content is embedded XML. |
144 | * Use element() to access the DOM tree, or asString() to get the XML |
145 | * as string. |
146 | */ |
147 | Q_REQUIRED_RESULT bool isXML() const; |
148 | |
149 | /** |
150 | * returns whether the content is binary content or not. |
151 | * Use asByteArray() to access it. |
152 | */ |
153 | Q_REQUIRED_RESULT bool isBinary() const; |
154 | |
155 | /** |
156 | * returns whether the content is plain text or not. |
157 | * Use asString() to access it. |
158 | */ |
159 | Q_REQUIRED_RESULT bool isPlainText() const; |
160 | |
161 | /** |
162 | * returns whether the content is escaped HTML or not |
163 | * Use asString() to access it |
164 | */ |
165 | Q_REQUIRED_RESULT bool isEscapedHTML() const; |
166 | |
167 | /** |
168 | * returns a description of the content object |
169 | * for debugging purposes |
170 | * |
171 | * @return debug string |
172 | */ |
173 | Q_REQUIRED_RESULT QString debugInfo() const; |
174 | |
175 | private: |
176 | class ContentPrivate; |
177 | QSharedPointer<ContentPrivate> d; |
178 | }; |
179 | |
180 | } // namespace Atom |
181 | } // namespace Syndication |
182 | |
183 | #endif // SYNDICATION_ATOM_CONTENT_H |
184 | |