# HG changeset patch # User sttwister@gmail.com # Date 1258924432 0 # Node ID a7dadbac9897def3f6bbd737b3b1a8ea09f5e597 # Parent 603248bd90b3ea9900cf50809ff045a29ccf210f# Parent e37f8516078454990713119419f982857833defe merge of '5dd45a65920d3936eba743066aaa34e00084f3bd' and 'fb6720021f78a702553fa19e56bba989db098b67' diff -r 603248bd90b3 -r a7dadbac9897 libpurple/prpl.h --- a/libpurple/prpl.h Sun Nov 22 21:13:50 2009 +0000 +++ b/libpurple/prpl.h Sun Nov 22 21:13:52 2009 +0000 @@ -91,14 +91,17 @@ PurpleIconScaleRules scale_rules; /**< How to stretch this icon */ }; +/** Represents an entry containing information that must be supplied by the + * user when joining a chat. + */ struct proto_chat_entry { - const char *label; - const char *identifier; - gboolean required; - gboolean is_int; - int min; - int max; - gboolean secret; + const char *label; /**< User-friendly name of the entry */ + const char *identifier; /**< Used by the PRPL to identify the option */ + gboolean required; /**< True if it's required */ + gboolean is_int; /**< True if the entry expects an integer */ + int min; /**< Minimum value in case of integer */ + int max; /**< Maximum value in case of integer */ + gboolean secret; /**< True if the entry is secret (password) */ }; /** Represents "nudges" and "buzzes" that you may send to a buddy to attract @@ -252,7 +255,26 @@ * node. */ GList *(*blist_node_menu)(PurpleBlistNode *node); + + /** + * Returns a list of #proto_chat_entry structs, which represent + * information required by the PRPL to join a chat. libpurple will + * call join_chat along with the information filled by the user. + * + * @return A list of #proto_chat_entry structs + */ GList *(*chat_info)(PurpleConnection *); + + /** + * Returns a hashtable which maps #proto_chat_entry struct identifiers + * to default options as strings based on chat_name. The resulting + * hashtable should be created with g_hash_table_new_full(g_str_hash, + * g_str_equal, NULL, g_free);. Use #get_chat_name if you instead need + * to extract a chat name from a hashtable. + * + * @param chat_name The chat name to be turned into components + * @return Hashtable containing the information extracted from chat_name + */ GHashTable *(*chat_info_defaults)(PurpleConnection *, const char *chat_name); /* All the server-related functions */ @@ -314,14 +336,80 @@ void (*rem_permit)(PurpleConnection *, const char *name); void (*rem_deny)(PurpleConnection *, const char *name); void (*set_permit_deny)(PurpleConnection *); + + /** + * Called when the user requests joining a chat. Should arrange for + * #serv_got_joined_chat to be called. + * + * @param components A hashtable containing information required to + * join the chat as described by the entries returned + * by #chat_info. It may also be called when accepting + * an invitation, in which case this matches the + * data parameter passed to #serv_got_chat_invite. + */ void (*join_chat)(PurpleConnection *, GHashTable *components); + + /** + * Called when the user refuses a chat invitation. + * + * @param components A hashtable containing information required to + * join the chat as passed to #serv_got_chat_invite. + */ void (*reject_chat)(PurpleConnection *, GHashTable *components); + + /** + * Returns a chat name based on the information in components. Use + * #chat_info_defaults if you instead need to generate a hashtable + * from a chat name. + * + * @param components A hashtable containing information about the chat. + */ char *(*get_chat_name)(GHashTable *components); + + /** + * Invite a user to join a chat. + * + * @param id The id of the chat to invite the user to. + * @param message A message displayed to the user when the invitation + * is received. + * @param who The name of the user to send the invation to. + */ void (*chat_invite)(PurpleConnection *, int id, const char *message, const char *who); + /** + * Called when the user requests leaving a chat. + * + * @param id The id of the chat to leave + */ void (*chat_leave)(PurpleConnection *, int id); + + /** + * Send a whisper to a user in a chat. + * + * @param id The id of the chat. + * @param who The name of the user to send the whisper to. + * @param message The message of the whisper. + */ void (*chat_whisper)(PurpleConnection *, int id, const char *who, const char *message); + + /** + * Send a message to a chat. + * This PRPL function should return a positive value on success. + * If the message is too big to be sent, return -E2BIG. If + * the account is not connected, return -ENOTCONN. If the + * PRPL is unable to send the message for another reason, return + * some other negative value. You can use one of the valid + * errno values, or just big something. If the message should + * not be echoed to the conversation window, return 0. + * + * @param id The id of the chat to send the message to. + * @param message The message to send to the chat. + * @param flags A bitwise OR of #PurpleMessageFlags representing + * message flags. + * @return A positive number or 0 in case of succes, + * a negative error number in case of failure. + */ int (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags); /** If implemented, this will be called regularly for this prpl's diff -r 603248bd90b3 -r a7dadbac9897 libpurple/server.h --- a/libpurple/server.h Sun Nov 22 21:13:50 2009 +0000 +++ b/libpurple/server.h Sun Nov 22 21:13:52 2009 +0000 @@ -168,6 +168,14 @@ const char *who, const char *message, GHashTable *data); +/** + * Called by a prpl when an account has joined a chat. + * + * @param gc The connection on which the chat was joined. + * @param id The id of the chat, assigned by the prpl. + * @param name The name of the chat. + * @return The resulting conversation + */ PurpleConversation *serv_got_joined_chat(PurpleConnection *gc, int id, const char *name); /** @@ -181,7 +189,24 @@ */ void purple_serv_got_join_chat_failed(PurpleConnection *gc, GHashTable *data); +/** + * Called by a prpl when an account has left a chat. + * + * @param g The connection on which the chat was left. + * @param id The id of the chat, as assigned by the prpl. + */ void serv_got_chat_left(PurpleConnection *g, int id); + +/** + * Called by a prpl when a message has been received in a chat. + * + * @param g The connection on which the message was received. + * @param id The id of the chat, as assigned by the prpl. + * @param who The name of the user who sent the message. + * @param flags The flags of the message. + * @param message The message received in the chat. + * @param mtime The time when the message was received. + */ void serv_got_chat_in(PurpleConnection *g, int id, const char *who, PurpleMessageFlags flags, const char *message, time_t mtime); void serv_send_file(PurpleConnection *gc, const char *who, const char *file);