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