X-Git-Url: http://git.maemo.org/git/?p=python-purple;a=blobdiff_plain;f=signal_cbs.pxd;h=5cc1075fac70f8106eb7127e07b7711793d9394c;hp=b1bb26d776dedde8301898b1d7d3be405b98b7a2;hb=fe31cc60e134bb3cb2794866f81acd2686307756;hpb=b4e3af9714befc9e9a71b843916a3dd48ef2c238

diff --git a/signal_cbs.pxd b/signal_cbs.pxd
index b1bb26d..5cc1075 100644
--- a/signal_cbs.pxd
+++ b/signal_cbs.pxd
@@ -21,54 +21,64 @@ cimport purple
 
 signal_cbs = {}
 
-cdef void signal_signed_on_cb (connection.PurpleConnection *gc, \
-                               glib.gpointer null):
-    cdef account.PurpleAccount *acc = connection.c_purple_connection_get_account(gc)
+cdef void signal_signed_on_cb(connection.PurpleConnection *gc, \
+        glib.gpointer null):
+    """
+    Emitted when a connection has signed on.
+    @params gc  The connection that has signed on.
+    """
+    cdef account.PurpleAccount *acc = connection.purple_connection_get_account(gc)
     cdef char *c_username = NULL
     cdef char *c_protocol_id = NULL
 
-    c_username = <char *> account.c_purple_account_get_username(acc)
+    c_username = <char *> account.purple_account_get_username(acc)
     if c_username == NULL:
         username = None
     else:
         username = c_username
 
-    c_protocol_id = <char *> account.c_purple_account_get_protocol_id(acc)
+    c_protocol_id = <char *> account.purple_account_get_protocol_id(acc)
     if c_protocol_id == NULL:
         protocol_id = None
     else:
         protocol_id = c_protocol_id
 
-    try:
+    if signal_cbs.has_key("signed-on"):
         (<object> signal_cbs["signed-on"])(username, protocol_id)
-    except KeyError:
-        pass
 
-cdef void signal_signed_off_cb (connection.PurpleConnection *gc, \
-                               glib.gpointer null):
-    cdef account.PurpleAccount *acc = connection.c_purple_connection_get_account(gc)
+cdef void signal_signed_off_cb(connection.PurpleConnection *gc, \
+        glib.gpointer null):
+    """
+    Emitted when a connection has signed off.
+    @params gc  The connection that has signed off.
+    """
+    cdef account.PurpleAccount *acc = connection.purple_connection_get_account(gc)
     cdef char *c_username = NULL
     cdef char *c_protocol_id = NULL
 
-    c_username = <char *> account.c_purple_account_get_username(acc)
+    c_username = <char *> account.purple_account_get_username(acc)
     if c_username == NULL:
         username = None
     else:
         username = c_username
 
-    c_protocol_id = <char *> account.c_purple_account_get_protocol_id(acc)
+    c_protocol_id = <char *> account.purple_account_get_protocol_id(acc)
     if c_protocol_id == NULL:
         protocol_id = None
     else:
         protocol_id = c_protocol_id
 
-    try:
+    if signal_cbs.has_key("signed-off"):
         (<object> signal_cbs["signed-off"])(username, protocol_id)
-    except KeyError:
-        pass
 
