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