1 /* Copyright (C) 2016-2019 Shengyu Zhang <i@silverrainz.me> 2 * 3 * This file is part of Srain. 4 * 5 * Srain is free software: you can redistribute it and/or modify 6 * it under the terms of the GNU General Public License as published by 7 * the Free Software Foundation, either version 3 of the License, or 8 * (at your option) any later version. 9 * 10 * This program is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU General Public License for more details. 14 * 15 * You should have received a copy of the GNU General Public License 16 * along with this program. If not, see <http://www.gnu.org/licenses/>. 17 */ 18 19 /* This is a private header file and should not be exported. */ 20 21 #ifndef __MARKUP_RENDERER_H 22 #define __MARKUP_RENDERER_H 23 24 #include <glib.h> 25 26 #include "ret.h" 27 28 /** 29 * @brief SrnMarkupRenderer is a helper object for conveniently parse and 30 * reorganize markup text (XML). 31 * 32 * SrnMarkupRenderer is backend with GMarkupParser, please refer to: 33 * https://developer.gnome.org/glib/stable/glib-Simple-XML-Subset-Parser.html 34 */ 35 typedef struct _SrnMarkupRenderer SrnMarkupRenderer; 36 37 SrnMarkupRenderer *srn_markup_renderer_new(void); 38 void srn_markup_renderer_free(SrnMarkupRenderer *self); 39 40 /** 41 * @brief srn_markup_renderer_render 42 * 43 * @param self 44 * @param markup_in is pass-in markup text to be rendered. 45 * @param markup_out is pass-out rendered markup text, must free it after use. 46 * @param user_data is user provided data which can be acessed by 47 * srn_markup_renderer_get_user_data(). 48 * 49 * @return SRN_OK if render successes. 50 */ 51 SrnRet srn_markup_renderer_render(SrnMarkupRenderer *self, 52 const char *markup_in, char **markup_out, void *user_data); 53 54 /** 55 * @brief srn_markup_renderer_get_markup_parser returns the backend markup parer, 56 * the returned parser change be changed to meet the needs of user. 57 * 58 * @param self is a SrnMarkupRenderer instance created by 59 * srn_markup_renderer_new(). 60 * 61 * @return a GMarkupParser. 62 */ 63 GMarkupParser* srn_markup_renderer_get_markup_parser(SrnMarkupRenderer *self); 64 65 /** 66 * @brief srn_markup_renderer_get_markup returns a GString which contains 67 * intermediate result of rendering. 68 * 69 * @param self is a SrnMarkupRenderer instance created by 70 * srn_markup_renderer_new(). 71 * 72 * @return a GString instance, which is held by SrnMarkupRenderer, do not free it. 73 * 74 * This function should only used in callbacks of GMarkupParser. 75 */ 76 GString* srn_markup_renderer_get_markup(SrnMarkupRenderer *self); 77 78 /** 79 * @brief srn_markup_renderer_get_user_data returns user-provided user data. 80 * 81 * @param self is a SrnMarkupRenderer instance created by 82 * srn_markup_renderer_new(). 83 * 84 * @return a pointer which is the user_data you passed to 85 * srn_markup_renderer_render(). 86 * 87 * This function should only used in callbacks of GMarkupParser. 88 */ 89 void *srn_markup_renderer_get_user_data(SrnMarkupRenderer *self); 90 91 #endif /* __MARKUP_RENDERER_H */ 92