diff --git a/docs/user/book.dox b/docs/user/book.dox index aa8edc312d..bfb88445bf 100644 --- a/docs/user/book.dox +++ b/docs/user/book.dox @@ -578,6 +578,8 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE); \defgroup libdevice Device Kit library (libdevice.so) + \defgroup libmail Mail Kit library (libmail.so) + */ ///// Subgroups ///// diff --git a/docs/user/mail/MailAttachment.dox b/docs/user/mail/MailAttachment.dox new file mode 100644 index 0000000000..0eb13226ed --- /dev/null +++ b/docs/user/mail/MailAttachment.dox @@ -0,0 +1,665 @@ +/* + * Copyright 2024 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * cafeina, cafeina@world + * + * Corresponds to: + * headers/os/mail/MailAttachment.h hrev58367 + * src/kits/mail/MailAttachment.cpp hrev58367 + */ + + +/*! + \file MailAttachment.h + \ingroup mail + \ingroup libmail + \brief Provides the BMailAttachment abstract class, as well as the derived + classes BSimpleMailAttachment and BAttributedMailAttachment. +*/ + + +///// BMailAttachment ///// + + +/*! + \class BMailAttachment + \ingroup mail + \ingroup libmail + \brief Abstract interface for objects that handle mail attachments. + + \since Haiku R1 +*/ + + +/*! + \name Attachment's filename +*/ + + +//! @{ + + +/*! + \fn virtual void BMailAttachment::SetFileName(const char *name) = 0 + \brief Pure virtual to change the filename of the attachment. + + \param[in] name The new filename string. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BMailAttachment::FileName(char *name) = 0 + \brief Pure virtual to return the filename of the attachment. + + \param[out] name A pre-allocated variable of \c B_FILE_NAME_LENGTH length + where to write the filename. + + \return A status code. + + \since Haiku R1 +*/ + + +//! @} + + +/*! + \fn virtual status_t BMailAttachment::SetTo(BFile *file, bool deleteFileWhenDone = false) = 0 + \brief Pure virtual to initialize the object's attached file. + + \param[in] file A file for the attachment's data. + \param[in] deleteFileWhenDone Tells if the file has to be deleted when + this object is destroyed. + + \return A status code. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BMailAttachment::SetTo(entry_ref *ref) = 0 + \brief Pure virtual to initialize the object's attached file. + + \param[in] ref An entry_ref for the attachment's data. + + \return A status code. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BMailAttachment::InitCheck() = 0 + \brief Pure virtual to check if the object was successfully initialized. + + \return A status code. + + \since Haiku R1 +*/ + + +///// BSimpleMailAttachment ///// + +/*! + \class BSimpleMailAttachment + \ingroup mail + \ingroup libmail + \brief Represents a basic mail attachment. + + \since Haiku R1 +*/ + + +/*! + \fn BSimpleMailAttachment::BSimpleMailAttachment(BPositionIO *dataToAttach, mail_encoding encoding = base64) + \brief Creates and initializes an attachment object from a BPositionIO + based data stream. + + \param[in] dataToAttach The data to attach. + \param[in] encoding The encoding format to use in the attachment object. + + \since Haiku R1 +*/ + + +/*! + \fn BSimpleMailAttachment::BSimpleMailAttachment(const void *dataToAttach, size_t lengthOfData, mail_encoding encoding = base64) + \brief Creates and initializes an attachment object from a buffer. + + This constructor takes ownership of the data. This means that the data is + deleted upon new calls of SetDecodedData() and when the object is destroyed + as well. + + \param[in] dataToAttach A buffer for the attachment data. + \param[in] lengthOfData The buffer length. + \param[in] encoding The encoding format to use in the attachment object. + + \since Haiku R1 +*/ + + +/*! + \fn BSimpleMailAttachment::BSimpleMailAttachment(BFile *file, bool delete_when_done) + \brief Creates and initializes an attachment object from a file. + + \param[in] file A file for the attachment. + \param[in] delete_when_done Tells if the file has to be deleted when + this object is destroyed. + + \sa SetTo(BFile*, bool) + + \since Haiku R1 +*/ + + +/*! + \fn BSimpleMailAttachment::BSimpleMailAttachment(entry_ref *ref) + \brief Creates and initializes an attachment object from a filesystem entry. + + \param[in] ref The filesystem entry from where to retrieve the attachment's data. + + \sa SetTo(entry_ref*) + + \since Haiku R1 +*/ + + +/*! + \fn BSimpleMailAttachment::BSimpleMailAttachment() + \brief Creates an uninitialized BSimpleMailAttachment object. + + It can be later be initialized with either SetTo(BFile*, bool) or + SetTo(entry_ref *). + + \since Haiku R1 +*/ + + +/*! + \fn virtual BSimpleMailAttachment::~BSimpleMailAttachment() + \brief Frees all resources associated with this object. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BSimpleMailAttachment::SetTo(BFile *file, bool delete_file_when_done = false) + \brief Initializes the object to the specified \a file. + + \param[in] file A file for the attachment. + \param[in] delete_file_when_done Tells if the file has to be deleted when + this object is destroyed. + + \return \c B_OK on success or an error code otherwise. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BSimpleMailAttachment::SetTo(entry_ref *ref) + \brief Initializes the object to the specified entry_ref. + + \param[in] ref The entry_ref for the attachment's data. + + \return \c B_OK on success or an error code otherwise. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BSimpleMailAttachment::InitCheck() + \brief Checks whether the object has been properly initialized or not. + + \return \c B_OK if the object has been properly initialized, or + \c B_NO_INIT otherwise. + + \since Haiku R1 +*/ + + +/*! + \name Attachment's filename +*/ + + +//! @{ + + +/*! + \fn virtual void BSimpleMailAttachment::SetFileName(const char *name) + \brief Changes the attachment's filename. + + \param[in] name The new filename string for the attachment. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BSimpleMailAttachment::FileName(char *name) + \brief Returns the attachment's filename. + + \param[out] name A pre-allocated variable of \c B_FILE_NAME_LENGTH length + where to write the filename. + + \retval B_OK The filename was retrieved successfully. + \retval B_NAME_NOT_FOUND The filename could not be found. + + \since Haiku R1 +*/ + + +//! @} + + +/*! + \name Attachment's data +*/ + + +//! @{ + + +/*! + \fn virtual status_t BSimpleMailAttachment::GetDecodedData(BPositionIO *data) + \brief Converts the attachment's encoded data back to its unencoded form and + writes the result into \a data. + + \param[out] data A BPositionIO based data stream where to write the + output data. + + \retval B_OK The attachment's data was written into \a data successfully. + \retval B_IO_ERROR There is internally no data associated with this + attachment. + \retval B_BAD_VALUE \a data is invalid. + + \since Haiku R1 +*/ + + +/*! + \fn virtual BPositionIO *BSimpleMailAttachment::GetDecodedData() + \brief Decodes the attachment's encoded data and returns the result + to a BPositionIO based data stream. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BSimpleMailAttachment::SetDecodedData(BPositionIO *data) + \brief Sets the attachment's content to \a data. + + \param[in] data The data stream from where the data will be copied. + + \retval B_OK No error. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BSimpleMailAttachment::SetDecodedData(const void *data, size_t length) + \brief Sets the attachment's content to the contents in the \a data generic + buffer of \a length. + + This overloaded version takes ownership of the data buffer, so the data is + deleted upon new calls of SetDecodedData() and when the object is destroyed + as well. + + \param[in] data The buffer from where obtain the new contents of the + attachment. + \param[in] length The buffer's length. + + \retval B_OK No error. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BSimpleMailAttachment::SetDecodedDataAndDeleteWhenDone(BPositionIO *data) + \brief Sets the attachment's content to the contents contained in \a data. + + This method takes ownership of the data buffer, so the data is + deleted upon new calls of SetDecodedData() and when the object is destroyed + as well. + + \param[in] data The source from where obtain the new contents of the + attachment. + + \retval B_OK No error. + + \since Haiku R1 +*/ + + +//! @} + + +/*! + \name Encoding +*/ + + +//! @{ + + +/*! + \fn void BSimpleMailAttachment::SetEncoding(mail_encoding encoding = base64) + \brief Sets the Content-Transfer-Encoding header to \a encoding. + + \since Haiku R1 +*/ + + +/*! + \fn mail_encoding BSimpleMailAttachment::Encoding() + \brief Returns the current Content-Transfer-Encoding header value. + + \since Haiku R1 +*/ + + +//! @} + + +/*! + \fn virtual status_t BSimpleMailAttachment::SetToRFC822(BPositionIO *data, size_t length, bool parse_now = false) + \brief Sets this object from a \a data stream in a + RFC-822 compliant format. + + Initializes this component to the RFC 822 format data in \a data, starting at + \c data->Position(), for up to \a length bytes. + + If \a parse_now is \c false, then the data will not be parsed (encoded) until + RenderToRFC822() is called. + + \param[in] data The data source. + \param[in] length The data's length. + \param[in] parse_now Whether the data will be parsed now or not. + + \retval B_OK The operation was performed successfully. + \retval B_ERROR Error in MIME headers' length. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BSimpleMailAttachment::RenderToRFC822(BPositionIO *render_to) + \brief Renders the component into RFC-822 format. + + \return \c B_OK if everything was performed successfully, or an error code + otherwise. + + \since Haiku R1 +*/ + + +///// BAttributedMailAttachment ///// + + +/*! + \class BAttributedMailAttachment + \ingroup mail + \ingroup libmail + \brief Represents an mail attachment compatible with Be File System attributes. + + This class builds a multipart container where the attached file is copied + alongside its Be File System attributes, allowing to send or receive files + without losing those filesystem attributes. + + \since Haiku R1 +*/ + + +/*! + \fn BAttributedMailAttachment::BAttributedMailAttachment() + \brief Creates an uninitialized BAttributedMailAttachment object. + + It can be later be initialized with either SetTo(BFile*, bool) or + SetTo(entry_ref *). + + \since Haiku R1 +*/ + + +/*! + \fn BAttributedMailAttachment::BAttributedMailAttachment(BFile *file, bool delete_when_done) + \brief Creates and initializes an attachment object from a file. + + \param[in] file A file to be used for the attachment. + \param[in] delete_when_done Tells if the file has to be deleted when + this object is destroyed. + + \sa SetTo(BFile*, bool) + + \since Haiku R1 +*/ + + +/*! + \fn BAttributedMailAttachment::BAttributedMailAttachment(entry_ref *ref) + \brief Creates and initializes an attachment object from a filesystem entry. + + \param[in] ref The filesystem entry from where to retrieve the attachment's data. + + \sa SetTo(entry_ref*) + + \since Haiku R1 +*/ + + +/*! + \fn virtual BAttributedMailAttachment::~BAttributedMailAttachment() + \brief Frees all resources associated with this object. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BAttributedMailAttachment::SetTo(BFile *file, bool delete_file_when_done = false) + \brief Initializes the object to the specified \a file. + + \param[in] file A file to be used for the attachment. + \param[in] delete_file_when_done Tells if the file has to be deleted when + this object is destroyed. + + \return \c B_OK on success or an error code otherwise. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BAttributedMailAttachment::SetTo(entry_ref *ref) + \brief Initializes the object to the specified entry_ref. + + \param[in] ref An entry_ref for the attachment's data. + + \return \c B_OK on success or an error code otherwise. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BAttributedMailAttachment::InitCheck() + \brief Checks whether the object has been properly initialized or not. + + \return \c B_OK if the object has been properly initialized, or + \c B_NO_INIT otherwise. + + \since Haiku R1 +*/ + + +/*! + \fn void BAttributedMailAttachment::SaveToDisk(BEntry* entry) + \brief Stores the attachment's decoded data in a temporary file on disk. + + The file path will be saved to \a entry. + + \param[out] entry A pre-allocated BEntry where to write the + temporary file path. + + \since Haiku R1 +*/ + + +/*! + \name Encoding +*/ + + +//! @{ + + +/*! + \fn void BAttributedMailAttachment::SetEncoding(mail_encoding encoding) + \brief Sets the Content-Transfer-Encoding header to \a encoding. + + \since Haiku R1 +*/ + + +/*! + \fn mail_encoding BAttributedMailAttachment::Encoding() + \brief Returns the current Content-Transfer-Encoding header value. + + \since Haiku R1 +*/ + +//! @} + + +/*! + \name Attachment's filename +*/ + + +//! @{ + + +/*! + \fn virtual void BAttributedMailAttachment::SetFileName(const char *name) + \brief Changes the attachment's filename. + + \param[in] name The new filename string for the attachment. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BAttributedMailAttachment::FileName(char *name) + \brief Returns the attachment's filename. + + \param[out] name A pre-allocated variable of \c B_FILE_NAME_LENGTH length + where to write the filename. + + \retval B_OK The filename was retrieved successfully. + \retval B_NAME_NOT_FOUND The filename could not be found. + + \since Haiku R1 +*/ + + +//! @} + + +/*! + \name Attachment's data +*/ + + +//! @{ + + +/*! + \fn virtual status_t BAttributedMailAttachment::GetDecodedData(BPositionIO *data) + \brief Retrieves the attachment's decoded data with its attributes and + writes them into \a data. + + \param[out] data A BPositionIO based data stream where to write the + output data. + + \retval B_OK The decoded data and attributes were retrieved successfully. + \retval B_IO_ERROR There is internally no data associated with this + attachment. + \retval B_BAD_VALUE \a data is invalid. + + \since Haiku R1 +*/ + +/*! + \fn virtual status_t BAttributedMailAttachment::SetDecodedData(BPositionIO *data) + \brief Sets the attachment's attributes and data to \a data. + + \param[in] data The data stream from where the data and the attributes will + be copied. + + \retval B_OK No error. + + \since Haiku R1 +*/ + + +//! @} + + +/*! + \fn virtual status_t BAttributedMailAttachment::SetToRFC822(BPositionIO *data, size_t length, bool parse_now = false) + \brief Sets this object from a \a data stream in a + RFC-822 compliant format. + + Initializes this component to the RFC 822 format data in \a data, starting at + \c data->Position(), for up to \a length bytes. + + If \a parse_now is \c false, then the data will not be parsed until + RenderToRFC822() is called. + + \param[in] data The data source. + \param[in] length The data's length. + \param[in] parse_now Whether the data will be parsed now or not. + + \retval B_OK The operation was performed successfully. + \retval B_BAD_TYPE The underlying multipart container mimetype is invalid. + \retval B_BAD_VALUE The data and attributes are \c NULL. + \retval B_NO_MEMORY Not enough memory to decode the attachment's attributes. + \retval B_IO_ERROR Input/output error retrieving the attributes' data. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BAttributedMailAttachment::RenderToRFC822(BPositionIO *render_to) + \brief Renders the component into RFC-822 format. + + \return \c B_OK if everything was performed successfully, or an error code + otherwise. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BAttributedMailAttachment::MIMEType(BMimeType *mime) + \brief Places the MIME type of the data into \a mime. + + \param[out] mime A pre-allocated BMimeType variable where to write + the mimetype. + + \since Haiku R1 +*/ diff --git a/docs/user/mail/MailComponent.dox b/docs/user/mail/MailComponent.dox index 6c9fa8a1c0..7001012e1a 100644 --- a/docs/user/mail/MailComponent.dox +++ b/docs/user/mail/MailComponent.dox @@ -15,6 +15,7 @@ /*! \file MailComponent.h \ingroup mail + \ingroup libmail \brief Provides the BMailComponent and BTextMailComponent classes. */ @@ -68,6 +69,7 @@ /*! \class BMailComponent \ingroup mail + \ingroup libmail \brief The base class for most of the Mail Kit. Note that BMailComponent is not abstract, and is useful diff --git a/docs/user/mail/MailDaemon.dox b/docs/user/mail/MailDaemon.dox new file mode 100644 index 0000000000..0f569f9fc9 --- /dev/null +++ b/docs/user/mail/MailDaemon.dox @@ -0,0 +1,196 @@ +/* + * Copyright 2024 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * cafeina, cafeina@world + * + * Corresponds to: + * headers/os/mail/MailDaemon.h hrev58367 + * src/kits/mail/MailDaemon.cpp hrev58367 + */ + + +/*! + \file MailDaemon.h + \ingroup mail + \ingroup libmail + \brief Provides the BMailDaemon class. +*/ + + +/*! + \class BMailDaemon + \ingroup mail + \ingroup libmail + \brief Provides user level access to the mail_daemon to perform common + mail tasks such as check for new messages or send queued messages. + + \since Haiku R1 +*/ + + +/*! + \fn BMailDaemon::BMailDaemon() + \brief Creates a BMailDaemon object that communicates with the + mail_daemon server. + + \since Haiku R1 +*/ + + +/*! + \fn virtual BMailDaemon::~BMailDaemon() + \brief Frees all resources associated with this object. + + \since Haiku R1 +*/ + + +/*! + \name Mail tasks +*/ + + +//! @{ + + +/*! + \fn status_t BMailDaemon::CheckMail(int32 accountID = -1) + \brief Asks the mail_daemon to check if there are new messages for the + account with ID \a accountID. + + If \a accountID is \c -1, it will check for new messages for all + the available accounts. + + \param[in] accountID The ID of the account. + + \retval B_OK The request has been sent successfully. + \retval B_MAIL_NO_DAEMON The mail_daemon is not currently running. + + \since Haiku R1 +*/ + + +/*! + \fn status_t BMailDaemon::CheckAndSendQueuedMail(int32 accountID = -1) + \brief Asks the mail_daemon to check if there are new messages and + to send any queued messages pending to be sent, for the + account with ID \a accountID. + + If \a accountID is \c -1, it will check for new messages and send the + queued messages for all the available accounts. + + \param[in] accountID The ID of the account. + + \retval B_OK The request has been sent successfully. + \retval B_MAIL_NO_DAEMON The mail_daemon is not currently running. + + \since Haiku R1 +*/ + + +/*! + \fn status_t BMailDaemon::SendQueuedMail() + \brief Asks the mail_daemon to send any queued message pending to be sent. + + \retval B_OK The request has been sent successfully. + \retval B_MAIL_NO_DAEMON The mail_daemon is not currently running. + + \since Haiku R1 +*/ + + +/*! + \fn int32 BMailDaemon::CountNewMessages(bool waitForFetchCompletion = false) + \brief Asks the mail_daemon how many new messages there are. + + \param[in] waitForFetchCompletion If \c true, it will make the count + once the mail server fetching is completed. + + \return The number of new messages, or \c B_MAIL_NO_DAEMON if the + mail_daemon is not currently running. + + \since Haiku R1 +*/ + + +/*! + \fn status_t BMailDaemon::MarkAsRead(int32 account, const entry_ref& ref, read_flags flag = B_READ) + \brief Requests the mail_daemon to mark an e-mail message as read + or unread. + + \param[in] account The account's ID. + \param[in] ref The entry_ref of the target message. + \param[in] flag Can be one of these: \c B_UNREAD, \c B_SEEN, \c B_READ. + + \retval B_OK The request has been sent successfully. + \retval B_MAIL_NO_DAEMON The mail_daemon is not currently running. + + \since Haiku R1 +*/ + + +/*! + \fn status_t BMailDaemon::FetchBody(const entry_ref& ref, BMessenger* listener = NULL) + \brief Requests the mail_daemon to retrieve the message's body. + + If \a listener is not \c NULL, it will receive a \c B_MAIL_BODY_FETCHED + notification after the e-mail message's body was fetched successfully, or else + an error code if something went wrong. + + \param[in] ref The entry_ref of the target message. + \param[in] listener A BMessenger where a reply will be sent to. + + \retval B_OK The request has been sent successfully. + \retval B_MAIL_NO_DAEMON The mail_daemon is not currently running. + + \since Haiku R1 +*/ + + +//! @} + + +/*! + \name Running status +*/ + + +//! @{ + + +/*! + \fn status_t BMailDaemon::Launch() + \brief Launches the mail_daemon. + + \retval B_OK The mail_daemon has been launched successfully. + \retval B_ALREADY_RUNNING The mail_daemon is already running. + + \since Haiku R1 +*/ + + +/*! + \fn bool BMailDaemon::IsRunning() + \brief Checks if the mail_daemon is running. + + \retval true The mail_daemon is running. + \retval false The mail_daemon is not running. + + \since Haiku R1 +*/ + + +/*! + \fn status_t BMailDaemon::Quit() + \brief Request the mail_daemon to quit. + + \retval B_OK The request has been sent successfully. + \retval B_MAIL_NO_DAEMON The mail_daemon is not currently running. + + \since Haiku R1 +*/ + +//! @} + diff --git a/docs/user/mail/TextMailComponent.dox b/docs/user/mail/TextMailComponent.dox index 1b0953e1eb..65876991bc 100644 --- a/docs/user/mail/TextMailComponent.dox +++ b/docs/user/mail/TextMailComponent.dox @@ -15,6 +15,7 @@ /*! \class BTextMailComponent \ingroup mail + \ingroup libmail \brief A component that stores plain text. It uses UTF8 text as its canonical format and reads and writes diff --git a/docs/user/mail/mail_encoding.dox b/docs/user/mail/mail_encoding.dox new file mode 100644 index 0000000000..f3892740cb --- /dev/null +++ b/docs/user/mail/mail_encoding.dox @@ -0,0 +1,308 @@ +/* + * Copyright 2024 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * cafeina, cafeina@world + * + * Corresponds to: + * headers/os/mail/mail_encoding.h hrev58367 + * src/kits/mail/mail_encoding.cpp hrev58367 + * src/kits/support/Base64.cpp hrev58367 + */ + +/*! + \file mail_encoding.h + \ingroup mail + \ingroup libmail + \brief Provides tools to convert data to or from a content encoding format. + + The "7bit" and "8bit" encodings do not perform a binary-to-text + conversion but copy the input data into an output buffer. "base64" and + "quoted-printable" are as defined in + RFC 2045. + "uuencode" content format is as defined in the + POSIX + specification. +*/ + + +/*! + \def B_MAIL_NULL_CONVERSION + \brief Do not specify a character set for converting, rely on + autodetection instead. + + \since Haiku R1 +*/ + + +/*! + \def B_MAIL_UTF8_CONVERSION + \brief Specifies the UTF-8 character set when converting from or to UTF-8. + + \since Haiku R1 +*/ + + +/*! + \def B_MAIL_US_ASCII_CONVERSION + \brief Specifies the 7bit ASCII character set (a subset of UTF-8) when + converting from or to 7bit. + + \since Haiku R1 +*/ + + +/*! + \fn mail_encoding::base64 + \brief Base64 binary-to-text encoding. + + \since Haiku R1 +*/ + + +/*! + \fn mail_encoding::quoted_printable + \brief quoted-printable binary-to-text encoding. + + \since Haiku R1 +*/ + + +/*! + \fn mail_encoding::seven_bit + \brief 7bit encoding. + + \since Haiku R1 +*/ + + +/*! + \fn mail_encoding::eight_bit + \brief 8bit encoding. + + \since Haiku R1 +*/ + + +/*! + \fn mail_encoding::uuencode + \brief uuencode binary-to-text encoding. + + \since Haiku R1 +*/ + + +/*! + \fn mail_encoding::null_encoding + \brief Used to indicate the encoding, will not be changed. + + \since Haiku R1 +*/ + + +/*! + \fn mail_encoding::no_encoding + \brief Represents an undefined encoding or no encoding at all. + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t encode(mail_encoding encoding, char *out, const char *in, + off_t length, int headerMode) + \brief Encodes data to a content encoding. + + Converts an arbitrary input data \a in of \a length bytes as \a encoding + into \a out. + + This wrapper function can be used to convert to base64 or quoted-printable, + or in the case of using 7bit, 8bit or \c no_encoding, to copy the data from + \a in to \a out. However, it is unable to convert the data to uuencode. + + \a headerMode is used when the output will be used in a header, + and is only used for conversions to quoted-printable or base64, + ignored otherwise. + + \param[in] encoding Target encoding. + \param[out] out Where the output data will be written to. + \param[in] in Input data. + \param[in] length Input data's length. + \param[in] headerMode Whether the output data will be used in + a header or not. + + \return The amount of bytes written, or \c -1 if the encoding is + not compatible nor recognized. + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t decode(mail_encoding encoding, char *out, const char *in, off_t length, int underscore_is_space) + \brief Decodes data from a certain encoding. + + Takes an input data \a in of \a length bytes and converts it back from + \a encoding to its unencoded form into \a out. + + This wrapper function can be used to convert an input data in base64, + quoted-printable or uuencoding formats to its original form. However, if + \a encoding is not recognized, it will not perform any operation and will + return \c -1. On the other hand, if \a encoding is equal to \c seven_bit, + \c eight_bit or \c no_encoding, it will just make a copy of the data. + + \a underscore_is_space is only useful when converting from quoted-printable + encoding, when the data is going to be decoded from a header field. + + \param[in] encoding Input data's encoding. + \param[out] out Where the resulting data will be written to. + \param[in] in Input data. + \param[in] length Input data's length. + \param[in] underscore_is_space Should be equal to \c 1 to indicate when + decoding a header field. + + \return The amount of bytes written, or \c -1 if the encoding is + not compatible nor recognized. + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t max_encoded_length(mail_encoding encoding, off_t cur_length) + \brief Returns the output size of a certain encoding, given + an input data has \a cur_length of length. + + It can perform the calculation for base64, quoted-printable, 7bit and 8bit. + If \a encoding is equal to \c no_encoding, it will just return the same + value as \a cur_length. However, this function cannot perform the + calculation for uuencode. + + \param[in] encoding The target encoding. + \param[in] cur_length The input data's length. + + \return The amount of bytes the conversion to \a encoding + will take if the input data is of \a cur_length, or \c -1 if + the encoding is not compatible nor recognized. + + \since Haiku R1 +*/ + + +/*! + \fn mail_encoding encoding_for_cte(const char *content_transfer_encoding) + \brief Returns a mail_encoding value for the \a content_transfer_encoding + string. + + \param[in] content_transfer_encoding A string with the name of the encoding: + \n- \c "uuencode" for mail_encoding::uuencode + \n- \c "base64" for mail_encoding::base64 + \n- \c "quoted-printable" for mail_encoding::quoted_printable + \n- \c "7bit" for mail_encoding::seven_bit + \n- \c "8bit" for mail_encoding::eight_bit + \n- Other strings or if \a content_transfer_encoding is \c NULL + return mail_encoding::no_encoding + + \return A mail_encoding value. + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t encode_base64(char *out, const char *in, off_t length, int headerMode) + \brief Encodes a string to base64. + + Converts an input data \a in of \a length bytes as base64 into \a out. + + \a headerMode is used when the output will be used in a header, where + there should not be any line breaks. + + \param[out] out Where the resulting data will be written to. + \param[in] in Input data. + \param[in] length Input data's length. + \param[in] headerMode Whether the output data will be used in + a header or not. + + \return The amount of bytes written. + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t decode_base64(char *out, const char *in, off_t length) + \brief Decodes a base64 data buffer. + + Takes an input data \a in encoded in base64 of \a length bytes and converts + it back to its unencoded form into \a out. + + \param[out] out Where the output data will be written to. + \param[in] in Input data. + \param[in] length Input data's length. + + \return The amount of bytes written. + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t encode_qp(char *out, const char *in, off_t length, int headerMode) + \brief Encodes an input data to quoted-printable. + + Converts an input data \a in of \a length bytes as quoted-printable into + \a out. + + \a headerMode is used when the output will be used in a header, where + there should not be any line breaks. + + \param[out] out Where the output data will be written to. + \param[in] in Input data. + \param[in] length Input data's length. + \param[in] headerMode Whether the output data will be used in + a header or not. + + \return The amount of bytes written. + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t decode_qp(char *out, const char *in, off_t length, int underscore_is_space) + \brief Decodes a quoted-printable data buffer. + + Takes an input data \a in encoded in quoted-printable of \a length bytes and + converts it back to its unencoded form into \a out. + + \param[out] out Where the output data will be written to. + \param[in] in Input data. + \param[in] length Input data's length. + \param[in] underscore_is_space Should be equal to \c 1 to indicate when + decoding a header field. + + \return The amount of bytes written. + + \since Haiku R1 +*/ + + +/*! + \fn ssize_t uu_decode(char *out, const char *in, off_t length) + \brief Decodes a uuencoded data buffer. + + Takes an input data \a in encoded in uuencode of \a length bytes and + converts it back to its unencoded form into \a out. + + \param[out] out Where the output data will be written to. + \param[in] in Input data. + \param[in] length Input data's length. + + \return The amount of bytes written. + + \since Haiku R1 +*/ + +