From 97f4f2b559a2395fd5031651ed037ea1943f75c1 Mon Sep 17 00:00:00 2001 From: Augustin Cavalier Date: Tue, 26 Dec 2017 13:56:25 -0500 Subject: [PATCH] Migrate the BTextMailComponent docs to the Haiku Book. --- .../mail/Public API/PlainTextBodyComponent.html | 614 --------------------- docs/user/mail/MailComponent.dox | 2 +- docs/user/mail/TextMailComponent.dox | 154 ++++++ 3 files changed, 155 insertions(+), 615 deletions(-) delete mode 100644 docs/apps/mail/Public API/PlainTextBodyComponent.html create mode 100644 docs/user/mail/TextMailComponent.dox diff --git a/docs/apps/mail/Public API/PlainTextBodyComponent.html b/docs/apps/mail/Public API/PlainTextBodyComponent.html deleted file mode 100644 index 3c78c909cf..0000000000 --- a/docs/apps/mail/Public API/PlainTextBodyComponent.html +++ /dev/null @@ -1,614 +0,0 @@ - - - PlainTextBodyComponent - - -

- - - - - -

- - - - -
-
Mail - Kit 2 Root
- -
The - Public API
-
-

- -

- - - -

- -

PlainTextBodyComponent

- -

Derived - from: MailComponent
- Declared in: - include/public/MailComponent.h
- Library: libmail.so
- -

-
- -
PlainTextBodyComponent stores plain text. It uses UTF8 text as - its canonical format and reads and writes RFC 2047 style text. As - such, it handles accents and other 8 bit characters with ease. If - you want to send text, this is the way to go.

- -

Constructor -and -Destructor

- -

- - - - - - -

- -	- PlainTextBodyComponent() -

- -

- - - -
-
- - - -
-
PlainTextBodyComponent(const - char*text - = - NULL)
-
-
-
- -
Initializes the component and sets its content to text, - which can be NULL. The argument is a UTF8 null-terminated string. - Encoding defaults to quoted printable with the ISO-8859-1 - charset.
- -

- -

- - - - - - -

- -	- ~PlainTextBodyComponent() -

- -

- - - -
-
- - - -
-
virtual - ~PlainTextBodyComponent()
-
-
-
- -
Destroys the component and frees internal buffers. Does nothing - of interest.

- -

Member -Functions

- -

- - - - - - -

- -	- GetDecodedData () -

- -

- - - -
-
- - - -
-
virtual status_t - GetDecodedData(BPositionIO - *data)
-
-
-
- -
Retrieves the data contained in this component as a UTF8 string - and places the contents of this string in - data.
- -
Return Value:
- -
- B_OK if everything succeeds. - -
- B_ERROR if something goes wrong.

- -

- - - - - - -

- -	- Text () -

- -

- - - -
-
- - - -
-
const char * - Text()
-
-
-
- -
Returns the contents of this component as a UTF8 - string.

- -

- - - - - - -

- -	- BStringText () -

- -

- - - -
-
- - - -
-
BString * - BStringText()
-
-
-
- -
Returns the internal UTF8 format BString used by this component. - As such, you can do raw text operations on the content of the message. The use of - this function is not reccomended.
- -

- -

- - - - - - -

- -	- Quote () -

- -

- - - -
-
- - - -
-
void - Quote( - const char *message = NULL, - const char *quote_style = "> " - )
-
-
-
- -
Quotes the contents of this component. Inserts quote_style at the start of every line, - and prefaces the content with message, if it is not NULL. message - should be something like "On September 30, 2001, John Smith said:", or something in that vein. Note that the new line after message - is supplied for you, so you do not need to add it.
- -

- -

- - - - - - -

- -	- SetDecodedData () -

- -

- - - -
-
- - - -
-
virtual status_t - SetDecodedData(BPositionIO - *data)
-
-
-
- -
Sets the contents of this component to the UTF8 format data - contained in data.
- -
Return Value:
- -
- B_OK if everything succeeds. - -
- B_ERROR if something goes wrong.

- -

- - - - - - -

- -	- SetText () -

- -

- - - -
-
- - - -
-
void - SetText(const - char *text)
-
-
-
- -
Sets the contents of this component to the UTF8 string - contained in text.

- -

- - - - - - -

- -	- AppendText () -

- -

- - - -
-
- - - -
-
void - AppendText(const - char *text)
-
-
-
- -
Appends text - to the current contents of this component. text - should be a UTF8 string.

- -

- - - - - - -

- -	- SetEncoding () -

- -

- - - -
-
- - - -
-
void - SetEncoding(mail_encoding - encoding, - int32 charset)
-
-
-
- -
Sets the encoding and charset used by Render() - to encoding - and charset, - respectively. Use the conversion constants from UTF8.h for - charset. We - strongly reccomend that you always use the defaults for the - reasons outlined in RFC - 2047.

- -

- - - - - - -

- -	- Instantiate () -

- -

- - - -
-
- - - -
-
virtual status_t - Instantiate(BPositionIO - *data, - size_t length)
-
-
-
- -
Initializes this component to the RFC 822 format data in - data, - starting at data - ->Position(), for up to length - bytes. Handles encoded data according to RFC 2047
- -
Return Value:
- -
- B_OK if everything succeeds. - -
- B_BAD_TYPE if data - does not seem to be plain text.

- -

