Changeset 3150

Show
Ignore:
Timestamp:
12/17/07 21:14:37
Author:
pvanhoof
Message:

2007-12-17 Philip Van Hoof <pvanhoof@gnome.org>

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/ChangeLog

    r3149 r3150  
     12007-12-17  Philip Van Hoof <pvanhoof@gnome.org> 
     2 
     3        * New documentation style, first commit (GtkDocFuture) 
     4 
    152007-12-17  Philip Van Hoof <pvanhoof@gnome.org> 
    26 

  • trunk/docs/devel/reference/tmpl/tny-account.sgml

    r3143 r3150  
    360360 
    361361@self:  
    362 @canceled:  
     362@cancelled:  
    363363 
    364364 

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

    r2825 r3150  
    1818 */ 
    1919 
     20 
     21/** 
     22 * TnyAccountStore: 
     23 *  
     24 * A account store, holding a list of accounts 
     25 * 
     26 * free-function: g_object_unref 
     27 */ 
     28 
    2029#include <config.h> 
    2130 
    …… 
    3645/** 
    3746 * tny_account_store_find_account: 
    38  * @self: a #TnyAccountStore object 
     47 * @self: a #TnyAccountStore 
    3948 * @url_string: the url-string of the account to find 
    4049 * 
    41  * Try to find the account in @self that corresponds to @url_string. If this  
    42  * method does not return NULL, the returned value is the found account and 
    43  * must be unreferenced after use. 
    44  * 
    45  * Implementors: when implementing a platform-specific library, you must 
    46  * implement this method. Let it return the account that corresponds to 
    47  * @url_string or let it return NULL. Also see tny_account_matches_url_string 
    48  * at #TnyAccount. 
    49  * 
    50  * This method can be used to resolve url-strings to #TnyAccount instances. 
    51  * 
    52  * Return value: the found account or NULL. 
     50 * Try to find the first account in account store @self that corresponds to  
     51 * @url_string. If found, the returned value must be unreferenced. 
     52 * 
     53 * returns (null-ok) (caller-owns): the found account or NULL 
     54 * since: 1.0 
     55 * audience: application-developer 
     56 * complexity: high 
    5357 **/ 
    5458TnyAccount*  
    …… 
    6165        g_assert (url_string); 
    6266        g_assert (strlen (url_string) > 0); 
    63         g_assert (strstr (url_string, "://")); 
     67        g_assert (strstr (url_string, ":")); 
    6468        g_assert (TNY_ACCOUNT_STORE_GET_IFACE (self)->find_account_func != NULL); 
    6569#endif 
    …… 
    7983/** 
    8084 * tny_account_store_alert: 
    81  * @self: a #TnyAccountStore object 
    82  * @account: The account (This is NULL sometimes for some current implementations). 
    83  * @type: the message type (severity) 
     85 * @self: a #TnyAccountStore 
     86 * @account (null-ok): The account or NULL 
     87 * @type: alert type 
    8488 * @question: whether or not this is a question 
    85  * @error: A GError, of domain TNY_ACCOUNT_ERROR or TNY_ACCOUNT_STORE_ERROR,  
    86  * which should be used to determine what to show to the user. 
    87  * 
    88  * This jump-to-the-ui method implements showing a message dialog appropriate  
     89 * @error: A #GError with the alert 
     90 * 
     91 * This callback method must implements showing a message dialog appropriate  
    8992 * for the @error and @type as message type. It will return TRUE if the reply  
    9093 * was affirmative or FALSE if not. 
    9194 * 
    92  * You must not try reconnecting in the implementation of this method. 
    93  * 
    94  * Implementors: when implementing a platform-specific library, you must 
    95  * implement this method. For example in GTK+ by using the #GtkDialog API. The 
    96  * implementation will, for example, be used to ask the user about accepting SSL 
    97  * certificates. The two possible answers that must be supported are  
    98  * "Yes" and "No" which must result in a TRUE or a FALSE return value, though  
    99  * your implementation should attempt to use explicit button names such as  
    100  * "Accept Certificate" and "Reject Certificate". Likewise, the dialog should be  
    101  * arranged according the the user interface guidelines of your target platform. 
     95 * The two possible answers that must be supported are "Yes" and "No" which must 
     96 * result in a TRUE or a FALSE return value, though your implementation should 
     97 * attempt to use explicit button names such as "Accept Certificate" and  
     98 * "Reject Certificate". Likewise, the dialog should be arranged according to 
     99 * the user interface guidelines of your target platform. 
    102100 * 
    103101 * Although there is a @question parameter, there is not always certainty about 
    …… 
    149147 * </programlisting></informalexample> 
    150148 * 
    151  * Return value: Whether the user pressed Ok/Yes (TRUE) or Cancel/No (FALSE) 
     149 * returns: Affirmative = TRUE,  Negative = FALSE 
     150 * since: 1.0 
     151 * audience: platform-developer, application-developer, type-implementer 
    152152 **/ 
    153153gboolean  
    …… 
    171171/** 
    172172 * tny_account_store_get_device: 
    173  * @self: a #TnyAccountStore object 
    174  * 
    175  * This method returns a #TnyDevice instance. You must unreference the return 
    176  * value after use. 
    177  * 
    178  * Implementors: when implementing a platform-specific library, you must 
    179  * implement this method by letting it return a #TnyDevice instance. You must 
    180  * add a reference count before returning. 
    181  * 
    182  * Return value: the device attached to this account store 
    183  * 
     173 * @self: a #TnyAccountStore 
     174 * 
     175 * This method returns the #TnyDevice instance used by #TnyAccountStore @self. You 
     176 * must unreference the return value after use. 
     177 * 
     178 * returns (caller-owns): the device used by @self 
     179 * since: 1.0 
     180 * audience: application-developer 
    184181 **/ 
    185182TnyDevice*  
    …… 
    205202/** 
    206203 * tny_account_store_get_cache_dir: 
    207  * @self: a #TnyAccountStore object 
     204 * @self: a #TnyAccountStore 
    208205 *  
    209  * Get the local path that will be used for storing the disk cache 
    210  * 
    211  * Implementors: when implementing a platform-specific library, you must 
    212  * implement this method. You can for example let it return the path to some 
    213  * folder in $HOME on the file system. 
    214  * 
    215  * Note that the callers of this method will not free the result. The 
    216  * implementor of a #TnyAccountStore is responsible for freeing it up. For 
    217  * example when destroying @self (in its finalize method). 
    218  * 
    219  * Return value: the local path that will be used for storing the disk cache 
    220  * 
     206 * Returns the path that will be used for storing cache. Note that the callers 
     207 * of this method will not free up the result. The implementation of  
     208 * #TnyAccountStore @self is responsible for freeing up.  
     209 * 
     210 * returns: cache's path 
     211 * since: 1.0 
     212 * audience: platform-developer, type-implementer 
    221213 **/ 
    222214const gchar* 
    …… 
    243235/** 
    244236 * tny_account_store_get_accounts: 
    245  * @self: a #TnyAccountStore object 
    246  * @list: a #TnyList instance that will be filled with #TnyAccount instances 
    247  * @types: a #TnyGetAccountsRequestType that describes which account types are needed 
     237 * @self: a #TnyAccountStore 
     238 * @list: a #TnyList that will be filled with #TnyAccount instances 
     239 * @types: a #TnyGetAccountsRequestType that indicates which account types are wanted 
    248240 *  
    249  * Get a read-only list of accounts in the store. You must not change @list  
    250  * except for referencing and unreferencing. 
     241 * Get a list of accounts in the account store @self. 
    251242 * 
    252243 * Example: 
    …… 
    266257 * </programlisting></informalexample> 
    267258 * 
    268  * Implementors: when implementing a platform-specific library, you must  
    269  * implement this method. 
    270  * 
    271  * It is allowed to cache the list (but not required). If you are implementing 
    272  * an account store for account implementations from libtinymail-camel, you must 
    273  * register the created accounts with a #TnySessionCamel instance using the  
    274  * libtinymail-camel specific tny_session_camel_set_current_accounts API. 
    275  * 
    276  * If you use the #TnySessionCamel to register accounts, you must after  
    277  * registering your last initial account call the tny_session_camel_set_initialized 
    278  * API. 
    279  * 
    280  * The implementation must fillup @list with available accounts. Note that if 
     259 * When implementing this API it is allowed but not required to cache the list. 
     260 * If you are implementing an account store for #TnyCamelAccount account  
     261 * instances, register the created accounts with a #TnySessionCamel instance  
     262 * using the API tny_session_camel_set_current_accounts right after creating 
     263 * the accounts for the first time. 
     264 * 
     265 * If you use the #TnySessionCamel to register accounts, register each account 
     266 * using tny_camel_account_set_session and after registering your last account 
     267 * use the API tny_session_camel_set_initialized 
     268 * 
     269 * The method must fill up @list with available accounts. Note that if 
    281270 * you cache the list, you must add a reference to each account added to the 
    282  * list (else they will be unreferenced and if the reference count would reach 
    283  * zero, an account would no longer be correctly cached). 
    284  * 
    285  * With libtinymail-camel each created account must also be informed about the 
    286  * #TnySessionCamel instance being used. Read more about this at 
    287  * tny_camel_account_set_session of the libtinymail-camel specific  
    288  * #TnyCamelAccount. 
     271 * list. 
    289272 * 
    290273 * There are multiple samples of #TnyAccountStore implementations in 
    …… 
    295278 * The get_pass and forget_pass functionality of the example below is usually 
    296279 * implemented by utilizing a #TnyPasswordGetter that is returned by the  
    297  * #TnyPlatformFactory, that is usually available from the #TnyAccountStore.  
     280 * #TnyPlatformFactory. 
    298281 * 
    299282 * Example (that uses a cache): 
    …… 
    347330 * } 
    348331 * </programlisting></informalexample> 
     332 * 
     333 * since: 1.0 
     334 * audience: platform-developer, application-developer, type-implementer 
    349335 **/ 
    350336void 
    …… 
    379365 * @user_data: user data set when the signal handler was connected. 
    380366 * 
    381  * Emitted when the store starts trying to connect the accounts 
     367 * Emitted when the store starts trying to connect the accounts. Usage of this 
     368 * signal is not recommended as it's a candidate for API changes. 
     369 * 
     370 * since: 1.0 
    382371 */ 
    383372        tny_account_store_signals[TNY_ACCOUNT_STORE_CONNECTING_STARTED] = 
    …… 
    401390 * GType system helper function 
    402391 * 
    403  * Return value: a GType 
     392 * returns: a #GType 
     393 * since: 1.0 
    404394 **/ 
    405395GType 
    …… 
    436426 * GType system helper function 
    437427 * 
    438  * Return value: a GType 
     428 * returns: a #GType 
     429 * since: 1.0 
    439430 **/ 
    440431GType 
    …… 
    459450 * GType system helper function 
    460451 * 
    461  * Return value: a GType 
     452 * returns: a #GType 
     453 * since: 1.0 
    462454 **/ 
    463455GType 
    …… 
    484476 * GType system helper function 
    485477 * 
    486  * Return value: a GType 
     478 * returns: a #GType 
     479 * since: 1.0 
    487480 **/ 
    488481GType 

  • trunk/libtinymail/tny-account.c

    r3125 r3150  
    1818 */ 
    1919 
     20/** 
     21 * TnyAccount: 
     22 *  
     23 * A abstract account type with API shared between #TnyStoreAccount and 
     24 * #TnyTransportAccount. 
     25 * 
     26 * free-function: g_object_unref 
     27 */ 
     28 
    2029#include <config.h> 
    2130 
    …… 
    3443/** 
    3544 * tny_account_get_connection_policy: 
    36  * @self: a #TnyAccount object 
     45 * @self: a #TnyAccount 
    3746 * 
    3847 * Get the connection policy for @self. You must unreference the returned  
    3948 * value when you are finished with used it. 
    4049 * 
    41  * Return value: connection policy 
     50 * returns (caller-owns): connection policy 
     51 * since: 1.0 
     52 * audience: application-developer, platform-developer 
    4253 **/ 
    4354TnyConnectionPolicy*  
    …… 
    6273/** 
    6374 * tny_account_set_connection_policy: 
    64  * @self: a #TnyAccount object 
    65  * @policy: the #TnyConnectionStrategy 
     75 * @self: a #TnyAccount 
     76 * @policy: a #TnyConnectionStrategy 
    6677 * 
    6778 * Set the connection strategy for @self. 
     79 * 
     80 * since: 1.0 
     81 * audience: application-developer, platform-developer 
    6882 **/ 
    6983void  
    …… 
    87101/** 
    88102 * tny_account_is_ready: 
    89  * @self: a #TnyAccount object 
     103 * @self: a #TnyAccount 
    90104 * 
    91105 * Some implementations of #TnyAccount need registration in a subsystem or  
    …… 
    94108 * This boolean property will tell you if @self is ready for that. 
    95109 * 
    96  * Return value: whether @self is ready for use 
     110 * returns: TRUE if @self is ready for use, else FALSE 
     111 * since: 1.0 
     112 * audience: platform-developer 
    97113 **/ 
    98114gboolean  
    …… 
    116132/** 
    117133 * tny_account_start_operation: 
    118  * @self: a #TnyAccount object 
    119  * @domain: the domain of the #TnyStatus instances that will happen in @status_callback 
    120  * @code: the code of the #TnyStatus instances that will happen in @status_callback 
     134 * @self: a #TnyAccount 
     135 * @domain: the domain of the #TnyStatus that will happen in @status_callback 
     136 * @code: the code of the #TnyStatus that will happen in @status_callback 
    121137 * @status_callback: status callback handler 
    122138 * @status_user_data: the user-data to give to the @status_callback 
    123139 * 
    124  * Start an operation. This only works with methods that don't end with _async. 
     140 * Starts an operation. This only works for methods that don't end with _async. 
     141 * 
     142 * since: 1.0 
     143 * audience: application-developer 
    125144 **/ 
    126145void  
    …… 
    142161/** 
    143162 * tny_account_stop_operation: 
    144  * @self: a #TnyAccount object 
    145  * @canceled: NULL or byref whether the operation got canceled 
    146  * 
    147  * Stop the current operation. This only works with methods that don't end  
     163 * @self: a #TnyAccount 
     164 * @cancelled (out): NULL or byref whether the operation got canceled 
     165 * 
     166 * Stop the current operation. This only works for methods that don't end  
    148167 * with _async. 
     168 * 
     169 * since: 1.0 
     170 * audience: application-developer 
    149171 **/ 
    150172void  
    151 tny_account_stop_operation (TnyAccount *self, gboolean *canceled) 
     173tny_account_stop_operation (TnyAccount *self, gboolean *cancelled) 
    152174{ 
    153175#ifdef DBC /* require */ 
    …… 
    156178#endif 
    157179 
    158         TNY_ACCOUNT_GET_IFACE (self)->stop_operation_func (self, canceled); 
     180        TNY_ACCOUNT_GET_IFACE (self)->stop_operation_func (self, cancelled); 
    159181 
    160182#ifdef DBC /* ensure*/ 
    …… 
    166188/** 
    167189 * tny_account_matches_url_string: 
    168  * @self: a #TnyAccount object 
     190 * @self: a #TnyAccount 
    169191 * @url_string: the url-string of the account to find 
    170192 * 
    171  * Find out whether the account matches a certain url_string. 
    172  * 
    173  * Implementors: Be forgiving about things like passwords in the url_string: 
     193 * Returns whether the account's url-string matches @url_string. 
     194 * 
     195 * When implementing be forgiving about things like passwords in the url_string: 
    174196 * while matching the folder, password and message-id pieces are insignificant. 
    175197 * 
    176198 * An example url_string can be imap://user:password@server/INBOX/005. Only  
    177199 * "imap://user@server" is significant when searching. Also take a look at  
    178  * RFC 1808 and RFC 4467 for more information on url_string formatting. 
    179  * 
    180  * This method must be usable with and will be used for  
    181  * tny_account_store_find_account. 
    182  * 
    183  * Return value: whether or not @self matches with @url_string. 
     200 * RFC 1808 and RFC 4467 for more information on url-string formatting. 
     201 * 
     202 * This method will be used by tny_account_store_find_account(). 
     203 * 
     204 * returns: TRUE if @self matches with @url_string, else FALSE 
     205 * since: 1.0 
     206 * audience: application-developer, platform-developer 
    184207 **/ 
    185208gboolean  
    …… 
    205228/** 
    206229 * tny_account_cancel: 
    207  * @self: a #TnyAccount object 
     230 * @self: a #TnyAccount 
    208231 *  
    209232 * Try to cancel the current operation that is happening. This API, though, 
    210  * guarantees nothing about any cancelations. 
     233 * makes no guarantees about any cancellations taking place (it's a try). 
     234 * 
     235 * Since relatively few guarantees can be made, using this API is not recommended. 
     236 * 
     237 * since: 1.0 
     238 * audience: application-developer 
    211239 **/ 
    212240void  
    …… 
    228256/** 
    229257 * tny_account_get_account_type: 
    230  * @self: a #TnyAccount object 
     258 * @self: a #TnyAccount 
    231259 * 
    232260 * Get the account type of @self. There are two account types: a store and  
    …… 
    237265 * 
    238266 * A transport account has a send method for sending #TnyMsg instances 
    239  * using the transport implemented by the account (for example SMTP). 
    240  * 
    241  * Return value: The account type 
     267 * using the transport layer the account uses. For example SMTP. 
     268 * 
     269 * returns: The account type 
     270 * since: 1.0 
     271 * audience: application-developer 
    242272 **/ 
    243273TnyAccountType 
    …… 
    262292/** 
    263293 * tny_account_get_connection_status: 
    264  * @self: a #TnyAccount object 
    265  * 
    266  * Get the connection status of @self 
    267  * 
    268  * Return value: the status of the connection 
     294 * @self: a #TnyAccount 
     295 * 
     296 * Get the status of the connection for account @self. 
     297 * 
     298 * returns: the status of the connection 
     299 * since: 1.0 
     300 * complexity: low 
     301 * audience: application-developer 
    269302 **/ 
    270303TnyConnectionStatus  
    …… 
    289322/** 
    290323 * tny_account_get_id: 
    291  * @self: a #TnyAccount object 
    292  *  
    293  * Get the unique id of @self 
     324 * @self: a #TnyAccount 
     325 *  
     326 * Get the unique id of @self. 
    294327 * 
    295328 * A certainty you have about this property is that the id is unique in the  
    296  * #TnyAccountStore. It doesn't have to be unique in the entire application. 
    297  * 
    298  * The format of the id isn't specified. The implementor of the #TnyAccountStore 
     329 * #TnyAccountStore that contains @self. It doesn't have to be unique in the 
     330 * entire application if you have multiple #TnyAccountStore instances (which 
     331 * is unlikely). 
     332 * 
     333 * The format of the id isn't specified. The implementer of the #TnyAccountStore 
    299334 * must set this id using tny_account_set_id. 
    300335 *  
    301  * Return value: Unique id 
     336 * returns: unique id 
     337 * since: 1.0 
     338 * audience: application-developer 
    302339 **/ 
    303340const gchar* 
    …… 
    323360/** 
    324361 * tny_account_set_name: 
    325  * @self: a #TnyAccount object 
     362 * @self: a #TnyAccount 
    326363 * @name: the name 
    327364 * 
    328365 * Set the account's human readable name 
    329366 *  
     367 * since: 1.0 
     368 * audience: platform-developer 
    330369 **/ 
    331370void  
    …… 
    358397/** 
    359398 * tny_account_set_secure_auth_mech: 
    360  * @self: a #TnyAccount object 
     399 * @self: a #TnyAccount 
    361400 * @mech: the authentication mechanism 
    362401 *  
    …… 
    381420 * Other relevant standards: 
    382421 * - <ulink url="http://www.faqs.org/rfcs/rfc1731.html">RFC 1731 - IMAP4 Authentication Mechanisms</ulink>  
    383  *  
     422 * 
     423 * since: 1.0 
     424 * audience: platform-developer 
    384425 **/ 
    385426void 
    …… 
    404445/** 
    405446 * tny_account_set_id: 
    406  * @self: a #TnyAccount object 
     447 * @self: a #TnyAccount 
    407448 * @id: the id 
    408449 * 
    …… 
    410451 * can start using the account. The id must be unique in a #TnyAccountStore and 
    411452 * is typically set in the implementation of a #TnyAccountStore. 
    412  *  
     453 * 
     454 * since: 1.0 
     455 * audience: platform-developer 
    413456 **/ 
    414457void  
    …… 
    433476/** 
    434477 * tny_account_set_forget_pass_func: 
    435  * @self: a #TnyAccount object 
     478 * @self: a #TnyAccount 
    436479 * @forget_pass_func: a pointer to the function 
    437480 * 
    …… 
    469512 * } 
    470513 * </programlisting></informalexample> 
     514 *  
     515 * since: 1.0 
     516 * audience: platform-developer 
    471517 **/ 
    472518void 
    …… 
    489535/** 
    490536 * tny_account_get_forget_pass_func: 
    491  * @self: a #TnyAccount object 
    492  *  
    493  * Get a pointer to the forget-password function 
    494  * 
    495  * Return value: A pointer to the forget-password function 
     537 * @self: a #TnyAccount 
     538 *  
     539 * Get a pointer to the forget-password function for @self. 
     540 * 
     541 * returns: A pointer to the forget-password function 
    496542 **/ 
    497543TnyForgetPassFunc 
    …… 
    515561/** 
    516562 * tny_account_set_url_string: 
    517  * @self: a #TnyAccount object 
     563 * @self: a #TnyAccount 
    518564 * @url_string: the url string (ex. mbox://path) 
    519565 *   
    520566 * Set the url string of @self (RFC 1808). You don't need to use this for imap 
    521  * and pop where you can use the simplified API (set_proto, set_hostname, etc). 
    522  * This property is typically set in the implementation of a #TnyAccountStore. 
    523  *  
    524  * For example the url_string for an SMTP account that uses SSL with authentication 
     567 * and pop where you can use the simplified API (tny_account_set_proto(),  
     568 * tny_account_set_hostname(), etc). This property is typically set in the  
     569 * implementation of a #TnyAccountStore. 
     570 *  
     571 * For example the url-string for an SMTP account that uses SSL with authentication 
    525572 * type PLAIN: smtp://user;auth=PLAIN@smtp.server.com/;use_ssl=wrapped 
    526573 *  
    527  * Don't forget to set the name, type and proto setting of the account too. 
     574 * Don't forget to set the name, type and protocol setting of the account too. 
     575 * 
     576 * since: 1.0 
     577 * audience: platform-developer 
    528578 **/ 
    529579void 
    …… 
    553603/** 
    554604 * tny_account_set_proto: 
    555  * @self: a #TnyAccount object 
     605 * @self: a #TnyAccount 
    556606 * @proto: the protocol (ex. "imap") 
    557607 *  
    …… 
    559609 * using the account. This property is typically set in the implementation 
    560610 * of a #TnyAccountStore. 
    561  *  
     611 * 
     612 * since: 1.0 
     613 * audience: platform-developer 
    562614 **/ 
    563615void 
    …… 
    582634/** 
    583635 * tny_account_set_user: 
    584  * @self: a #TnyAccount object 
     636 * @self: a #TnyAccount 
    585637 * @user: the username 
    586638 *  
    587  * Set the user or login of @self. You need to set this property before you 
    588  * can start using the account. This property is typically set in the 
    589  * implementation of a #TnyAccountStore. 
    590  * 
     639 * Set the user or login of account @self. You need to set this property 
     640 * before you can start using the account. This property is typically set  
     641 * in the implementation of a #TnyAccountStore. 
     642 * 
     643 * since: 1.0 
     644 * complexity: high 
     645 * audience: platform-developer 
    591646 **/ 
    592647void 
    …… 
    612667/** 
    613668 * tny_account_set_hostname: 
    614  * @self: a #TnyAccount object 
     669 * @self: a #TnyAccount 
    615670 * @host: the hostname 
    616671 *  
    617  * Set the hostname of @self. You need to set this property before you can start 
    618  * using the account. This property is typically set in the implementation of a 
    619  * #TnyAccountStore. 
    620  * 
     672 * Set the hostname of account @self. You need to set this property before you 
     673 * can start using the account. This property is typically set in the  
     674 * implementation of a #TnyAccountStore. 
     675 * 
     676 * since: 1.0 
     677 * audience: platform-developer 
    621678 **/ 
    622679void 
    …… 
    644701/** 
    645702 * tny_account_set_port: 
    646  * @self: a #TnyAccount object 
    647  * @port: the port to connect to on the hostname 
     703 * @self: a #TnyAccount 
     704 * @port: the port to connect to on the hostname of @self 
    648705 *  
    649706 * Set the port of @self. If you don't set this property, the default port for 
    650  * the protocol will be used (for example 143 and 993 for IMAP and 110 for POP3). 
    651  * 
     707 * the protocol will be used (for example 143, 993 for IMAP and 110, 995 for POP3). 
     708 * 
     709 * since: 1.0 
     710 * audience: platform-developer 
    652711 **/ 
    653712void 
    …… 
    670729/** 
    671730 * tny_account_set_pass_func: 
    672  * @self: a #TnyAccount object 
     731 * @self: a #TnyAccount 
    673732 * @get_pass_func: a pointer to the function 
    674733 *  
    …… 
    681740 * this property as the last of all properties that you will set to an account 
    682741 * in the #TnyAccountStore. 
     742 * 
     743 * If possible, use the mlock() syscall on this memory. 
    683744 *  
    684745 * Also see #TnyGetPassFunc for more information about the function itself.  
    …… 
    696757 *    retval = (gchar*) tny_password_getter_get_password (pwdgetter,  
    697758 *       tny_account_get_id (account), prompt, cancel); 
    698  *    g_object_unref (G_OBJECT (pwdgetter)); 
     759 *    mlock (retval, strlen (retval)); 
     760 *    g_object_unref (pwdgetter); 
    699761 *    return retval; 
    700762 * } 
    …… 
    707769 *     tny_account_set_pass_func (account, per_account_get_pass_func); 
    708770 *     tny_list_prepend (list, (GObject*)account); 
    709  *     g_object_unref (G_OBJECT (account)); 
     771 *     g_object_unref (account); 
    710772 *     ... 
    711773 * } 
    712774 * </programlisting></informalexample> 
     775 * 
     776 * since: 1.0 
     777 * audience: platform-developer 
    713778 **/ 
    714779void 
    …… 
    731796/** 
    732797 * tny_account_get_proto: 
    733  * @self: a #TnyAccount object 
     798 * @self: a #TnyAccount 
    734799 *  
    735800 * Get the protocol of @self. The returned value should not be freed. 
    736801 *  
    737  * Return value: the protocol as a read-only string 
    738  * 
     802 * returns: the protocol as a read-only string 
     803 * since: 1.0 
     804 * audience: application-developer 
    739805 **/ 
    740806const gchar* 
    …… 
    760826/** 
    761827 * tny_account_get_url_string: 
    762  * @self: a #TnyAccount object 
    763  *  
    764  * Get the url string of @self or NULL if it's impossible to determine the url 
    765  * string of @self. If not NULL, the returned value must be freed. 
     828 * @self: a #TnyAccount 
     829 *  
     830 * Get the url-string of account @self or NULL if it's impossible to determine 
     831 * the url-string of @self. If not NULL, the returned value must be freed. 
    766832 *  
    767833 * The url string is specified in RFC 1808 and looks for example like this: 
    768834 * imap://user@hostname. Note that it doesn't necessarily contain the password  
    769  * of the IMAP account. 
    770  * 
    771  * Return value: the url string or NULL. 
     835 * of the account. 
     836 * 
     837 * returns (null-ok) (caller-owns): the url-string or NULL. 
     838 * since: 1.0 
     839 * audience: application-developer 
    772840 **/ 
    773841gchar* 
    …… 
    785853#ifdef DBC /* ensure */ 
    786854        if (retval) 
    787                 g_assert (strstr (retval, "://") != NULL); 
     855                g_assert (strstr (retval, ":") != NULL); 
    788856#endif 
    789857 
    …… 
    794862/** 
    795863 * tny_account_get_user: 
    796  * @self: a #TnyAccount object 
    797  *  
    798  * Get the user or login of @self. The returned value should not be freed. The 
    799  * returned value van be NULL in case of no user. 
    800  *  
    801  * Return value: the user as a read-only string 
    802  * 
     864 * @self: a #TnyAccount 
     865 *  
     866 * Get the user or login of account @self. The returned value should 
     867 * not be freed. The returned value can be NULL. 
     868 *  
     869 * returns: the user as a read-only string 
     870 * since: 1.0 
     871 * audience: application-developer 
    803872 **/ 
    804873const gchar* 
    …… 
    822891/** 
    823892 * tny_account_get_name: 
    824  * @self: a #TnyAccount object 
    825  *  
    826  * Get the human readable name of @self. The returned value should not  
    827  * be freed. The returned value van be NULL in case of no human reabable name. 
    828  *  
    829  * Return value: the human readable name as a read-only string 
    830  * 
     893 * @self: a #TnyAccount 
     894 *  
     895 * Get the human readable name of account@self. The returned value should not  
     896 * be freed. The returned value can be NULL. 
     897 *  
     898 * returns: the human readable name as a read-only string 
     899 * since: 1.0 
     900 * audience: application-developer 
    831901 **/ 
    832902const gchar* 
    …… 
    851921/** 
    852922 * tny_account_get_secure_auth_mech: 
    853  * @self: a #TnyAccount object 
    854  *  
    855  * Get the secure authentication mechanism for this account. Default is "PLAIN". The 
    856  * returned value can be NULL, in which case a undefined default is used. 
    857  *  
    858  * Return value: the authentication mechanism as a read-only string 
    859  * 
     923 * @self: a #TnyAccount 
     924 *  
     925 * Get the secure authentication mechanism for this account. Default is "PLAIN". 
     926 * The returned value can be NULL, in which case a undefined default is used. 
     927 * The returned value should not be freed. 
     928 *  
     929 * returns: the authentication mechanism as a read-only string 
     930 * since: 1.0 
     931 * audience: application-developer 
    860932 **/ 
    861933const gchar* 
    …… 
    886958 * for a local account). 
    887959 *  
    888  * Return value: the hostname as a read-only string 
    889  * 
     960 * returns: the hostname as a read-only string 
     961 * since: 1.0 
     962 * audience: application-developer 
    890963 **/ 
    891964const gchar* 
    …… 
    910983/** 
    911984 * tny_account_get_port: 
    912  * @self: a #TnyAccount object 
     985 * @self: a #TnyAccount 
    913986 *  
    914987 * Get the port of @self.  
    915988 *  
    916  * Return value: the port 
     989 * returns: the port 
     990 * since: 1.0 
     991 * audience: application-developer 
    917992 **/ 
    918993guint 
    …… 
    9351010/** 
    9361011 * tny_account_get_pass_func: 
    937  * @self: a #TnyAccount object 
     1012 * @self: a #TnyAccount 
    9381013 *  
    9391014 * Get a pointer to the get-password function 
    9401015 * 
    941  * Return value: A pointer to the get-password function 
     1016 * returns: A pointer to the get-password function 
     1017 * since: 1.0 
     1018 * audience: application-developer 
    9421019 **/ 
    9431020TnyGetPassFunc 
    …… 
    9751052 * 
    9761053 * Emitted when the connection status of an account changes. 
     1054 * 
     1055 * since: 1.0 
     1056 * audience: application-developer 
    9771057 **/ 
    9781058                tny_account_signals[TNY_ACCOUNT_CONNECTION_STATUS_CHANGED] = 
    …… 
    9921072 * @user_data: user data set when the signal handler was connected. 
    9931073 * 
    994  * Emitted when the account changes. 
     1074 * Emitted when one of the account's properties changes. 
     1075 * 
     1076 * since: 1.0 
     1077 * audience: application-developer 
    9951078 **/ 
    9961079                tny_account_signals[TNY_ACCOUNT_CHANGED] = 
    …… 
    10121095 * GType system helper function 
    10131096 * 
    1014  * Return value: a GType 
     1097 * returns: a #GType 
    10151098 **/ 
    10161099GType 
    …… 
    10481131 * GType system helper function 
    10491132 * 
    1050  * Return value: a GType 
     1133 * returns: a #GType 
    10511134 **/ 
    10521135GType 
    …… 
    10721155 * GType system helper function 
    10731156 * 
    1074  * Return value: a GType 
     1157 * returns: a #GType 
    10751158 **/ 
    10761159GType 
    …… 
    10951178 * GType system helper function 
    10961179 * 
    1097  * Return value: a GType 
     1180 * returns: a #GType 
    10981181 **/ 
    10991182GType 

  • trunk/libtinymail/tny-account.h

    r3125 r3150  
    108108        gboolean (*matches_url_string_func) (TnyAccount *self, const gchar *url_string); 
    109109        void (*start_operation_func) (TnyAccount *self, TnyStatusDomain domain, TnyStatusCode code, TnyStatusCallback status_callback, gpointer status_user_data); 
    110         void (*stop_operation_func) (TnyAccount *self, gboolean *canceled); 
     110        void (*stop_operation_func) (TnyAccount *self, gboolean *cancelled); 
    111111        gboolean (*is_ready_func) (TnyAccount *self); 
    112112        TnyConnectionPolicy* (*get_connection_policy_func) (TnyAccount *self); 
    …… 
    148148gboolean tny_account_matches_url_string (TnyAccount *self, const gchar *url_string); 
    149149void tny_account_start_operation (TnyAccount *self, TnyStatusDomain domain, TnyStatusCode code, TnyStatusCallback status_callback, gpointer status_user_data); 
    150 void tny_account_stop_operation (TnyAccount *self, gboolean *canceled); 
     150void tny_account_stop_operation (TnyAccount *self, gboolean *cancelled); 
    151151gboolean tny_account_is_ready (TnyAccount *self); 
    152152TnyConnectionPolicy* tny_account_get_connection_policy (TnyAccount *self); 

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

    r3141 r3150  
    1818 */ 
    1919 
     20/** 
     21 * TnyCombinedAccount: 
     22 *  
     23 * A combined account 
     24 * 
     25 * free-function: g_object_unref 
     26 */ 
     27 
    2028#include <config.h> 
    2129#include <glib.h> 
    …… 
    370378/** 
    371379 * tny_combined_account_new: 
    372  * @ta: A #TnyTransportAccount instance 
    373  * @sa: a #TnyStoreAccount instance 
     380 * @ta: A #TnyTransportAccount 
     381 * @sa: a #TnyStoreAccount 
    374382 *  
    375383 * Create a decorator for @ta, in case the tny_transport_account_send is used, 
    376  * and for @sa in case any other method of either TnyFolderStore, TnyAccount 
    377  * or TnyStoreAccount is used. 
     384 * and for @sa in case a method of either #TnyFolderStore, #TnyAccount or  
     385 * #TnyStoreAccount is used. 
    378386 * 
    379387 * Note though that you must not use instances created by this constructor for 
    380388 * either setting or getting members of the #TnyAccount type. You must get the 
    381  * actual instances to read this from using either  
    382  * tny_combined_account_get_transport_account or tny_combined_account_get_store_account. 
    383  * 
    384  * Return value: A new account instance that decorates both @ta and @sa 
     389 * actual instances to read these properties. 
     390 * 
     391 * returns (caller-owns): A new account instance that decorates both @ta and @sa 
     392 * 
     393 * since: 1.0 
     394 * complexity: high 
     395 * audience: application-developer 
    385396 **/ 
    386397TnyAccount * 
    …… 
    402413/** 
    403414 * tny_combined_account_get_transport_account: 
    404  * @self: a #TnyCombinedAccount instance 
     415 * @self: a #TnyCombinedAccount 
    405416 *  
    406417 * Get the transport account that is being decorated by @self. You must unreference 
    407418 * the returned value if not needed anymore. 
    408419 * 
    409  * Return value: the transport account being decorated 
     420 * returns (caller-owns): the transport account in @self 
     421 * since: 1.0 
     422 * complexity: low 
     423 * audience: application-developer 
    410424 **/ 
    411425TnyTransportAccount*  
    …… 
    419433/** 
    420434 * tny_combined_account_get_store_account: 
    421  * @self: a #TnyCombinedAccount instance 
     435 * @self: a #TnyCombinedAccount 
    422436 *  
    423437 * Get the store account that is being decorated by @self. You must unreference 
    424438 * the returned value if not needed anymore. 
    425439 * 
    426  * Return value: the store account being decorated 
     440 * returns (caller-owns): the store account in @self 
     441 * since: 1.0 
     442 * complexity: low 
     443 * audience: application-developer 
    427444 **/ 
    428445TnyStoreAccount*  

  • trunk/libtinymail/tny-connection-policy.c

    r3125