Changeset 2515

Show
Ignore:
Timestamp:
07/27/07 15:57:24
Author:
pvanhoof
Message:

Various fixes and comments added

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • devel/pvanhoof/sessionwork/libtinymail-camel/tny-session-camel.c

    r2514 r2515  
    6363 
    6464static void tny_session_camel_forget_password (CamelSession *, CamelService *, const char *, const char *, CamelException *); 
     65 
     66 
     67 
     68/* Hey Rob, look here! This gets called when the password is needed. It can have 
     69 * been implemented by the app developer without any Gtk+ code. Sometimes,  
     70 * however, it will launch Gtk+ code. For example the first time the password 
     71 * is needed. 
     72 * 
     73 * This happens in a thread, so does the tny_session_camel_forget_password. The  
     74 * thread is always the queue thread of the account.  
     75 * 
     76 * This is number #1 */ 
    6577 
    6678static char * 
    …… 
    129141} 
    130142 
    131 /** 
    132  * tny_session_camel_set_ui_locker: 
    133  * @self: a #TnySessionCamel instance 
    134  * @ui_lock: a #TnyLockable instance  
    135  * 
    136  * Set the user interface toolkit locker. The lock and unlock methods of this 
    137  * locker should be implemented with the lock and unlock functionality of your 
    138  * user interface toolkit. 
    139  * 
    140  * Good examples are gdk_threads_enter () and gdk_threads_leave () in gtk+. 
    141  **/ 
    142 void  
    143 tny_session_camel_set_ui_locker (TnySessionCamel *self, TnyLockable *ui_lock) 
    144 { 
    145         TnySessionCamelPriv *priv = self->priv; 
    146         if (priv->ui_lock) 
    147                 g_object_unref (G_OBJECT (priv->ui_lock)); 
    148         priv->ui_lock = TNY_LOCKABLE (g_object_ref (ui_lock)); 
    149         return; 
    150 } 
    151  
    152  
     143 
     144/* Hey Rob, look here! This gets called when the password was wrong. It can 
     145 * but usually wont use Gtk+ code by the implementer of the function pointer. 
     146 * Usually the application developer will "forget" the password here. So that 
     147 * The next request for a password gives the user a password dialog box.  
     148 * 
     149 * That request will happen by the tny_session_camel_get_password function. This 
     150 * happens in a thread, so does the tny_session_camel_get_password. The thread 
     151 * is always the queue thread of the account.  
     152 * 
     153 * This is number #2 */ 
    153154 
    154155static void 
    …… 
    176177} 
    177178 
     179/* This is a wrapper for the alerting. Called by on_account_connect_done and 
     180 * tny_session_camel_alert_user (see below for both) */ 
     181 
    178182static gboolean 
    179183tny_session_camel_do_an_error (TnySessionCamel *self, TnyAccount *account, TnyAlertType tnytype, gboolean question, GError *err) 
    …… 
    185189 
    186190/* tny_session_camel_alert_user will for example be called by camel when SSL is on and  
    187    camel_session_get_service is issued (for example TnyCamelTransportAccount and 
    188    TnyCamelStore account issue this function). Its implementation is often done 
    189    with GUI components (it should therefore not be called from a thread). This 
    190    is a known issue (and if someone fixes this, please remove this warning) */ 
     191 * camel_session_get_service is issued (for example TnyCamelTransportAccount and 
     192 * TnyCamelStore account issue this function). Its implementation is often done 
     193 * with GUI components (it should therefore not be called from a thread). */ 
     194 
     195/* Hey Rob, look here! This is an alert that will be launched from a thread.  
     196 * usually the queue thread of the account (I think always, but I have to verify 
     197 * this before making a statement out of it). The user sometimes has to answer  
     198 * this question. For example with a Yes or a No. The typical example is the  
     199 * SSL question and error reporting when the connection is lost)  
     200 * 
     201 * This is number #3 */ 
    191202 
    192203static gboolean 
    …… 
    197208        gboolean retval = FALSE; 
    198209        GError *err = NULL; 
    199  
    200210        TnyAccount *account = NULL; 
     211 
    201212        if (service && service->data) 
    202213                account = TNY_ACCOUNT (service->data); 
    …… 
    230241 
    231242                tny_lockable_lock (self->priv->ui_lock); 
    232  
    233                 TnyAccount *account = NULL; /* TODO. */ 
    234243                retval = tny_session_camel_do_an_error (self, account, tnytype, TRUE, err); 
    235  
    236244                tny_lockable_unlock (self->priv->ui_lock); 
    237245 
    …… 
    240248 
    241249        return retval; 
     250} 
     251 
     252 
     253 
     254/** 
     255 * tny_session_camel_set_ui_locker: 
     256 * @self: a #TnySessionCamel instance 
     257 * @ui_lock: a #TnyLockable instance  
     258 * 
     259 * Set the user interface toolkit locker. The lock and unlock methods of this 
     260 * locker should be implemented with the lock and unlock functionality of your 
     261 * user interface toolkit. 
     262 * 
     263 * Good examples are gdk_threads_enter () and gdk_threads_leave () in gtk+. 
     264 **/ 
     265void  
     266tny_session_camel_set_ui_locker (TnySessionCamel *self, TnyLockable *ui_lock) 
     267{ 
     268        TnySessionCamelPriv *priv = self->priv; 
     269        if (priv->ui_lock) 
     270                g_object_unref (G_OBJECT (priv->ui_lock)); 
     271        priv->ui_lock = TNY_LOCKABLE (g_object_ref (ui_lock)); 
     272        return; 
    242273} 
    243274 
    …… 
    396427 
    397428 
    398 /* Happens at tny_camel_account_set_session */ 
     429/* Happens at tny_camel_account_set_session. This does very few things, actually. 
     430 * Maybe we can factor this away and make the tny_camel_account_set_session not 
     431 * required anymore? Though, the account will always need to know what the session 
     432 * is. So we'd have to find another way to let the account know about this ... */ 
     433 
    399434void  
    400435_tny_session_camel_register_account (TnySessionCamel *self, TnyCamelAccount *account) 
    …… 
    408443 
    409444        return; 
    410  
    411445} 
    412446 
    …… 
    415449{ 
    416450        /* This one happens when a account is finished with connecting. On  
    417          * failure, err is not NULL */ 
     451         * failure, err is not NULL on success it is NULL. This happens in a 
     452         * thread: the queue thread of @account. */ 
     453 
     454        /* Hey Rob, look here! This will happen when you have an error. This 
     455         * "do_an_error" thing will invoke the alert_func from a thread. */ 
    418456 
    419457        if (err) 
    420458        { 
    421459                tny_lockable_lock (self->priv->ui_lock); 
    422                 tny_session_camel_do_an_error (self, TNY_ACCOUNT (account), TNY_ALERT_TYPE_ERROR, FALSE, err); 
     460                tny_session_camel_do_an_error (self, TNY_ACCOUNT (account),  
     461                        TNY_ALERT_TYPE_ERROR, FALSE, err); 
    423462                tny_lockable_unlock (self->priv->ui_lock); 
    424463        } 
    …… 
    639678        } 
    640679 
    641         /* TNY TODO: proper reference counting here please */ 
     680        /* TNY TODO: proper reference counting here please! Note that we can't 
     681         * have embraced references either. So be careful! */ 
     682 
    642683        priv->device = device; 
    643684