-cdef void signal_connection_error_cb (connection.PurpleConnection *gc, \
+cdef void signal_connection_error_cb(connection.PurpleConnection *gc, \
         connection.PurpleConnectionError err, char *c_desc):
+    """
+    Emitted when a connection error occurs, before signed-off.
+    @params gc   The connection on which the error has occured
+    @params err  The error that occured
+    @params desc A description of the error, giving more information
+    """
 
     short_desc = {
         0: "Network error",
@@ -94,78 +104,90 @@ cdef void signal_connection_error_cb (connection.PurpleConnection *gc, \
     else:
         desc = c_desc
 
-    try:
+    if signal_cbs.has_key("connection-error"):
         (<object> signal_cbs["connection-error"])(short_desc, desc)
-    except KeyError:
-        pass
 
-cdef void signal_buddy_signed_on_cb (blist.PurpleBuddy *buddy):
+cdef void signal_buddy_signed_on_cb(blist.PurpleBuddy *buddy):
+    """
+    Emitted when a buddy on your buddy list signs on.
+    @params buddy  The buddy that signed on.
+    """
     cdef char *c_name = NULL
     cdef char *c_alias = NULL
 
-    c_name = <char *> blist.c_purple_buddy_get_name(buddy)
+    c_name = <char *> blist.purple_buddy_get_name(buddy)
     if c_name == NULL:
         name = None
     else:
         name = c_name
 
-    c_alias = <char *> blist.c_purple_buddy_get_alias_only(buddy)
+    c_alias = <char *> blist.purple_buddy_get_alias_only(buddy)
     if c_alias == NULL:
         alias = None
     else:
         alias = c_alias
 
-    try:
+    if signal_cbs.has_key("buddy-signed-on"):
         (<object> signal_cbs["buddy-signed-on"])(name, alias)
-    except KeyError:
-        pass
 
-cdef void signal_buddy_signed_off_cb (blist.PurpleBuddy *buddy):
+cdef void signal_buddy_signed_off_cb(blist.PurpleBuddy *buddy):
+    """
+    Emitted when a buddy on your buddy list signs off.
+    @params buddy  The buddy that signed off.
+    """
     cdef char *c_name = NULL
     cdef char *c_alias = NULL
 
-    c_name = <char *> blist.c_purple_buddy_get_name(buddy)
+    c_name = <char *> blist.purple_buddy_get_name(buddy)
     if c_name == NULL:
         name = None
     else:
         name = c_name
 
-    c_alias = <char *> blist.c_purple_buddy_get_alias_only(buddy)
+    c_alias = <char *> blist.purple_buddy_get_alias_only(buddy)
     if c_alias == NULL:
         alias = None
     else:
         alias = c_alias
 
-    try:
+    if signal_cbs.has_key("buddy-signed-off"):
         (<object> signal_cbs["buddy-signed-off"])(name, alias)
-    except KeyError:
-        pass
 
-cdef glib.gboolean signal_receiving_im_msg_cb (account.PurpleAccount *account,
-        char **sender, char **message, conversation.PurpleConversation *conv,
+cdef glib.gboolean signal_receiving_im_msg_cb(account.PurpleAccount *account, \
+        char **sender, char **message, conversation.PurpleConversation *conv, \
         conversation.PurpleMessageFlags *flags):
-    cdef blist.PurpleBuddy *buddy = blist.c_purple_find_buddy(account, sender[0])
+    """
+    Emitted when an IM is received. The callback can replace the name of the
+    sender, the message, or the flags by modifying the pointer to the strings
+    and integer. This can also be used to cancel a message by returning TRUE.
+    @note Make sure to free *sender and *message before you replace them!
+    @returns TRUE if the message should be canceled, or FALSE otherwise.
+    @params account  The account the message was received on.
+    @params sender   A pointer to the username of the sender.
+    @params message  A pointer to the message that was sent.
+    @params conv     The IM conversation.
+    @params flags    A pointer to the IM message flags.
+    """
+    cdef blist.PurpleBuddy *buddy = blist.purple_find_buddy(account, sender[0])
     cdef char *c_alias = NULL
 
-    c_alias = <char *> blist.c_purple_buddy_get_alias_only(buddy)
+    c_alias = <char *> blist.purple_buddy_get_alias_only(buddy)
     if c_alias == NULL:
         alias = None
     else:
         alias = c_alias
 
-    stripped = util.c_purple_markup_strip_html(message[0])
+    stripped = util.purple_markup_strip_html(message[0])
 
-    try:
+    if signal_cbs.has_key("receiving-im-msg"):
         return (<object> signal_cbs["receiving-im-msg"])(sender[0], alias, stripped)
-    except KeyError:
-        return False
 
-cdef void jabber_receiving_xmlnode_cb (connection.PurpleConnection *gc,
+cdef void jabber_receiving_xmlnode_cb(connection.PurpleConnection *gc, \
         xmlnode.xmlnode **packet, glib.gpointer null):
-
+    """
+    Emitted when jabber receives a XML node.
+    """
     message = xmlnode.xmlnode_to_str(packet[0], NULL)
 
-    try:
+    if signal_cbs.has_key("jabber-receiving-xmlnode"):
         (<object> signal_cbs["jabber-receiving-xmlnode"])(message)
-    except KeyError:
-        pass