Changeset 1856

Show
Ignore:
Timestamp:
04/28/07 13:17:21
Author:
pvanhoof
Message:

Doc updates

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/libtinymail/tny-folder-change.c

    r1836 r1856  
    6767 * @self: a #TnyFolderChange instance 
    6868 * 
    69  * Get the message that got received 
    70  * 
    71  * Return value: the message that got received 
     69 * Get the message that got received, if the change includes receiving a message. 
     70 * If no message was received, NULL will be returned. If not NULL, the returned 
     71 * value must be unreferenced after use. 
     72 * 
     73 * Return value: the message that got received or NULL if no message was received 
     74 * during this change. 
    7275 **/ 
    7376TnyMsg * 
    …… 
    113116        TnyFolderChangePriv *priv = TNY_FOLDER_CHANGE_GET_PRIVATE (self); 
    114117 
     118        g_mutex_lock (priv->lock); 
    115119        priv->new_all_count = new_all_count; 
     120        priv->changed |= TNY_FOLDER_CHANGE_CHANGED_ALL_COUNT; 
     121        g_mutex_unlock (priv->lock); 
    116122 
    117123        return; 
    …… 
    130136        TnyFolderChangePriv *priv = TNY_FOLDER_CHANGE_GET_PRIVATE (self); 
    131137 
     138        g_mutex_lock (priv->lock); 
    132139        priv->new_unread_count = new_unread_count; 
    133140        priv->changed |= TNY_FOLDER_CHANGE_CHANGED_UNREAD_COUNT; 
     141        g_mutex_unlock (priv->lock); 
    134142 
    135143        return; 
    …… 
    329337 * tny_folder_change_get_rename: 
    330338 * @self: a #TnyFolderChange instance 
    331  * @oldname: a pointer to a string 
     339 * @oldname: a pointer to a string (by reference) 
    332340 * 
    333341 * Get the new name of the folder in case of a rename. This will return NULL 
    334  * of nu rename happened. You can pass a pointer if you need the old folder 
     342 * of no rename happened. You can pass a pointer if you need the old folder 
    335343 * name too. 
    336344 * 
    337  * You must not free the return value nor the @oldname pointer. It's handled 
    338  * internally in the TnyFolderChange type. 
     345 * You should not free the returned value nor the @oldname pointer. 
     346 * 
     347 * Return value: The new folder name or NULL 
    339348 **/ 
    340349const gchar * 
    …… 
    365374 * Mark the change in such a way that the user can know that a rename has  
    366375 * happened. The TnyFolderChange will copy your @newname internally, so you 
    367  * can do whatever you want with what you passed afterwards. 
     376 * can do whatever you want with what you passed afterwards (like freeing it). 
    368377 **/ 
    369378void  
    …… 
    406415 * 
    407416 * Get the folder of @self. The return value of this method must be unreferenced  
    408  * after use 
    409  * 
    410  * Return value: the #TnyFolder instance related to this changeset 
     417 * after use. 
     418 * 
     419 * Return value: the #TnyFolder related to this changeset 
    411420 **/ 
    412421TnyFolder*  
    …… 
    464473        priv->added = NULL; 
    465474        priv->removed = NULL; 
    466  
    467475        if (priv->msg) 
    468476                g_object_unref (priv->msg); 

  • trunk/libtinymail/tny-folder-monitor.c

    r1636 r1856  
    4545 * @list: a #TnyList instance 
    4646 * 
    47  * Add @list to the lists that are interested in changes. The list will remain 
    48  * referenced until it's unregisterd using tny_folder_monitor_remove_list or  
    49  * until @self is finalized. 
     47 * Add @list to the registered lists that are interested in changes. @list will 
     48 * remain referenced until it's unregisterd using tny_folder_monitor_remove_list 
     49 * or until @self is finalized. 
    5050 * 
    5151 **/ 
    …… 
    7777 * 
    7878 * Remove @list from the lists that are interested in changes. This will remove 
    79  * the reference added to @list that got added when you ussed the  
    80  * tny_folder_monitor_add_list API. 
     79 * the reference that got added when you ussed the tny_folder_monitor_add_list. 
    8180 * 
    8281 **/ 
    …… 
    107106 * 
    108107 * Trigger the poke method on the folder instance being monitored. 
    109  * Also take a look at the tny_folder_poke_status API. 
     108 * Also take a look at tny_folder_poke_status in #TnyFolder. 
    110109 * 
    111110 **/ 
    …… 
    261260 * @self).  
    262261 * 
    263  * The reason for that is that unless otherwise the folder is finalized, @self 
    264  * would still have a reference being held by the TnyFolder instance being 
    265  * monitored. By stopping this monitor, you explicitly ask that folder instance 
    266  * to unregister @self as an observer. And by that loosing that reference too. 
     262 * The reason for that is that unless you stop @self, it would still have a 
     263 * reference being held by the #TnyFolder instance being monitored. By stopping 
     264 * this monitor, you explicitly ask that folder instance to unregister @self as 
     265 * an observer. And by that loosing that reference too. 
    267266 * 
    268267 **/ 
    …… 
    287286 * 
    288287 * Start monitoring the folder. The starting of a monitor implies that @self 
    289  * will become an observer of the folder instance, adding a reference to @self 
     288 * will become an observer of the folder instance. This adds a reference to @self 
    290289 * that at some point in time must be removed using tny_folder_monitor_stop. 
    291290 * 
    292  * This means that if you start the monitor, you must also stop it somewhere. 
    293  * Which makes perfect sense, but I bet that I'm going to be surprised to see 
    294  * the vast amounts of people that are not going to stop their monitors, and be 
    295  * surprised to have memory leaks (which is normal, if the lists never get 
    296  * unreferenced, of course). 
     291 * This means that if you start the monitor, you must also at some point stop it. 
    297292 *  
    298  * Keep this in mind: monitoring means that the lists are kept alive. A list 
    299  * that is alive means that it's consuming memory. Simple and plain. Or not? 
     293 * Keep this in mind: monitoring means that registered lists are kept alive. A 
     294 * list that is alive means that it's consuming memory! 
    300295 **/ 
    301296void  

  • trunk/libtinymail/tny-folder-observer.c

    r1727 r1856  
    2929 * @change: A #TnyFolderChange instance 
    3030 * 
    31  * Observer's update method, @change is the delta of changes between the last  
    32  * and the current state. Containing the added and removed headers, and the 
    33  * new all -and unread count of the #TnyFolder.  
     31 * Observer's update method. The @change is the delta of changes between the last  
     32 * and the current state. It contains for example the added and removed headers 
     33 * and the new all and unread count of the #TnyFolder.  
    3434 * 
    3535 **/ 

  • trunk/libtinymail/tny-folder-stats.c

    r1683 r1856  
    7777 * @local_size: the local size of the folder 
    7878 * 
    79  * Set the local disk space that @self is consuming 
     79 * Set the local disk space that @self is consuming (should probably only be 
     80 * used by the #TnyFolder implementation internally: it'll define the value 
     81 * that tny_folder_stats_get_local_size will return). 
    8082 **/ 
    8183void  

  • trunk/libtinymail/tny-folder-store-change.c

    r1649 r1856  
    236236 * @self: a #TnyFolderStoreChange instance 
    237237 * 
    238  * Get the folderstore of @self. The return value of this method must be unreferenced  
    239  * after use 
     238 * Get the folderstore of @self. The return value of this method must be  
     239 * unreferenced after use 
    240240 * 
    241241 * Return value: the #TnyFolderStore instance related to this changeset 

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

    r1728 r1856  
    2828#include <tny-list.h> 
    2929 
    30 /* Possible future API changes: 
    31  * tny_folder_store_find_folder for finding a folder using an url_string, maybe  
    32  * also a tny_folder_store_set_find_folder_strategy and a  
    33  * tny_folder_store_get_find_folder_strategy if in future alternative ways to  
    34  * find a folder are to be specified and developed */ 
    3530 
    3631/** 
    …… 
    3934 * @observer: a #TnyFolderStoreObserver instance 
    4035 * 
    41  * Add @observer to the list of interested observers for the  
    42  * event that could happen. 
     36 * Add @observer to the list of interested observers for events that could happen 
     37 * caused by for example folder creates and deletions and other spontaneous  
     38 * changes. 
     39 * 
     40 * After this, @observer will start receiving notification of changes about @self.  
     41 *  
     42 * You must use tny_folder_store_remove_observer, in for example the finalization 
     43 * of your type if you used this method. Adding an observer to @self, changes 
     44 * reference counting of the objects involved. Removing the observer will undo 
     45 * those reference counting changes. Therefore if you don't, you will introduce 
     46 * memory leaks. 
    4347 * 
    4448 **/ 
    …… 
    6872 * @observer: a #TnyFolderStoreObserver instance 
    6973 * 
    70  * Remove @observer from the list of interested observers for the  
    71  * event that could happen. 
     74 * Remove @observer from the list of interested observers for events that could 
     75 * happen caused by for example folder creates and deletions and other  
     76 * spontaneous changes. 
     77 * 
     78 * After this, @observer will no longer receive notification of changes about @self.  
     79 *  
     80 * You must use this method, in for example the finalization of your type 
     81 * if you used tny_folder_store_add_observer. Adding an observer to @self, changes 
     82 * reference counting of the objects involved. Removing the observer will undo 
     83 * those reference counting changes. Therefore if you don't, you will introduce 
     84 * memory leaks. 
    7285 * 
    7386 **/ 
    …… 
    105118 * but of course not of @self, will automatically be unsubscribed. 
    106119 *  
     120 * API question and TODO (undetermined): what about recursive deleting? 
     121 * 
    107122 * Example: 
    108123 * <informalexample><programlisting> 
    …… 
    152167 * </programlisting></informalexample> 
    153168 *  
    154  * Return value: A new folder instance representing the folder that was created or NULL in case of failure 
     169 * Return value: A new folder instance representing the folder that was created  
     170 * or NULL in case of failure 
    155171 * 
    156172 **/ 

  • trunk/libtinymail/tny-folder.c

    r1855 r1856  
    124124 * @observer: a #TnyFolderObserver instance 
    125125 * 
    126  * Add @observer to the list of interested observers for evemts that could happen 
     126 * Add @observer to the list of interested observers for events that could happen 
    127127 * caused by for example a tny_folder_poke_status and other spontaneous changes  
    128128 * (like Push E-mail events). 

  • trunk/libtinymail/tny-fs-stream.c

    r1199 r1856  
    1818 */ 
    1919 
    20 /* 
     20/* Parts of this file were copied from the Evolution project. This is the 
     21 * original copyright of that file. The file's source code was distributed as  
     22 * LGPL content. Therefore the copyright of Tinymail is compatible with this. 
     23 * 
    2124 * Authors: Bertrand Guiheneuf <bertrand@helixcode.com> 
    2225 *          Michael Zucchi <notzed@ximian.com> 
    …… 
    165168 * you. 
    166169 * 
    167  * Therefore use it with care. It's more or less an exception in the framework 
     170 * Therefore use it with care. It's more or less an exception in the framework, 
    168171 * whether or not you call it an exception depends on your point of view). 
    169172 * 
    170  * The the instance will on top of close() when destructing, also fsync() the 
     173 * The the instance will on top of close() when destructing also fsync() the 
    171174 * filedescriptor. It does this depending on its mood, the weather and your 
    172175 * wives periods using a complex algorithm that abuses your privacy and might 

  • trunk/libtinymail/tny-iterator.c

    r1732 r1856  
    111111 * 
    112112 * Does not move the iterator. Returns the object at the current position. If 
    113  * there no current position, this method returns NULL. If not NULL, the  
     113 * there's no current position, this method returns NULL. If not NULL, the  
    114114 * returned value must be unreferenced after use. 
    115115 * 

  • trunk/libtinymail/tny-list.c

    r1737 r1856  
    6868 * means loosing your reason of existance. So you'll get destroyed. 
    6969 * 
     70 * You should not prepend, remove nor append items while iterating @self. There's 
     71 * no guarantee whatsoever that existing iterators of @self will be valid after  
     72 * this method returned. 
     73 * 
    7074 * Implementers: if you have to choose, make this one the fast one 
    71  * 
    7275 **/ 
    7376void 
    …… 
    120123 * means loosing your reason of existance. So you'll get destroyed. 
    121124 * 
     125 * You should not prepend, remove nor append items while iterating @self. There's 
     126 * no guarantee whatsoever that existing iterators of @self will be valid after  
     127 * this method returned. 
     128 * 
    122129 * Implementers: if you have to choose, make the prepend one the fast one 
    123  * 
    124130 **/ 
    125131void  
    …… 
    150156 * Removes an item from a list.  Removing a item might invalidate all existing 
    151157 * iterators or put them in an unknown and unspecified state. You'll need to  
    152  * recreate the iterator(s) if you remove an item to be certain. 
     158 * recreate the iterator(s) if you removed an item. 
    153159 * 
    154160 * If you want to clear a list, consider using the tny_list_foreach or simply 

  • trunk/libtinymail/tny-merge-folder.c

    r1820 r1856  
    954954} 
    955955 
     956/** 
     957 * tny_merge_folder_new: 
     958 * 
     959 * Creates a a new TnyMergeFolder instance that can merge multiple #TnyFolder  
     960 * instances together (partly read only, though). 
     961 * 
     962 * Return value: a new #TnyMergeFolder instance 
     963 **/ 
    956964TnyFolder* 
    957965tny_merge_folder_new (void) 

  • trunk/libtinymail/tny-send-queue.c

    r1732 r1856  
    8080 * 
    8181 * Get the folder which contains the messages that have not yet been sent. The  
    82  * return value must be unreferenced after use 
     82 * return value must be unreferenced after use. It's not guaranteed that when 
     83 * changing the content of @outbox, @self will automatically adjust itself to 
     84 * the new situation. Although some implementations of #TnySendQueue might 
     85 * indeed do this, it's advisable to use tny_send_queue_add in stead of  
     86 * tny_folder_add_msg on @outbox. The reason for that is lack of specification 
     87 * and a #TnySendQueue implementation not having to implement #TnyFolderObserver 
     88 * too (which makes it possible to act on changes happening to @outbox). 
    8389 * 
    8490 * Return value: a #TnyFolder instance 

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

    r1732 r1856  
    3030 * @err: a #GError object or NULL 
    3131 * 
    32  * Send @msg 
     32 * Send @msg. Note that @msg must be a correct #TnyMsg instance with a correct 
     33 * #TnyHeader, which can be used as the envelope while sending. 
    3334 *  
    3435 **/ 
    …… 
    4344#endif 
    4445 
     46        TNY_TRANSPORT_ACCOUNT_GET_IFACE (self)->send_func (self, msg, err); 
    4547 
    46         TNY_TRANSPORT_ACCOUNT_GET_IFACE (self)->send_func (self, msg, err); 
    4748        return; 
    4849}