Changeset 1855

Show
Ignore:
Timestamp:
04/28/07 12:27:56
Author:
pvanhoof
Message:

Documentation updates and changes to TnyAccountStore

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/ChangeLog

    r1851 r1855  
     12007-04-28  Philip Van Hoof  <pvanhoof@gnome.org> 
     2 
     3        * Documentation updates 
     4        * Changes to the TnyAccountStore API 
     5 
     6        * This was a major API change 
     7 
    182007-04-27  Philip Van Hoof  <pvanhoof@gnome.org> 
    29 

  • trunk/libtinymail-acap/tny-acap-account-store.c

    r1784 r1855  
    109109 
    110110 
    111  
    112 static void 
    113 add_account_remote (TnyAccountStore *self, TnyAccount *account, const gchar *type) 
    114 { 
    115         g_warning ("Not implemented\n"); 
    116  
    117         /* TODO: implement for ACAP */ 
    118  
    119         return; 
    120 } 
    121  
    122  
    123 static void 
    124 add_account_journal (TnyAccountStore *self, TnyAccount *account, const gchar *type) 
    125 { 
    126         g_warning ("Not implemented\n"); 
    127  
    128         /* TODO: implement for ACAP */ 
    129  
    130         return; 
    131 } 
    132  
    133 static void 
    134 tny_acap_account_store_add_store_account (TnyAccountStore *self, TnyStoreAccount *account) 
    135 { 
    136         TnyAcapAccountStorePriv *priv = TNY_ACAP_ACCOUNT_STORE_GET_PRIVATE (self); 
    137         TnyDevice *device = tny_account_store_get_device (priv->real); 
    138  
    139         if (tny_device_is_online (device)) 
    140                 add_account_remote (self, TNY_ACCOUNT (account), "store"); 
    141         else 
    142                 add_account_journal (self, TNY_ACCOUNT (account), "store"); 
    143  
    144         g_object_unref (G_OBJECT (device)); 
    145  
    146         tny_account_store_add_store_account (priv->real, account); 
    147  
    148         return; 
    149 } 
    150  
    151 static void 
    152 tny_acap_account_store_add_transport_account (TnyAccountStore *self, TnyTransportAccount *account) 
    153 { 
    154         TnyAcapAccountStorePriv *priv = TNY_ACAP_ACCOUNT_STORE_GET_PRIVATE (self); 
    155         TnyDevice *device = tny_account_store_get_device (priv->real); 
    156  
    157         if (tny_device_is_online (device)) 
    158                 add_account_remote (self, TNY_ACCOUNT (account), "transport"); 
    159         else 
    160                 add_account_journal (self, TNY_ACCOUNT (account), "transport"); 
    161  
    162         g_object_unref (G_OBJECT (device)); 
    163  
    164         tny_account_store_add_transport_account (priv->real, account); 
    165  
    166         return; 
    167 } 
    168  
    169111static TnyDevice* 
    170112tny_acap_account_store_get_device (TnyAccountStore *self) 
    …… 
    275217 
    276218        klass->get_accounts_func = tny_acap_account_store_get_accounts; 
    277         klass->add_store_account_func = tny_acap_account_store_add_store_account; 
    278         klass->add_transport_account_func = tny_acap_account_store_add_transport_account; 
    279219        klass->get_cache_dir_func = tny_acap_account_store_get_cache_dir; 
    280220        klass->get_device_func = tny_acap_account_store_get_device; 

  • trunk/libtinymail-gnome-desktop/tny-gnome-account-store.c

    r1784 r1855  
    492492 
    493493 
    494  
    495 static void 
    496 tny_gnome_account_store_add_store_account (TnyAccountStore *self, TnyStoreAccount *account) 
    497 { 
    498         tny_gnome_account_store_notify_remove (self); 
    499         tny_gnome_account_store_add_account (self, TNY_ACCOUNT (account), "store"); 
    500         tny_gnome_account_store_notify_add (self); 
     494void 
     495tny_gnome_account_store_add_store_account (TnyGnomeAccountStore *self, TnyStoreAccount *account) 
     496{ 
     497        tny_gnome_account_store_notify_remove (TNY_ACCOUNT_STORE (self)); 
     498        tny_gnome_account_store_add_account (TNY_ACCOUNT_STORE (self), TNY_ACCOUNT (account), "store"); 
     499        tny_gnome_account_store_notify_add (TNY_ACCOUNT_STORE (self)); 
    501500 
    502501        g_signal_emit (self, tny_account_store_signals [TNY_ACCOUNT_STORE_ACCOUNT_INSERTED], 0, account); 
    …… 
    505504} 
    506505 
    507 static void 
    508 tny_gnome_account_store_add_transport_account (TnyAccountStore *self, TnyTransportAccount *account) 
    509 { 
    510         tny_gnome_account_store_notify_remove (self); 
    511         tny_gnome_account_store_add_account (self, TNY_ACCOUNT (account), "transport"); 
    512         tny_gnome_account_store_notify_add (self); 
     506void 
     507tny_gnome_account_store_add_transport_account (TnyGnomeAccountStore *self, TnyTransportAccount *account) 
     508{ 
     509        tny_gnome_account_store_notify_remove (TNY_ACCOUNT_STORE (self)); 
     510        tny_gnome_account_store_add_account (TNY_ACCOUNT_STORE (self), TNY_ACCOUNT (account), "transport"); 
     511        tny_gnome_account_store_notify_add (TNY_ACCOUNT_STORE (self)); 
    513512 
    514513        g_signal_emit (self, tny_account_store_signals [TNY_ACCOUNT_STORE_ACCOUNT_INSERTED], 0, account); 
    …… 
    621620 
    622621        klass->get_accounts_func = tny_gnome_account_store_get_accounts; 
    623         klass->add_store_account_func = tny_gnome_account_store_add_store_account; 
    624         klass->add_transport_account_func = tny_gnome_account_store_add_transport_account; 
    625622        klass->get_cache_dir_func = tny_gnome_account_store_get_cache_dir; 
    626623        klass->get_device_func = tny_gnome_account_store_get_device; 

  • trunk/libtinymail-gnome-desktop/tny-gnome-account-store.h

    r1736 r1855  
    5353TnySessionCamel* tny_gnome_account_store_get_session (TnyGnomeAccountStore *self); 
    5454 
     55void tny_gnome_account_store_add_store_account (TnyGnomeAccountStore *self, TnyStoreAccount *account); 
     56void tny_gnome_account_store_add_transport_account (TnyGnomeAccountStore *self, TnyTransportAccount *account); 
     57 
    5558G_END_DECLS 
    5659 

  • trunk/libtinymail-gpe/tny-gpe-account-store.c

    r1784 r1855  
    493493 
    494494 
    495 static void 
    496 tny_gpe_account_store_add_store_account (TnyAccountStore *self, TnyStoreAccount *account) 
    497 { 
    498         TnyGpeAccountStorePriv *priv = TNY_GPE_ACCOUNT_STORE_GET_PRIVATE (self); 
    499  
    500         tny_gpe_account_store_notify_remove (self); 
    501         tny_gpe_account_store_add_account (self, TNY_ACCOUNT (account), "store"); 
    502         tny_gpe_account_store_notify_add (self); 
     495void 
     496tny_gpe_account_store_add_store_account (TnyGpeAccountStore *self, TnyStoreAccount *account) 
     497{ 
     498        TnyGpeAccountStorePriv *priv = TNY_GPE_ACCOUNT_STORE_GET_PRIVATE (self); 
     499 
     500        tny_gpe_account_store_notify_remove (TNY_ACCOUNT_STORE (self)); 
     501        tny_gpe_account_store_add_account (TNY_ACCOUNT_STORE (self), TNY_ACCOUNT (account), "store"); 
     502        tny_gpe_account_store_notify_add (TNY_ACCOUNT_STORE (self)); 
    503503 
    504504        g_signal_emit (self, tny_account_store_signals [TNY_ACCOUNT_STORE_ACCOUNT_INSERTED], 0, account); 
    …… 
    507507} 
    508508 
    509 static void 
    510 tny_gpe_account_store_add_transport_account (TnyAccountStore *self, TnyTransportAccount *account) 
    511 { 
    512         TnyGpeAccountStorePriv *priv = TNY_GPE_ACCOUNT_STORE_GET_PRIVATE (self); 
    513  
    514         tny_gpe_account_store_notify_remove (self); 
    515         tny_gpe_account_store_add_account (self, TNY_ACCOUNT (account), "transport"); 
    516         tny_gpe_account_store_notify_add (self); 
     509void 
     510tny_gpe_account_store_add_transport_account (TnyGpeAccountStore *self, TnyTransportAccount *account) 
     511{ 
     512        TnyGpeAccountStorePriv *priv = TNY_GPE_ACCOUNT_STORE_GET_PRIVATE (self); 
     513 
     514        tny_gpe_account_store_notify_remove (TNY_ACCOUNT_STORE (self)); 
     515        tny_gpe_account_store_add_account (TNY_ACCOUNT_STORE (self), TNY_ACCOUNT (account), "transport"); 
     516        tny_gpe_account_store_notify_add (TNY_ACCOUNT_STORE (self)); 
    517517 
    518518        g_signal_emit (self, tny_account_store_signals [TNY_ACCOUNT_STORE_ACCOUNT_INSERTED], 0, account); 
    …… 
    626626 
    627627        klass->get_accounts_func = tny_gpe_account_store_get_accounts; 
    628         klass->add_store_account_func = tny_gpe_account_store_add_store_account; 
    629         klass->add_transport_account_func = tny_gpe_account_store_add_transport_account; 
    630628        klass->get_cache_dir_func = tny_gpe_account_store_get_cache_dir; 
    631629        klass->get_device_func = tny_gpe_account_store_get_device; 

  • trunk/libtinymail-gpe/tny-gpe-account-store.h

    r1736 r1855  
    5353TnySessionCamel* tny_gpe_account_store_get_session (TnyGpeAccountStore *self); 
    5454 
     55void tny_gpe_account_store_add_transport_account (TnyGpeAccountStore *self, TnyTransportAccount *account); 
     56void tny_gpe_account_store_add_store_account (TnyGpeAccountStore *self, TnyStoreAccount *account); 
     57 
    5558G_END_DECLS 
    5659 

  • trunk/libtinymail-maemo/tny-maemo-account-store.c

    r1785 r1855  
    494494 
    495495 
    496 static void 
    497 tny_maemo_account_store_add_store_account (TnyAccountStore *self, TnyStoreAccount *account) 
    498 { 
    499         TnyMaemoAccountStorePriv *priv = TNY_MAEMO_ACCOUNT_STORE_GET_PRIVATE (self); 
    500  
    501         tny_maemo_account_store_notify_remove (self); 
    502         tny_maemo_account_store_add_account (self, TNY_ACCOUNT (account), "store"); 
    503         tny_maemo_account_store_notify_add (self); 
     496void 
     497tny_maemo_account_store_add_store_account (TnyMaemoAccountStore *self, TnyStoreAccount *account) 
     498{ 
     499        TnyMaemoAccountStorePriv *priv = TNY_MAEMO_ACCOUNT_STORE_GET_PRIVATE (self); 
     500 
     501        tny_maemo_account_store_notify_remove (TNY_ACCOUNT_STORE (self)); 
     502        tny_maemo_account_store_add_account (NY_ACCOUNT_STORE (self), TNY_ACCOUNT (account), "store"); 
     503        tny_maemo_account_store_notify_add (NY_ACCOUNT_STORE (self)); 
    504504 
    505505        g_signal_emit (self, tny_account_store_signals [TNY_ACCOUNT_STORE_ACCOUNT_INSERTED], 0, account); 
    …… 
    508508} 
    509509 
    510 static void 
     510void 
    511511tny_maemo_account_store_add_transport_account (TnyAccountStore *self, TnyTransportAccount *account) 
    512512{ 
    513513        TnyMaemoAccountStorePriv *priv = TNY_MAEMO_ACCOUNT_STORE_GET_PRIVATE (self); 
    514514 
    515         tny_maemo_account_store_notify_remove (self); 
    516         tny_maemo_account_store_add_account (self, TNY_ACCOUNT (account), "transport"); 
    517         tny_maemo_account_store_notify_add (self); 
     515        tny_maemo_account_store_notify_remove (NY_ACCOUNT_STORE (self)); 
     516        tny_maemo_account_store_add_account (NY_ACCOUNT_STORE (self), TNY_ACCOUNT (account), "transport"); 
     517        tny_maemo_account_store_notify_add (NY_ACCOUNT_STORE (self)); 
    518518 
    519519        g_signal_emit (self, tny_account_store_signals [TNY_ACCOUNT_STORE_ACCOUNT_INSERTED], 0, account); 
    …… 
    628628 
    629629        klass->get_accounts_func = tny_maemo_account_store_get_accounts; 
    630         klass->add_store_account_func = tny_maemo_account_store_add_store_account; 
    631         klass->add_transport_account_func = tny_maemo_account_store_add_transport_account; 
    632630        klass->get_cache_dir_func = tny_maemo_account_store_get_cache_dir; 
    633631        klass->get_device_func = tny_maemo_account_store_get_device; 

  • trunk/libtinymail-maemo/tny-maemo-account-store.h

    r1736 r1855  
    5454TnySessionCamel* tny_maemo_account_store_get_session (TnyMaemoAccountStore *self); 
    5555 
     56void tny_maemo_account_store_add_store_account (TnyMaemoAccountStore *self, TnyStoreAccount *account); 
     57void tny_maemo_account_store_add_transport_account (TnyAccountStore *self, TnyTransportAccount *account); 
     58 
    5659G_END_DECLS 
    5760 

  • trunk/libtinymail-olpc/tny-olpc-account-store.c

    r1784 r1855  
    368368 
    369369 
    370 static void 
    371 tny_olpc_account_store_add_store_account (TnyAccountStore *self, TnyStoreAccount *account) 
    372 { 
    373         TnyOlpcAccountStorePriv *priv = TNY_OLPC_ACCOUNT_STORE_GET_PRIVATE (self); 
    374  
    375         tny_olpc_account_store_add_account (self, TNY_ACCOUNT (account), "store"); 
     370void 
     371tny_olpc_account_store_add_store_account (TnyOlpcAccountStore *self, TnyStoreAccount *account) 
     372{ 
     373        TnyOlpcAccountStorePriv *priv = TNY_OLPC_ACCOUNT_STORE_GET_PRIVATE (self); 
     374 
     375        tny_olpc_account_store_add_account (TNY_ACCOUNT_STORE (self), TNY_ACCOUNT (account), "store"); 
    376376 
    377377        g_signal_emit (self, tny_account_store_signals [TNY_ACCOUNT_STORE_ACCOUNT_INSERTED], 0, account); 
    …… 
    380380} 
    381381 
    382 static void 
    383 tny_olpc_account_store_add_transport_account (TnyAccountStore *self, TnyTransportAccount *account) 
    384 { 
    385         TnyOlpcAccountStorePriv *priv = TNY_OLPC_ACCOUNT_STORE_GET_PRIVATE (self); 
    386  
    387         tny_olpc_account_store_add_account (self, TNY_ACCOUNT (account), "transport"); 
     382void 
     383tny_olpc_account_store_add_transport_account (TnyOlpcAccountStore *self, TnyTransportAccount *account) 
     384{ 
     385        TnyOlpcAccountStorePriv *priv = TNY_OLPC_ACCOUNT_STORE_GET_PRIVATE (self); 
     386 
     387        tny_olpc_account_store_add_account (TNY_ACCOUNT_STORE (self), TNY_ACCOUNT (account), "transport"); 
    388388 
    389389        g_signal_emit (self, tny_account_store_signals [TNY_ACCOUNT_STORE_ACCOUNT_INSERTED], 0, account); 

  • trunk/libtinymail-olpc/tny-olpc-account-store.h

    r1736 r1855  
    5353TnySessionCamel* tny_olpc_account_store_get_session (TnyOlpcAccountStore *self); 
    5454 
     55void tny_olpc_account_store_add_store_account (TnyOlpcAccountStore *self, TnyStoreAccount *account); 
     56void tny_olpc_account_store_add_transport_account (TnyOlpcAccountStore *self, TnyTransportAccount *account); 
     57 
    5558G_END_DECLS 
    5659 

  • trunk/libtinymail/tny-account-store.c

    r1737 r1855  
    3333guint tny_account_store_signals [TNY_ACCOUNT_STORE_LAST_SIGNAL]; 
    3434 
    35 /* Possible future API changes: 
    36  * tny_account_store_set_find_account_strategy 
    37  * tny_account_store_get_find_account_strategy */ 
    3835 
    3936/** 
    …… 
    4845 * Implementors: when implementing a platform-specific library, you must 
    4946 * implement this method. Let it return the account that corresponds to 
    50  * @url_string or let it return NULL. Also see  
    51  * tny_account_matches_url_string at #TnyAccount. 
     47 * @url_string or let it return NULL. Also see tny_account_matches_url_string 
     48 * at #TnyAccount. 
    5249 * 
    5350 * This method can be used to resolve url-strings to #TnyAccount instances. 
    …… 
    257254 * you cache the list, you must add a reference to each account added to the 
    258255 * list (else they will be unreferenced and if the reference count would reach 
    259  * zero, an account would no longer be cached). 
     256 * zero, an account would no longer be correctly cached). 
    260257 * 
    261258 * With libtinymail-camel each created account must also be informed about the 
    …… 
    268265 * libtinymail-maemo and tests/shared/account-store.c which is being used by 
    269266 * the unit tests and the normal tests. 
     267 * 
     268 * The get_pass and forget_pass functionality of the example below is usually 
     269 * implemented by utilizing a #TnyPasswordGetter that is returned by the  
     270 * #TnyPlatformFactory, that is usually available from the #TnyAccountStore.  
    270271 * 
    271272 * Example (that uses a cache): 
    …… 
    338339 
    339340 
    340 /** 
    341  * tny_account_store_add_transport_account: 
    342  * @self: a #TnyAccountStore object 
    343  * @account: the account to add 
    344  *  
    345  * API WARNING: This API might change 
    346  * 
    347  * Add a transport account to the store 
    348  **/ 
    349 void 
    350 tny_account_store_add_transport_account (TnyAccountStore *self, TnyTransportAccount *account) 
    351 { 
    352 #ifdef DBC /* require */ 
    353         g_assert (TNY_IS_ACCOUNT_STORE (self)); 
    354         g_assert (account); 
    355         g_assert (TNY_IS_TRANSPORT_ACCOUNT (account)); 
    356         g_assert (TNY_ACCOUNT_STORE_GET_IFACE (self)->add_transport_account_func != NULL); 
    357 #endif 
    358  
    359         TNY_ACCOUNT_STORE_GET_IFACE (self)->add_transport_account_func (self, account); 
    360  
    361  
    362 #ifdef DBC /* ensure */ 
    363 #endif 
    364  
    365         return; 
    366 } 
    367  
    368  
    369 /** 
    370  * tny_account_store_add_store_account: 
    371  * @self: a #TnyAccountStore object 
    372  * @account: the account to add 
    373  *  
    374  * API WARNING: This API might change 
    375  *  
    376  * Add a storage account to the store 
    377  **/ 
    378 void 
    379 tny_account_store_add_store_account (TnyAccountStore *self, TnyStoreAccount *account) 
    380 { 
    381 #ifdef DBC /* require */ 
    382         g_assert (TNY_IS_ACCOUNT_STORE (self)); 
    383         g_assert (account); 
    384         g_assert (TNY_IS_STORE_ACCOUNT (account)); 
    385         g_assert (TNY_ACCOUNT_STORE_GET_IFACE (self)->add_store_account_func != NULL); 
    386 #endif 
    387  
    388         TNY_ACCOUNT_STORE_GET_IFACE (self)->add_store_account_func (self, account); 
    389  
    390 #ifdef DBC /* ensure */ 
    391 #endif 
    392  
    393         return; 
    394 } 
    395  
    396  
    397341static void 
    398342tny_account_store_base_init (gpointer g_class) 

  • trunk/libtinymail/tny-account-store.h

    r1713 r1855  
    7777        /* Methods */ 
    7878        void (*get_accounts_func) (TnyAccountStore *self, TnyList *list, TnyGetAccountsRequestType types); 
    79         void (*add_store_account_func) (TnyAccountStore *self, TnyStoreAccount *account); 
    80         void (*add_transport_account_func) (TnyAccountStore *self, TnyTransportAccount *account); 
    8179        const gchar* (*get_cache_dir_func) (TnyAccountStore *self); 
    8280        TnyDevice* (*get_device_func) (TnyAccountStore *self); 
    …… 
    9088 
    9189void tny_account_store_get_accounts (TnyAccountStore *self, TnyList *list, TnyGetAccountsRequestType types); 
    92 void tny_account_store_add_store_account (TnyAccountStore *self, TnyStoreAccount *account); 
    93 void tny_account_store_add_transport_account (TnyAccountStore *self, TnyTransportAccount *account); 
    9490const gchar*  tny_account_store_get_cache_dir (TnyAccountStore *self); 
    9591TnyDevice* tny_account_store_get_device (TnyAccountStore *self); 

  • trunk/libtinymail/tny-account.c

    r1726 r1855  
    3333 * Find out whether the account matches a certain url_string. 
    3434 * 
    35  * Implementors: Be forgiving about things like passwords in the url_string. 
    36  * While matching the folder, password and message-id pieces are insignificant. 
     35 * Implementors: Be forgiving about things like passwords in the url_string: 
     36 * while matching the folder, password and message-id pieces are insignificant. 
    3737 * 
    3838 * An example url_string can be imap://user:password@server/INBOX/005. Only  
    …… 
    4040 * RFC 1808 for more information on url_string formatting. 
    4141 * 
    42  * This method must be usable with tny_account_store_find_account. 
     42 * This method must be usable with and will be used for  
     43 * tny_account_store_find_account. 
    4344 * 
    4445 * Return value: whether or not @self matches with @url_string. 
    …… 
    6869 * @self: a #TnyAccount object 
    6970 * 
    70  * Cancels the current operation 
    71  * 
     71 * Forcefully cancels the current operation that is happening on @self. 
     72 *  
    7273 **/ 
    7374void  
    …… 
    154155 * Get the unique id of @self 
    155156 * 
    156  * The only certainty you have is that the id is unique in the #TnyAccountStore. 
     157 * A certainty you have about this property is that the id is unique in the  
     158 * #TnyAccountStore. It doesn't have to be unique in the entire application. 
     159 * 
    157160 * The format of the id isn't specified. The implementor of the #TnyAccountStore 
    158161 * must set this id using tny_account_set_id. 
    …… 
    215218 * you use "PLAIN" here. For anonymous you use "ANONYMOUS". This last one  
    216219 * will for example result in a AUTHENTICATE ANONYMOUS request, as specified 
    217  * in RFC 2245. 
     220 * in RFC 2245, on for example IMAP servers. 
    218221 *  
    219222 **/ 
    …… 
    285288 * per_account_forget_pass_func (TnyAccount *account) 
    286289 * { 
    287  *     if (passwords) 
    288  *     { 
    289  *          const gchar *accountid = tny_account_get_id (account); 
    290  *          gchar *pwd = g_hash_table_lookup (passwords, accountid); 
    291  *          if (pwd) 
    292  *          { 
    293  *             memset (pwd, 0, strlen (pwd)); 
    294  *             g_hash_table_remove (passwords, accountid); 
    295  *          } 
    296  *     } 
    297  * return; 
     290 *    TnyPlatformFactory *platfact = tny_my_platform_factory_get_instance (); 
     291 *    TnyPasswordGetter *pwdgetter; 
     292 *    pwdgetter = tny_platform_factory_new_password_getter (platfact); 
     293 *    tny_password_getter_forget_password (pwdgetter, tny_account_get_id (account)); 
     294 *    g_object_unref (G_OBJECT (pwdgetter)); 
     295 *    return; 
    298296 * } 
    299297 * static void 
    …… 
    357355 * @url_string: the url string (ex. mbox://path) 
    358356 *   
    359  * Set the url string of @self (RFC 1808). You don't need to use this for imap and pop 
    360  * where you can use the simplified API (set_proto, set_hostname, etc). This 
    361  * property is typically set in the implementation of a #TnyAccountStore. 
     357 * Set the url string of @self (RFC 1808). You don't need to use this for imap 
     358 * and pop where you can use the simplified API (set_proto, set_hostname, etc). 
     359 * This property is typically set in the implementation of a #TnyAccountStore. 
    362360 *  
    363361 * For example the url_string for an SMTP account that uses SSL with authentication 
    …… 
    370368{ 
    371369#ifdef DBC /* require */ 
     370        gchar *ptr1, *ptr2; 
    372371        g_assert (TNY_IS_ACCOUNT (self)); 
    373372        g_assert (url_string); 
    …… 
    380379 
    381380#ifdef DBC /* ensure */ 
     381 
    382382        /* TNY TODO: It's possible that tny_account_get_url_string strips the 
    383383         * password. It would be interesting to have a contract check that  
    384384         * deals with this. */ 
     385 
     386        /* TNY TODO: check this DBC implementation for correctness: */ 
     387        ptr1 = tny_account_get_url_string (self); 
     388        ptr2 = strchr (ptr1, '@'); 
     389        ptr1 = strchr (url_string, '@'); 
     390        g_assert (!strcmp (ptr1, ptr2)); 
    385391#endif 
    386392 
    …… 
    524530 * per_account_get_pass_func (TnyAccount *account, const gchar *prompt, gboolean *cancel) 
    525531 * { 
    526  *     gchar *retval = NULL; 
    527  *     const gchar *accountid = tny_account_get_id (account); 
    528  *     if (!passwords) 
    529  *         passwords = g_hash_table_new (g_str_hash, g_str_equal); 
    530  *     retval = g_hash_table_lookup (passwords, accountid); 
    531  *     if (!retval) 
    532  *     { 
    533  *         GtkDialog *dialog = GTK_DIALOG (tny_gnome_password_dialog_new ()); 
    534  *         tny_gnome_password_dialog_set_prompt (TNY_GNOME_PASSWORD_DIALOG (dialog), prompt); 
    535  *         if (gtk_dialog_run (dialog) == GTK_RESPONSE_OK) 
    536  *         { 
    537  *              const gchar *pwd = tny_gnome_password_dialog_get_password  
    538  *                     (TNY_GNOME_PASSWORD_DIALOG (dialog)); 
    539  *              retval = g_strdup (pwd); 
    540  *              mlock (retval, strlen (retval)); 
    541  *              g_hash_table_insert (passwords, g_strdup (accountid), retval); 
    542  *              *cancel = FALSE; 
    543  *         } else 
    544  *              *cancel = TRUE; 
    545  *         gtk_widget_destroy (GTK_WIDGET (dialog)); 
    546  *         while (gtk_events_pending ()) 
    547  *               gtk_main_iteration (); 
    548  *     } else 
    549  *         *cancel = FALSE; 
    550  *     return retval; 
     532 *    TnyPlatformFactory *platfact = tny_my_platform_factory_get_instance (); 
     533 *    TnyPasswordGetter *pwdgetter; 
     534 *    gchar *retval; 
     535 *    pwdgetter = tny_platform_factory_new_password_getter (platfact); 
     536 *    retval = (gchar*) tny_password_getter_get_password (pwdgetter,  
     537 *       tny_account_get_id (account), prompt, cancel); 
     538 *    g_object_unref (G_OBJECT (pwdgetter)); 
     539 *    return retval; 
    551540 * } 
    552541 * static void 

  • trunk/libtinymail/tny-device.c

    r1844 r1855  
    2929 *  
    3030 * Reset the status (unforce the status). 
    31  * This reverses the effects of tny_device_force_online() or tny_device_force_offline(),  
    32  * so that future changes of connection status will cause the connection_changed signal  
    33  * to be emitted, and tny_device_is_online() will return a correct value. 
    34  * 
    35  * The connection_changed signal will be emitted if this tny_device_is_online() to  
    36  * return a different value than before, for instance if the network connection has actually  
    37  * become available or unavailable while the status was forced. 
     31 * 
     32 * This reverses the effects of tny_device_force_online() or  
     33 * tny_device_force_offline(), so that future changes of connection status will  
     34 * cause the connection_changed signal to be emitted, and tny_device_is_online() 
     35 * will return a correct value. 
     36 * 
     37 * The connection_changed signal will be emitted if this tny_device_is_online() 
     38 * to return a different value than before, for instance if the network  
     39 * connection has actually become available or unavailable while the status was  
     40 * forced. 
    3841 **/ 
    3942void  
    …… 
    5760 * @self: a #TnyDevice object 
    5861 *  
    59  * Force online status, so that tny_device_is_online() returns TRUE,  
    60  * regardless of whether there is an actual network connection. 
    61  * The connection_changed signal will be emitted if the online status is changed by this function,  
    62  * but note if a real network connection is made or lost later, the connection_changed signal will not be  
    63  * emitted again, and tny_device_is_online() will continue to return TRUE; 
    64  * 
    65  * This might be used on platforms that cannot detect whether a network connection exists. 
     62 * Force online status, so that tny_device_is_online() returns TRUE, regardless  
     63 * of whether there is an actual network connection. The connection_changed  
     64 * signal will be emitted if the online status is changed by this function,  
     65 * but note if a real network connection is made or lost later, the  
     66 * connection_changed signal will not be emitted again, and tny_device_is_online() 
     67 * will continue to return TRUE; 
     68 * 
     69 * This might be used on platforms that cannot detect whether a network 
     70 * connection exists. 
    6671 * 
    6772 * This will usually not attempt to make a real network connection.  
    …… 
    9095 * @self: a #TnyDevice object 
    9196 *  
    92  * Force offline status, so that tny_device_is_online() returns FALSE,  
    93  * regardless of whether there is an actual network connection. 
    94  * The connection_changed signal will be emitted if the online status is changed by this function,  
    95  * but note if a real network connection is made or lost later, the connection_changed signal will not be  
    96  * emitted again, and tny_device_is_online() will continue to return FALSE; 
    97  * 
    98  * This might be used to mark a device as offline if the connection is partly unusable  
    99  * due to some specific error, such as a failure to access a server or to use a particular port,  
    100  * or if the user specifically chose "offline mode".  
    101  * It might also be used on platforms that cannot detect whether a network connection exists.   
     97 * Force offline status, so that tny_device_is_online() returns FALSE, regardless  
     98 * of whether there is an actual network connection. The connection_changed  
     99 * signal will be emitted if the online status is changed by this function, but  
     100 * note if a real network connection is made or lost later, the connection_changed  
     101 * signal will not be emitted again, and tny_device_is_online() will continue to  
     102 * return FALSE; 
     103 * 
     104 * This might be used to mark a device as offline if the connection is partly  
     105 * unusable due to some specific error, such as a failure to access a server or 
     106 * to use a particular port,  or if the user specifically chose "offline mode".  
     107 * It might also be used on platforms that cannot detect whether a network  
     108 * connection exists.   
    102109 * 
    103110 * This will usually not attempt to disconnect a real network connection.  
    …… 
    183190 * Emitted when the connection status of a device changes. 
    184191 * This signal will not be emitted in response to actual connection changes  
    185  * while the status is forced with tny_device_force_online() or tny_device_force_offline(). 
     192 * while the status is forced with tny_device_force_online() or  
     193 * tny_device_force_offline(). 
    186194 */ 
    187195                tny_device_signals[TNY_DEVICE_CONNECTION_CHANGED] = 

  • trunk/libtinymail/tny-error.h

    r1827 r1855  
    3232        TNY_FOLDER_STORE_ERROR = 2, 
    3333        TNY_TRANSPORT_ACCOUNT_ERROR = 3, 
    34         TNY_ACCOUNT_ERROR = 4 
     34        TNY_ACCOUNT_ERROR = 4, 
    3535}; 
    3636 
    …… 
    5656        TNY_TRANSPORT_ACCOUNT_ERROR_SEND = 13, 
    5757 
    58         TNY_ACCOUNT_ERROR_TRY_CONNECT = 14 
     58        TNY_ACCOUNT_ERROR_TRY_CONNECT = 14, 
    5959}; 
    6060 

  • trunk/libtinymail/tny-folder.c

    r1820 r1855  
    3434guint tny_folder_signals [TNY_FOLDER_LAST_SIGNAL]; 
    3535 
    36 /* Possible future API changes: 
    37  * tny_folder_get_msg_async will get a status callback handler. Also take a look 
    38  * at the possible API changes for TnyMsgReceiveStrategy as this would affect 
    39  * that API too.  
    40  * 
    41  * tny_folder_find_msg for finding a message using an url_string, maybe also a  
    42  * tny_folder_set_find_msg_strategy and a tny_folder_get_find_msg_strategy if 
    43  * in future alternative ways to find a message are to be specified and  
    44  * developed */ 
    4536 
    4637/** 
    …… 
    6859 * @self: a #TnyFolder object 
    6960 *  
    70  * Get the url_string @self or NULL if it's impossible to determine the url  
     61 * Get the url_string of @self or NULL if it's impossible to determine the url  
    7162 * string of @self. If not NULL, the returned value must be freed after use. 
    7263 * 
    73  * The url string is specified in RFC 1808 and looks for example like this: 
     64 * The url string is specified in RFC 1808 and looks like this: 
    7465 * imap://user@hostname/INBOX/folder. Note that it doesn't necessarily contain  
    75  * the password of the IMAP account. 
     66 * the password of the IMAP account but can contain it. 
    7667 *  
    7768 * Return value: The url string or NULL. 
    …… 
    10394 * @self: a TnyFolder object 
    10495 * 
    105  * Get some statistics of the folder @self. You must unreference the return  
    106  * value after use. 
    107  * 
    108  * Return value: some stats of the folder 
     96 * Get some statistics of the folder @self. The returned statistics object will 
     97 * not change after you got it. If you need an updated version, you need to call 
     98 * this method again. You must unreference the return value after use. 
     99 * 
     100 * Return value: some statistics of the folder 
    109101 **/ 
    110102TnyFolderStats*  
    …… 
    132124 * @observer: a #TnyFolderObserver instance 
    133125 * 
    134  * Add @observer to the list of interested observers for the  
    135  * event that could happen caused by a tny_folder_poke_recent_changes or 
    136  * other urgent changes. 
     126 * Add @observer to the list of interested observers for evemts that could happen 
     127 * caused by for example a tny_folder_poke_status and other spontaneous changes  
     128 * (like Push E-mail events). 
     129 * 
     130 * After this, @observer will start receiving notification of changes about @self.  
     131 *  
     132 * You must use tny_folder_remove_observer, in for example the finalization of  
     133 * your type if you used this method. Adding an observer to @self, changes 
     134 * reference counting of the objects involved. Removing the observer will undo 
     135 * those reference counting changes. Therefore if you don't, you will introduce 
     136 * memory leaks. 
    137137 * 
    138138 **/ 
    …… 
    157157 * @observer: a #TnyFolderObserver instance 
    158158 * 
    159  * Remove @observer from the list of interested observers for the  
    160  * event that could happen caused by a tny_folder_poke_recent_changes or 
    161  * other urgent changes. 
     159 * Remove @observer from the list of interested observers for events that could 
     160 * happen caused by for example a tny_folder_poke_status and other spontaneous  
     161 * changes (like Push E-mail events). 
     162 * 
     163 * After this, @observer will no longer receive notification of changes about @self.  
     164 *  
     165 * You must use this method, in for example the finalization of your type 
     166 * if you used tny_folder_add_observer. Adding an observer to @self, changes 
     167 * reference counting of the objects involved. Removing the observer will undo 
     168 * those reference counting changes. Therefore if you don't, you will introduce 
     169 * memory leaks. 
    162170 * 
    163171 **/ 
    …… 
    181189 * @self: a TnyFolder object 
    182190 * 
    183  * Poke for the status, this might ignite the event that a !TnyFolderChange is  
    184  * to be sent to the observers (tny_folder_add_observer and !TnyFolderObserver). 
    185  * 
    186  * This functionality is to be used for E-mail services that don't do what for 
    187  * example the Push-IMAP (P-IMAP) protocol promises (the pushing of changes, as 
    188  * described in draft-maes-lemonade-p-imap-12). 
     191 * Poke for the status, this will invoke the event of sending a #TnyFolderChange   
     192 * to the observers. The change will always at least contain the unread and total 
     193 * folder count. It will also invoke if the unread and total didn't change at  
     194 * all. This makes it possible for a model or view that shows folders to get the 
     195 * initial folder unread and total counts (the #TnyGtkFolderListModel uses this 
     196 * method internally, for example). 
     197 * 
    189198 **/ 
    190199void  
    …… 
    439448 * @err: a #GError object or NULL 
    440449 * 
    441  * Add a message to a folder. It's recommended to destroy @msg afterwards as  
    442  * after receiving the message from the folder again, the instance wont be the 
    443  * same anymore and property like the tny_msg_get_id might have changed and 
    444  * assigned too. 
     450 * Add a message to a folder. It's recommended to destroy @msg afterwards because  
     451 * after receiving the same message from the folder again, the instance wont be 
     452 * the same anymore and a property like the tny_msg_get_id might have changed 
     453 * and assigned too. 
    445454 *  
    446455 * Folder observers of @self will get a header-added trigger caused by this 
    …… 
    532541 * tny_folder_get_unread_count are guaranteed to be correct. 
    533542 * 
    534  * If you want to use this functionality, it's advised to let your application  
     543 * If you want to use this method, it's advised to let your application  
    535544 * use the #GMainLoop. All Gtk+ applications have this once gtk_main () is 
    536545 * called. 
    …… 
    539548 * Without a #GMainLoop, which the libtinymail-camel implementation detects 
    540549 * using (g_main_depth > 0), the callbacks will happen in a worker thread at an 
    541  * unknown moment in time (check your locking). 
     550 * unknown moment in time (check your locking in this case). 
    542551 * 
    543552 * When using Gtk+, the callback doesn't need the gdk_threads_enter and  
    …… 
    547556 * <informalexample><programlisting> 
    548557 * static void 
    549  * status_update_cb (TnyFolder *folder, const gchar *what, gint sofar, gint oftotal, gpointer user_data) 
     558 * status_update_cb (GObject *sender, TnyStatus *status, gpointer user_data) 
    550559 * { 
    551560 *     g_print ("."); 
    …… 
    690699 * @self: a TnyFolder object 
    691700 *  
    692  * Get a the parent account of this folder. You must unreference the return 
    693  * value after use. 
    694  *  
    695  * Return value: the account of this folder 
     701 * Get a the parent account of this folder or NULL. If not NULL, you must  
     702 * unreference the return value after use. 
     703 *  
     704 * Return value: the account of this folder or NULL 
    696705 * 
    697706 **/ 
    …… 
    727736 * Transfers messages of which the headers are in @header_list from @self to  
    728737 * @folder_dst. They could be moved or just copied depending on the value of  
    729  * the @delete_originals argument 
     738 * the @delete_originals argument. 
    730739 * 
    731740 **/ 
    …… 
    770779 * When using Gtk+, the callback doesn't need the gdk_threads_enter and  
    771780 * gdk_threads_leave guards (because it happens in the #GMainLoop). 
     781 * 
     782 * API warning: It's possible that this API will change (it might get a status 
     783 * callback handler after the callback and before the user_data). Don't use 
     784 * this method if you want API or ABI compatibility with your binary. 
    772785 **/ 
    773786void  
    …… 
    848861 * TnyMsgView *message_view = tny_platform_factory_new_msg_view (platfact); 
    849862 * TnyFolder *folder = ... 
    850  * TnyMsg *message = tny_folder_get_msg (folder, "imap://account/INBOX/100", NULL); 
     863 * TnyMsg *message = tny_folder_find_msg (folder, "imap://account/INBOX/100", NULL); 
    851864 * tny_msg_view_set_msg (message_view, message); 
    852865 * g_object_unref (G_OBJECT (message)); 
    …… 
    905918 * <informalexample><programlisting> 
    906919 * static void  
    907  * status_cb (gpointer folder, const gchar *what, gint sofar, gint oftotal, gpointer user_data) 
     920 * status_cb (GObject *sender, TnyStatus *status, gpointer user_data) 
    908921 * { 
    909922 *       printf ("."); 
    …… 
    984997 * @self: a TnyFolder object 
    985998 *  
    986  * Get an unique id of @self (unique per account). The ID will be a "/"  
     999 * Get an unique id of @self (unique per account). The ID will usually be a "/"  
    9871000 * separated string like (but not guaranteed) "INBOX/parent-folder/folder" 
    9881001 * depending on the service type (the example is for IMAP using the  
    …… 
    10531066 *  
    10541067 * Rename a folder. Most services require the name to be unique in the  
    1055  * parent folder. 
     1068 * parent folder. A rename operation that didn't succeed will put an error  
     1069 * in @err. 
    10561070 * 
    10571071 **/ 
    …… 
    11001114 * @self: a TnyFolder object 
    11011115 *  
    1102  * Get a the parent account of this folder. You must unreference the 
     1116 * Get a the parent store of this folder. You must unreference the 
    11031117 * return value after use. Note that not every folder strictly has to 
    11041118 * be inside a folder store. 
    …… 
    11811195      { TNY_FOLDER_TYPE_JUNK, "TNY_FOLDER_TYPE_JUNK", "junk" }, 
    11821196      { TNY_FOLDER_TYPE_SENT, "TNY_FOLDER_TYPE_SENT", "sent" }, 
     1197      { TNY_FOLDER_TYPE_ROOT, "TNY_FOLDER_TYPE_ROOT", "root" }, 
     1198      { TNY_FOLDER_TYPE_NOTES, "TNY_FOLDER_TYPE_NOTES", "notes" }, 
     1199      { TNY_FOLDER_TYPE_DRAFTS, "TNY_FOLDER_TYPE_DRAFTS", "drafts" }, 
     1200      { TNY_FOLDER_TYPE_CONTACTS, "TNY_FOLDER_TYPE_CONTACTS", "contacts" }, 
     1201      { TNY_FOLDER_TYPE_CALENDAR, "TNY_FOLDER_TYPE_CALENDAR", "calendar" }, 
     1202      { TNY_FOLDER_TYPE_ARCHIVE, "TNY_FOLDER_TYPE_ARCHIVE", "archive" }, 
     1203      { TNY_FOLDER_TYPE_MERGE, "TNY_FOLDER_TYPE_MERGE", "merge" }, 
    11831204      { 0, NULL, NULL } 
    11841205    }; 

  • trunk/libtinymail/tny-password-getter.c

    r1784 r1855  
    2929 * tny_password_getter_get_password: 
    3030 * @self: a #TnyPasswordGetter object 
    31  * @account: a #TnyAccount object 
     31 * @aid: a unique string identifying the requested password 
    3232 * @prompt: the password question 
    3333 * @cancel: whether or not the user cancelled 
    3434 *  
    35  * Get the password of @self 
     35 * Get the password of @self identified by @aid. If you set the by reference 
     36 * boolean @cancel to TRUE, the caller (who requested the password) will see  
     37 * this as a negative answer (For example when the user didn't know the password, 
     38 * and therefore pressed a cancel button). 
     39 * 
     40 * The @aid string can be used for so called password stores. It will contain  
     41 * a unique string. Possible values of this string are "acap.server.com" or the 
     42 * result of a tny_account_get_id. 
    3643 * 
    3744 * Return value: the password 
    …… 
    5158 * tny_password_getter_forget_password: 
    5259 * @self: a #TnyPasswordGetter object 
    53  * @account: a #TnyAccount object 
     60 * @aid: a unique string identifying the requested password 
    5461 *  
    55  * Set the password question of @self 
     62 * Forget the password in @self identified by @aid. 
    5663 **/ 
    5764void