Changeset 1198

Show
Ignore:
Timestamp:
11/21/06 14:57:12
Author:
pvanhoof
Message:

API doc enhancements

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/ChangeLog

    r1194 r1198  
    33        * Major changes in TnyMsg and TnyMimePart 
    44        * First support for message/rfc822 messages 
    5  
     5        * API documentation enhancements 
     6        * Date fixes in TnyCamelHeader 
     7         
    68        * This was a major API change in all libraries 
    79 

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

    r1192 r1198  
    300300                } 
    301301 
    302         tny_msg_remove_strategy_remove (priv->remove_strat, self, header); 
     302        tny_msg_remove_strategy_perform_remove (priv->remove_strat, self, header); 
    303303 
    304304        g_mutex_unlock (priv->folder_lock); 
    …… 
    941941 
    942942static void 
    943 tny_camel_folder_transfer_msgs (TnyFolder *folder_src,  
     943tny_camel_folder_transfer_msgs (TnyFolder *self,  
    944944                                TnyList *headers,  
    945945                                TnyFolder *folder_dst,  
    946946                                gboolean delete_originals) 
    947947{ 
    948         TNY_CAMEL_FOLDER_GET_CLASS (folder_src)->transfer_msgs_func (folder_src, headers, folder_dst, delete_originals); 
    949 } 
    950  
    951 static void 
    952 tny_camel_folder_transfer_msgs_default (TnyFolder *folder_src,  
    953                                         TnyList *headers, 
    954                                         TnyFolder *folder_dst, 
    955                                         gboolean delete_originals) 
    956 { 
     948        TNY_CAMEL_FOLDER_GET_CLASS (self)->transfer_msgs_func (self, headers, folder_dst, delete_originals); 
     949} 
     950 
     951static void 
     952tny_camel_folder_transfer_msgs_default (TnyFolder *self, TnyList *headers, TnyFolder *folder_dst, gboolean delete_originals) 
     953{ 
     954        TnyFolder *folder_src = self; 
    957955        TnyCamelFolderPriv *priv_src, *priv_dst; 
    958956        TnyIterator *iter; 

  • trunk/libtinymail-camel/tny-camel-folder.h

    r1179 r1198  
    6868        void (*refresh_async_func) (TnyFolder *self, TnyRefreshFolderCallback callback, TnyRefreshFolderStatusCallback status_callback, gpointer user_data); 
    6969        void (*refresh_func) (TnyFolder *self); 
    70         void (*transfer_msgs_func) (TnyFolder *folder_src, TnyList *headers, TnyFolder *folder_dst, gboolean delete_originals); 
     70        void (*transfer_msgs_func) (TnyFolder *self, TnyList *headers, TnyFolder *folder_dst, gboolean delete_originals); 
    7171 
    7272        void (*get_folders_async_func) (TnyFolderStore *self, TnyList *list, TnyGetFoldersCallback callback, TnyFolderStoreQuery *query, gpointer user_data); 

  • trunk/libtinymail-camel/tny-camel-header.c

    r1197 r1198  
    394394        } 
    395395        else 
    396                 retval = camel_message_info_date_received ((CamelMessageInfo*)me->info); 
     396                retval = camel_message_info_date_sent ((CamelMessageInfo*)me->info); 
    397397 
    398398        return retval; 

  • trunk/libtinymail-camel/tny-camel-msg-remove-strategy.c

    r1148 r1198  
    3838 
    3939static void 
    40 tny_camel_msg_remove_strategy_remove (TnyMsgRemoveStrategy *self, TnyFolder *folder, TnyHeader *header) 
     40tny_camel_msg_remove_strategy_perform_remove (TnyMsgRemoveStrategy *self, TnyFolder *folder, TnyHeader *header) 
    4141{ 
    4242        const gchar *id; 
    …… 
    8888        TnyMsgRemoveStrategyIface *klass = (TnyMsgRemoveStrategyIface *)g; 
    8989 
    90         klass->remove_func = tny_camel_msg_remove_strategy_remove; 
     90        klass->perform_remove_func = tny_camel_msg_remove_strategy_perform_remove; 
    9191 
    9292        return; 

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

    r1010 r1198  
    3131 * @prompt: the prompt 
    3232 * 
    33  * This jump-to-the-ui method implements showing a message dialog with prompt 
    34  * as prompt. It will return TRUE if the reply was affirmative or FALSE if not. 
     33 * This jump-to-the-ui method implements showing a message dialog with @prompt 
     34 * as prompt and @type as message type. It will return TRUE if the reply was  
     35 * affirmative or FALSE if not. 
    3536 * 
    3637 * Implementors: when implementing a platform-specific library, you must 
    37  * implement this method. For example in Gtk+ by using the #GtkDialog API. 
     38 * implement this method. For example in Gtk+ by using the #GtkDialog API. The 
     39 * implementation will for example be used to ask the user about accepting SSL 
     40 * certificates. The two possible answers that must be supported are  
     41 * "Yes" and "No" which must result in a TRUE or a FALSE return value. 
    3842 * 
    3943 * Example implementation for Gtk+: 
    …… 
    4246 * tny_gnome_account_store_alert (TnyAccountStore *self, TnyAlertType type, const gchar *prompt) 
    4347 * { 
    44  *     GtkMessageType gtktype; 
    45  *     gboolean retval = FALSE; 
    46  *     GtkWidget *dialog; 
    47  *     switch (type) 
    48  *     { 
    49  *             case TNY_ALERT_TYPE_INFO: 
    50  *             gtktype = GTK_MESSAGE_INFO; 
    51  *             break; 
    52  *             case TNY_ALERT_TYPE_WARNING: 
    53  *             gtktype = GTK_MESSAGE_WARNING; 
    54  *             break; 
    55  *             case TNY_ALERT_TYPE_ERROR: 
    56  *             default: 
    57  *             gtktype = GTK_MESSAGE_ERROR; 
    58  *             break; 
    59  *     } 
    60  *     dialog = gtk_message_dialog_new (NULL, GTK_DIALOG_MODAL, 
    61  *             gtktype, GTK_BUTTONS_YES_NO, prompt); 
    62  *     if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_YES) 
    63  *             retval = TRUE; 
    64  *     gtk_widget_destroy (dialog); 
    65  *     return retval; 
     48 *     GtkMessageType gtktype; 
     49 *     gboolean retval = FALSE; 
     50 *     GtkWidget *dialog; 
     51 *     switch (type) 
     52 *     { 
     53 *         case TNY_ALERT_TYPE_INFO: 
     54 *         gtktype = GTK_MESSAGE_INFO; 
     55 *         break; 
     56 *         case TNY_ALERT_TYPE_WARNING: 
     57 *         gtktype = GTK_MESSAGE_WARNING; 
     58 *         break; 
     59 *         case TNY_ALERT_TYPE_ERROR: 
     60 *         default: 
     61 *         gtktype = GTK_MESSAGE_ERROR; 
     62 *         break; 
     63 *     } 
     64 *     dialog = gtk_message_dialog_new (NULL, GTK_DIALOG_MODAL, 
     65 *            gtktype, GTK_BUTTONS_YES_NO, prompt); 
     66 *     if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_YES) 
     67 *            retval = TRUE; 
     68 *     gtk_widget_destroy (dialog); 
     69 *     return retval; 
    6670 * } 
    6771 * </programlisting></informalexample> 
    6872 * 
    69  * The @prompt will be a message like a question to the user whether or not he 
    70  * accepts the SSL certificate of the service. 
    71  * 
    7273 * Return value: Whether the user pressed Ok/Yes (TRUE) or Cancel/No (FALSE) 
    7374 * 
    …… 
    9192 * 
    9293 * Implementors: when implementing a platform-specific library, you must 
    93  * implement this method and a #TnyDevice implementation.  
    94   
    95  * As the implementor of this method, you must add a reference count before  
    96  * returning. 
     94 * implement this method by letting it return a #TnyDevice instance. You must 
     95 * add a reference count before returning. 
    9796 * 
    9897 * Return value: the device attached to this account store 
    …… 
    120119 * 
    121120 * Note that the callers of this method will not free the result. The 
    122  * implementor of a #TnyAccountStore is responsible of freeing it up. For 
    123  * example when destroying the instance. 
     121 * implementor of a #TnyAccountStore is responsible for freeing it up. For 
     122 * example when destroying @self (in its finalize method). 
    124123 * 
    125124 * Return value: the local path that will be used for storing the disk cache 
    …… 
    143142 * @types: a #TnyGetAccountsRequestType that describes which account types are needed 
    144143 *  
    145  * Get a read-only list of accounts in the store 
     144 * Get a read-only list of accounts in the store. You must not change @list  
     145 * except for referencing and unreferencing. 
    146146 * 
    147147 * Example: 
    …… 
    163163 * Implementors: when implementing a platform-specific library, you must  
    164164 * implement this method. 
    165  *  
     165 * 
    166166 * It is allowed to cache the list (but not required). If you are implementing 
    167167 * an account store for account implementations from libtinymail-camel, you must 
    …… 
    169169 * libtinymail-camel specific tny_session_camel_set_current_accounts API. 
    170170 * 
    171  * The implementation must obviously fillup @list with available accounts. 
    172  * Note that if you cache the list, you must add a reference to each account 
    173  * added to the list (else they will be unreferenced and if the reference count 
    174  * would reach zero, an account would no longer be cached). 
     171 * The implementation must fillup @list with available accounts. Note that if 
     172 * you cache the list, you must add a reference to each account added to the 
     173 * list (else they will be unreferenced and if the reference count would reach 
     174 * zero, an account would no longer be cached). 
    175175 * 
    176176 * With libtinymail-camel each created account must also be informed about the 
    …… 
    303303 * @user_data: user data set when the signal handler was connected 
    304304 * 
     305 * API WARNING: This API might change 
     306 * 
    305307 * Emitted when an account in the store changed 
    306308 */ 
    …… 
    320322 * @user_data: user data set when the signal handler was connected. 
    321323 * 
     324 * API WARNING: This API might change 
     325 * 
    322326 * Emitted when an account is added to the store 
    323327 */ 
    324  
    325  
    326328                tny_account_store_signals[TNY_ACCOUNT_STORE_ACCOUNT_INSERTED] = 
    327329                   g_signal_new ("account_inserted", 
    …… 
    338340 * @arg1: the #TnyAccount of the account that got removed 
    339341 * @user_data: user data set when the signal handler was connected. 
     342 * 
     343 * API WARNING: This API might change 
    340344 * 
    341345 * Emitted when an account is removed from the store 
    …… 
    353357 * TnyAccountStore::accounts-reloaded 
    354358 * @self: the object on which the signal is emitted 
     359 * 
     360 * API WARNING: This API might change 
    355361 * 
    356362 * Emitted when the store reloads the accounts 

  • trunk/libtinymail/tny-account.c

    r927 r1198  
    2727 * @self: a #TnyAccount object 
    2828 * 
    29  * Get the account type. There are two account types: a store and a transport 
    30  * account type. 
    31  * 
    32  * A store account will implement the #TnyFolderStore  
    33  * interfaces which means that the type can contain folders. 
     29 * Get the account type of @self. There are two account types: a store and  
     30 * transport account type. 
     31 * 
     32 * A store account typically contains folders and messages. Examples are NNTP, 
     33 * IMAP and POP accounts. 
    3434 * 
    3535 * A transport account has a send method for sending #TnyMsg instances 
    36  * using the transport protocol of the account (for example SMTP). 
     36 * using the transport implemented by the account (for example SMTP). 
    3737 * 
    3838 * Return value: The account type 
    …… 
    5454 * @self: a #TnyAccount object 
    5555 * 
    56  * Get the connection status of an account 
     56 * Get the connection status of @self 
    5757 * 
    5858 * Return value: whether or not the account is connected 
    …… 
    7474 * @self: a #TnyAccount object 
    7575 *  
    76  * Get the unique id of the account. The only certainty you have is that the 
    77  * id is unique. The format of the id isn't specified. The implementor of the 
    78  * #TnyAccountStore must set this id using tny_account_set_id. 
     76 * Get the unique id of @self 
     77 * 
     78 * The only certainty you have is that the id is unique in the #TnyAccountStore. 
     79 * The format of the id isn't specified. The implementor of the #TnyAccountStore 
     80 * must set this id using tny_account_set_id. 
    7981 *  
    8082 * Return value: Unique id 
    …… 
    117119 * 
    118120 * Set the unique id of the account. You need to set this property before you  
    119  * can start using the account. The id must be unique and is typically set in the 
    120  * implementation of a #TnyAccountStore. 
     121 * can start using the account. The id must be unique in a #TnyAccountStore and 
     122 * is typically set in the implementation of a #TnyAccountStore. 
    121123 *  
    122124 **/ 
    …… 
    139141 * 
    140142 * Set the function that will be called in case the password was wrong and  
    141  * therefore can be forgotten by the password store. 
     143 * therefore can, for example, be forgotten by a password store. 
    142144 * 
    143145 * You need to set this property before you can start using the account. This 
    …… 
    182184 * @url_string: the url string (ex. mbox://path) 
    183185 *   
    184  * Set the url string of an account. You don't need to use this for imap and pop 
     186 * Set the url string of @self. You don't need to use this for imap and pop 
    185187 * where you can use the simplified API (set_proto, set_hostname, etc). This 
    186188 * property is typically set in the implementation of a #TnyAccountStore. 
    …… 
    204206 * @proto: the protocol (ex. "imap") 
    205207 *  
    206  * Set the protocol of an account. You need to set this property before you can 
    207  * start using the account. This property is typically set in the implementation 
     208 * Set the protocol of @self. You need to set this property before you can start 
     209 * using the account. This property is typically set in the implementation 
    208210 * of a #TnyAccountStore. 
    209211 *  
    …… 
    226228 * @user: the username 
    227229 *  
    228  * Set the user or login of an account. You need to set this property before you 
     230 * Set the user or login of @self. You need to set this property before you 
    229231 * can start using the account. This property is typically set in the 
    230232 * implementation of a #TnyAccountStore. 
    …… 
    248250 * @host: the hostname 
    249251 *  
    250  * Set the hostname of an account. You need to set this property before you can 
    251  * start using the account. This property is typically set in the implementation 
    252  * of a #TnyAccountStore. 
     252 * Set the hostname of @self. You need to set this property before you can start 
     253 * using the account. This property is typically set in the implementation of a 
     254 * #TnyAccountStore. 
    253255 * 
    254256 **/ 
    …… 
    272274 *  
    273275 * Set the function that will be called when the password is needed. The 
    274  * function should return the password for a specific account. 
     276 * function should return the password for a specific account. The password  
     277 * itself is usually stored in a secured password store. 
    275278 * 
    276279 * You need to set this property before you can start using the account. This 
    …… 
    296299 * @self: a #TnyAccount object 
    297300 *  
    298  * Get the protocol of an account. The returned value should not be freed. 
     301 * Get the protocol of @self. The returned value should not be freed. 
    299302 *  
    300303 * Return value: the protocol as a read-only string 
    …… 
    318321 * @self: a #TnyAccount object 
    319322 *  
    320  * Get the url string of an account. The returned value should not be freed. 
     323 * Get the url string of @self. The returned value should not be freed. 
    321324 *  
    322325 * Return value: the url string as a read-only string 
    …… 
    338341 * @self: a #TnyAccount object 
    339342 *  
    340  * Get the user or login of an account. The returned value should not be freed. 
     343 * Get the user or login of @self. The returned value should not be freed. 
    341344 *  
    342345 * Return value: the user as a read-only string 
    …… 
    358361 * @self: a #TnyAccount object 
    359362 *  
    360  * Get the human readable name of an account. The returned value should not  
     363 * Get the human readable name of @self. The returned value should not  
    361364 * be freed. 
    362365 *  
    …… 
    379382 * @self: a #TnyAccount object 
    380383 *  
    381  * Get the hostname of an account. The returned value should not be freed. 
     384 * Get the hostname of @self. The returned value should not be freed. 
    382385 *  
    383386 * Return value: the hostname as a read-only string 

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

    r1173 r1198  
    3838tny_folder_store_query_new (void) 
    3939{ 
    40     TnyFolderStoreQuery *self = g_object_new (TNY_TYPE_FOLDER_STORE_QUERY, NULL); 
    41      
    42     return self; 
     40        TnyFolderStoreQuery *self = g_object_new (TNY_TYPE_FOLDER_STORE_QUERY, NULL); 
     41        return self; 
    4342} 
    4443 
    …… 
    173172 * TNY_FOLDER_STORE_QUERY_OPTION_MATCH_ON_ID then @pattern will be used as 
    174173 * regular expression for matching the property of the folders. What the 
    175  * properties tny_folder_get_name and tny_folder_get_id would contain will  
    176  * be used in this case. 
     174 * properties tny_folder_get_name and tny_folder_get_id would contain, will  
     175 * be used while matching. 
    177176 * 
    178177 * Example: 
    …… 
    186185 * while (!tny_iterator_is_done (iter)) 
    187186 * { 
    188  *     TnyFolder *folder = TNY_FOLDER (tny_iterator_get_current (iter)); 
    189  *     g_print ("%s\n", tny_folder_get_name (folder)); 
    190  *     g_object_unref (G_OBJECT (folder)); 
    191  *     tny_iterator_next (iter);            
     187 *      TnyFolder *folder = TNY_FOLDER (tny_iterator_get_current (iter)); 
     188 *      g_print ("%s\n", tny_folder_get_name (folder)); 
     189 *      g_object_unref (G_OBJECT (folder)); 
     190 *      tny_iterator_next (iter); 
    192191 * } 
    193192 * g_object_unref (G_OBJECT (iter)); 
    …… 
    210209 * while (!tny_iterator_is_done (iter)) 
    211210 * { 
    212  *     TnyFolder *folder = TNY_FOLDER (tny_iterator_get_current (iter)); 
    213  *     g_print ("%s\n", tny_folder_get_name (folder)); 
    214  *     g_object_unref (G_OBJECT (folder)); 
    215  *     tny_iterator_next (iter);            
     211 *      TnyFolder *folder = TNY_FOLDER (tny_iterator_get_current (iter)); 
     212 *      g_print ("%s\n", tny_folder_get_name (folder)); 
     213 *      g_object_unref (G_OBJECT (folder)); 
     214 *      tny_iterator_next (iter); 
    216215 * } 
    217216 * g_object_unref (G_OBJECT (iter)); 
    …… 
    260259 * @query: a #TnyFolderStoreQuery object 
    261260 * 
    262  * Get a list of query items  
     261 * Get a list of query items in @query. The return value must be unreferenced 
     262 * after use. 
    263263 * 
    264264 * Return value: a list of query items 
    …… 
    267267tny_folder_store_query_get_items (TnyFolderStoreQuery *query) 
    268268{ 
    269         return g_object_ref (G_OBJECT (query->items)); 
     269        return TNY_LIST (g_object_ref (G_OBJECT (query->items))); 
    270270} 
    271271 
    …… 
    275275 * @item: a #TnyFolderStoreQueryItem object 
    276276 * 
    277  * Get the options of @item 
     277 * Get the options of @item as a #TnyFolderStoreQueryOption enum. 
    278278 * 
    279279 * Return value: the options of a query item 

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

    r1187 r1198  
    3030 * Removes a folder represented by @folder from the folder store @self. You are 
    3131 * responsible for unreferencing the @folder instance yourself. This method will 
    32  * not do this for you, leaving the instance in an unusable state. The id of the 
    33  * @folder instance will be blanked once really deleted from the service. 
    34  * 
    35  * Example: 
    36  * <informalexample><programlisting> 
    37  * TnyFolderStore *store = ... 
    38  * TnyFolder *remfol; 
    39  * TnyIterator *iter; 
    40  * TnyList *folders = tny_simple_list_new (); 
    41  * tny_folder_store_get_folders (store, folders, NULL); 
    42  * iter = tny_list_create_iterator (folders); 
    43  * tny_iterator_first (iter); 
    44  * remfol = TNY_FOLDER (tny_iterator_get_current (iter)); 
    45  * g_object_unref (G_OBJECT (iter)); 
    46  * g_object_unref (G_OBJECT (folders));  
    47  * tny_folder_store_remove_folder (store, remfol); 
    48  * g_object_unref (G_OBJECT (remfol)); 
     32 * not do this for you, leaving the @folder instance in an unusable state. The  
     33 * id of the @folder instance will be blanked once really deleted from the 
     34 * service. 
     35 * 
     36 * Example: 
     37 * <informalexample><programlisting> 
     38 * static void 
     39 * my_remove_a_folder (TnyFolderStore *store, TnyFolder *remfol) 
     40 * { 
     41 *     tny_folder_store_remove_folder (store, remfol); 
     42 *     g_object_unref (G_OBJECT (remfol)); 
     43 * } 
    4944 * </programlisting></informalexample> 
    5045 * 
    …… 
    6762 * @name: The folder name to create 
    6863 * 
    69  * Creates a new folder in folder store @self. The value returned is the newly 
    70  * created folder and must be unreferenced after use. 
     64 * Creates a new folder in @self. The value returned is the newly created folder 
     65 * instance and must be unreferenced after use. 
    7166 * 
    7267 * Example: 
    …… 
    9893 * @query: A #TnyFolderStoreQuery object or NULL 
    9994 * 
    100  * Get a list of child folders from the folder store @self. You can use @query  
    101  * to limit the list of folders with only folders that match the query. 
    102  *   
     95 * Get a list of child folders from @self. You can use @query to limit the list  
     96 * of folders with only folders that match a query or NULL if you don't want 
     97 * to limit the list at all. 
     98 *  
    10399 * Example: 
    104100 * <informalexample><programlisting> 
    …… 
    140136 * 
    141137 * Get a list of child folders from the folder store @self and call back when  
    142  * finished.  
     138 * finished. You can use @query to limit the list of folders with only folders  
     139 * that match a query or NULL if you don't want to limit the list at all. 
    143140 * 
    144141 * Example: 
    …… 
    172169 * 
    173170 * If you want to use this functionality, you are advised to let your application  
    174  * use the #GMainLoop. All Gtk+ applications have this once gtk_main () is 
    175  * called. 
     171 * use a #GMainLoop. All Gtk+ applications have this once gtk_main () is called. 
    176172 *  
    177173 * When using a #GMainLoop, this method will callback using g_idle_add_full. 

  • trunk/libtinymail/tny-folder.c

    r1188 r1198  
    3333 * Get the strategy for removing a message. The return value of this method 
    3434 * must be unreferenced after use. 
    35  *  
     35 * 
     36 * Implementors: This method must return the strategy for removing a message. 
     37 * being the implementer, you must add a reference before returning the instance. 
     38 * 
    3639 * Return value: the strategy for removing a message 
    3740 **/ 
    …… 
    5255 * 
    5356 * Set the strategy for removing a message 
    54  *  
     57 * 
     58 * Implementors: This method must set (store) the strategy for removing a 
     59 * message. 
     60 * 
     61 * The idea is that devices can have a specific such strategy. For example a 
     62 * strategy that removes it immediately from both local cache and a service 
     63 * or a strategy that does nothing but flag the message for removal upon next 
     64 * expunge or a strategy that does nothing. 
     65 * 
     66 * For more information take a look at tny_msg_remove_strategy_peform_remove 
     67 * of #TnyMsgRemoveStrategy. 
     68 * 
    5569 **/ 
    5670void  
    …… 
    120134 * Remove a message from a folder. It will use a #TnyMsgRemoveStrategy to  
    121135 * perform the removal itself. For more details, check out the documentation 
    122  * of the #TnyMsgRemoveStrategy type.  
     136 * of the #TnyMsgRemoveStrategy type and the implementation that you activated 
     137 * using tny_folder_set_msg_remove_strategy. The default implementation for 
     138 * libtinymail-camel is the #TnyCamelMsgRemoveStrategy. 
    123139 * 
    124140 * Example: 
    …… 
    170186 * @user_data: user data for the callback 
    171187 * 
    172  * Refresh the folder and call back when finished. This gets the summary  
    173  * information from the E-Mail service and writes it to the the on-disk cache  
    174  * and/or updates it. 
     188 * Refresh @self and call back when finished. This gets the summary information 
     189 * from the E-Mail service, writes it to the the on-disk cache and/or updates 
     190 * it. 
    175191 * 
    176192 * After this method, tny_folder_get_all_count and  
    …… 
    242258 * @self: a TnyFolder object 
    243259 * 
    244  * Refresh the folder. This gets the summary information from the E-Mail service 
    245  * and writes it to the the on-disk cache and/or updates it. 
     260 * Refresh the folder. This gets the summary information from the E-Mail 
     261 * service, writes it to the the on-disk cache and/or updates it. 
    246262 * 
    247263 * After this method, tny_folder_get_all_count and  
    …… 
    268284 * @self: a TnyFolder object 
    269285 *  
    270  * 
    271  * Get the subscribed status of this folder. 
     286 * Get the subscribtion status of this folder. 
    272287 *  
    273288 * Return value: subscribe status 
    …… 
    289304 *  
    290305 * Get the amount of unread messages in this folder. The value is only 
    291  * garuanteed to be correct after tny_folder_refresh. 
     306 * garuanteed to be correct after tny_folder_refresh or after the callback of 
     307 * a tny_folder_refresh_async happened. 
    292308 *  
    293309 * Return value: amount of unread messages 
    …… 
    309325 * @self: a TnyFolder object 
    310326 *  
    311  * Get the amount of messages in this folder. The value is only 
    312  * garuanteed to be correct after tny_folder_refresh. 
     327 * Get the amount of messages in this folder. The value is only garuanteed to be 
     328 * correct after tny_folder_refresh or after the callback of a  
     329 * tny_folder_refresh_async happened. 
    313330 *  
    314331 * Return value: amount of messages 
    …… 
    349366/** 
    350367 * tny_folder_transfer_msgs: 
    351  * @folder_src: the TnyFolder where the headers are stored 
     368 * @self: the TnyFolder where the headers are stored 
    352369 * @header_list: a list of TnyHeader objects 
    353370 * @folder_dst: the TnyFolder where the msgs will be transfered 
    354371 * @delete_originals: if TRUE then move msgs, else copy them 
    355372 *  
    356  * Transfers messages from a folder to another. They could be moved or 
    357  * just copied depending on the value of the delete_originals argument 
     373 * Transfers messages of which the headers are in @header_list from @self to  
     374 * @folder_dst. They could be moved or just copied depending on the value of  
     375 * the @delete_originals argument 
     376 * 
    358377 **/ 
    359378void  
    360 tny_folder_transfer_msgs (TnyFolder *folder_src,  
    361                           TnyList *headers,  
    362                           TnyFolder *folder_dst,  
    363                           gboolean delete_originals) 
    364 { 
    365 #ifdef DEBUG 
    366         if (!TNY_FOLDER_GET_IFACE (folder_src)->transfer_msgs_func) 
     379tny_folder_transfer_msgs (TnyFolder *self, TnyList *headers, TnyFolder *folder_dst, gboolean delete_originals) 
     380{ 
     381#ifdef DEBUG 
     382        if (!TNY_FOLDER_GET_IFACE (self)->transfer_msgs_func) 
    367383                g_critical ("You must implement tny_folder_transfer_msgs\n"); 
    368384#endif 
    369385 
    370         return TNY_FOLDER_GET_IFACE (folder_src)->transfer_msgs_func (folder_src, headers, folder_dst, delete_originals); 
     386        return TNY_FOLDER_GET_IFACE (self)->transfer_msgs_func (self, headers, folder_dst, delete_originals); 
    371387} 
    372388 

  • trunk/libtinymail/tny-folder.h

    r1188 r1198  
    6565        TNY_FOLDER_TYPE_ROOT 
    6666}; 
    67          
    68 /* TODO: Moving messages */ 
    6967 
    7068struct _TnyFolderIface 
    …… 
    9088        void (*refresh_async_func) (TnyFolder *self, TnyRefreshFolderCallback callback, TnyRefreshFolderStatusCallback status_callback, gpointer user_data); 
    9189        void (*refresh_func) (TnyFolder *self); 
    92         void (*transfer_msgs_func) (TnyFolder *folder_src, TnyList *header_list, TnyFolder *folder_dst, gboolean delete_originals); 
     90        void (*transfer_msgs_func) (TnyFolder *self, TnyList *header_list, TnyFolder *folder_dst, gboolean delete_originals); 
    9391}; 
    9492 

  • trunk/libtinymail/tny-msg-remove-strategy.c

    r1117 r1198  
    2323 
    2424/** 
    25  * tny_msg_remove_strategy_remove: 
     25 * tny_msg_remove_strategy_peform_remove: 
    2626 * @self: A #TnyMsgRemoveStrategy instance 
    2727 * @folder: The #TnyFolder instance from which the message will be removed 
    …… 
    5959 **/ 
    6060void 
    61 tny_msg_remove_strategy_remove (TnyMsgRemoveStrategy *self, TnyFolder *folder, TnyHeader *header) 
     61tny_msg_remove_strategy_perform_remove (TnyMsgRemoveStrategy *self, TnyFolder *folder, TnyHeader *header) 
    6262{ 
    6363#ifdef DEBUG 
    64         if (!TNY_MSG_REMOVE_STRATEGY_GET_IFACE (self)->remove_func) 
     64        if (!TNY_MSG_REMOVE_STRATEGY_GET_IFACE (self)->perform_remove_func) 
    6565                g_critical ("You must implement tny_msg_remove_strategy_remove\n"); 
    6666#endif 
    6767 
    68         TNY_MSG_REMOVE_STRATEGY_GET_IFACE (self)->remove_func (self, folder, header); 
     68        TNY_MSG_REMOVE_STRATEGY_GET_IFACE (self)->perform_remove_func (self, folder, header); 
    6969        return; 
    7070} 

  • trunk/libtinymail/tny-msg-remove-strategy.h

    r1092 r1198  
    4141        GTypeInterface parent; 
    4242 
    43         void (*remove_func) (TnyMsgRemoveStrategy *self, TnyFolder *folder, TnyHeader *header); 
     43        void (*perform_remove_func) (TnyMsgRemoveStrategy *self, TnyFolder *folder, TnyHeader *header); 
    4444}; 
    4545 
    4646GType tny_msg_remove_strategy_get_type (void); 
    47 void tny_msg_remove_strategy_remove (TnyMsgRemoveStrategy *self, TnyFolder *folder, TnyHeader *header); 
     47void tny_msg_remove_strategy_perform_remove (TnyMsgRemoveStrategy *self, TnyFolder *folder, TnyHeader *header); 
    4848 
    4949G_END_DECLS 

  • trunk/libtinymailui-gtk/tny-gtk-header-list-model.c

    r1197 r1198  
    492492 
    493493static void 
    494 tny_gtk_header_list_model_unref_node (GtkTreeModel *self, GtkTreeIter  *iter) 
    495 { 
    496         return; 
    497 } 
    498 /* 
    499         TnyHeader *header = NULL; 
    500         TnyGtkHeaderListModel *list_model = TNY_GTK_HEADER_LIST_MODEL (self); 
    501  
    502         g_return_if_fail (self); 
    503         g_return_if_fail (iter->stamp == TNY_GTK_HEADER_LIST_MODEL (self)->stamp); 
    504  
    505         * Unref node happens when the GtkTreeView no longer needs the  
    506            reference to the GtkTreeIter (nor its user_data) * 
    507  
    508         if (!iter->user_data); 
    509                 return; 
    510  
    511         g_mutex_lock (list_model->folder_lock); 
    512         g_mutex_lock (list_model->iterator_lock); 
    513  
    514         header = iter->user_data; 
    515  
    516         * We can use the knowledge that it no longer needs the reference, 
    517            to uncache the instance. Uncached instances are instances that 
    518            typically no longer have their real subject inmem. Next time they'll 
    519            get a property-request, they'll create a new real subject (which 
    520            takes a certain amount of time) and will cache that before replying 
    521            the request using the real subject. * 
    522  
    523         if (G_LIKELY (header)) 
    524                 tny_header_uncache (header); 
    525  
    526         g_mutex_unlock (list_model->iterator_lock); 
    527         g_mutex_unlock (list_model->folder_lock); 
    528  
    529         return; 
    530 } 
    531 */ 
    532  
    533 static void 
    534 tny_gtk_header_list_model_ref_node (GtkTreeModel *self, GtkTreeIter  *iter) 
    535 { 
    536         return; 
    537 } 
    538  
    539 static void 
    540494tny_gtk_header_list_model_tree_model_init (GtkTreeModelIface *iface) 
    541495{ 
    …… 
    550504        iface->iter_n_children = tny_gtk_header_list_model_iter_n_children; 
    551505        iface->iter_nth_child = tny_gtk_header_list_model_iter_nth_child; 
    552         iface->ref_node = tny_gtk_header_list_model_ref_node; 
    553         iface->unref_node = tny_gtk_header_list_model_unref_node; 
    554506 
    555507        return; 
    …… 
    814766        d->list = g_list_copy (self->first); 
    815767        d->final_func = final_func; 
    816       d->ffdata = ffdata; 
    817       d->ffudata = ffudata; 
    818      
     768      d->ffdata = ffdata; 
     769      d->ffudata = ffudata; 
     770 
    819771        g_idle_add_full (G_PRIORITY_LOW, tny_gtk_header_list_model_relaxed_performer,  
    820772                d, tny_gtk_header_list_model_relaxed_data_destroyer); 
    …… 
    10711023 
    10721024                g_type_add_interface_static (object_type, GTK_TYPE_TREE_MODEL, 
    1073                                              &tree_model_info); 
     1025                                               &tree_model_info); 
    10741026 
    10751027                g_type_add_interface_static (object_type, TNY_TYPE_LIST, 
    1076                                              &tny_list_info); 
     1028                                               &tny_list_info); 
    10771029 
    10781030        } 

  • trunk/libtinymailui-gtk/tny-gtk-header-view.c

    r1197 r1198  
    4343 
    4444 
    45 /* TODO: refactor */ 
    4645static gchar * 
    4746_get_readable_date (time_t file_time_raw) 

  • trunk/libtinymailui/tny-account-store-view.c

    r1002 r1198  
    3030 * Set the account store of the view. 
    3131 * 
    32  * Implementors: This should let the account store view @self display the  
    33  * account store @account_store. 
     32 * Implementors: This should let @self display @account_store. 
    3433 **/ 
    3534void 

  • trunk/libtinymailui/tny-header-view.c

    r1002 r1198  
    2626 * @self: A #TnyHeaderView instance 
    2727 * 
    28  * Clear the view @self (show nothing) 
     28 * Clear @self (show nothing) 
    2929 * 
    3030 * Implementors: this method should clear view @self (display nothing and  
    …… 
    5050 * @header: A #TnyHeader instace 
    5151 * 
    52  * Set header of the view @self 
     52 * Set @self to display @header 
    5353 *  
    54  * Implementors: this method should cause the view @self to show the header 
    55  * @header to the user. This typically means showing the from, to, subject, date 
    56  * and cc labels. 
     54 * Implementors: this method should cause @self to show @header to the user. 
     55 * This typically means showing the from, to, subject, date and cc labels. 
    5756 * 
    58  * #TnyHeaderView is often used in a composition with a #TnyMsgView 
     57 * The #TnyHeaderView type is often used in a composition with a #TnyMsgView 
    5958 * type (the #TnyMsgView implementation contains or aggregates a #TnyHeaderView). 
    6059 * 

  • trunk/libtinymailui/tny-mime-part-save-strategy.c

    r1136 r1198  
    2727 * @part: The #TnyMimePart instance that must be saved 
    2828 * 
    29  * Performs the saving of a mime part 
     29 * With @self being a delegate of a #TnyMimePartSaver, this method performs the 
     30 * saving of @part. 
    3031 * 
    3132 * A save strategy for a mime part is used with a type that implements the  
    3233 * #TnyMimePartSaver interface. Types that do, will often also implement the  
    33  * #TnyMsgView interface (it's not a requirement). In this case they say that  
    34  * the view has functionality for saving mime parts. 
     34 * #TnyMsgView or #TnyMimePartView interface (it's not a requirement). In this 
     35 * case they say that the view has functionality for saving mime parts. 
    3536 * 
    3637 * You can for example inherit an implementation of a #TnyMsgView, like the  
    3738 * #TnyGtkMsgView one, and let yours also implement #TnyMimePartSaver. The  
    38  * example shown here is such a situation 
     39 * example shown here is for example such a situation. 
    3940 * 
    4041 * Example: 
    …… 
    4849 * </programlisting></informalexample> 
    4950 * 
    50  * Implementors: The idea is that devices can have specific such strategies. 
     51 * Implementors: The idea is that devices can have specific strategies that can 
     52 * be changed at runtime. 
     53 * 
    5154 * For example a strategy that sends it to another computer and/or a strategy 
    5255 * that saves it to a flash disk. Configurable at runtime by simply switching 
    5356 * the strategy property of a #TnyMimePartSaver. 
    5457 * 
    55  * The implementation shown in the example implements it using the gtk+ toolkit. 
    56  * Saving a mime part can also be doing nothing, if your device doesn't support 
    57  * it. Maybe you will implement it by letting it contact a service and sending 
    58  * the mime part to it? It's up to you. 
     58 * The implementation shown in this example implements it using the gtk+ toolkit. 
     59 * If your device doesn't support saving mime parts, saving a mime part can also 
     60 * be implemented by doing nothing. For example a #TnyMyDoNothingSaveStrategy.  
     61 * Maybe you will implement it by letting it contact a service and sending the 
     62 * mime part to it? It's up to you. 
    5963 * 
    6064 * Example: 
    …… 
    7074 *            GTK_RESPONSE_ACCEPT, NULL)); 
    7175 *      gtk_file_chooser_set_current_name (dialog,  
    72  *            tny_mime_part_get_filename (part)); 
    73  *      if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT) { 
     76 *                    tny_mime_part_get_filename (part)); 
     77 *      if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)  
     78 *      { 
    7479 *            gchar *uri; int fd; 
    7580 *            uri = gtk_file_chooser_get_filename (dialog); 
    …… 
    8691 * 
    8792 * The method is typically called by the implementation of a #TnyMsgView. 
    88  * For example a clicked handler of a popup menu of a attachment view in the 
     93 * For example a clicked handler of a popup menu of a attachment view in your 
    8994 * #TnyMsgView implementation. 
    9095 *  
    91  * Note that a mime can mean both the entire message (without its headers) and 
    92  * one individual