*
* Create and returns a new exception object.
*
- *
- * Return value: The newly allocated exception object.
+ * Returns the newly allocated exception object
**/
CamelException *
camel_exception_new (void)
}
/**
- * camel_exception_init: init a (statically allocated) exception.
- *
- * Init an exception. This routine is mainly
- * useful when using a statically allocated
- * exception.
- *
+ * camel_exception_init:
+ * @ex: a #CamelException
*
+ * Init an exception. This routine is mainly useful when using a
+ * statically allocated exception.
**/
void
camel_exception_init (CamelException *ex)
/**
- * camel_exception_clear: Clear an exception
- * @exception: the exception object
+ * camel_exception_clear:
+ * @ex: a #CamelException
*
- * Clear an exception, that is, set the
- * exception ID to CAMEL_EXCEPTION_NONE and
- * free the description text.
- * If the exception is NULL, this funtion just
- * returns.
+ * Clear an exception, that is, set the exception ID to
+ * #CAMEL_EXCEPTION_NONE and free the description text. If the
+ * exception is %NULL, this funtion just returns.
**/
void
camel_exception_clear (CamelException *exception)
}
/**
- * camel_exception_free: Free an exception
- * @exception: The exception object to free
+ * camel_exception_free:
+ * @ex: a #CamelException
*
- * Free an exception object. If the exception
- * is NULL, nothing is done, the routine simply
- * returns.
+ * Free an exception object. If the exception is %NULL, nothing is
+ * done, the routine simply returns.
**/
void
camel_exception_free (CamelException *exception)
/**
* camel_exception_set: set an exception
- * @ex: exception object
+ * @ex: a #CamelException
* @id: exception id
* @desc: textual description of the exception
*
* textual description is a small text explaining
* what happened and provoked the exception.
*
- * When @ex is NULL, nothing is done, this routine
+ * When @ex is %NULL, nothing is done, this routine
* simply returns.
- *
**/
void
camel_exception_set (CamelException *ex,
/**
* camel_exception_setv: set an exception
- * @ex: exception object
+ * @ex: a #CamelException
* @id: exception id
* @format: format of the description string. The format string is
* used as in printf().
* It is safe to say:
* camel_exception_setv (ex, ..., camel_exception_get_description (ex), ...);
*
- * When @ex is NULL, nothing is done, this routine
+ * When @ex is %NULL, nothing is done, this routine
* simply returns.
- *
**/
void
camel_exception_setv (CamelException *ex,
}
/**
- * camel_exception_xfer: transfer an exception
+ * camel_exception_xfer:
* @ex_dst: Destination exception object
* @ex_src: Source exception object
*
- * Transfer the content of an exception from
- * an exception object to another.
- * The destination exception receives the id and
- * the description text of the source exception.
+ * Transfer the content of an exception from an exception object to
+ * another. The destination exception receives the id and the
+ * description text of the source exception.
**/
void
camel_exception_xfer (CamelException *ex_dst,
}
/**
- * camel_exception_get_id: get the exception id
- * @ex: The exception object
+ * camel_exception_get_id:
+ * @ex: a #CamelException
*
- * Return the id of an exception.
- * If @ex is NULL, return CAMEL_EXCEPTION_NONE;
+ * Get the id of an exception.
*
- * Return value: Exception ID.
+ * Returns the exception id (#CAMEL_EXCEPTION_NONE will be returned if
+ * @ex is %NULL or unset)
**/
ExceptionId
camel_exception_get_id (CamelException *ex)
}
/**
- * camel_exception_get_description: get the description of an exception.
- * @ex: The exception object
- *
- * Return the exception description text.
- * If @ex is NULL, return NULL;
+ * camel_exception_get_description:
+ * @ex: a #CamelException
*
+ * Get the exception description text.
*
- * Return value: Exception description text.
+ * Returns the exception description text (%NULL will be returned if
+ * @ex is %NULL or unset)
**/
const gchar *
camel_exception_get_description (CamelException *ex)
/* creation and destruction functions */
CamelException * camel_exception_new (void);
-void camel_exception_free (CamelException *exception);
+void camel_exception_free (CamelException *ex);
void camel_exception_init (CamelException *ex);
/* exception content manipulation */
-void camel_exception_clear (CamelException *exception);
+void camel_exception_clear (CamelException *ex);
void camel_exception_set (CamelException *ex,
ExceptionId id,
const char *desc);
camel_object_unref (value);
}
+
+/**
+ * camel_mime_message_new:
+ *
+ * Create a new #CamelMimeMessage object.
+ *
+ * Returns a new #CamelMimeMessage object
+ **/
CamelMimeMessage *
camel_mime_message_new (void)
{
/* **** Date: */
+
+/**
+ * camel_mime_message_set_date:
+ * @message: a #CamelMimeMessage object
+ * @date: a time_t date
+ * @offset: an offset from GMT
+ *
+ * Set the date on a message.
+ **/
void
camel_mime_message_set_date (CamelMimeMessage *message, time_t date, int offset)
{
g_free (datestr);
}
+
+/**
+ * camel_mime_message_get_date:
+ * @message: a #CamelMimeMessage object
+ * @offset: output for the GMT offset
+ *
+ * Get the date and GMT offset of a message.
+ *
+ * Returns the date of the message
+ **/
time_t
camel_mime_message_get_date (CamelMimeMessage *msg, int *offset)
{
return msg->date;
}
+
+/**
+ * camel_mime_message_get_date_received:
+ * @message: a #CamelMimeMessage object
+ * @offset: output for the GMT offset
+ *
+ * Get the received date and GMT offset of a message.
+ *
+ * Returns the received date of the message
+ **/
time_t
camel_mime_message_get_date_received (CamelMimeMessage *msg, int *offset)
{
/* **** Message-Id: */
+/**
+ * camel_mime_message_set_message_id:
+ * @message: a #CamelMimeMessage object
+ * @message_id: id of the message
+ *
+ * Set the message-id on a message.
+ **/
void
camel_mime_message_set_message_id (CamelMimeMessage *mime_message, const char *message_id)
{
g_free (id);
}
+
+/**
+ * camel_mime_message_get_message_id:
+ * @message: a #CamelMimeMessage object
+ *
+ * Get the message-id of a message.
+ *
+ * Returns the message-id of a message
+ **/
const char *
camel_mime_message_get_message_id (CamelMimeMessage *mime_message)
{
/* **** Reply-To: */
+
+/**
+ * camel_mime_message_set_reply_to:
+ * @message: a #CamelMimeMessage object
+ * @reply_to: a #CamelInternetAddress object
+ *
+ * Set the Reply-To of a message.
+ **/
void
camel_mime_message_set_reply_to (CamelMimeMessage *msg, const CamelInternetAddress *reply_to)
{
g_free (addr);
}
+
+/**
+ * camel_mime_message_get_reply_to:
+ * @message: a #CamelMimeMessage object
+ *
+ * Get the Reply-To of a message.
+ *
+ * Returns the Reply-Toa ddress of the message
+ **/
const CamelInternetAddress *
camel_mime_message_get_reply_to (CamelMimeMessage *mime_message)
{
/* **** Subject: */
+/**
+ * camel_mime_message_set_subject:
+ * @message: a #CamelMimeMessage object
+ * @subject: UTF-8 message subject
+ *
+ * Set the subject text of a message.
+ **/
void
camel_mime_message_set_subject (CamelMimeMessage *mime_message, const char *subject)
{
g_free (text);
}
+
+/**
+ * camel_mime_message_get_subject:
+ * @message: a #CamelMimeMessage object
+ *
+ * Get the UTF-8 subject text of a message.
+ *
+ * Returns the message subject
+ **/
const char *
camel_mime_message_get_subject (CamelMimeMessage *mime_message)
{
/* Thought: Since get_from/set_from are so rarely called, it is probably not useful
to cache the from (and reply_to) addresses as InternetAddresses internally, we
could just get it from the headers and reprocess every time. */
+
+/**
+ * camel_mime_message_set_from:
+ * @message: a #CamelMimeMessage object
+ * @from: a #CamelInternetAddress object
+ *
+ * Set the from address of a message.
+ **/
void
camel_mime_message_set_from (CamelMimeMessage *msg, const CamelInternetAddress *from)
{
g_free(addr);
}
+
+/**
+ * camel_mime_message_get_from:
+ * @message: a #CamelMimeMessage object
+ *
+ * Get the from address of a message.
+ *
+ * Returns the from address of the message
+ **/
const CamelInternetAddress *
camel_mime_message_get_from (CamelMimeMessage *mime_message)
{
/* **** To: Cc: Bcc: */
+/**
+ * camel_mime_message_set_recipients:
+ * @message: a #CamelMimeMessage object
+ * @type: recipient type (one of #CAMEL_RECIPIENT_TYPE_TO, #CAMEL_RECIPIENT_TYPE_CC, or #CAMEL_RECIPIENT_TYPE_BCC)
+ * @recipients: a #CamelInternetAddress with the recipient addresses set
+ *
+ * Set the recipients of a message.
+ **/
void
camel_mime_message_set_recipients(CamelMimeMessage *mime_message, const char *type, const CamelInternetAddress *r)
{
g_free(text);
}
+
+/**
+ * camel_mime_message_get_recipients:
+ * @message: a #CamelMimeMessage object
+ * @type: recipient type
+ *
+ * Get the message recipients of a specified type.
+ *
+ * Returns the requested recipients
+ **/
+const CamelInternetAddress *
+camel_mime_message_get_recipients (CamelMimeMessage *mime_message, const char *type)
+{
+ g_assert(mime_message);
+
+ return g_hash_table_lookup (mime_message->recipients, type);
+}
+
+
void
camel_mime_message_set_source (CamelMimeMessage *mime_message, const char *src)
{
return src;
}
-const CamelInternetAddress *
-camel_mime_message_get_recipients (CamelMimeMessage *mime_message, const char *type)
-{
- g_assert(mime_message);
-
- return g_hash_table_lookup (mime_message->recipients, type);
-}
-
/* mime_message */
static int
construct_from_parser (CamelMimePart *dw, CamelMimeParser *mp)
return !(*has8bit);
}
+
+/**
+ * camel_mime_message_has_8bit_parts:
+ * @message: a #CamelMimeMessage object
+ *
+ * Find out if a message contains 8bit or binary encoded parts.
+ *
+ * Returns %TRUE if the message contains 8bit parts or %FALSE otherwise
+ **/
gboolean
camel_mime_message_has_8bit_parts (CamelMimeMessage *msg)
{
return TRUE;
}
+
+/**
+ * camel_mime_message_set_best_encoding:
+ * @message: a #CamelMimeMessage object
+ * @required: a bitwise ORing of #CAMEL_BESTENC_GET_ENCODING and #CAMEL_BESTENC_GET_CHARSET
+ * @enctype: an encoding to enforce
+ *
+ * Re-encode all message parts to conform with the required encoding rules.
+ *
+ * If @enctype is #CAMEL_BESTENC_7BIT, then all parts will be re-encoded into
+ * one of the 7bit transfer encodings. If @enctype is #CAMEL_BESTENC_8bit, all
+ * parts will be re-encoded to either a 7bit encoding or, if the part is 8bit
+ * text, allowed to stay 8bit. If @enctype is #CAMEL_BESTENC_BINARY, then binary
+ * parts will be encoded as binary and 8bit textual parts will be encoded as 8bit.
+ **/
void
camel_mime_message_set_best_encoding (CamelMimeMessage *msg, CamelBestencRequired required, CamelBestencEncoding enctype)
{
camel_mime_message_foreach_part (msg, best_encoding, &data);
}
+
+/**
+ * camel_mime_message_encode_8bit_parts:
+ * @message: a #CamelMimeMessage object
+ *
+ * Encode all message parts to a suitable transfer encoding for transport (7bit clean).
+ **/
void
camel_mime_message_encode_8bit_parts (CamelMimeMessage *mime_message)
{
return !found;
}
+
+/**
+ * camel_mime_message_get_part_by_content_id:
+ * @message: a #CamelMimeMessage object
+ * @content_id: content-id to search for
+ *
+ * Get a MIME part by id from a message.
+ *
+ * Returns the MIME part with the requested id or %NULL if not found
+ **/
CamelMimePart *
camel_mime_message_get_part_by_content_id (CamelMimeMessage *message, const char *id)
{
"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"
};
+
+/**
+ * camel_mime_message_build_mbox_from:
+ * @message: a #CamelMimeMessage object
+ *
+ * Build an MBox from-line from @message.
+ *
+ * Returns an MBox from-line suitable for use in an mbox file
+ **/
char *
camel_mime_message_build_mbox_from (CamelMimeMessage *message)
{
/* public methods */
CamelMimeMessage *camel_mime_message_new (void);
-void camel_mime_message_set_date (CamelMimeMessage *mime_message,
+void camel_mime_message_set_date (CamelMimeMessage *message,
time_t date,
int offset);
-time_t camel_mime_message_get_date (CamelMimeMessage *mime_message,
+time_t camel_mime_message_get_date (CamelMimeMessage *message,
int *offset);
-time_t camel_mime_message_get_date_received (CamelMimeMessage *mime_message,
+time_t camel_mime_message_get_date_received (CamelMimeMessage *message,
int *offset);
-void camel_mime_message_set_message_id (CamelMimeMessage *mime_message,
+void camel_mime_message_set_message_id (CamelMimeMessage *message,
const char *message_id);
-const char *camel_mime_message_get_message_id (CamelMimeMessage *mime_message);
-void camel_mime_message_set_reply_to (CamelMimeMessage *mime_message,
+const char *camel_mime_message_get_message_id (CamelMimeMessage *message);
+void camel_mime_message_set_reply_to (CamelMimeMessage *message,
const CamelInternetAddress *reply_to);
-const CamelInternetAddress *camel_mime_message_get_reply_to (CamelMimeMessage *mime_message);
+const CamelInternetAddress *camel_mime_message_get_reply_to (CamelMimeMessage *message);
-void camel_mime_message_set_subject (CamelMimeMessage *mime_message,
+void camel_mime_message_set_subject (CamelMimeMessage *message,
const char *subject);
-const char *camel_mime_message_get_subject (CamelMimeMessage *mime_message);
-void camel_mime_message_set_from (CamelMimeMessage *mime_message,
+const char *camel_mime_message_get_subject (CamelMimeMessage *message);
+void camel_mime_message_set_from (CamelMimeMessage *message,
const CamelInternetAddress *from);
-const CamelInternetAddress *camel_mime_message_get_from (CamelMimeMessage *mime_message);
+const CamelInternetAddress *camel_mime_message_get_from (CamelMimeMessage *message);
-const CamelInternetAddress *camel_mime_message_get_recipients (CamelMimeMessage *mime_message,
+const CamelInternetAddress *camel_mime_message_get_recipients (CamelMimeMessage *message,
const char *type);
-void camel_mime_message_set_recipients (CamelMimeMessage *mime_message,
+void camel_mime_message_set_recipients (CamelMimeMessage *message,
const char *type,
- const CamelInternetAddress *r);
+ const CamelInternetAddress *recipients);
-void camel_mime_message_set_source (CamelMimeMessage *mime_message,
+void camel_mime_message_set_source (CamelMimeMessage *message,
const char *identity);
-const char *camel_mime_message_get_source (CamelMimeMessage *mime_message);
+const char *camel_mime_message_get_source (CamelMimeMessage *message);
/* utility functions */
-gboolean camel_mime_message_has_8bit_parts (CamelMimeMessage *mime_message);
-void camel_mime_message_set_best_encoding (CamelMimeMessage *msg,
+gboolean camel_mime_message_has_8bit_parts (CamelMimeMessage *message);
+void camel_mime_message_set_best_encoding (CamelMimeMessage *message,
CamelBestencRequired required,
CamelBestencEncoding enctype);
-void camel_mime_message_encode_8bit_parts (CamelMimeMessage *mime_message);
+void camel_mime_message_encode_8bit_parts (CamelMimeMessage *message);
CamelMimePart *camel_mime_message_get_part_by_content_id (CamelMimeMessage *message, const char *content_id);
-char *camel_mime_message_build_mbox_from (CamelMimeMessage *mime_message);
+char *camel_mime_message_build_mbox_from (CamelMimeMessage *message);
void camel_mime_message_dump(CamelMimeMessage *msg, int body);
/* **** Content-Transfer-Encoding: */
+
+/**
+ * camel_mime_part_set_encoding:
+ * @mime_part: a #CamelMimePart object
+ * @encoding: a #CamelTransferEncoding
+ *
+ * Set the Content-Transfer-Encoding to use on a MIME part.
+ **/
void
camel_mime_part_set_encoding (CamelMimePart *mime_part,
CamelTransferEncoding encoding)
"Content-Transfer-Encoding", text);
}
+
+/**
+ * camel_mime_part_get_encoding:
+ * @mime_part: a #CamelMimePart object
+ *
+ * Get the Content-Transfer-Encoding of a MIME part.
+ *
+ * Returns a #CamelTransferEncoding
+ **/
CamelTransferEncoding
camel_mime_part_get_encoding (CamelMimePart *mime_part)
{
/* FIXME: do something with this stuff ... */
+
+/**
+ * camel_mime_part_set_content_languages:
+ * @mime_part: a #CamelMimePart object
+ * @content_languages: list of languages
+ *
+ * Set the Content-Languages field of a MIME part.
+ **/
void
camel_mime_part_set_content_languages (CamelMimePart *mime_part, GList *content_languages)
{
/* FIXME: translate to a header and set it */
}
+
+/**
+ * camel_mime_part_get_content_languages:
+ * @mime_part: a #CamelMimePart object
+ *
+ * Get the Content-Languages set on the MIME part.
+ *
+ * Returns a #GList of languages
+ **/
const GList *
camel_mime_part_get_content_languages (CamelMimePart *mime_part)
{
/* **** Content-Type: */
-void
+/**
+ * camel_mime_part_set_content_type:
+ * @mime_part: a #CamelMimePart object
+ * @content_type: content-type string
+ *
+ * Set the content-type on a MIME part.
+ **/
+void
camel_mime_part_set_content_type (CamelMimePart *mime_part, const char *content_type)
{
camel_medium_set_header (CAMEL_MEDIUM (mime_part),
"Content-Type", content_type);
}
+
+/**
+ * camel_mime_part_get_content_type:
+ * @mime_part: a #CamelMimePart object
+ *
+ * Get the Content-Type of a MIME part.
+ *
+ * Returns the parsed #CamelContentType of the MIME part
+ **/
CamelContentType *
camel_mime_part_get_content_type (CamelMimePart *mime_part)
{
/**
* camel_mime_part_construct_from_parser:
- * @mime_part:
- * @mp:
- *
- *
+ * @mime_part: a #CamelMimePart object
+ * @parser: a #CamelMimeParser object
+ *
+ * Constructs a MIME part from a parser.
*
- * Return value:
+ * Returns %0 on success or %-1 on fail
**/
int
camel_mime_part_construct_from_parser(CamelMimePart *mime_part, CamelMimeParser *mp)
/**
* camel_mime_part_new:
*
- * Return value: a new CamelMimePart
+ * Create a new MIME part.
+ *
+ * Returns a new #CamelMimePart object
**/
CamelMimePart *
camel_mime_part_new (void)
/**
* camel_mime_part_set_content:
- * @camel_mime_part: Mime part
+ * @mime_part: a #CamelMimePart object
* @data: data to put into the part
* @length: length of @data
* @type: Content-Type of the data
* ignored and may be %NULL).
**/
void
-camel_mime_part_set_content (CamelMimePart *camel_mime_part,
+camel_mime_part_set_content (CamelMimePart *mime_part,
const char *data, int length,
const char *type) /* why on earth is the type last? */
{
- CamelMedium *medium = CAMEL_MEDIUM (camel_mime_part);
+ CamelMedium *medium = CAMEL_MEDIUM (mime_part);
if (length) {
CamelDataWrapper *dw;
void camel_mime_part_set_content_location (CamelMimePart *mime_part, const char *location);
const char *camel_mime_part_get_content_location (CamelMimePart *mime_part);
-void camel_mime_part_set_encoding (CamelMimePart *mime_part, CamelTransferEncoding type);
+void camel_mime_part_set_encoding (CamelMimePart *mime_part, CamelTransferEncoding encoding);
CamelTransferEncoding camel_mime_part_get_encoding (CamelMimePart *mime_part);
void camel_mime_part_set_content_languages (CamelMimePart *mime_part, GList *content_languages);
int camel_mime_part_construct_from_parser (CamelMimePart *mime_part, CamelMimeParser *parser);
/* utility functions */
-void camel_mime_part_set_content (CamelMimePart *camel_mime_part,
+void camel_mime_part_set_content (CamelMimePart *mime_part,
const char *content, int length, const char *type);
#ifdef __cplusplus
/**
* camel_multipart_encrypted_new:
*
- * Create a new CamelMultipartEncrypted object.
+ * Create a new #CamelMultipartEncrypted object.
*
* A MultipartEncrypted should be used to store and create parts of
* type "multipart/encrypted".
*
- * Returns a new CamelMultipartEncrypted
+ * Returns a new #CamelMultipartEncrypted object
**/
CamelMultipartEncrypted *
camel_multipart_encrypted_new (void)
/**
* camel_multipart_signed_new:
*
- * Create a new CamelMultipartSigned object.
+ * Create a new #CamelMultipartSigned object.
*
* A MultipartSigned should be used to store and create parts of
* type "multipart/signed". This is because multipart/signed is
* set the mime_type appropriately to match the data uses, so
* that the multiple parts my be extracted.
*
- * Use construct_from_parser. The parser MUST be in the CAMEL_MIME_PARSER_STATE_HEADER
+ * Use construct_from_parser. The parser MUST be in the #CAMEL_MIME_PARSER_STATE_HEADER
* state, and the current content_type MUST be "multipart/signed" with
* the appropriate boundary and it SHOULD include the appropriate protocol
* and hash specifiers.
* create a 'transport-safe' version (as safe as can be expected with
* such a broken specification).
*
- * Return value: a new CamelMultipartSigned
+ * Returns a new #CamelMultipartSigned object
**/
CamelMultipartSigned *
camel_multipart_signed_new (void)
return total;
}
+
+/**
+ * camel_multipart_signed_get_content_stream:
+ * @mps: a #CamlMultipartSigned object
+ * @ex: a #CamelException
+ *
+ * Get the raw signed content stream of the multipart/signed MIME part
+ * suitable for use with verification of the signature.
+ *
+ * Returns the signed content stream
+ **/
CamelStream *
camel_multipart_signed_get_content_stream(CamelMultipartSigned *mps, CamelException *ex)
{
/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
/* camel-multipart.c : Abstract class for a multipart */
-
-
/*
*
* Author :
/**
* camel_multipart_new:
*
- * Create a new CamelMultipart object.
+ * Create a new #CamelMultipart object.
*
- * Return value: a new CamelMultipart
+ * Returns a new #CamelMultipart object
**/
CamelMultipart *
camel_multipart_new (void)
camel_object_ref (part);
}
+
/**
* camel_multipart_add_part:
- * @multipart: a CamelMultipart
- * @part: the part to add
+ * @multipart: a #CamelMultipart object
+ * @part: a #CamelMimePart to add
*
* Appends the part to the multipart object.
**/
/**
* camel_multipart_add_part_at:
- * @multipart: a CamelMultipart
- * @part: the part to add
+ * @multipart: a #CamelMultipart object
+ * @part: a #CamelMimePart to add
* @index: index to add the multipart at
*
* Adds the part to the multipart object after the @index'th
* element. If @index is greater than the number of parts, it is
- * equivalent to camel_multipart_add_part().
+ * equivalent to #camel_multipart_add_part.
**/
void
camel_multipart_add_part_at (CamelMultipart *multipart,
/**
* camel_multipart_remove_part:
- * @multipart: a CamelMultipart
- * @part: the part to remove
+ * @multipart: a #CamelMultipart object
+ * @part: a #CamelMimePart to remove
*
* Removes @part from @multipart.
**/
/**
* camel_multipart_remove_part_at:
- * @multipart: a CamelMultipart
+ * @multipart: a #CamelMultipart object
* @index: a zero-based index indicating the part to remove
*
* Remove the indicated part from the multipart object.
*
- * Return value: the removed part. Note that it is camel_object_unref()ed
+ * Returns the removed part. Note that it is #camel_object_unref'ed
* before being returned, which may cause it to be destroyed.
**/
CamelMimePart *
/**
* camel_multipart_get_part:
- * @multipart: a CamelMultipart
+ * @multipart: a #CamelMultipart object
* @index: a zero-based index indicating the part to get
*
- * Return value: the indicated subpart, or %NULL
+ * Returns the indicated subpart, or %NULL
**/
CamelMimePart *
camel_multipart_get_part (CamelMultipart *multipart, guint index)
/**
* camel_multipart_get_number:
- * @multipart: a CamelMultipart
+ * @multipart: a #CamelMultipart object
*
- * Return value: the number of subparts in @multipart
+ * Returns the number of subparts in @multipart
**/
guint
camel_multipart_get_number (CamelMultipart *multipart)
/**
* camel_multipart_set_boundary:
- * @multipart: a CamelMultipart
+ * @multipart: a #CamelMultipart object
* @boundary: the message boundary, or %NULL
*
* Sets the message boundary for @multipart to @boundary. This should
/**
* camel_multipart_get_boundary:
- * @multipart: a CamelMultipart
+ * @multipart: a #CamelMultipart object
*
- * Return value: @multipart's message boundary
+ * Returns the boundary
**/
-const gchar *
+const char *
camel_multipart_get_boundary (CamelMultipart *multipart)
{
return CMP_CLASS (multipart)->get_boundary (multipart);
/**
* camel_multipart_set_preface:
- * @multipart:
- * @preface:
+ * @multipart: a #CamelMultipart object
+ * @preface: the multipart preface
*
* Set the preface text for this multipart. Will be written out infront
* of the multipart. This text should only include US-ASCII strings, and
/**
* camel_multipart_set_postface:
- * @multipart:
- * @postface:
+ * @multipart: a #CamelMultipart object
+ * @postface: multipat postface
*
* Set the postfix text for this multipart. Will be written out after
* the last boundary of the multipart, and ignored by any MIME mail
return 0;
}
+
+/**
+ * camel_multipart_construct_from_parser:
+ * @multipart: a #CamelMultipart object
+ * @parser: a #CamelMimeParser object
+ *
+ * Construct a multipart from a parser.
+ *
+ * Returns %0 on success or %-1 on fail
+ **/
int
camel_multipart_construct_from_parser(CamelMultipart *multipart, struct _CamelMimeParser *mp)
{
guint camel_multipart_get_number (CamelMultipart *multipart);
void camel_multipart_set_boundary (CamelMultipart *multipart,
const char *boundary);
-const gchar * camel_multipart_get_boundary (CamelMultipart *multipart);
+const char * camel_multipart_get_boundary (CamelMultipart *multipart);
void camel_multipart_set_preface (CamelMultipart *multipart, const char *preface);
void camel_multipart_set_postface (CamelMultipart *multipart, const char *postface);
-int camel_multipart_construct_from_parser(CamelMultipart *multipart, struct _CamelMimeParser *mp);
+int camel_multipart_construct_from_parser(CamelMultipart *multipart, struct _CamelMimeParser *parser);
#ifdef __cplusplus
}
return type;
}
+
+/**
+ * camel_sasl_anonymous_new:
+ * @type: trace type
+ * @trace_info: trace info
+ *
+ * Create a new #CamelSaslAnonymous object.
+ *
+ * Returns a new #CamelSasl object
+ **/
CamelSasl *
camel_sasl_anonymous_new (CamelSaslAnonTraceType type, const char *trace_info)
{
/**
* camel_sasl_challenge:
- * @sasl: a SASL object
+ * @sasl: a #CamelSasl object
* @token: a token, or %NULL
- * @ex: exception
+ * @ex: a #CamelException
*
* If @token is %NULL, generate the initial SASL message to send to
* the server. (This will be %NULL if the client doesn't initiate the
* exchange.) Otherwise, @token is a challenge from the server, and
* the return value is the response.
*
- * Return value: The SASL response or %NULL. If an error occurred, @ex
- * will also be set.
+ * Returns the SASL response or %NULL. If an error occurred, @ex will
+ * also be set.
**/
GByteArray *
camel_sasl_challenge (CamelSasl *sasl, GByteArray *token, CamelException *ex)
/**
* camel_sasl_challenge_base64:
- * @sasl: a SASL object
+ * @sasl: a #CamelSasl object
* @token: a base64-encoded token
- * @ex: exception
+ * @ex: a #CamelException
*
- * As with camel_sasl_challenge(), but the challenge @token and the
+ * As with #camel_sasl_challenge, but the challenge @token and the
* response are both base64-encoded.
*
- * Return value: As with camel_sasl_challenge(), but base64-encoded.
+ * Returns the base64 encoded challenge string
**/
char *
camel_sasl_challenge_base64 (CamelSasl *sasl, const char *token, CamelException *ex)
/**
* camel_sasl_authenticated:
- * @sasl: a SASL object
+ * @sasl: a #CamelSasl object
*
- * Return value: whether or not @sasl has successfully authenticated
- * the user. This will be %TRUE after it returns the last needed response.
- * The caller must still pass that information on to the server and verify
- * that it has accepted it.
+ * Returns whether or not @sasl has successfully authenticated the
+ * user. This will be %TRUE after it returns the last needed response.
+ * The caller must still pass that information on to the server and
+ * verify that it has accepted it.
**/
gboolean
camel_sasl_authenticated (CamelSasl *sasl)
* @mechanism: the SASL mechanism
* @service: the CamelService that will be using this SASL
*
- * Return value: a new CamelSasl for the given @service_name,
+ * Returns a new #CamelSasl object for the given @service_name,
* @mechanism, and @service, or %NULL if the mechanism is not
* supported.
**/
* camel_sasl_authtype_list:
* @include_plain: whether or not to include the PLAIN mechanism
*
- * Return value: a GList of SASL-supported authtypes. The caller must
+ * Returns a #GList of SASL-supported authtypes. The caller must
* free the list, but not the contents.
**/
GList *
* camel_sasl_authtype:
* @mechanism: the SASL mechanism to get an authtype for
*
- * Return value: a CamelServiceAuthType for the given mechanism, if
+ * Returns a #CamelServiceAuthType for the given mechanism, if
* it is supported.
**/
CamelServiceAuthType *
/**
* camel_session_construct:
- * @session: a session object to construct
+ * @session: a #CamelSession object to construct
* @storage_path: path to a directory the session can use for
* persistent storage. (This directory must already exist.)
*
/**
* camel_session_get_service:
- * @session: the CamelSession
- * @url_string: a Camel URL describing the service to get
- * @type: the provider type (%CAMEL_PROVIDER_STORE or
- * %CAMEL_PROVIDER_TRANSPORT) to get, since some URLs may be able
+ * @session: a #CamelSession object
+ * @url_string: a #CamelURL describing the service to get
+ * @type: the provider type (#CAMEL_PROVIDER_STORE or
+ * #CAMEL_PROVIDER_TRANSPORT) to get, since some URLs may be able
* to specify either type.
- * @ex: a CamelException
+ * @ex: a #CamelException
*
- * This resolves a CamelURL into a CamelService, including loading the
+ * This resolves a #CamelURL into a #CamelService, including loading the
* provider library for that service if it has not already been loaded.
*
* Services are cached, and asking for "the same" @url_string multiple
* incremented by one each time). What constitutes "the same" URL
* depends in part on the provider.
*
- * Return value: the requested CamelService, or %NULL
+ * Returns the requested #CamelService, or %NULL
**/
CamelService *
camel_session_get_service (CamelSession *session, const char *url_string,
/**
* camel_session_get_service_connected:
- * @session: the CamelSession
- * @url_string: a Camel URL describing the service to get
+ * @session: a #CamelSession object
+ * @url_string: a #CamelURL describing the service to get
* @type: the provider type
- * @ex: a CamelException
+ * @ex: a #CamelException
*
- * This works like camel_session_get_service(), but also ensures that
+ * This works like #camel_session_get_service, but also ensures that
* the returned service will have been successfully connected (via
- * camel_service_connect().)
+ * #camel_service_connect.)
*
- * Return value: the requested CamelService, or %NULL
+ * Returns the requested #CamelService, or %NULL
**/
CamelService *
camel_session_get_service_connected (CamelSession *session,
/**
* camel_session_get_storage_path:
- * @session: session object
- * @service: a CamelService
- * @ex: a CamelException
+ * @session: a #CamelSession object
+ * @service: a #CamelService
+ * @ex: a #CamelException
*
* This returns the path to a directory which the service can use for
* its own purposes. Data stored there will remain between Evolution
* files in this directory. If the directory does not exist, it will
* be created.
*
- * Return value: the path (which the caller must free), or %NULL if
- * an error occurs.
+ * Returns the path (which the caller must free), or %NULL if an error
+ * occurs.
**/
char *
camel_session_get_storage_path (CamelSession *session, CamelService *service,
/**
* camel_session_get_password:
- * @session: session object
- * @service: the service this query is being made by
+ * @session: a #CamelSession object
+ * @service: the #CamelService this query is being made by
* @domain: domain of password request. May be null to use the default.
* @prompt: prompt to provide to user
* @item: an identifier, unique within this service, for the information
- * @flags: CAMEL_SESSION_PASSWORD_REPROMPT, the prompt should force a reprompt
- * CAMEL_SESSION_PASSWORD_SECRET, whether the password is secret
- * CAMEL_SESSION_PASSWORD_STATIC, the password is remembered externally
- * @ex: a CamelException
+ * @flags: #CAMEL_SESSION_PASSWORD_REPROMPT, the prompt should force a reprompt
+ * #CAMEL_SESSION_PASSWORD_SECRET, whether the password is secret
+ * #CAMEL_SESSION_PASSWORD_STATIC, the password is remembered externally
+ * @ex: a #CamelException
*
- * This function is used by a CamelService to ask the application and
+ * This function is used by a #CamelService to ask the application and
* the user for a password or other authentication data.
*
* @service and @item together uniquely identify the piece of data the
* caller is concerned with.
*
* @prompt is a question to ask the user (if the application doesn't
- * already have the answer cached). If CAMEL_SESSION_PASSWORD_SECRET
+ * already have the answer cached). If #CAMEL_SESSION_PASSWORD_SECRET
* is set, the user's input will not be echoed back.
*
- * If CAMEL_SESSION_PASSWORD_STATIC is set, it means the password returned
+ * If #CAMEL_SESSION_PASSWORD_STATIC is set, it means the password returned
* will be stored statically by the caller automatically, for the current
* session.
*
- * The authenticator
- * should set @ex to %CAMEL_EXCEPTION_USER_CANCEL if the user did not
- * provide the information. The caller must g_free() the information
- * returned when it is done with it.
+ * The authenticator should set @ex to #CAMEL_EXCEPTION_USER_CANCEL if
+ * the user did not provide the information. The caller must #g_free
+ * the information returned when it is done with it.
*
- * Return value: the authentication information or %NULL.
+ * Returns the authentication information or %NULL
**/
char *
camel_session_get_password (CamelSession *session, CamelService *service,
/**
* camel_session_forget_password:
- * @session: session object
- * @service: the service rejecting the password
+ * @session: a #CamelSession object
+ * @service: the #CamelService rejecting the password
* @item: an identifier, unique within this service, for the information
- * @ex: a CamelException
+ * @ex: a #CamelException
*
- * This function is used by a CamelService to tell the application
+ * This function is used by a #CamelService to tell the application
* that the authentication information it provided via
- * camel_session_get_password was rejected by the service. If the
+ * #camel_session_get_password was rejected by the service. If the
* application was caching this information, it should stop,
* and if the service asks for it again, it should ask the user.
*
* @service and @item identify the rejected authentication information,
- * as with camel_session_get_password.
+ * as with #camel_session_get_password.
**/
void
camel_session_forget_password (CamelSession *session, CamelService *service,
/**
* camel_session_alert_user:
- * @session: session object
+ * @session: a #CamelSession object
* @type: the type of alert (info, warning, or error)
* @prompt: the message for the user
* @cancel: whether or not to provide a "Cancel" option in addition to
* @type. If @cancel is %TRUE, the user will be able to accept or
* cancel. Otherwise, the message is purely informational.
*
- * Return value: %TRUE if the user accepts, %FALSE if they cancel.
+ * Returns %TRUE if the user accepts, %FALSE if they cancel.
*/
gboolean
camel_session_alert_user (CamelSession *session, CamelSessionAlertType type,
/**
* camel_session_is_online:
- * @session: the session.
+ * @session: a #CamelSession object
*
- * Return value: whether or not @session is online.
+ * Returns whether or not @session is online
**/
gboolean
camel_session_is_online (CamelSession *session)
/**
* camel_session_set_online:
- * @session: the session
+ * @session: a #CamelSession object
* @online: whether or not the session should be online
*
* Sets the online status of @session to @online.
/**
* camel_session_get_filter_driver:
- * @session: the session
+ * @session: a #CamelSession object
* @type: the type of filter (eg, "incoming")
- * @ex: a CamelException
+ * @ex: a #CamelException
*
- * Return value: a filter driver, loaded with applicable rules
+ * Returns a filter driver, loaded with applicable rules
**/
CamelFilterDriver *
camel_session_get_filter_driver (CamelSession *session,
/**
* camel_session_thread_msg_new:
- * @session:
- * @ops:
- * @size:
+ * @session: a #CamelSession object
+ * @ops: thread operations
+ * @size: number of bytes
*
* Create a new thread message, using ops as the receive/reply/free
* ops, of @size bytes.
*
* @ops points to the operations used to recieve/process and finally
* free the message.
+ *
+ * Returns a new #CamelSessionThreadMsg
**/
-void *camel_session_thread_msg_new(CamelSession *session, CamelSessionThreadOps *ops, unsigned int size)
+void *
+camel_session_thread_msg_new(CamelSession *session, CamelSessionThreadOps *ops, unsigned int size)
{
g_assert(CAMEL_IS_SESSION(session));
g_assert(ops != NULL);
/**
* camel_session_thread_msg_free:
- * @session:
- * @msg:
+ * @session: a #CamelSession object
+ * @msg: a #CamelSessionThreadMsg
*
* Free a @msg. Note that the message must have been allocated using
* msg_new, and must nto have been submitted to any queue function.
**/
-void camel_session_thread_msg_free(CamelSession *session, CamelSessionThreadMsg *msg)
+void
+camel_session_thread_msg_free(CamelSession *session, CamelSessionThreadMsg *msg)
{
g_assert(CAMEL_IS_SESSION(session));
g_assert(msg != NULL);
/**
* camel_session_thread_queue:
- * @session:
- * @msg:
+ * @session: a #CamelSession object
+ * @msg: a #CamelSessionThreadMsg
* @flags: queue type flags, currently 0.
*
* Queue a thread message in another thread for processing.
* The operation should be (but needn't) run in a queued manner
* with other operations queued in this manner.
*
- * Return value: The id of the operation queued.
+ * Returns the id of the operation queued
**/
-int camel_session_thread_queue(CamelSession *session, CamelSessionThreadMsg *msg, int flags)
+int
+camel_session_thread_queue(CamelSession *session, CamelSessionThreadMsg *msg, int flags)
{
g_assert(CAMEL_IS_SESSION(session));
g_assert(msg != NULL);
/**
* camel_session_thread_wait:
- * @session:
- * @id:
+ * @session: a #CamelSession object
+ * @id: id of the operation to wait on
*
* Wait on an operation to complete (by id).
**/
-void camel_session_thread_wait(CamelSession *session, int id)
+void
+camel_session_thread_wait(CamelSession *session, int id)
{
g_assert(CAMEL_IS_SESSION(session));
/**
* camel_session_check_junk:
- * @session:
+ * @session: a #CamelSession object
*
* Do we have to check incoming messages to be junk?
+ *
+ * Returns whether or not we are checking incoming messages for junk
**/
gboolean
camel_session_check_junk (CamelSession *session)
/**
* camel_session_set_check_junk:
- * @session:
- * @check_junk:
+ * @session: a #CamelSession object
+ * @check_junk: state
*
* Set check_junk flag, if set, incoming mail will be checked for being junk.
**/
*
* Parses @url_string relative to @base.
*
- * Return value: a parsed CamelURL.
+ * Returns a parsed #CamelURL
**/
CamelURL *
camel_url_new_with_base (CamelURL *base, const char *url_string)
/**
* camel_url_new:
- * @url_string: a URL
- * @ex: a CamelException
+ * @url_string: a URL string
+ * @ex: a #CamelException
*
* Parses an absolute URL.
*
- * Return value: a CamelURL, or %NULL.
+ * Returns a #CamelURL if it can be parsed, or %NULL otherwise
**/
CamelURL *
camel_url_new (const char *url_string, CamelException *ex)
/**
* camel_url_to_string:
- * @url: a CamelURL
- * @flags: additional translation options.
+ * @url: a #CamelURL
+ * @flags: additional translation options
*
- * Return value: a string representing @url, which the caller must free.
+ * Flatten a #CamelURL into a string.
+ *
+ * Returns a string representing @url, which the caller must free
**/
char *
camel_url_to_string (CamelURL *url, guint32 flags)
/**
* camel_url_free:
- * @url: a CamelURL
+ * @url: a #CamelURL
*
- * Frees @url
+ * Frees @url.
**/
void
camel_url_free (CamelURL *url)
url->part = g_strdup (part); \
}
+
+/**
+ * camel_url_set_protocol:
+ * @url: a #CamelURL
+ * @protocol: protocol schema
+ *
+ * Set the protocol of a #CamelURL.
+ **/
DEFINE_CAMEL_URL_SET (protocol)
+
+
+/**
+ * camel_url_set_user:
+ * @url: a #CamelURL
+ * @user: username
+ *
+ * Set the user of a #CamelURL.
+ **/
DEFINE_CAMEL_URL_SET (user)
+
+
+/**
+ * camel_url_set_authmech:
+ * @url: a #CamelURL
+ * @authmech: authentication mechanism
+ *
+ * Set the authmech of a #CamelURL.
+ **/
DEFINE_CAMEL_URL_SET (authmech)
+
+
+/**
+ * camel_url_set_passwd:
+ * @url: a #CamelURL
+ * @passwd: password
+ *
+ * Set the password of a #CamelURL.
+ **/
DEFINE_CAMEL_URL_SET (passwd)
+
+
+/**
+ * camel_url_set_host:
+ * @url: a #CamelURL
+ * @host: hostname
+ *
+ * Set the hostname of a #CamelURL.
+ **/
DEFINE_CAMEL_URL_SET (host)
+
+
+/**
+ * camel_url_set_path:
+ * @url: a #CamelURL
+ * @path: path
+ *
+ * Set the path component of a #CamelURL.
+ **/
DEFINE_CAMEL_URL_SET (path)
+
+
+/**
+ * camel_url_set_query:
+ * @url: a #CamelURL
+ * @query: url query
+ *
+ * Set the query of a #CamelURL.
+ **/
DEFINE_CAMEL_URL_SET (query)
+
+
+/**
+ * camel_url_set_fragment:
+ * @url: a #CamelURL
+ * @fragment: url fragment
+ *
+ * Set the fragment of a #CamelURL.
+ **/
DEFINE_CAMEL_URL_SET (fragment)
+
+/**
+ * camel_url_set_port:
+ * @url: a #CamelURL
+ * @port: port
+ *
+ * Set the port on a #CamelURL.
+ **/
void
camel_url_set_port (CamelURL *url, int port)
{
url->port = port;
}
+
+/**
+ * camel_url_set_param:
+ * @url: a #CamelURL
+ * @name: name of the param to set
+ * @value: value of the param to set
+ *
+ * Set a param on the #CamelURL.
+ **/
void
camel_url_set_param (CamelURL *url, const char *name, const char *value)
{
g_datalist_remove_data(&url->params, name);
}
+
+/**
+ * camel_url_get_param:
+ * @a #CamelURL
+ * @name: name of the param
+ *
+ * Get the value of the specified param on the URL.
+ *
+ * Returns the value of a param if found or %NULL otherwise
+ **/
const char *
camel_url_get_param (CamelURL *url, const char *name)
{
*
* This %-encodes the given URL part and returns the escaped version
* in allocated memory, which the caller must free when it is done.
+ *
+ * Returns the encoded string
**/
char *
camel_url_encode (const char *part, const char *escape_extra)
&& u1->port == u2->port;
}
+
+/**
+ * camel_url_copy:
+ * @in: a #CamelURL to copy
+ *
+ * Copy a #CamelURL.
+ *
+ * Returns a duplicate copy of @in
+ **/
CamelURL *
camel_url_copy(const CamelURL *in)
{
projects / platform / upstream / evolution-data-server.git / commitdiff