Haiku Book: Added MailAttachment, MailDaemon and mail_encoding
Modified book, MailComponent and TextMailComponent to add libmail group. Change-Id: I958ff0188c5ae33745bff061ee24e80d5af7845f Reviewed-on: https://review.haiku-os.org/c/haiku/+/8683 Reviewed-by: Adrien Destugues <[email protected]>
This commit is contained in:
cafeina
committed by
Adrien Destugues
Adrien Destugues
parent
f3ba3dd008
commit
0681754858
@@ -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 /////
|
||||
|
||||
@@ -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
|
||||
<a href="https://www.ietf.org/rfc/rfc822.txt">RFC-822</a> 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
|
||||
<a href="https://www.ietf.org/rfc/rfc822.txt">RFC-822</a> 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
|
||||
*/
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
<a href="https://www.rfc-editor.org/rfc/rfc2045.html">RFC 2045</a>.
|
||||
"uuencode" content format is as defined in the
|
||||
<a href="https://pubs.opengroup.org/onlinepubs/9799919799/utilities/uuencode.html">POSIX</a>
|
||||
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
|
||||
*/
|
||||
|
||||
|
||||
Reference in New Issue
Block a user