Changeset 2007

Show
Ignore:
Timestamp:
05/18/07 02:35:04
Author:
pvanhoof
Message:

Doc updates

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

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

    r1997 r2007  
    13141314 */ 
    13151315  
    1316 /* tny_camel_account_get_supported_secure_authentication: 
     1316/**  
     1317 * TnyCamelGetSupportedSecureAuthCallback: 
     1318 * @self: The TnyCamelAccount on which tny_camel_account_get_supported_secure_authentication() was called. 
     1319 * @cancelled: Whether the operation was cancelled. 
     1320 * @auth_types: A TnyList of TnyPair objects. Each TnyPair in the list has a supported secure authentication method name as its name. This list must be freed with g_object_unref(). 
     1321 * @err: A GError if an error occurred, or NULL. This must be freed with g_error_free(). 
     1322 * @user_data: The user data that was provided to tny_camel_account_get_supported_secure_authentication(). 
     1323 *  
     1324 * The callback for tny_camel_account_get_supported_secure_authentication(). 
     1325 **/ 
     1326 
     1327/** 
     1328 * tny_camel_account_get_supported_secure_authentication: 
    13171329 * @self: a #TnyCamelAccount object. 
    13181330 * @callback: A function to be called when the operation is complete. 
    1319  * @status_callback: A function to be called one or more times while the  
    1320  * operation is in progress. 
     1331 * @status_callback: A function to be called one or more times while the operation is in progress. 
    13211332 * @user_data: Data to be passed to the callback and status callback. 
    13221333 *  
    …… 
    13261337 * The returned strings may be used as parameters to  
    13271338 * tny_account_set_secure_auth_mech(). 
    1328  */ 
    1329 void tny_camel_account_get_supported_secure_authentication ( 
    1330   TnyCamelAccount *self, 
    1331   TnyCamelGetSupportedSecureAuthCallback callback, 
    1332   TnyStatusCallback status_callback, 
    1333   gpointer user_data) 
     1339 **/ 
     1340void  
     1341tny_camel_account_get_supported_secure_authentication (TnyCamelAccount *self, TnyCamelGetSupportedSecureAuthCallback callback, TnyStatusCallback status_callback, gpointer user_data) 
    13341342{  
    13351343        TnyCamelAccountPriv *priv = TNY_CAMEL_ACCOUNT_GET_PRIVATE (self); 
    13361344        g_return_if_fail (callback); 
    13371345        g_return_if_fail (priv->session); 
    1338          
    1339          
     1346 
    13401347        /* Store all the interesting info in a struct  
    13411348         * launch a thread and keep that struct-instance around. 

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

    r1965 r2007  
    9090 
    9191 
    92 /** TnyCamelGetSupportedSecureAuthCallback: 
    93  * 
    94  * @self: The TnyCamelAccount on which  
    95  * tny_camel_account_get_supported_secure_authentication() was called. 
    96  * @cancelled: Whether the operation was cancelled. 
    97  * @auth_types: A TnyList of TnyPair objects. Each TnyPair in the list has a  
    98  * supported secure authentication method name as its name. This list must  
    99  * be freed with g_object_unref(). 
    100  * @err: A GError if an error occurred, or NULL. This must be freed with  
    101  * g_error_free(). 
    102  * @user_data: The user data that was provided to  
    103  * tny_camel_account_get_supported_secure_authentication(). 
    104  *  
    105  * The callback for tny_camel_account_get_supported_secure_authentication(). 
    106  **/ 
    107 typedef void (*TnyCamelGetSupportedSecureAuthCallback) ( 
    108   TnyCamelAccount *self, gboolean cancelled, 
    109   TnyList *auth_types, GError **err,  
    110   gpointer user_data); 
    111  
    112 void tny_camel_account_get_supported_secure_authentication( 
    113   TnyCamelAccount *self, 
    114   TnyCamelGetSupportedSecureAuthCallback callback, 
    115   TnyStatusCallback status_callback, 
    116   gpointer user_data); 
     92typedef void (*TnyCamelGetSupportedSecureAuthCallback) (TnyCamelAccount *self, gboolean cancelled, TnyList *auth_types, GError **err, gpointer user_data); 
     93void tny_camel_account_get_supported_secure_authentication(TnyCamelAccount *self, TnyCamelGetSupportedSecureAuthCallback callback, TnyStatusCallback status_callback, gpointer user_data); 
    11794 
    11895G_END_DECLS 

  • trunk/libtinymail/tny-account.c

    r1947 r2007  
    3838 * An example url_string can be imap://user:password@server/INBOX/005. Only  
    3939 * "imap://user@server" is significant when searching. Also take a look at  
    40  * RFC 1808 for more information on url_string formatting. 
     40 * RFC 1808 and RFC 4467 for more information on url_string formatting. 
    4141 * 
    4242 * This method must be usable with and will be used for  
    …… 
    6868 * tny_account_cancel: 
    6969 * @self: a #TnyAccount object 
    70  * 
    71  * Forcefully cancels the current operation that is happening on @self. 
    72  *  
     70 *  
     71 * Try to cancel the current operation that is happening. This API, though, 
     72 * guarantees nothing about any cancelations. 
    7373 **/ 
    7474void  

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

    r1879 r2007  
    113113 * Removes a folder represented by @folder from the folder store @self. You are 
    114114 * responsible for unreferencing the @folder instance yourself. This method will 
    115  * not do this for you, leaving the @folder instance in an unusable state. The  
    116  * id of the @folder instance will be blanked once really deleted from the 
    117  * service. All the #TnyFolderObservers and #TnyFolderStoreObservers of @folder, 
    118  * but of course not of @self, will automatically be unsubscribed. 
    119  *  
    120  * API question and TODO (undetermined): what about recursive deleting? 
     115 * not do this for you, leaving the @folder instance in an unusable state. 
     116 * 
     117 * All the #TnyFolderObservers and #TnyFolderStoreObservers of @folder, but of  
     118 * course not of @self, will automatically be unsubscribed. 
     119 *  
     120 * This method will always recursively delete all child folders of @self. While 
     121 * deleting folders, the folders will also always get unsubscribed (for example 
     122 * in case of IMAP, which means that the folder wont be in LSUB either anymore). 
     123 * 
     124 * Observers of @self and of any the child folders of @self will receive delete 
     125 * observer events in deletion order (childs first, parents after that). Types 
     126 * like the #TnyGtkFolderStoreListModel know about this and act on folder  
     127 * deletions by automatically updating themselves. 
    121128 * 
    122129 * Example: 

  • trunk/libtinymail/tny-folder.c

    r1989 r2007  
    3939 * @self: a #TnyFolder object 
    4040 *  
    41  * Get the capabilities of @self. 
     41 * Get a few relevant capabilities of @self. 
    4242 *  
    4343 * Return value: The capabilities of the folder 
    4444 **/ 
    45  
    4645TnyFolderCaps  
    4746tny_folder_get_caps (TnyFolder *self) 
    …… 
    6261 * string of @self. If not NULL, the returned value must be freed after use. 
    6362 * 
    64  * The url string is specified in RFC 1808 and looks like this: 
    65  * imap://user@hostname/INBOX/folder. Note that it doesn't necessarily contain  
     63 * The url string is specified in RFC 1808 and / or RFC 4467 and looks like  
     64 * this: imap://server/INBOX/folder. Note that it doesn't necessarily contain  
    6665 * the password of the IMAP account but can contain it. 
    6766 *  
    …… 
    130129 * After this, @observer will start receiving notification of changes about @self.  
    131130 *  
    132  * You must use tny_folder_remove_observer, in for example the finalization of  
     131 * You must use tny_folder_remove_observer in for example the finalization of  
    133132 * your type if you used this method. Adding an observer to @self, changes 
    134133 * reference counting of the objects involved. Removing the observer will undo 
    135134 * those reference counting changes. Therefore if you don't, you will introduce 
    136135 * memory leaks. 
    137  * 
    138136 **/ 
    139137void  
    …… 
    163161 * After this, @observer will no longer receive notification of changes about @self.  
    164162 *  
    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. 
    170  * 
     163 * You must use this method in for example the finalization of your type if you 
     164 * used tny_folder_add_observer. Adding an observer to @self, changes reference  
     165 * counting of the objects involved. Removing the observer will undo those  
     166 * reference counting changes. Therefore if you don't, you will introduce memory 
     167 * leaks. 
    171168 **/ 
    172169void  
    …… 
    191188 * Poke for the status, this will invoke the event of sending a #TnyFolderChange   
    192189 * 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  * 
     190 * folder count, also if the unread and total didn't change at all. This makes  
     191 * it possible for a model or view that shows folders to get the initial folder  
     192 * unread and total counts (the #TnyGtkFolderStoreListModel uses this method  
     193 * internally, for example). 
    198194 **/ 
    199195void  
    …… 
    217213 * must be unreferenced after use. 
    218214 * 
    219  * Implementors: This method must return the strategy for receiving a message. 
    220  * being the implementer, you must add a reference before returning the instance. 
    221  * 
    222215 * Return value: the strategy for receiving a message 
    223216 **/ 
    …… 
    247240 * 
    248241 * Set the strategy for receiving a message 
    249  * 
    250  * Implementors: This method must set (store) the strategy for receiving a 
    251  * message. 
    252242 * 
    253243 * The idea is that devices can have a specific such strategy. For example a 
    …… 
    294284 * 
    295285 * Copies @self to @into giving the new folder the name @new_name. Returns the 
    296  * newly created folder in @into, which will carry the name @new_name. 
    297  * 
    298  * Very important note:  
    299  * When you are moving @self to @into by setting @del to true, you MUST make  
    300  * sure that @self is not used anymore. For example if you have gotten its  
    301  * headers using tny_folder_get_headers, you need to get rid of those first. 
    302  * In case you used a default component like the TnyGtkHeaderListModel or  
    303  * TnyGtkHeaderListTree as TnyList for storing the headers in, you can easily 
    304  * get rid if your headers by setting the model of the GtkTreeView to an empty 
    305  * one. You MUST NOT try to keep using it further (as the original folder, its  
    306  * memory caches and it's offline on-disk cache will have been removed 
    307  * permanently behind your back). Especially the memory caches will get you in 
    308  * severe problems, like segmentation errors when trying to access the now  
    309  * invalid TnyHeader's properties. This is a design decision and can't be fixed 
    310  * (it's not a bug): a removed folder is permanently destroyed. Moving a folder 
    311  * is the same as removing it and creating a new one. 
    312  *  
    313  * Note, though, that you need to give a @self with one reference count. And get 
    314  * rid of that reference once you are done. 
    315  *  
    316  * Implementors: The return value must be the new folder in @into carrying the  
    317  * name @new_name. Invoking the tny_folder_get_folder_store API on the return  
    318  * value must return the @into instance. The implementation must copy all  
    319  * messages from @self to @into. In case @del was TRUE, the messages that got 
    320  * successfully copied must be removed from @self. If @new_name already exists 
    321  * in @into and @err is not NULL, then an error must be set in @err and no  
    322  * further action may be performed. 
     286 * newly created folder in @into, which will carry the name @new_name. For some 
     287 * remote services this functionality is implemented as a rename operation. 
     288 * 
     289 * It will do both copying and in case of @del being TRUE, removing too,  
     290 * recursively. If you don't want it to be recursive, you should in stead create 
     291 * the folder @new_name in @into manually using tny_folder_store_create_folder 
     292 * and then use the tny_folder_transfer_msgs API. 
     293 * 
     294 * This method will always result in create observer events being throw for each 
     295 * subfolder of @self that is copied or moved to @new_name in creation order  
     296 * (parents first, childs after that).  
     297 * 
     298 * In case of @del being TRUE it will on top of that and before those create 
     299 * events also result in remove observer events being throw for each subfolder 
     300 * of @self in deletion order (the exact reversed order: childs first, parents 
     301 * after that) 
     302 * 
     303 * Standard folder models like the #TnyGtkFolderStoreListModel know about this 
     304 * behavior and will act by updating themselves automatically. 
     305 *  
     306 * When you are moving @self to @into with @del set to TRUE (moving @self), you 
     307 * MUST make sure that @self nor any of its sub folders are used anymore. For 
     308 * example if you have gotten headers using tny_folder_get_headers, you MUST get  
     309 * rid of those first. In case you used a default component like the  
     310 * TnyGtkHeaderListModel or any other TnyList for storing the headers, you can  
     311 * easily get rid if your headers by setting the model of the GtkTreeView to 
     312 * an empty one or unreferencing the list. You MUST NOT try to keep using it nor 
     313 * any of its headers. These instances will be invalid and in a destroyed state. 
     314 *  
     315 * If @new_name already exists in @into and @err is not NULL, then an error will 
     316 * be set in @err and no further action will be performed. 
    323317 *  
    324318 * Return value: a new folder instance to whom was copied 
    …… 
    362356 * 
    363357 * Copies @self to @into giving the new folder the name @new_name. Returns the 
    364  * newly created folder in @into, which will carry the name @new_name. 
    365  * 
    366  * After the method's callback happened, tny_folder_get_all_count and  
    367  * tny_folder_get_unread_count are guaranteed to be correct. 
     358 * newly created folder in @into, which will carry the name @new_name. For some 
     359 * remote services this functionality is implemented as a rename operation. 
     360 * 
     361 * It will do both copying and in case of @del being TRUE, removing too,  
     362 * recursively. If you don't want it to be recursive, you should in stead create 
     363 * the folder @new_name in @into manually using tny_folder_store_create_folder 
     364 * and then use the tny_folder_transfer_msgs API. 
     365 * 
     366 * This method will always result in create observer events being throw for each 
     367 * subfolder of @self that is copied or moved to @new_name in creation order  
     368 * (parents first, childs after that).  
     369 * 
     370 * In case of @del being TRUE it will on top of that and before those create 
     371 * events also result in remove observer events being throw for each subfolder 
     372 * of @self in deletion order (the exact reversed order: childs first, parents 
     373 * after that) 
     374 * 
     375 * Standard folder models like the #TnyGtkFolderStoreListModel know about this 
     376 * behavior and will act by updating themselves automatically. 
     377 *  
     378 * When you are moving @self to @into with @del set to TRUE (moving @self), you 
     379 * MUST make sure that @self nor any of its sub folders are used anymore. For 
     380 * example if you have gotten headers using tny_folder_get_headers, you MUST get  
     381 * rid of those first. In case you used a default component like the  
     382 * TnyGtkHeaderListModel or any other TnyList for storing the headers, you can  
     383 * easily get rid if your headers by setting the model of the GtkTreeView to 
     384 * an empty one or unreferencing the list. You MUST NOT try to keep using it nor 
     385 * any of its headers. These instances will be invalid and in a destroyed state. 
     386 *  
     387 * If @new_name already exists in @into and @err is not NULL, then an error will 
     388 * be set in @err and no further action will be performed. 
    368389 * 
    369390 * If you want to use this method, it's advised to let your application  
    …… 
    419440tny_folder_copy_async (TnyFolder *self, TnyFolderStore *into, const gchar *new_name, gboolean del, TnyCopyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data) 
    420441{ 
    421         TnyFolder *retval; 
    422442 
    423443#ifdef DBC /* require */ 
    …… 
    10711091 * about tny_folder_refresh. 
    10721092 * 
     1093 * API warning: it's possible that between the @refresh and @err, a pointer to 
     1094 * a query object will be placed. This will introduce both an API and ABI  
     1095 * breakage. 
     1096 * 
    10731097 * Example: 
    10741098 * <informalexample><programlisting> 
    …… 
    11771201 *  
    11781202 * Return value: The folder type as a #TnyFolderType enum 
    1179  * 
    11801203 **/ 
    11811204TnyFolderType