libpurple/server.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_SERVER_H
  23 #define PURPLE_SERVER_H
  24 /**
  25  * SECTION:server
  26  * @section_id: libpurple-server
  27  * @short_description: <filename>server.h</filename>
  28  * @title: Server API
  29  */
  30
  31 #include "accounts.h"
  32 #include "attention.h"
  33 #include "conversations.h"
  34 #include "group.h"
  35 #include "message.h"
  36 #include "protocols.h"
  37
  38 G_BEGIN_DECLS
  39
  40 /**
  41  * purple_serv_send_typing:
  42  * @gc:    The connection over which to send the typing notification.
  43  * @name:  The user to send the typing notification to.
  44  * @state: One of PURPLE_IM_TYPING, PURPLE_IM_TYPED, or PURPLE_IM_NOT_TYPING.
  45  *
  46  * Send a typing message to a given user over a given connection.
  47  *
  48  * Returns: A quiet-period, specified in seconds, where Purple will not
  49  *         send any additional typing notification messages.  Most
  50  *         protocols should return 0, which means that no additional
  51  *         PURPLE_IM_TYPING messages need to be sent.  If this is 5, for
  52  *         example, then Purple will wait five seconds, and if the Purple
  53  *         user is still typing then Purple will send another PURPLE_IM_TYPING
  54  *         message.
  55  */
  56 /* TODO Could probably move this into the conversation API. */
  57 unsigned int purple_serv_send_typing(PurpleConnection *gc, const char *name, PurpleIMTypingState state);
  58
  59 /**
  60  * purple_serv_move_buddy:
  61  * @buddy:  The Buddy.
  62  * @orig:   Original group.
  63  * @dest:   Destiny group.
  64  *
  65  * Move a buddy from one group to another on server.
  66  */
  67 void purple_serv_move_buddy(PurpleBuddy *buddy, PurpleGroup *orig, PurpleGroup *dest);
  68
  69 /**
  70  * purple_serv_send_im:
  71  * @gc:     The connection over which to send the typing notification.
  72  * @msg:    The message.
  73  *
  74  * Sends the message to the user through the required protocol.
  75  *
  76  * Returns: The error value returned from the protocol interface function.
  77  */
  78 int  purple_serv_send_im(PurpleConnection *gc, PurpleMessage *msg);
  79
  80 /**
  81  * purple_get_attention_type_from_code:
  82  * @account: The #PurpleAccount
  83  * @type_code: The protocol specific attention type code to convert
  84  *
  85  * Get information about an account's attention commands, from the protocol.
  86  *
  87  * Returns: The attention command numbered 'code' from the protocol's attention_types, or NULL.
  88  */
  89 PurpleAttentionType *purple_get_attention_type_from_code(PurpleAccount *account, guint type_code);
  90
  91 /**
  92  * purple_serv_get_info:
  93  * @gc:     The connection over which to send the typing notification.
  94  * @name:   The name of the buddy we were asking information from.
  95  *
  96  * Request user infromation from the server.
  97  */
  98 void purple_serv_get_info(PurpleConnection *gc, const char *name);
  99
 100 /**
 101  * purple_serv_set_info:
 102  * @gc:     The connection over which to send the typing notification.
 103  * @info:   Information text to be sent to the server.
 104  *
 105  * Set user account information on the server.
 106  */
 107 void purple_serv_set_info(PurpleConnection *gc, const char *info);
 108
 109 /******************************************************************************
 110  * Privacy interface
 111  *****************************************************************************/
 112
 113 /**
 114  * purple_serv_add_permit:
 115  * @gc:     The connection over which to send the typing notification.
 116  * @name:   The name of the remote user.
 117  *
 118  * Add the buddy on the required authorized list.
 119  */
 120 void purple_serv_add_permit(PurpleConnection *gc, const char *name);
 121
 122 /**
 123  * purple_serv_add_deny:
 124  * @gc:     The connection over which to send the typing notification.
 125  * @name:   The name of the remote user.
 126  *
 127  * Add the buddy on the required blocked list.
 128  */
 129 void purple_serv_add_deny(PurpleConnection *gc, const char *name);
 130
 131 /**
 132  * purple_serv_rem_permit:
 133  * @gc:     The connection over which to send the typing notification.
 134  * @name:   The name of the remote user.
 135  *
 136  * Remove the buddy from the required authorized list.
 137  */
 138 void purple_serv_rem_permit(PurpleConnection *gc, const char *name);
 139
 140 /**
 141  * purple_serv_rem_deny:
 142  * @gc:     The connection over which to send the typing notification.
 143  * @name:   The name of the remote user.
 144  *
 145  * Remove the buddy from the required blocked list.
 146  */
 147 void purple_serv_rem_deny(PurpleConnection *gc, const char *name);
 148
 149 /**
 150  * purple_serv_set_permit_deny:
 151  * @gc:     The connection over which to send the typing notification.
 152  *
 153  * Update the server with the privacy information on the permit and deny lists.
 154  */
 155 void purple_serv_set_permit_deny(PurpleConnection *gc);
 156
 157 /******************************************************************************
 158  * Chat Interface
 159  *****************************************************************************/
 160
 161 /**
 162  * purple_serv_chat_invite
 163  * @gc:     The connection over which to send the typing notification.
 164  * @id:     The id of the chat to invite the user to.
 165  * @message:A message displayed to the user when the invitation.
 166  * @name:   The name of the remote user to send the invitation to.
 167  *
 168  * Invite a user to join a chat.
 169  */
 170 void purple_serv_chat_invite(PurpleConnection *gc, int id, const char *message, const char *name);
 171
 172 /**
 173  * purple_serv_chat_leave:
 174  * @gc:     The connection over which to send the typing notification.
 175  * @id:     The id of the chat to leave.
 176  *
 177  * Called when the user requests leaving a chat.
 178  */
 179 void purple_serv_chat_leave(PurpleConnection *gc, int id);
 180
 181 /**
 182  * purple_serv_chat_send:
 183  * @gc:     The connection over which to send the typing notification.
 184  * @id:     The id of the chat to send the message to.
 185  * @msg:    The message to send to the chat.
 186  *
 187  * Send a message to a chat.
 188  *
 189  * This protocol function should return a positive value on
 190  * success. If the message is too big to be sent, return
 191  * <literal>-E2BIG</literal>. If the account is not connected,
 192  * return <literal>-ENOTCONN</literal>. If the protocol is unable
 193  * to send the message for another reason, return some other
 194  * negative value. You can use one of the valid #errno values, or
 195  * just big something.
 196  *
 197  * Returns:  A positive number or 0 in case of success, a
 198  *           negative error number in case of failure.
 199  */
 200 int  purple_serv_chat_send(PurpleConnection *gc, int id, PurpleMessage *msg);
 201
 202 /******************************************************************************
 203  * Server Interface
 204  *****************************************************************************/
 205
 206 /**
 207  * purple_serv_alias_buddy:
 208  * @buddy:  The Buddy.
 209  *
 210  * Save/store buddy's alias on server list/roster
 211  */
 212 void purple_serv_alias_buddy(PurpleBuddy *buddy);
 213
 214 /**
 215  * purple_serv_got_alias:
 216  * @gc:     The connection over which to send the typing notification.
 217  * @who: The name of the buddy whose alias was received.
 218  * @alias: The alias that was received.
 219  *
 220  * Protocol should call this function when it retrieves an alias form the server.
 221  *
 222  */
 223 void purple_serv_got_alias(PurpleConnection *gc, const char *who, const char *alias);
 224
 225 /**
 226  * purple_serv_got_private_alias:
 227  * @gc: The connection on which the alias was received.
 228  * @who: The name of the buddy whose alias was received.
 229  * @alias: The alias that was received.
 230  *
 231  * A protocol should call this when it retrieves a private alias from
 232  * the server.  Private aliases are the aliases the user sets, while public
 233  * aliases are the aliases or display names that buddies set for themselves.
 234  */
 235 void purple_serv_got_private_alias(PurpleConnection *gc, const char *who, const char *alias);
 236
 237
 238 /**
 239  * purple_serv_got_typing:
 240  * @gc:      The connection on which the typing message was received.
 241  * @name:    The name of the remote user.
 242  * @timeout: If this is a number greater than 0, then
 243  *        Purple will wait this number of seconds and then
 244  *        set this buddy to the PURPLE_IM_NOT_TYPING state.  This
 245  *        is used by protocols that send repeated typing messages
 246  *        while the user is composing the message.
 247  * @state:   The typing state received
 248  *
 249  * Receive a typing message from a remote user.  Either PURPLE_IM_TYPING
 250  * or PURPLE_IM_TYPED.  If the user has stopped typing then use
 251  * purple_serv_got_typing_stopped instead.
 252  *
 253  * @todo Could probably move this into the conversation API.
 254  */
 255 void purple_serv_got_typing(PurpleConnection *gc, const char *name, int timeout,
 256                                          PurpleIMTypingState state);
 257
 258 /**
 259  * purple_serv_got_typing_stopped:
 260  * @gc: The #PurpleConnection
 261  * @name: The name of the person that stopped typing.
 262  *
 263  * Called from a protocol when it has recieved a type stopped.
 264  *
 265  * @todo Could probably move this into the conversation API.
 266  */
 267 void purple_serv_got_typing_stopped(PurpleConnection *gc, const char *name);
 268
 269 /**
 270  * purple_serv_got_im:
 271  * @gc:     The connection on which the typing message was received.
 272  * @who:    The username of the buddy that sent the message.
 273  * @msg:    The actual message received.
 274  * @flags:  The flags applicable to this message.
 275  * @mtime:  The timestamp of the message.
 276  *
 277  * This function is called by the protocol when it receives an IM message.
 278  */
 279 void purple_serv_got_im(PurpleConnection *gc, const char *who, const char *msg,
 280                                  PurpleMessageFlags flags, time_t mtime);
 281
 282 /**
 283  * purple_serv_join_chat:
 284  * @gc:   The #PurpleConnection
 285  * @data: The hash function should be g_str_hash() and the equal
 286  *             function should be g_str_equal().
 287  */
 288 void purple_serv_join_chat(PurpleConnection *gc, GHashTable *data);
 289
 290 /**
 291  * purple_serv_reject_chat:
 292  * @gc: The #PurpleConnection
 293  * @data: The hash function should be g_str_hash() and the equal
 294  *             function should be g_str_equal().
 295  */
 296 void purple_serv_reject_chat(PurpleConnection *gc, GHashTable *data);
 297
 298 /**
 299  * purple_serv_got_chat_invite:
 300  * @gc:      The connection on which the invite arrived.
 301  * @name:    The name of the chat you're being invited to.
 302  * @who:     The username of the person inviting the account.
 303  * @message: The optional invite message.
 304  * @data:    The components necessary if you want to call purple_serv_join_chat().
 305  *                The hash function should be g_str_hash() and the equal
 306  *                function should be g_str_equal().
 307  *
 308  * Called by a protocol when an account is invited into a chat.
 309  */
 310 void purple_serv_got_chat_invite(PurpleConnection *gc, const char *name,
 311                                                   const char *who, const char *message,
 312                                                   GHashTable *data);
 313
 314 /**
 315  * purple_serv_got_joined_chat:
 316  * @gc:   The connection on which the chat was joined.
 317  * @id:   The id of the chat, assigned by the protocol.
 318  * @name: The name of the chat.
 319  *
 320  * Called by a protocol when an account has joined a chat.
 321  *
 322  * Returns: (transfer none): The resulting conversation.
 323  */
 324 PurpleChatConversation *purple_serv_got_joined_chat(PurpleConnection *gc,
 325                                                                            int id, const char *name);
 326 /**
 327  * purple_serv_got_join_chat_failed:
 328  * @gc:      The connection on which chat joining failed
 329  * @data:    The components passed to purple_serv_join_chat() originally.
 330  *                The hash function should be g_str_hash() and the equal
 331  *                function should be g_str_equal().
 332  *
 333  * Called by a protocol when an attempt to join a chat via purple_serv_join_chat()
 334  * fails.
 335  */
 336 void purple_serv_got_join_chat_failed(PurpleConnection *gc, GHashTable *data);
 337
 338 /**
 339  * purple_serv_got_chat_left:
 340  * @g:  The connection on which the chat was left.
 341  * @id: The id of the chat, as assigned by the protocol.
 342  *
 343  * Called by a protocol when an account has left a chat.
 344  */
 345 void purple_serv_got_chat_left(PurpleConnection *g, int id);
 346
 347 /**
 348  * purple_serv_got_chat_in:
 349  * @g:       The connection on which the message was received.
 350  * @id:      The id of the chat, as assigned by the protocol.
 351  * @who:     The name of the user who sent the message.
 352  * @flags:   The flags of the message.
 353  * @message: The message received in the chat.
 354  * @mtime:   The time when the message was received.
 355  *
 356  * Called by a protocol when a message has been received in a chat.
 357  */
 358 void purple_serv_got_chat_in(PurpleConnection *g, int id, const char *who,
 359                                           PurpleMessageFlags flags, const char *message, time_t mtime);
 360
 361 /**
 362  * purple_serv_send_file:
 363  * @gc:     The connection on which the message was received.
 364  * @who:    The name of the user to who send the file.
 365  * @file:   The filename to send.
 366  *
 367  * Send a filename to a given contact.
 368  */
 369 void purple_serv_send_file(PurpleConnection *gc, const char *who, const char *file);
 370
 371 G_END_DECLS
 372
 373 #endif /* PURPLE_SERVER_H */