- - - - - - -

- -	- Render () -

- -

- - - -
-
- - - -
-
virtual status_t - Render(BPositionIO - *data)
-
-
-
- -
Renders the component into RFC 822 format and places the result - in data, - starting at data - ->Position(). Encodes and translates charsets - according to the arguments passed to SetEncoding(). - Encoding defaults to quoted printable and charset to - ISO-8859-1.
- -
Return Value:
- -
- B_OK if everything succeeds.
- -

- -

- - - - - -

- - - - -
-
Mail - Kit 2 Root
- -
The - Public API
-
-

- - -

- -Mail Daemon 2 API -Documentation - -

- - diff --git a/docs/user/mail/MailComponent.dox b/docs/user/mail/MailComponent.dox index b1bf14c71b..6c9fa8a1c0 100644 --- a/docs/user/mail/MailComponent.dox +++ b/docs/user/mail/MailComponent.dox @@ -240,7 +240,7 @@ const char *subject = component->HeaderField("Subject"); and places it into \a data. The various attachments subclasses implement this function to return - decoded data, and \c BPlainTextBodyComponent returns UTF8 text. \c BMailComponent + decoded data, and BTextMailComponent returns UTF8 text. \c BMailComponent implements this function to do nothing and return \c B_OK. \since Haiku R1 diff --git a/docs/user/mail/TextMailComponent.dox b/docs/user/mail/TextMailComponent.dox new file mode 100644 index 0000000000..1b0953e1eb --- /dev/null +++ b/docs/user/mail/TextMailComponent.dox @@ -0,0 +1,154 @@ +/* + * Copyright 2017 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Augustin Cavalier + * Nathan Whitehorn + * + * Corresponds to: + * headers/os/mail/MailComponent.h hrev51708 + * src/kits/mail/MailComponent.cpp hrev51708 + */ + + +/*! + \class BTextMailComponent + \ingroup mail + \brief A component that stores plain text. + + It uses UTF8 text as its canonical format and reads and writes + RFC-2047 style text. As such, + it handles accents and other 8 bit characters with ease. If you want to + send text, this is the way to go. + + \since Haiku R1 +*/ + + +/*! + \fn BTextMailComponent::BTextMailComponent(const char *text = NULL, + uint32 defaultCharSet = B_MAIL_NULL_CONVERSION) + \brief Initializes the component and sets its content to \a text. + + \a text can be \c NULL. The argument is a UTF-8 null-terminated string. + Encoding defaults to quoted_printable with the ISO-15 charset. + + \since Haiku R1 +*/ + + +/*! + \fn BTextMailComponent::~BTextMailComponent() + \brief Destructor. +*/ + + +/*! + \fn void BTextMailComponent::SetEncoding(mail_encoding encoding, + int32 charset) + \brief Sets the \a encoding and \a charset used by Render(). + + Use the conversion constants from UTF8.h for \a charset. We strongly + reccomend that you always use the defaults (and strongly recommend + against using base64) for the reasons outlined in RFC 2047. + + \since Haiku R1 +*/ + + +/*! + \fn void BTextMailComponent::SetText(const char *text) + \brief Sets the contents of this component to the UTF8 string \a text. + + \since Haiku R1 +*/ + + +/*! + \fn void BTextMailComponent::AppendText(const char *text) + \brief Appends the UTF8 string \a text to the current contents of this + component. + + \since Haiku R1 +*/ + + +/*! + \fn const char* BTextMailComponent::Text() + \brief Returns the contents of this component as a UTF8 string. + + \since Haiku R1 +*/ + + +/*! + \fn BString* BTextMailComponent::BStringText() + \brief Returns the internal UTF8 format BString used by this component. + + As such, you can do raw text operations on the content of the message. + The use of this function is not reccomended. + + \since Haiku R1 +*/ + + +/*! + \fn void BTextMailComponent::Quote(const char *message = NULL, + const char *quote_style = "> ") + \brief Quotes the contents of this component. + + Inserts \a quote_style at the start of every line, and prefaces the content + with \a message, if it is not \c NULL. \a message should be something like + "On September 30, 2001, John Smith said:", or something in that vein. + Note that the new line after \a message is supplied for you, so you do not + need to add it. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BTextMailComponent::GetDecodedData(BPositionIO *data) + \brief Retrieves the data contained in this component as a UTF8 string + into \a data. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BTextMailComponent::SetDecodedData(BPositionIO *data) + \brief Sets the contents of this component to the UTF8 format \a data. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BTextMailComponent::SetToRFC822(BPositionIO *data, + size_t length, bool parse_now = false) + \brief Sets this object from a component in RFC-822 format. + + Initializes this component to the RFC 822 format data in \a data, + starting at data->Position(), for up to \a length bytes. + Handles encoded data according to RFC 2047. + + If \a parse_now is \c false, then the \a data will not be parsed + until RenderToRFC822 is called. + + \since Haiku R1 +*/ + + +/*! + \fn virtual status_t BTextMailComponent::RenderToRFC822(BPositionIO* render_to) + \brief Renders the component into RFC-822 format. + + It places the result in data, starting at data->Position(). + Encodes and translates charsets according to the arguments passed to + SetEncoding(), or the defaults set in BTextMailComponent::BTextMailComponent() + otherwise. + + \since Haiku R1 +*/ -- 2.11.4.GIT