2005-05-07 Sankar P <psankar@novell.com>
- * camel-provider.h
- Added a new flag CAMEL_PROVIDER_DISABLE_SENT_FOLDER so as to facilitate
- disabling sent button and prevent copying sent items.
- This flag is introduced for the GroupWise provider, but can be made use
- of by any other type of provider, if needed.
+ * camel-provider.h: Added a new flag
+ CAMEL_PROVIDER_DISABLE_SENT_FOLDER so as to facilitate disabling
+ sent button and prevent copying sent items. This flag is
+ introduced for the GroupWise provider, but can be made use of by
+ any other type of provider, if needed.
2005-04-26 Ross Burton <ross@burtonini.com>
*
* Create a new #CamelAddress object.
*
- * Returns a new CamelAddress widget.
+ * Returns a new #CamelAddress object
**/
CamelAddress *
camel_address_new (void)
return new;
}
+
/**
* camel_address_new_clone:
- * @in:
+ * @addr: a #CamelAddress object
*
* Clone an existing address type.
*
- * Return value:
+ * Returns the cloned address
**/
CamelAddress *
-camel_address_new_clone(const CamelAddress *in)
+camel_address_new_clone (const CamelAddress *addr)
{
- CamelAddress *new = CAMEL_ADDRESS(camel_object_new(CAMEL_OBJECT_GET_TYPE(in)));
+ CamelAddress *new = CAMEL_ADDRESS(camel_object_new(CAMEL_OBJECT_GET_TYPE(addr)));
- camel_address_cat(new, in);
+ camel_address_cat(new, addr);
return new;
}
+
/**
* camel_address_length:
- * @a:
+ * @addr: a #CamelAddress object
*
- * Return the number of addresses stored in the address @a.
+ * Get the number of addresses stored in the address @addr.
*
- * Return value:
+ * Returns the number of addresses contained in @addr
**/
int
-camel_address_length(CamelAddress *a)
+camel_address_length (CamelAddress *addr)
{
- return a->addresses->len;
+ return addr->addresses->len;
}
+
/**
* camel_address_decode:
- * @a: An address.
- * @raw: Raw address description.
- *
+ * @addr: a #CamelAddress object
+ * @raw: raw address description
+ *
* Construct a new address from a raw address field.
- *
- * Return value: Returns the number of addresses found,
- * or -1 if the addresses could not be parsed fully.
+ *
+ * Returns the number of addresses parsed or %-1 on fail
**/
int
-camel_address_decode (CamelAddress *a, const char *raw)
+camel_address_decode (CamelAddress *addr, const char *raw)
{
- g_return_val_if_fail(CAMEL_IS_ADDRESS(a), -1);
+ g_return_val_if_fail(CAMEL_IS_ADDRESS(addr), -1);
- return CAMEL_ADDRESS_CLASS (CAMEL_OBJECT_GET_CLASS (a))->decode(a, raw);
+ return CAMEL_ADDRESS_CLASS (CAMEL_OBJECT_GET_CLASS (addr))->decode(addr, raw);
}
+
/**
* camel_address_encode:
- * @a:
+ * @addr: a #CamelAddress object
*
* Encode an address in a format suitable for a raw header.
*
- * Return value: The encoded address.
+ * Returns the encoded address
**/
char *
-camel_address_encode (CamelAddress *a)
+camel_address_encode (CamelAddress *addr)
{
- g_return_val_if_fail(CAMEL_IS_ADDRESS(a), NULL);
+ g_return_val_if_fail(CAMEL_IS_ADDRESS(addr), NULL);
- return CAMEL_ADDRESS_CLASS (CAMEL_OBJECT_GET_CLASS (a))->encode(a);
+ return CAMEL_ADDRESS_CLASS (CAMEL_OBJECT_GET_CLASS (addr))->encode(addr);
}
+
/**
* camel_address_unformat:
- * @a:
- * @raw:
+ * @addr: a #CamelAddress object
+ * @raw: raw address description
*
* Attempt to convert a previously formatted and/or edited
* address back into internal form.
*
- * Return value: -1 if it could not be parsed, or the number
- * of valid addresses found.
+ * Returns the number of addresses parsed or %-1 on fail
**/
int
-camel_address_unformat(CamelAddress *a, const char *raw)
+camel_address_unformat(CamelAddress *addr, const char *raw)
{
- g_return_val_if_fail(CAMEL_IS_ADDRESS(a), -1);
+ g_return_val_if_fail(CAMEL_IS_ADDRESS(addr), -1);
- return CAMEL_ADDRESS_CLASS (CAMEL_OBJECT_GET_CLASS (a))->unformat(a, raw);
+ return CAMEL_ADDRESS_CLASS (CAMEL_OBJECT_GET_CLASS (addr))->unformat(addr, raw);
}
+
/**
* camel_address_format:
- * @a:
+ * @addr: a #CamelAddress object
*
* Format an address in a format suitable for display.
*
- * Return value: The formatted address.
+ * Returns a newly allocated string containing the formatted addresses
**/
char *
-camel_address_format (CamelAddress *a)
+camel_address_format (CamelAddress *addr)
{
- if (a == NULL)
- return NULL;
-
- g_return_val_if_fail(CAMEL_IS_ADDRESS(a), NULL);
+ g_return_val_if_fail(CAMEL_IS_ADDRESS(addr), NULL);
- return CAMEL_ADDRESS_CLASS (CAMEL_OBJECT_GET_CLASS (a))->format(a);
+ return CAMEL_ADDRESS_CLASS (CAMEL_OBJECT_GET_CLASS (addr))->format(addr);
}
+
/**
* camel_address_cat:
- * @dest:
- * @source:
+ * @dest: destination #CamelAddress object
+ * @source: source #CamelAddress object
*
- * Concatenate one address onto another. The addresses must
+ * Concatenate one address onto another. The addresses must
* be of the same type.
*
- * Return value:
+ * Returns the number of addresses concatenated
**/
int
-camel_address_cat (CamelAddress *dest, const CamelAddress *source)
+camel_address_cat (CamelAddress *dest, const CamelAddress *source)
{
g_return_val_if_fail(CAMEL_IS_ADDRESS(dest), -1);
g_return_val_if_fail(CAMEL_IS_ADDRESS(source), -1);
return CAMEL_ADDRESS_CLASS(CAMEL_OBJECT_GET_CLASS(dest))->cat(dest, source);
}
+
/**
* camel_address_copy:
- * @dest:
- * @source:
+ * @dest: destination #CamelAddress object
+ * @source: source #CamelAddress object
*
- * Copy an address contents.
+ * Copy the contents of one address into another.
*
- * Return value:
+ * Returns the number of addresses copied
**/
int
-camel_address_copy (CamelAddress *dest, const CamelAddress *source)
+camel_address_copy (CamelAddress *dest, const CamelAddress *source)
{
g_return_val_if_fail(CAMEL_IS_ADDRESS(dest), -1);
g_return_val_if_fail(CAMEL_IS_ADDRESS(source), -1);
return camel_address_cat(dest, source);
}
+
/**
* camel_address_remove:
- * @a:
- * @index: The address to remove, use -1 to remove all address.
+ * @addr: a #CamelAddress object
+ * @index: The address to remove, use %-1 to remove all address.
*
* Remove an address by index, or all addresses.
**/
void
-camel_address_remove (CamelAddress *a, int index)
+camel_address_remove (CamelAddress *addr, int index)
{
- g_return_if_fail(CAMEL_IS_ADDRESS(a));
+ g_return_if_fail(CAMEL_IS_ADDRESS(addr));
if (index == -1) {
- for (index=a->addresses->len; index>-1; index--)
- CAMEL_ADDRESS_CLASS (CAMEL_OBJECT_GET_CLASS (a))->remove(a, index);
+ for (index = addr->addresses->len; index>-1; index--)
+ CAMEL_ADDRESS_CLASS (CAMEL_OBJECT_GET_CLASS (addr))->remove(addr, index);
} else {
- CAMEL_ADDRESS_CLASS (CAMEL_OBJECT_GET_CLASS (a))->remove(a, index);
+ CAMEL_ADDRESS_CLASS (CAMEL_OBJECT_GET_CLASS (addr))->remove(addr, index);
}
}
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
/*
* Copyright (C) 2000 Ximian Inc.
*
CamelType camel_address_get_type (void);
CamelAddress *camel_address_new (void);
-CamelAddress *camel_address_new_clone (const CamelAddress *);
-int camel_address_length (CamelAddress *);
+CamelAddress *camel_address_new_clone (const CamelAddress *addr);
+int camel_address_length (CamelAddress *addr);
-int camel_address_decode (CamelAddress *, const char *);
-char *camel_address_encode (CamelAddress *);
-int camel_address_unformat (CamelAddress *, const char *);
-char *camel_address_format (CamelAddress *);
+int camel_address_decode (CamelAddress *addr, const char *raw);
+char *camel_address_encode (CamelAddress *addr);
+int camel_address_unformat (CamelAddress *addr, const char *raw);
+char *camel_address_format (CamelAddress *addr);
-int camel_address_cat (CamelAddress *, const CamelAddress *);
-int camel_address_copy (CamelAddress *, const CamelAddress *);
+int camel_address_cat (CamelAddress *dest, const CamelAddress *source);
+int camel_address_copy (CamelAddress *dest, const CamelAddress *source);
-void camel_address_remove (CamelAddress *, int index);
+void camel_address_remove (CamelAddress *addr, int index);
#ifdef __cplusplus
}
g_ptr_array_remove_index(a->addresses, index);
}
+
/**
* camel_internet_address_new:
*
- * Create a new CamelInternetAddress object.
+ * Create a new #CamelInternetAddress object.
*
- * Return value: A new CamelInternetAddress object.
+ * Returns a new #CamelInternetAddress object
**/
CamelInternetAddress *
camel_internet_address_new (void)
return new;
}
+
/**
* camel_internet_address_add:
- * @a: internet address object
- * @name:
- * @address:
+ * @addr: a #CamelInternetAddress object
+ * @name: name associated with the new address
+ * @address: routing address associated with the new address
*
- * Add a new internet address to the address object.
+ * Add a new internet address to @addr.
*
- * Return value: Index of added entry.
+ * Returns the index of added entry
**/
int
-camel_internet_address_add (CamelInternetAddress *a, const char *name, const char *address)
+camel_internet_address_add (CamelInternetAddress *addr, const char *name, const char *address)
{
struct _address *new;
int index;
- g_assert(CAMEL_IS_INTERNET_ADDRESS(a));
+ g_assert(CAMEL_IS_INTERNET_ADDRESS(addr));
new = g_malloc(sizeof(*new));
new->name = g_strdup(name);
new->address = g_strdup(address);
- index = ((CamelAddress *)a)->addresses->len;
- g_ptr_array_add(((CamelAddress *)a)->addresses, new);
+ index = ((CamelAddress *)addr)->addresses->len;
+ g_ptr_array_add(((CamelAddress *)addr)->addresses, new);
return index;
}
+
/**
* camel_internet_address_get:
- * @a: internet address object
+ * @addr: a #CamelInternetAddress object
* @index: address's array index
- * @namep: Holder for the returned name, or NULL, if not required.
- * @addressp: Holder for the returned address, or NULL, if not required.
+ * @namep: holder for the returned name, or %NULL, if not required.
+ * @addressp: holder for the returned address, or %NULL, if not required.
*
* Get the address at @index.
*
- * Return value: TRUE if such an address exists, or FALSE otherwise.
+ * Returns %TRUE if such an address exists, or %FALSE otherwise
**/
gboolean
-camel_internet_address_get (const CamelInternetAddress *a, int index, const char **namep, const char **addressp)
+camel_internet_address_get (const CamelInternetAddress *addr, int index, const char **namep, const char **addressp)
{
- struct _address *addr;
+ struct _address *a;
- g_assert(CAMEL_IS_INTERNET_ADDRESS(a));
+ g_assert(CAMEL_IS_INTERNET_ADDRESS(addr));
- if (index < 0 || index >= ((CamelAddress *)a)->addresses->len)
+ if (index < 0 || index >= ((CamelAddress *)addr)->addresses->len)
return FALSE;
- addr = g_ptr_array_index( ((CamelAddress *)a)->addresses, index);
+ a = g_ptr_array_index (((CamelAddress *)addr)->addresses, index);
if (namep)
- *namep = addr->name;
+ *namep = a->name;
if (addressp)
- *addressp = addr->address;
+ *addressp = a->address;
return TRUE;
}
+
/**
* camel_internet_address_find_name:
- * @a:
- * @name:
- * @addressp: Holder for address part, or NULL, if not required.
+ * @addr: a #CamelInternetAddress object
+ * @name: name to lookup
+ * @addressp: holder for address part, or %NULL, if not required.
*
* Find address by real name.
*
- * Return value: The index of the address matching the name, or -1
- * if no match was found.
+ * Returns the index of the address matching the name, or %-1 if no
+ * match was found
**/
int
-camel_internet_address_find_name(CamelInternetAddress *a, const char *name, const char **addressp)
+camel_internet_address_find_name(CamelInternetAddress *addr, const char *name, const char **addressp)
{
- struct _address *addr;
+ struct _address *a;
int i, len;
- g_assert(CAMEL_IS_INTERNET_ADDRESS(a));
+ g_assert(CAMEL_IS_INTERNET_ADDRESS(addr));
- len = ((CamelAddress *)a)->addresses->len;
+ len = ((CamelAddress *)addr)->addresses->len;
for (i=0;i<len;i++) {
- addr = g_ptr_array_index( ((CamelAddress *)a)->addresses, i );
- if (!strcmp(addr->name, name)) {
+ a = g_ptr_array_index (((CamelAddress *)addr)->addresses, i);
+ if (a->name && !strcmp(a->name, name)) {
if (addressp)
- *addressp = addr->address;
+ *addressp = a->address;
return i;
}
}
return -1;
}
+
/**
* camel_internet_address_find_address:
- * @a:
- * @address:
- * @namep: Return for the matching name, or NULL, if not required.
+ * @addr: a #CamelInternetAddress object
+ * @address: address to lookup
+ * @namep: holder for the matching name, or %NULL, if not required.
*
* Find an address by address.
*
- * Return value: The index of the address, or -1 if not found.
+ * Returns the index of the address, or %-1 if not found
**/
int
-camel_internet_address_find_address(CamelInternetAddress *a, const char *address, const char **namep)
+camel_internet_address_find_address(CamelInternetAddress *addr, const char *address, const char **namep)
{
- struct _address *addr;
+ struct _address *a;
int i, len;
- g_assert(CAMEL_IS_INTERNET_ADDRESS(a));
+ g_assert(CAMEL_IS_INTERNET_ADDRESS(addr));
- len = ((CamelAddress *)a)->addresses->len;
+ len = ((CamelAddress *)addr)->addresses->len;
for (i=0;i<len;i++) {
- addr = g_ptr_array_index( ((CamelAddress *)a)->addresses, i );
- if (!strcmp(addr->address, address)) {
+ a = g_ptr_array_index (((CamelAddress *)addr)->addresses, i);
+ if (!strcmp(a->address, address)) {
if (namep)
- *namep = addr->name;
+ *namep = a->name;
return i;
}
}
g_string_append(out, addr);
}
+
/**
* camel_internet_address_encode_address:
- * @len: The encoded length so far, of this line
- * @name:
- * @addr:
+ * @len: the length of the line the address is being appended to
+ * @name: the unencoded real name associated with the address
+ * @addr: the routing address
*
* Encode a single address ready for internet usage. Header folding
- * as per rfc 822 is also performed, based on the length *@inlen. If @inlen
- * is NULL, then no folding will occur.
+ * as per rfc822 is also performed, based on the length *@len. If @len
+ * is %NULL, then no folding will occur.
+ *
+ * Note: The value at *@in will be updated based on any linewrapping done
*
- * Return value: The encoded address.
+ * Returns the encoded address
**/
char *
camel_internet_address_encode_address(int *inlen, const char *real, const char *addr)
return ret;
}
+
/**
* camel_internet_address_format_address:
- * @name: A name, quotes may be stripped from it.
- * @addr: Assumes a valid rfc822 email address.
+ * @name: a name, quotes may be stripped from it
+ * @addr: an rfc822 routing address
*
* Function to format a single address, suitable for display.
*
- * Return value:
+ * Returns a nicely formatted string containing the rfc822 address
**/
char *
camel_internet_address_format_address(const char *name, const char *addr)
CamelType camel_internet_address_get_type (void);
CamelInternetAddress *camel_internet_address_new (void);
-int camel_internet_address_add (CamelInternetAddress *, const char *, const char *);
-gboolean camel_internet_address_get (const CamelInternetAddress *, int, const char **, const char **);
+int camel_internet_address_add (CamelInternetAddress *addr, const char *name, const char *address);
+gboolean camel_internet_address_get (const CamelInternetAddress *addr, int index, const char **namep, const char **addressp);
-int camel_internet_address_find_name(CamelInternetAddress *, const char *, const char **);
-int camel_internet_address_find_address(CamelInternetAddress *, const char *, const char **);
+int camel_internet_address_find_name(CamelInternetAddress *addr, const char *name, const char **addressp);
+int camel_internet_address_find_address(CamelInternetAddress *addr, const char *address, const char **namep);
/* utility functions, for network/display formatting */
char * camel_internet_address_encode_address(int *len, const char *name, const char *addr);
/**
* camel_service_construct:
- * @service: the CamelService
- * @session: the session for the service
- * @provider: the service's provider
- * @url: the default URL for the service (may be NULL)
- * @ex: a CamelException
+ * @service: a #CamelService object
+ * @session: the #CamelSession for @service
+ * @provider: the #CamelProvider associated with @service
+ * @url: the default URL for the service (may be %NULL)
+ * @ex: a #CamelException
*
- * Constructs a CamelService initialized with the given parameters.
+ * Constructs a #CamelService initialized with the given parameters.
**/
void
camel_service_construct (CamelService *service, CamelSession *session,
return TRUE;
}
+
/**
* camel_service_connect:
- * @service: CamelService object
- * @ex: a CamelException
+ * @service: a #CamelService object
+ * @ex: a #CamelException
*
* Connect to the service using the parameters it was initialized
* with.
*
- * Return value: whether or not the connection succeeded
+ * Returns %TRUE if the connection is made or %FALSE otherwise
**/
-
gboolean
camel_service_connect (CamelService *service, CamelException *ex)
{
return TRUE;
}
+
/**
* camel_service_disconnect:
- * @service: CamelService object
- * @clean: whether or not to try to disconnect cleanly.
- * @ex: a CamelException
+ * @service: a #CamelService object
+ * @clean: whether or not to try to disconnect cleanly
+ * @ex: a #CamelException
*
* Disconnect from the service. If @clean is %FALSE, it should not
* try to do any synchronizing or other cleanup of the connection.
*
- * Return value: whether or not the disconnection succeeded without
- * errors. (Consult @ex if %FALSE.)
+ * Returns %TRUE if the disconnect was successful or %FALSE otherwise
**/
gboolean
camel_service_disconnect (CamelService *service, gboolean clean,
/**
* camel_service_cancel_connect:
- * @service: a service
+ * @service: a #CamelService object
*
* If @service is currently attempting to connect to or disconnect
* from a server, this causes it to stop and fail. Otherwise it is a
/**
* camel_service_get_url:
- * @service: a service
+ * @service: a #CamelService object
*
- * Returns the URL representing a service. The returned URL must be
+ * Gets the URL representing @service. The returned URL must be
* freed when it is no longer needed. For security reasons, this
* routine does not return the password.
*
- * Return value: the url name
+ * Returns the URL representing @service
**/
char *
camel_service_get_url (CamelService *service)
return g_strdup ("???");
}
+
/**
* camel_service_get_name:
- * @service: the service
+ * @service: a #CamelService object
* @brief: whether or not to use a briefer form
*
* This gets the name of the service in a "friendly" (suitable for
* such as for use in the folder tree. If @brief is %FALSE, it should
* be a more complete and mostly unambiguous description.
*
- * Return value: the description, which the caller must free.
+ * Returns a description of the service which the caller must free
**/
char *
camel_service_get_name (CamelService *service, gboolean brief)
return path;
}
+
/**
* camel_service_get_path:
- * @service: the service
+ * @service: a #CamelService object
*
- * This gets a valid UNIX relative path describing the service, which
+ * This gets a valid UNIX relative path describing @service, which
* is guaranteed to be different from the path returned for any
* different service. This path MUST start with the name of the
* provider, followed by a "/", but after that, it is up to the
* provider.
*
- * Return value: the path, which the caller must free.
+ * Returns the path, which the caller must free
**/
char *
camel_service_get_path (CamelService *service)
/**
* camel_service_get_session:
- * @service: a service
+ * @service: a #CamelService object
*
- * Returns the CamelSession associated with the service.
+ * Gets the #CamelSession associated with the service.
*
- * Return value: the session
+ * Returns the session
**/
CamelSession *
camel_service_get_session (CamelService *service)
return service->session;
}
+
/**
* camel_service_get_provider:
- * @service: a service
+ * @service: a #CamelService object
*
- * Returns the CamelProvider associated with the service.
+ * Gets the #CamelProvider associated with the service.
*
- * Return value: the provider
+ * Returns the provider
**/
CamelProvider *
camel_service_get_provider (CamelService *service)
return NULL;
}
+
/**
* camel_service_query_auth_types:
- * @service: a CamelService
- * @ex: a CamelException
+ * @service: a #CamelService object
+ * @ex: a #CamelException
*
* This is used by the mail source wizard to get the list of
* authentication types supported by the protocol, and information
* about them.
*
- * Return value: a list of CamelServiceAuthType records. The caller
- * must free the list with g_list_free() when it is done with it.
+ * Returns a list of #CamelServiceAuthType records. The caller
+ * must free the list with #g_list_free when it is done with it.
**/
GList *
camel_service_query_auth_types (CamelService *service, CamelException *ex)
}
/**
- * camel_store_get_folder: Return the folder corresponding to a path.
- * @store: a CamelStore
+ * camel_store_get_folder:
+ * @store: a #CamelStore object
* @folder_name: name of the folder to get
* @flags: folder flags (create, save body index, etc)
- * @ex: a CamelException
+ * @ex: a #CamelException
+ *
+ * Get a specific folder object from the store by name.
*
- * Return value: the folder corresponding to the path @folder_name.
+ * Returns the folder corresponding to the path @folder_name.
**/
CamelFolder *
camel_store_get_folder (CamelStore *store, const char *folder_name, guint32 flags, CamelException *ex)
/**
* camel_store_create_folder:
- * @store: a CamelStore
+ * @store: a #CamelStore object
* @parent_name: name of the new folder's parent, or %NULL
* @folder_name: name of the folder to create
- * @ex: a CamelException
+ * @ex: a #CamelException
*
* Creates a new folder as a child of an existing folder.
* @parent_name can be %NULL to create a new top-level folder.
*
- * Return value: info about the created folder, which the caller must
- * free with camel_store_free_folder_info().
+ * Returns info about the created folder, which the caller must
+ * free with #camel_store_free_folder_info
**/
CamelFolderInfo *
camel_store_create_folder (CamelStore *store, const char *parent_name,
}
/**
- * camel_store_delete_folder: Delete the folder corresponding to a path.
- * @store: a CamelStore
+ * camel_store_delete_folder:
+ * @store: a #CamelStore object
* @folder_name: name of the folder to delete
- * @ex: a CamelException
+ * @ex: a #CamelException
*
* Deletes the named folder. The folder must be empty.
**/
/**
* camel_store_rename_folder:
- * @store: a CamelStore
- * @old_name: the current name of the folder
+ * @store: a #CamelStore object
+ * @old_namein: the current name of the folder
* @new_name: the new name of the folder
- * @ex: a CamelException
+ * @ex: a #CamelException
*
* Rename a named folder to a new name.
**/
/**
* camel_store_get_inbox:
- * @store: a CamelStore
- * @ex: a CamelException
+ * @store: a #CamelStore object
+ * @ex: a #CamelException
*
- * Return value: the folder in the store into which new mail is
- * delivered, or %NULL if no such folder exists.
+ * Returns the folder in the store into which new mail is delivered,
+ * or %NULL if no such folder exists.
**/
CamelFolder *
camel_store_get_inbox (CamelStore *store, CamelException *ex)
/**
* camel_store_get_trash:
- * @store: a CamelStore
- * @ex: a CamelException
+ * @store: a #CamelStore object
+ * @ex: a #CamelException
*
- * Return value: the folder in the store into which trash is
- * delivered, or %NULL if no such folder exists.
+ * Returns the folder in the store into which trash is delivered, or
+ * %NULL if no such folder exists.
**/
CamelFolder *
camel_store_get_trash (CamelStore *store, CamelException *ex)
/**
* camel_store_get_junk:
- * @store: a CamelStore
- * @ex: a CamelException
+ * @store: a #CamelStore object
+ * @ex: a #CamelException
*
- * Return value: the folder in the store into which junk is
- * delivered, or %NULL if no such folder exists.
+ * Returns the folder in the store into which junk is delivered, or
+ * %NULL if no such folder exists.
**/
CamelFolder *
camel_store_get_junk (CamelStore *store, CamelException *ex)
/**
* camel_store_sync:
- * @store: a CamelStore
- * @expunge: do we expunge deleted messages too?
- * @ex: a CamelException
+ * @store: a #CamelStore object
+ * @expunge: %TRUE if an expunge should be done after sync or %FALSE otherwise
+ * @ex: a #CamelException
*
* Syncs any changes that have been made to the store object and its
* folders with the real store.
/**
* camel_store_get_folder_info:
- * @store: a CamelStore
+ * @store: a #CamelStore object
* @top: the name of the folder to start from
* @flags: various CAMEL_STORE_FOLDER_INFO_* flags to control behavior
- * @ex: a CamelException
+ * @ex: a #CamelException
*
* This fetches information about the folder structure of @store,
* starting with @top, and returns a tree of CamelFolderInfo
- * structures. If @flags includes %CAMEL_STORE_FOLDER_INFO_SUBSCRIBED,
+ * structures. If @flags includes #CAMEL_STORE_FOLDER_INFO_SUBSCRIBED,
* only subscribed folders will be listed. (This flag can only be used
* for stores that support subscriptions.) If @flags includes
- * %CAMEL_STORE_FOLDER_INFO_RECURSIVE, the returned tree will include
+ * #CAMEL_STORE_FOLDER_INFO_RECURSIVE, the returned tree will include
* all levels of hierarchy below @top. If not, it will only include
* the immediate subfolders of @top. If @flags includes
- * %CAMEL_STORE_FOLDER_INFO_FAST, the unread_message_count fields of
- * some or all of the structures may be set to -1, if the store cannot
+ * #CAMEL_STORE_FOLDER_INFO_FAST, the unread_message_count fields of
+ * some or all of the structures may be set to %-1, if the store cannot
* determine that information quickly. If @flags includes
- * %CAMEL_STORE_FOLDER_INFO_NO_VIRTUAL, don't include special virtual
+ * #CAMEL_STORE_FOLDER_INFO_NO_VIRTUAL, don't include special virtual
* folders (such as vTrash or vJunk).
*
- * Return value: a CamelFolderInfo tree, which must be freed with
- * camel_store_free_folder_info.
+ * Returns a #CamelFolderInfo tree, which must be freed with
+ * #camel_store_free_folder_info
**/
CamelFolderInfo *
camel_store_get_folder_info(CamelStore *store, const char *top, guint32 flags, CamelException *ex)
/**
* camel_store_free_folder_info:
- * @store: a CamelStore
- * @tree: the tree returned by camel_store_get_folder_info()
+ * @store: a #CamelStore object
+ * @fi: a #CamelFolderInfo as gotten via #camel_store_get_folder_info
*
- * Frees the data returned by camel_store_get_folder_info().
+ * Frees the data returned by #camel_store_get_folder_info
**/
void
camel_store_free_folder_info (CamelStore *store, CamelFolderInfo *fi)
/**
* camel_store_free_folder_info_full:
- * @store: a CamelStore
- * @tree: the tree returned by camel_store_get_folder_info()
+ * @store: a #CamelStore object
+ * @fi: a #CamelFolderInfo as gotten via #camel_store_get_folder_info
*
- * An implementation for CamelStore::free_folder_info. Frees all
+ * An implementation for #CamelStore::free_folder_info. Frees all
* of the data.
**/
void
/**
* camel_store_free_folder_info_nop:
- * @store: a CamelStore
- * @tree: the tree returned by camel_store_get_folder_info()
+ * @store: a #CamelStore object
+ * @fi: a #CamelFolderInfo as gotten via #camel_store_get_folder_info
*
- * An implementation for CamelStore::free_folder_info. Does nothing.
+ * An implementation for #CamelStore::free_folder_info. Does nothing.
**/
void
camel_store_free_folder_info_nop (CamelStore *store, CamelFolderInfo *fi)
/**
* camel_folder_info_free:
- * @fi: the CamelFolderInfo
+ * @fi: a #CamelFolderInfo
*
* Frees @fi.
**/
/**
* camel_folder_info_build:
- * @folders: an array of CamelFolderInfo
+ * @folders: an array of #CamelFolderInfo
* @namespace: an ignorable prefix on the folder names
* @separator: the hieararchy separator character
* @short_names: %TRUE if the (short) name of a folder is the part after
* to the hierarchy described by their full_names and @separator. If
* @namespace is non-%NULL, then it will be ignored as a full_name
* prefix, for purposes of comparison. If necessary,
- * camel_folder_info_build will create additional CamelFolderInfo with
+ * #camel_folder_info_build will create additional #CamelFolderInfo with
* %NULL urls to fill in gaps in the tree. The value of @short_names
* is used in constructing the names of these intermediate folders.
*
* NOTE: This is deprected, do not use this.
* FIXME: remove this/move it to imap, which is the only user of it now.
*
- * Return value: the top level of the tree of linked folder info.
+ * Returns the top level of the tree of linked folder info.
**/
CamelFolderInfo *
camel_folder_info_build (GPtrArray *folders, const char *namespace,
return top;
}
-static CamelFolderInfo *folder_info_clone_rec(CamelFolderInfo *fi, CamelFolderInfo *parent)
+static CamelFolderInfo *
+folder_info_clone_rec(CamelFolderInfo *fi, CamelFolderInfo *parent)
{
CamelFolderInfo *info;
return info;
}
+
+/**
+ * camel_folder_info_clone:
+ * @fi: a #CamelFolderInfo
+ *
+ * Clones @fi recursively.
+ *
+ * Returns the cloned #CamelFolderInfo tree.
+ **/
CamelFolderInfo *
camel_folder_info_clone(CamelFolderInfo *fi)
{
return folder_info_clone_rec(fi, NULL);
}
+
+/**
+ * camel_store_supports_subscriptions:
+ * @store: a #CamelStore object
+ *
+ * Get whether or not @store supports subscriptions to folders.
+ *
+ * Returns %TRUE if folder subscriptions are supported or %FALSE otherwise
+ **/
gboolean
camel_store_supports_subscriptions (CamelStore *store)
{
}
/**
- * camel_store_folder_subscribed: Tell whether or not a folder has been subscribed to.
- * @store: a CamelStore
- * @folder_name: the folder on which we're querying subscribed status.
- * Return value: TRUE if folder is subscribed, FALSE if not.
+ * camel_store_folder_subscribed:
+ * @store: a #CamelStore object
+ * @folder_name: full path of the folder
+ *
+ * Find out if a folder has been subscribed to.
+ *
+ * Returns %TRUE if the folder has been subscribed to or %FALSE otherwise
**/
gboolean
camel_store_folder_subscribed(CamelStore *store, const char *folder_name)
}
/**
- * camel_store_subscribe_folder: marks a folder as subscribed.
- * @store: a CamelStore
- * @folder_name: the folder to subscribe to.
+ * camel_store_subscribe_folder:
+ * @store: a #CamelStore object
+ * @folder_name: full path of the folder
+ * @ex: a #CamelException
+ *
+ * Subscribe to the folder described by @folder_name.
**/
void
camel_store_subscribe_folder(CamelStore *store, const char *folder_name, CamelException *ex)
camel_type_to_name (CAMEL_OBJECT_GET_TYPE (store))));
}
+
/**
- * camel_store_unsubscribe_folder: marks a folder as unsubscribed.
- * @store: a CamelStore
- * @folder_name: the folder to unsubscribe from.
+ * camel_store_unsubscribe_folder:
+ * @store: a #CamelStore object
+ * @folder_name: full path of the folder
+ * @ex: a #CamelException
+ *
+ * Unsubscribe from the folder described by @folder_name.
**/
void
camel_store_unsubscribe_folder(CamelStore *store, const char *folder_name, CamelException *ex)
/**
* camel_store_noop:
- * @store: CamelStore
- * @ex: exception
+ * @store: a #CamelStore object
+ * @ex: a #CamelException
*
* Pings @store so that its connection doesn't timeout.
**/
/**
* camel_store_folder_uri_equal:
- * @store: CamelStore
- * @uri0: a uri
- * @uri1: another uri
+ * @store: a #CamelStore object
+ * @uri0: a folder uri
+ * @uri1: another folder uri
*
* Compares 2 folder uris to check that they are equal.
*
- * Returns %TRUE if they are equal or %FALSE otherwise.
+ * Returns %TRUE if they are equal or %FALSE otherwise
**/
int
camel_store_folder_uri_equal (CamelStore *store, const char *uri0, const char *uri1)
g_warning("Trying to invoke unimplemented unsubscribe method on a store");
}
-
#define CAMEL_STORE_FILTER_INBOX (1 << 2)
#define CAMEL_STORE_VJUNK (1 << 3)
-struct _CamelStore
-{
+struct _CamelStore {
CamelService parent_object;
struct _CamelStorePrivate *priv;
/**
* camel_tcp_stream_raw_new:
*
- * Return value: a tcp stream
+ * Create a new #CamelTcpStreamRaw object.
+ *
+ * Returns a new #CamelTcpStream object
**/
CamelStream *
camel_tcp_stream_raw_new ()
/**
* camel_tcp_stream_ssl_new:
- * @session: active session
- * @expected_host: host that the stream is expected to connect with.
- * @flags: ENABLE_SSL2, ENABLE_SSL3 and/or ENABLE_TLS
+ * @session: an active #CamelSession object
+ * @expected_host: host that the stream is expected to connect with
+ * @flags: a bitwise combination of any of
+ * #CAMEL_TCP_STREAM_SSL_ENABLE_SSL2,
+ * #CAMEL_TCP_STREAM_SSL_ENABLE_SSL3 or
+ * #CAMEL_TCP_STREAM_SSL_ENABLE_TLS
*
* Since the SSL certificate authenticator may need to prompt the
- * user, a CamelSession is needed. @expected_host is needed as a
+ * user, a #CamelSession is needed. @expected_host is needed as a
* protection against an MITM attack.
*
- * Return value: a ssl stream (in ssl mode)
+ * Returns a new #CamelTcpStreamSSL stream preset in SSL mode
**/
CamelStream *
camel_tcp_stream_ssl_new (CamelSession *session, const char *expected_host, guint32 flags)
/**
* camel_tcp_stream_ssl_new_raw:
- * @session: active session
- * @expected_host: host that the stream is expected to connect with.
- * @flags: ENABLE_SSL2, ENABLE_SSL3 and/or ENABLE_TLS
+ * @session: an active #CamelSession object
+ * @expected_host: host that the stream is expected to connect with
+ * @flags: a bitwise combination of any of
+ * #CAMEL_TCP_STREAM_SSL_ENABLE_SSL2,
+ * #CAMEL_TCP_STREAM_SSL_ENABLE_SSL3 or
+ * #CAMEL_TCP_STREAM_SSL_ENABLE_TLS
*
* Since the SSL certificate authenticator may need to prompt the
* user, a CamelSession is needed. @expected_host is needed as a
* protection against an MITM attack.
*
- * Return value: a ssl-capable stream (in non ssl mode)
+ * Returns a new #CamelTcpStreamSSL stream not yet toggled into SSL mode
**/
CamelStream *
camel_tcp_stream_ssl_new_raw (CamelSession *session, const char *expected_host, guint32 flags)
/**
* camel_tcp_stream_ssl_enable_ssl:
- * @ssl: ssl stream
+ * @ssl: a #CamelTcpStreamSSL object
*
* Toggles an ssl-capable stream into ssl mode (if it isn't already).
*
- * Returns 0 on success or -1 on fail.
+ * Returns %0 on success or %-1 on fail
**/
int
camel_tcp_stream_ssl_enable_ssl (CamelTcpStreamSSL *ssl)
struct _CamelSession;
-enum {
- CAMEL_TCP_STREAM_SSL_ENABLE_SSL2 = (1 << 0),
- CAMEL_TCP_STREAM_SSL_ENABLE_SSL3 = (1 << 1),
- CAMEL_TCP_STREAM_SSL_ENABLE_TLS = (1 << 2),
-};
+#define CAMEL_TCP_STREAM_SSL_ENABLE_SSL2 (1 << 0)
+#define CAMEL_TCP_STREAM_SSL_ENABLE_SSL3 (1 << 1)
+#define CAMEL_TCP_STREAM_SSL_ENABLE_TLS (1 << 2)
struct _CamelTcpStreamSSL {
CamelTcpStream parent_object;
/**
* camel_tcp_stream_connect:
- * @stream: a CamelTcpStream object.
- * @host: A linked list of addrinfo structures to try to connect, in
+ * @stream: a #CamelTcpStream object
+ * @host: a linked list of addrinfo structures to try to connect, in
* the order of most likely to least likely to work.
*
* Create a socket and connect based upon the data provided.
*
- * Return value: zero on success or -1 on fail.
+ * Returns %0 on success or %-1 on fail
**/
int
camel_tcp_stream_connect (CamelTcpStream *stream, struct addrinfo *host)
/**
* camel_tcp_stream_getsockopt:
- * @stream: tcp stream object
+ * @stream: a #CamelTcpStream object
* @data: socket option data
*
- * Get the socket options set on the stream and populate #data.
+ * Get the socket options set on the stream and populate @data.
*
- * Return value: zero on success or -1 on fail.
+ * Returns %0 on success or %-1 on fail
**/
int
camel_tcp_stream_getsockopt (CamelTcpStream *stream, CamelSockOptData *data)
/**
* camel_tcp_stream_setsockopt:
- * @stream: tcp stream object
+ * @stream: a #CamelTcpStream object
* @data: socket option data
*
- * Set the socket options contained in #data on the stream.
+ * Set the socket options contained in @data on the stream.
*
- * Return value: zero on success or -1 on fail.
+ * Returns %0 on success or %-1 on fail
**/
int
camel_tcp_stream_setsockopt (CamelTcpStream *stream, const CamelSockOptData *data)
/**
* camel_tcp_stream_get_local_address:
- * @stream: tcp stream object
- * @len: Pointer to address length which must be supplied.
+ * @stream: a #CamelTcpStream object
+ * @len: pointer to address length which must be supplied
*
* Get the local address of @stream.
*
- * Return value: the stream's local address (which must be freed with
- * g_free()) if the stream is connected, or %NULL if not.
+ * Returns the stream's local address (which must be freed with
+ * #g_free) if the stream is connected, or %NULL if not
**/
struct sockaddr *
camel_tcp_stream_get_local_address (CamelTcpStream *stream, socklen_t *len)
/**
* camel_tcp_stream_get_remote_address:
- * @stream: tcp stream object
- * @len: Pointer to address length, which must be supplied.
+ * @stream: a #CamelTcpStream object
+ * @len: pointer to address length, which must be supplied
*
* Get the remote address of @stream.
*
- * Return value: the stream's remote address (which must be freed with
- * g_free()) if the stream is connected, or %NULL if not.
+ * Returns the stream's remote address (which must be freed with
+ * #g_free) if the stream is connected, or %NULL if not.
**/
struct sockaddr *
camel_tcp_stream_get_remote_address (CamelTcpStream *stream, socklen_t *len)
/**
* camel_transport_send_to:
- * @transport: the transport
- * @message: the message
- * @from: from address
- * @recipients: the recipients
- * @ex: a CamelException
+ * @transport: a #CamelTransport object
+ * @message: a #CamelMimeMessage to send
+ * @from: a #CamelAddress to send from
+ * @recipients: a #CamelAddress containing all recipients
+ * @ex: a #CamelException
*
* Sends the message to the given recipients, regardless of the contents
* of @message. If the message contains a "Bcc" header, the transport
* is responsible for stripping it.
*
- * Return value: success or failure.
+ * Return %TRUE on success or %FALSE on fail
**/
gboolean
camel_transport_send_to (CamelTransport *transport, CamelMimeMessage *message,
/**
* camel_vee_store_new:
*
- * Create a new CamelVeeStore object.
+ * Create a new #CamelVeeStore object.
*
- * Return value: A new CamelVeeStore widget.
+ * Returns new #CamelVeeStore object
**/
CamelVeeStore *
camel_vee_store_new (void)
projects / platform / upstream / evolution-data-server.git / commitdiff