libpurple/smiley-parser.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
  20  */
  21
  22 #ifndef PURPLE_SMILEY_PARSER_H
  23 #define PURPLE_SMILEY_PARSER_H
  24 /**
  25  * SECTION:smiley-parser
  26  * @include:smiley-parser.h
  27  * @section_id: libpurple-smiley-parser
  28  * @short_description: a efficient smiley processor
  29  * @title: Smiley parser
  30  *
  31  * This module is a fast and easy method for searching (and optionally replacing)
  32  * #PurpleSmiley's in a text. It may use all suitable smiley sets to smileyify
  33  * the message in one step. The priority if always the following: remote
  34  * smileys > local custom smileys > theme smileys.
  35  */
  36
  37 #include "purple.h"
  38
  39 /**
  40  * PurpleSmileyParseCb:
  41  * @out: the message buffer.
  42  * @smiley: found smiley.
  43  * @conv: the conversation of a message (or %NULL, if not passed).
  44  * @ui_data: the data being passed to #purple_smiley_parse.
  45  *
  46  * A replace callback for the found @smiley. It should append a HTML tag
  47  * representing the @smiley to the @out string. It must not modify the
  48  * @out string in other way than appending to its end.
  49  *
  50  * If callback decides not to replace a smiley, it must not modify
  51  * @out in any way.
  52  *
  53  * Returns: %TRUE if the smiley was inserted.
  54  */
  55 typedef gboolean (*PurpleSmileyParseCb)(GString *out, PurpleSmiley *smiley,
  56         PurpleConversation *conv, gpointer ui_data);
  57
  58 /**
  59  * purple_smiley_parser_smileify:
  60  * @conv: the conversation of a message.
  61  * @html_message: the html message, or escaped plain message.
  62  * @use_remote_smileys: %TRUE if remote smileys of @conv should be parsed.
  63  * @cb: (scope call): The callback to replace smiley text with an image.
  64  * @ui_data: the user data to be passed to @cb and
  65  *           #purple_smiley_theme_get_smileys.
  66  *
  67  * Replaces all textual smiley representations with proper smiley images
  68  * configured for libpurple.
  69  *
  70  * The @use_remote_smileys parameter should be %TRUE for incoming messages,
  71  * %FALSE for outgoing.
  72  *
  73  * This function is intended for replacing all smileys before displaying. For
  74  * replacing custom smileys before sending to the other party,
  75  * see #purple_smiley_parser_replace.
  76  *
  77  * Returns: (transfer full): the smileifed message. Should be #g_free'd when
  78  *          done using it. Returns %NULL if and only if @html_message was %NULL.
  79  */
  80 gchar *
  81 purple_smiley_parser_smileify(PurpleConversation *conv, const gchar *html_message,
  82         gboolean use_remote_smileys, PurpleSmileyParseCb cb, gpointer ui_data);
  83
  84 /**
  85  * purple_smiley_parser_replace:
  86  * @smileys: the list of smileys to replace.
  87  * @html_message: the html message, or escaped plain message.
  88  * @cb: (scope call): The callback to replace smiley text with an image.
  89  * @ui_data: (closure cb): The user data to be passed to the callback.
  90  *
  91  * Replaces all textual smiley representations from @smileys list with images.
  92  *
  93  * This function is intended for replacing custom smileys before sending to the
  94  * other party. For replacing all sets of smileys (custom, remote and theme) at
  95  * once (ie. before displaying), use #purple_smiley_parser_smileify.
  96  *
  97  * Returns: (transfer full): the smileifed message. Should be #g_free'd when
  98  *          done using it. Returns %NULL if and only if @html_message was %NULL.
  99  */
 100 gchar *
 101 purple_smiley_parser_replace(PurpleSmileyList *smileys,
 102         const gchar *html_message, PurpleSmileyParseCb cb, gpointer ui_data);
 103
 104 /**
 105  * purple_smiley_parser_find:
 106  * @smileys: the list of smileys to find.
 107  * @message: the message.
 108  * @is_html: %TRUE if the message is HTML, %FALSE if it's plain, unescaped.
 109  *
 110  * Searches for all smileys from the @smileys list present in @message.
 111  * Each smiley is returned only once, regardless how many times it appeared in
 112  * text. However, distinct smileys may share common image file (thus, their
 113  * paths will be the same).
 114  *
 115  * Returns: (element-type PurpleSmiley) (transfer container): the list of found smileys.
 116  */
 117 GList *
 118 purple_smiley_parser_find(PurpleSmileyList *smileys, const gchar *message,
 119         gboolean is_html);
 120
 121 /**
 122  * _purple_smiley_parser_init: (skip)
 123  *
 124  * Initializes the smileys parser subsystem.
 125  */
 126 void
 127 _purple_smiley_parser_init(void);
 128
 129 /**
 130  * _purple_smiley_parser_uninit: (skip)
 131  *
 132  * Uninitializes the smileys parser subsystem.
 133  */
 134 void
 135 _purple_smiley_parser_uninit(void);
 136
 137 #endif /* PURPLE_SMILEY_PARSER_H */