libpurple/attention.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_ATTENTION_H
  23 #define PURPLE_ATTENTION_H
  24
  25 #include <glib.h>
  26 #include <glib-object.h>
  27
  28 /**
  29  * SECTION:attention
  30  * @section_id: libpurple-attention
  31  * @short_description: <filename>attention.h</filename>
  32  * @title: Attention Object and Interfaces
  33  */
  34
  35 #define PURPLE_TYPE_ATTENTION_TYPE  (purple_attention_type_get_type())
  36
  37 /**
  38  * PurpleAttentionType:
  39  * @name: The name to show in GUI elements.
  40  * @incoming_description: Shown when received.
  41  * @outgoing_description: Shown when sent.
  42  * @icon_name: Optional name of the icon to display.
  43  * @unlocalized_name: An unlocalized name for UIs that would rather use that.
  44  *
  45  * Represents "nudges" and "buzzes" that you may send to a buddy to attract
  46  * their attention (or vice-versa).
  47  */
  48 typedef struct _PurpleAttentionType PurpleAttentionType;
  49
  50 #include "account.h"
  51 #include "connection.h"
  52
  53 G_BEGIN_DECLS
  54
  55 #define PURPLE_TYPE_PROTOCOL_ATTENTION (purple_protocol_attention_get_type())
  56
  57 /******************************************************************************
  58  * AttentionType API
  59  *****************************************************************************/
  60
  61 /**
  62  * purple_attention_type_get_type:
  63  *
  64  * Returns: The #GType for the #PurpleAttentionType boxed structure.
  65  */
  66 GType purple_attention_type_get_type(void);
  67
  68 PurpleAttentionType *purple_attention_type_copy(PurpleAttentionType *attn);
  69
  70 /**
  71  * purple_attention_type_new:
  72  * @unlocalized_name: A non-localized string that can be used by UIs in need of such
  73  *               non-localized strings.  This should be the same as @name,
  74  *               without localization.
  75  * @name: A localized string that the UI may display for the event. This
  76  *             should be the same string as @unlocalized_name, with localization.
  77  * @incoming_description: A localized description shown when the event is received.
  78  * @outgoing_description: A localized description shown when the event is sent.
  79  *
  80  * Creates a new #PurpleAttentionType object and sets its mandatory parameters.
  81  *
  82  * Returns: A pointer to the new object.
  83  */
  84 PurpleAttentionType *purple_attention_type_new(const gchar *unlocalized_name, const gchar *name,
  85                                                                 const gchar *incoming_description, const gchar *outgoing_description);
  86
  87 /**
  88  * purple_attention_type_get_name:
  89  * @type: The attention type.
  90  *
  91  * Get the attention type's name as displayed by the UI.
  92  *
  93  * Returns: The name.
  94  */
  95 const gchar *purple_attention_type_get_name(const PurpleAttentionType *type);
  96
  97 /**
  98  * purple_attention_type_set_name:
  99  * @type: The attention type.
 100  * @name: The localized name that will be displayed by UIs. This should be
 101  *             the same string given as the unlocalized name, but with
 102  *             localization.
 103  *
 104  * Sets the displayed name of the attention-demanding event.
 105  */
 106 void purple_attention_type_set_name(PurpleAttentionType *type, const gchar *name);
 107
 108 /**
 109  * purple_attention_type_get_incoming_desc:
 110  * @type: The attention type.
 111  *
 112  * Get the attention type's description shown when the event is received.
 113  *
 114  * Returns: The description.
 115  */
 116 const gchar *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type);
 117
 118 /**
 119  * purple_attention_type_set_incoming_desc:
 120  * @type: The attention type.
 121  * @desc: The localized description for incoming events.
 122  *
 123  * Sets the description of the attention-demanding event shown in conversations
 124  * when the event is received.
 125  */
 126 void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const gchar *desc);
 127
 128 /**
 129  * purple_attention_type_get_outgoing_desc:
 130  * @type: The attention type.
 131  *
 132  * Get the attention type's description shown when the event is sent.
 133  *
 134  * Returns: The description.
 135  */
 136 const gchar *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type);
 137
 138 /**
 139  * purple_attention_type_set_outgoing_desc:
 140  * @type: The attention type.
 141  * @desc: The localized description for outgoing events.
 142  *
 143  * Sets the description of the attention-demanding event shown in conversations
 144  * when the event is sent.
 145  */
 146 void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const gchar *desc);
 147
 148 /**
 149  * purple_attention_type_get_icon_name:
 150  * @type: The attention type.
 151  *
 152  * Get the attention type's icon name.
 153  *
 154  * Note: Icons are optional for attention events.
 155  *
 156  * Returns: The icon name or %NULL if unset/empty.
 157  */
 158 const gchar *purple_attention_type_get_icon_name(const PurpleAttentionType *type);
 159
 160 /**
 161  * purple_attention_type_set_icon_name:
 162  * @type: The attention type.
 163  * @name: The icon's name.
 164  *
 165  * Sets the name of the icon to display for the attention event; this is optional.
 166  *
 167  * Note: Icons are optional for attention events.
 168  */
 169 void purple_attention_type_set_icon_name(PurpleAttentionType *type, const gchar *name);
 170
 171 /**
 172  * purple_attention_type_get_unlocalized_name:
 173  * @type: The attention type
 174  *
 175  * Get the attention type's unlocalized name; this is useful for some UIs.
 176  *
 177  * Returns: The unlocalized name.
 178  */
 179 const gchar *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type);
 180
 181 /**
 182  * purple_attention_type_set_unlocalized_name:
 183  * @type: The attention type.
 184  * @ulname: The unlocalized name.  This should be the same string given as
 185  *               the localized name, but without localization.
 186  *
 187  * Sets the unlocalized name of the attention event; some UIs may need this,
 188  * thus it is required.
 189  */
 190 void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const gchar *ulname);
 191
 192 /******************************************************************************
 193  * Protocol Interface
 194  *****************************************************************************/
 195
 196 /**
 197  * purple_protocol_attention_get_type:
 198  *
 199  * Returns: The #GType for the protocol attention interface.
 200  */
 201 G_DECLARE_INTERFACE(PurpleProtocolAttention, purple_protocol_attention, PURPLE,
 202                     PROTOCOL_ATTENTION, GObject)
 203
 204 /**
 205  * PurpleProtocolAttentionInterface:
 206  *
 207  * The protocol attention interface.
 208  *
 209  * This interface provides attention API for sending and receiving
 210  * zaps/nudges/buzzes etc.
 211  */
 212 struct _PurpleProtocolAttentionInterface {
 213         /*< private >*/
 214         GTypeInterface parent;
 215
 216         /*< public >*/
 217         gboolean (*send)(PurpleProtocolAttention *attn, PurpleConnection *gc,
 218                          const gchar *username, guint type);
 219
 220         GList *(*get_types)(PurpleProtocolAttention *attn, PurpleAccount *acct);
 221 };
 222
 223 /**
 224  * purple_protocol_attention_get_types:
 225  * @attn: The #PurpleProtocolAttention.
 226  * @acct: The #PurpleAccount whose attention types to get.
 227  *
 228  * Returns a list of #PurpleAttentionType's for @attn.
 229  *
 230  * Returns: (transfer container) (element-type PurpleAttentionType): The list of #PurpleAttentionType's.
 231  */
 232 GList *purple_protocol_attention_get_types(PurpleProtocolAttention *attn, PurpleAccount *acct);
 233
 234 /**
 235  * purple_protocol_attention_send:
 236  * @attn: The #PurpleProtocolAttention instance.
 237  * @gc: The #PurpleConnection to send on
 238  * @username: The name of the user to send the attention to.
 239  * @type: The type of attention to send.
 240  *
 241  * Sends an attention message of @type to @username.
 242  *
 243  * Returns: TRUE on success, FALSE otherwise.
 244  */
 245 gboolean purple_protocol_attention_send(PurpleProtocolAttention *attn, PurpleConnection *gc, const gchar *username, guint type);
 246
 247 G_END_DECLS
 248
 249 #endif /* PURPLE_ATTENTION_H */