docs/user/mail/TextMailComponent.dox

   1 /*
   2  * Copyright 2017 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Augustin Cavalier <waddlesplash>
   7  *              Nathan Whitehorn
   8  *
   9  * Corresponds to:
  10  *              headers/os/mail/MailComponent.h  hrev51708
  11  *              src/kits/mail/MailComponent.cpp  hrev51708
  12  */
  13
  14
  15 /*!
  16         \class BTextMailComponent
  17         \ingroup mail
  18         \brief A component that stores plain text.
  19
  20         It uses UTF8 text as its canonical format and reads and writes
  21         <a href="https://www.ietf.org/rfc/rfc2047.txt">RFC-2047</a> style text. As such,
  22         it handles accents and other 8 bit characters with ease. If you want to
  23         send text, this is the way to go.
  24
  25         \since Haiku R1
  26 */
  27
  28
  29 /*!
  30         \fn BTextMailComponent::BTextMailComponent(const char *text = NULL,
  31                 uint32 defaultCharSet = B_MAIL_NULL_CONVERSION)
  32         \brief Initializes the component and sets its content to \a text.
  33
  34         \a text can be \c NULL. The argument is a UTF-8 null-terminated string.
  35         Encoding defaults to quoted_printable with the ISO-15 charset.
  36
  37         \since Haiku R1
  38 */
  39
  40
  41 /*!
  42         \fn BTextMailComponent::~BTextMailComponent()
  43         \brief Destructor.
  44 */
  45
  46
  47 /*!
  48         \fn void BTextMailComponent::SetEncoding(mail_encoding encoding,
  49                 int32 charset)
  50         \brief Sets the \a encoding and \a charset used by Render().
  51
  52         Use the conversion constants from UTF8.h for \a charset. We strongly
  53         reccomend that you always use the defaults (and strongly recommend
  54         against using base64) for the reasons outlined in RFC 2047.
  55
  56         \since Haiku R1
  57 */
  58
  59
  60 /*!
  61         \fn void BTextMailComponent::SetText(const char *text)
  62         \brief Sets the contents of this component to the UTF8 string \a text.
  63
  64         \since Haiku R1
  65 */
  66
  67
  68 /*!
  69         \fn void BTextMailComponent::AppendText(const char *text)
  70         \brief Appends the UTF8 string \a text to the current contents of this
  71                 component.
  72
  73         \since Haiku R1
  74 */
  75
  76
  77 /*!
  78         \fn const char* BTextMailComponent::Text()
  79         \brief Returns the contents of this component as a UTF8 string.
  80
  81         \since Haiku R1
  82 */
  83
  84
  85 /*!
  86         \fn BString* BTextMailComponent::BStringText()
  87         \brief Returns the internal UTF8 format BString used by this component.
  88
  89         As such, you can do raw text operations on the content of the message.
  90         The use of this function is not reccomended.
  91
  92         \since Haiku R1
  93 */
  94
  95
  96 /*!
  97         \fn void BTextMailComponent::Quote(const char *message = NULL,
  98                 const char *quote_style = "> ")
  99         \brief Quotes the contents of this component.
 100
 101         Inserts \a quote_style at the start of every line, and prefaces the content
 102         with \a message, if it is not \c NULL. \a message should be something like
 103         <code>"On September 30, 2001, John Smith said:"</code>, or something in that vein.
 104         Note that the new line after \a message is supplied for you, so you do not
 105         need to add it.
 106
 107         \since Haiku R1
 108 */
 109
 110
 111 /*!
 112         \fn virtual status_t BTextMailComponent::GetDecodedData(BPositionIO *data)
 113         \brief Retrieves the data contained in this component as a UTF8 string
 114                 into \a data.
 115
 116         \since Haiku R1
 117 */
 118
 119
 120 /*!
 121         \fn virtual status_t BTextMailComponent::SetDecodedData(BPositionIO *data)
 122         \brief Sets the contents of this component to the UTF8 format \a data.
 123
 124         \since Haiku R1
 125 */
 126
 127
 128 /*!
 129         \fn virtual status_t BTextMailComponent::SetToRFC822(BPositionIO *data,
 130                         size_t length, bool parse_now = false)
 131         \brief Sets this object from a component in RFC-822 format.
 132
 133         Initializes this component to the RFC 822 format data in \a data,
 134         starting at <code>data->Position()</code>, for up to \a length bytes.
 135         Handles encoded data according to RFC 2047.
 136
 137         If \a parse_now is \c false, then the \a data will not be parsed
 138         until RenderToRFC822 is called.
 139
 140         \since Haiku R1
 141 */
 142
 143
 144 /*!
 145         \fn virtual status_t BTextMailComponent::RenderToRFC822(BPositionIO* render_to)
 146         \brief Renders the component into RFC-822 format.
 147
 148         It places the result in data, starting at data->Position().
 149         Encodes and translates charsets according to the arguments passed to
 150         SetEncoding(), or the defaults set in BTextMailComponent::BTextMailComponent()
 151         otherwise.
 152
 153         \since Haiku R1
 154 */