libpurple/server.h

   1 /**
   2  * @file server.h Server API
   3  * @ingroup core
   4  */
   5
   6 /* purple
   7  *
   8  * Purple is the legal property of its developers, whose names are too numerous
   9  * to list here.  Please refer to the COPYRIGHT file distributed with this
  10  * source distribution.
  11  *
  12  * This program is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  25  */
  26 #ifndef _PURPLE_SERVER_H_
  27 #define _PURPLE_SERVER_H_
  28
  29 #include "account.h"
  30 #include "conversation.h"
  31 #include "prpl.h"
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /**
  38  * Send a typing message to a given user over a given connection.
  39  *
  40  * TODO: Could probably move this into the conversation API.
  41  *
  42  * @param gc    The connection over which to send the typing notification.
  43  * @param name  The user to send the typing notification to.
  44  * @param state One of PURPLE_TYPING, PURPLE_TYPED, or PURPLE_NOT_TYPING.
  45  * @return A quiet-period, specified in seconds, where Purple will not
  46  *         send any additional typing notification messages.  Most
  47  *         protocols should return 0, which means that no additional
  48  *         PURPLE_TYPING messages need to be sent.  If this is 5, for
  49  *         example, then Purple will wait five seconds, and if the Purple
  50  *         user is still typing then Purple will send another PURPLE_TYPING
  51  *         message.
  52  */
  53 unsigned int serv_send_typing(PurpleConnection *gc, const char *name, PurpleTypingState state);
  54
  55 void serv_move_buddy(PurpleBuddy *, PurpleGroup *, PurpleGroup *);
  56 int  serv_send_im(PurpleConnection *, const char *, const char *, PurpleMessageFlags flags);
  57
  58 /** Get information about an account's attention commands, from the prpl.
  59  *
  60  * @return The attention command numbered 'code' from the prpl's attention_types, or NULL.
  61  */
  62 PurpleAttentionType *purple_get_attention_type_from_code(PurpleAccount *account, guint type_code);
  63
  64 /** Send an attention request message.
  65  *
  66  * @deprecated Use purple_prpl_send_attention() instead.
  67  *
  68  * @param gc The connection to send the message on.
  69  * @param who Whose attention to request.
  70  * @param type_code An index into the prpl's attention_types list determining the type
  71  *      of the attention request command to send. 0 if prpl only defines one
  72  *      (for example, Yahoo and MSN), but some protocols define more (MySpaceIM).
  73  *
  74  * Note that you can't send arbitrary PurpleAttentionType's, because there is
  75  * only a fixed set of attention commands.
  76  */
  77 void serv_send_attention(PurpleConnection *gc, const char *who, guint type_code);
  78
  79 /** Process an incoming attention message.
  80  *
  81  * @deprecated Use purple_prpl_got_attention() instead.
  82  *
  83  * @param gc The connection that received the attention message.
  84  * @param who Who requested your attention.
  85  * @param type_code An index into the prpl's attention_types list determining the type
  86  *      of the attention request command to send.
  87  */
  88 void serv_got_attention(PurpleConnection *gc, const char *who, guint type_code);
  89
  90 void serv_get_info(PurpleConnection *, const char *);
  91 void serv_set_info(PurpleConnection *, const char *);
  92
  93 void serv_add_permit(PurpleConnection *, const char *);
  94 void serv_add_deny(PurpleConnection *, const char *);
  95 void serv_rem_permit(PurpleConnection *, const char *);
  96 void serv_rem_deny(PurpleConnection *, const char *);
  97 void serv_set_permit_deny(PurpleConnection *);
  98 void serv_chat_invite(PurpleConnection *, int, const char *, const char *);
  99 void serv_chat_leave(PurpleConnection *, int);
 100 void serv_chat_whisper(PurpleConnection *, int, const char *, const char *);
 101 int  serv_chat_send(PurpleConnection *, int, const char *, PurpleMessageFlags flags);
 102 void serv_alias_buddy(PurpleBuddy *);
 103 void serv_got_alias(PurpleConnection *gc, const char *who, const char *alias);
 104
 105 /**
 106  * A protocol plugin should call this when it retrieves a private alias from
 107  * the server.  Private aliases are the aliases the user sets, while public
 108  * aliases are the aliases or display names that buddies set for themselves.
 109  *
 110  * @param gc The connection on which the alias was received.
 111  * @param who The name of the buddy whose alias was received.
 112  * @param alias The alias that was received.
 113  */
 114 void purple_serv_got_private_alias(PurpleConnection *gc, const char *who, const char *alias);
 115
 116
 117 /**
 118  * Receive a typing message from a remote user.  Either PURPLE_TYPING
 119  * or PURPLE_TYPED.  If the user has stopped typing then use
 120  * serv_got_typing_stopped instead.
 121  *
 122  * TODO: Could probably move this into the conversation API.
 123  *
 124  * @param gc      The connection on which the typing message was received.
 125  * @param name    The name of the remote user.
 126  * @param timeout If this is a number greater than 0, then
 127  *        Purple will wait this number of seconds and then
 128  *        set this buddy to the PURPLE_NOT_TYPING state.  This
 129  *        is used by protocols that send repeated typing messages
 130  *        while the user is composing the message.
 131  * @param state   The typing state received
 132  */
 133 void serv_got_typing(PurpleConnection *gc, const char *name, int timeout,
 134                                          PurpleTypingState state);
 135
 136 /**
 137  * TODO: Could probably move this into the conversation API.
 138  */
 139 void serv_got_typing_stopped(PurpleConnection *gc, const char *name);
 140
 141 void serv_got_im(PurpleConnection *gc, const char *who, const char *msg,
 142                                  PurpleMessageFlags flags, time_t mtime);
 143
 144 /**
 145  * @param data The hash function should be g_str_hash() and the equal
 146  *             function should be g_str_equal().
 147  */
 148 void serv_join_chat(PurpleConnection *, GHashTable *data);
 149
 150 /**
 151  * @param data The hash function should be g_str_hash() and the equal
 152  *             function should be g_str_equal().
 153  */
 154 void serv_reject_chat(PurpleConnection *, GHashTable *data);
 155
 156 /**
 157  * Called by a prpl when an account is invited into a chat.
 158  *
 159  * @param gc      The connection on which the invite arrived.
 160  * @param name    The name of the chat you're being invited to.
 161  * @param who     The username of the person inviting the account.
 162  * @param message The optional invite message.
 163  * @param data    The components necessary if you want to call serv_join_chat().
 164  *                The hash function should be g_str_hash() and the equal
 165  *                function should be g_str_equal().
 166  */
 167 void serv_got_chat_invite(PurpleConnection *gc, const char *name,
 168                                                   const char *who, const char *message,
 169                                                   GHashTable *data);
 170
 171 /**
 172  * Called by a prpl when an account has joined a chat.
 173  *
 174  * @param gc   The connection on which the chat was joined.
 175  * @param id   The id of the chat, assigned by the prpl.
 176  * @param name The name of the chat.
 177  * @return     The resulting conversation
 178  */
 179 PurpleConversation *serv_got_joined_chat(PurpleConnection *gc,
 180                                                                            int id, const char *name);
 181 /**
 182  * Called by a prpl when an attempt to join a chat via serv_join_chat()
 183  * fails.
 184  *
 185  * @param gc      The connection on which chat joining failed
 186  * @param data    The components passed to serv_join_chat() originally.
 187  *                The hash function should be g_str_hash() and the equal
 188  *                function should be g_str_equal().
 189  */
 190 void purple_serv_got_join_chat_failed(PurpleConnection *gc, GHashTable *data);
 191
 192 /**
 193  * Called by a prpl when an account has left a chat.
 194  *
 195  * @param g  The connection on which the chat was left.
 196  * @param id The id of the chat, as assigned by the prpl.
 197  */
 198 void serv_got_chat_left(PurpleConnection *g, int id);
 199
 200 /**
 201  * Called by a prpl when a message has been received in a chat.
 202  *
 203  * @param g       The connection on which the message was received.
 204  * @param id      The id of the chat, as assigned by the prpl.
 205  * @param who     The name of the user who sent the message.
 206  * @param flags   The flags of the message.
 207  * @param message The message received in the chat.
 208  * @param mtime   The time when the message was received.
 209  */
 210 void serv_got_chat_in(PurpleConnection *g, int id, const char *who,
 211                                           PurpleMessageFlags flags, const char *message, time_t mtime);
 212 void serv_send_file(PurpleConnection *gc, const char *who, const char *file);
 213
 214 #ifdef __cplusplus
 215 }
 216 #endif
 217
 218 #endif /* _PURPLE_SERVER_H_ */