[haiku-commits] haiku: hrev51709 - API docs/user/mail headers/os/mail

From: waddlesplash@xxxxxxxxx
To: haiku-commits@xxxxxxxxxxxxx
Date: Tue, 26 Dec 2017 01:46:23 +0100 (CET)

hrev51709 adds 1 changeset to branch 'master'
old head: cba277f2f9124a2f311f0538fd6588ad7889b41c
new head: 95c9effd68127df2dce202d5e254a7c86560010a
overview:
http://cgit.haiku-os.org/haiku/log/?qt=range&q=95c9effd6812+%5Ecba277f2f912

----------------------------------------------------------------------------

95c9effd6812: Migrate the BMailComponent docs to the Haiku Book.

 I've updated the docs to match the current BMailComponent, documented
 new functions, and cleaned up the MailComponent.h file to at least
 somewhat match our coding style.

 First in a series (there are 3 more old API docs on the Mail Kit in that
 "Public API" folder.)

 [ Augustin Cavalier <waddlesplash@xxxxxxxxx> ]

----------------------------------------------------------------------------

Revision: hrev51709
Commit: 95c9effd68127df2dce202d5e254a7c86560010a
URL: http://cgit.haiku-os.org/haiku/commit/?id=95c9effd6812
Author: Augustin Cavalier <waddlesplash@xxxxxxxxx>
Date: Tue Dec 26 00:43:51 2017 UTC

----------------------------------------------------------------------------

5 files changed, 346 insertions(+), 816 deletions(-)
docs/apps/mail/Public API/MailComponent.html | 763 -----------------------
docs/user/Doxyfile | 2 +
docs/user/book.dox | 9 +-
docs/user/mail/MailComponent.dox | 287 +++++++++
headers/os/mail/MailComponent.h | 101 ++-

----------------------------------------------------------------------------

diff --git a/docs/apps/mail/Public API/MailComponent.html
b/docs/apps/mail/Public API/MailComponent.html
deleted file mode 100644
index 70a897e..0000000
--- a/docs/apps/mail/Public API/MailComponent.html
+++ /dev/null
@@ -1,763 +0,0 @@
-<HTML>
-<HEAD>
- <TITLE>MailComponent</TITLE>
-</HEAD>
-<BODY BGCOLOR="#FFFFFF" LINK="#2222AA" BACKGROUND="../art/bodyBack.gif">
-<A NAME=BCursor></A> 
-
-<CENTER><TABLE BORDER=2 BGCOLOR="#FFDD88">
- <TR>
- <TD>
- <TABLE BGCOLOR="#550033" CELLPADDING=5>
- <TR>
- <TD>
- <A HREF="../index.html">Mail
- Kit 2 Root</A>
- </TD>
- <TD>
- <A HREF="index.html">The
- Public API</A>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
-</TABLE>
-
-<HR NOSHADE>
-
-</CENTER>
-
-
-
-<H1>MailComponent</H1>
-
-<BLOCKQUOTE>Derived
- from: none 
- Declared in: 
- include/public/MailComponent.h 
- Library: libmail.so 
-
- 
- 
-
- MailComponent is the base class for the vast majority of the
- public Mail Kit. It is, however, important to remember that
- MailComponent is not abstract, and is useful by itself. A
- MailComponent has the important quality of being able to read the
- headers of a message or component without instantiating whatever
- massive quantity of data might lie therein. This is useful
- primarily to determine the kind of data you are dealing with, so
- that the user can make a decision as to whether it should be
- shown.</BLOCKQUOTE>
-
-
-
-<HR NOSHADE>
-
-
-
-<H2>Constructor
-and
-Destructor</H2>
-
-
-
-<HR>
-
-<A NAME=MailComponent></A><TABLE>
- <TR>
- <TD>
- 
- </TD>
- <TD>
- MailComponent()
- 
- </TD>
- </TR>
-</TABLE>
-
-
- 
-
-<BLOCKQUOTE><TABLE BORDER=2 BGCOLOR="#550033" WIDTH=1000>
- <TR>
- <TD>
- <TABLE BORDER=1 BGCOLOR="#FFFFFF" CELLPADDING=8 WIDTH=1000>
- <TR>
- <TD>
- <TT>MailComponent()</TT>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
- </TABLE>
-
- Initializes the MailComponent and does nothing else.
-
-  </BLOCKQUOTE>
-
-
-
-<HR>
-
-<A NAME="~MailComponent"></A><TABLE>
- <TR>
- <TD>
- 
- </TD>
- <TD>
- ~MailComponent()
- 
- </TD>
- </TR>
-</TABLE>
-
-
- 
-
-<BLOCKQUOTE><TABLE BORDER=2 BGCOLOR="#550033" WIDTH=1000>
- <TR>
- <TD>
- <TABLE BORDER=1 BGCOLOR="#FFFFFF" CELLPADDING=8 WIDTH=1000>
- <TR>
- <TD>
- virtual
- <TT>~MailComponent()</TT>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
- </TABLE>
-
- Destroys the MailComponent. Does nothing of interest.</BLOCKQUOTE>
-
-
-
-<HR NOSHADE>
-
-
-
-<H2>Hook
-Functions</H2>
-
-
-
-<HR>
-
-<A NAME=GetDecodedData></A><TABLE>
- <TR>
- <TD>
- 
- </TD>
- <TD>
- GetDecodedData () 
- </TD>
- </TR>
-</TABLE>
-
-
- 
-
-<BLOCKQUOTE><TABLE BORDER=2 BGCOLOR="#550033" WIDTH=1000>
- <TR>
- <TD>
- <TABLE BORDER=1 BGCOLOR="#FFFFFF" CELLPADDING=8 WIDTH=1000>
- <TR>
- <TD>
- virtual status_t
- <TT>GetDecodedData(</TT>BPositionIO
- *data<TT>)</TT>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
- </TABLE>
-
- Retrieves the data contained in this component in canonical
- format and places this data in
- data. The various attachments subclasses implement this
- function to return decoded data, and PlainTextBodyComponent
- returns UTF8 text. MailComponent implements this function to do
- nothing and return B_OK.
-
- Return Value:
-
- <BLOCKQUOTE>- B_OK if everything succeeds.
-
- - Something else in the event of
failure.</BLOCKQUOTE></BLOCKQUOTE>
-
-
-
-<HR>
-
-<A NAME=SetDecodedData></A><TABLE>
- <TR>
- <TD>
- 
- </TD>
- <TD>
- SetDecodedData () 
- </TD>
- </TR>
-</TABLE>
-
-
- 
-
-<BLOCKQUOTE><TABLE BORDER=2 BGCOLOR="#550033" WIDTH=1000>
- <TR>
- <TD>
- <TABLE BORDER=1 BGCOLOR="#FFFFFF" CELLPADDING=8 WIDTH=1000>
- <TR>
- <TD>
- virtual status_t
- <TT>SetDecodedData(</TT>BPositionIO
- *data<TT>)</TT>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
- </TABLE>
-
- Sets the content of this component to the canonical format data
- contained in data.
- Thus, an attachment subclass would accept a file here and encode
- it into the specified encoding. MailComponent implements this
- function to do nothing and return B_OK.
-
- Return Value:
-
- <BLOCKQUOTE>- B_OK if everything succeeds.
-
- - Something else in the event of
failure.</BLOCKQUOTE></BLOCKQUOTE>
-
-
-
-<HR>
-
-<A NAME=Instantiate></A><TABLE>
- <TR>
- <TD>
- 
- </TD>
- <TD>
- Instantiate () 
- </TD>
- </TR>
-</TABLE>
-
-
- 
-
-<BLOCKQUOTE><TABLE BORDER=2 BGCOLOR="#550033" WIDTH=1000>
- <TR>
- <TD>
- <TABLE BORDER=1 BGCOLOR="#FFFFFF" CELLPADDING=8 WIDTH=1000>
- <TR>
- <TD>
- virtual status_t
- <TT>Instantiate(</TT>BPositionIO
- *data,
- size_t length<TT>)</TT>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
- </TABLE>
-
- Initializes this component to the RFC 822 format data in
- data,
- starting at data
- ->Position(), for up to length
- bytes. Note that if you implement this function, your
- subclass may have taken up some of your data. As such, cache the
- position of data
- before calling your parent's version of
- <TT>Instantiate()</TT>, and then
- subtract the difference between the new position and your cached
- value, like this:
-
- <BLOCKQUOTE><CODE>off_t cache = data->Position(); 
- MailComponent::Instantiate(data,length); 
- length -= (data->Position() - cache);</CODE></BLOCKQUOTE>
-
- Return Value:
-
- <BLOCKQUOTE>- B_OK if everything succeeds.
-
- - B_BAD_TYPE if we cannot handle data.
-
- - Something else in the event of another kind of
- failure.</BLOCKQUOTE></BLOCKQUOTE>
-
-
-
-<HR>
-
-<A NAME=Render></A><TABLE>
- <TR>
- <TD>
- 
- </TD>
- <TD>
- Render () 
- </TD>
- </TR>
-</TABLE>
-
-
- 
-
-<BLOCKQUOTE><TABLE BORDER=2 BGCOLOR="#550033" WIDTH=1000>
- <TR>
- <TD>
- <TABLE BORDER=1 BGCOLOR="#FFFFFF" CELLPADDING=8 WIDTH=1000>
- <TR>
- <TD>
- virtual status_t
- <TT>Render(</TT>BPositionIO
- *data<TT>)</TT>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
- </TABLE>
-
- Renders the component into RFC 822 format and places the result
- in data,
- starting at data
- ->Position().
-
- Return Value:
-
- <BLOCKQUOTE>- B_OK if everything succeeds.
-
- - Something else in the event of
failure.</BLOCKQUOTE></BLOCKQUOTE>
-
-
-
-<HR>
-
-<A NAME=MIMEType></A><TABLE>
- <TR>
- <TD>
- 
- </TD>
- <TD>
- MIMEType () 
- </TD>
- </TR>
-</TABLE>
-
-
- 
-
-<BLOCKQUOTE><TABLE BORDER=2 BGCOLOR="#550033" WIDTH=1000>
- <TR>
- <TD>
- <TABLE BORDER=1 BGCOLOR="#FFFFFF" CELLPADDING=8 WIDTH=1000>
- <TR>
- <TD>
- virtual status_t
- <TT>MIMEType(</TT>BMimeType
- *mime<TT>)</TT>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
- </TABLE>
-
- Places the MIME type of the data into mime.
-
- Return Value:
-
- <BLOCKQUOTE>- B_OK if everything succeeds.
-
- - Something else in the event of
failure.</BLOCKQUOTE></BLOCKQUOTE>
-
-
-
-<HR NOSHADE>
-
-
-
-<H2>Member
-Functions</H2>
-
-
-
-<HR>
-
-<A NAME=WhatIsThis></A><TABLE>
- <TR>
- <TD>
- 
- </TD>
- <TD>
- WhatIsThis() 
- </TD>
- </TR>
-</TABLE>
-
-
- 
-
-<BLOCKQUOTE><TABLE BORDER=2 BGCOLOR="#550033" WIDTH=1000>
- <TR>
- <TD>
- <TABLE BORDER=1 BGCOLOR="#FFFFFF" CELLPADDING=8 WIDTH=1000>
- <TR>
- <TD>
- MailComponent*
- <TT>WhatIsThis()</TT>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
- </TABLE>
-
- Employs simple heuristics such as the MIME type to present you
- with an instance of a useful subclass of MailComponent. You can
- then use any of MailComponent's hook functions or RTTI calls to
- get more information. Bear in mind that the returned component is
- not set to any data. You must still <A
HREF="#Instantiate">Instantiate()</A>
- it from whatever data this object was instantiated from.</BLOCKQUOTE>
-
-
-
-<HR>
-
-<A NAME=IsAttachment></A><TABLE>
- <TR>
- <TD>
- 
- </TD>
- <TD>
- IsAttachment() 
- </TD>
- </TR>
-</TABLE>
-
-
- 
-
-<BLOCKQUOTE><TABLE BORDER=2 BGCOLOR="#550033" WIDTH=1000>
- <TR>
- <TD>
- <TABLE BORDER=1 BGCOLOR="#FFFFFF" CELLPADDING=8 WIDTH=1000>
- <TR>
- <TD>
- bool
- <TT>IsAttachment()</TT>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
- </TABLE>
-
- Employs simple heuristics such as the MIME type and the
- Content-Disposition: header to determine whether this component is
- an attachment. Returns true if it is an attachment,
- false if not.</BLOCKQUOTE>
-
-
-
-<HR>
-
-<A NAME=SetHeaderField></A><TABLE>
- <TR>
- <TD>
- 
- </TD>
- <TD>
- SetHeaderField() 
- </TD>
- </TR>
-</TABLE>
-
-
- 
-
-<BLOCKQUOTE><TABLE BORDER=2 BGCOLOR="#550033" WIDTH=1000>
- <TR>
- <TD>
- <TABLE BORDER=1 BGCOLOR="#FFFFFF" CELLPADDING=8 WIDTH=1000>
- <TR>
- <TD>
- void
- <TT>SetHeaderField(</TT>
-
- <BLOCKQUOTE>
- const char *key, 
- const char *value, 
- uint32 charset = B_ISO1_CONVERSION, 
- mail_encoding encoding = quoted_printable, 
- bool replace_existing= true
-
- <TT>)</TT></BLOCKQUOTE>
- </TD>
- </TR>
- <TR>
- <TD>
- void
- <TT>SetHeaderField(</TT>
-
- <BLOCKQUOTE>
- const char *key, 
- BMessage *structured_header, 
- bool replace_existing= true
-
- <TT>)</TT></BLOCKQUOTE>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
- </TABLE>
-
- Adds the specificed header of type key
- and with the UTF8 contents value
- to the component.
- <TT>SetHeaderField()</TT> converts
- any 8 bit data in value
- to charset
- (see the Support Kit on UTF8 for more information on this), and
- encodes it into 7 bit data using encoding.
-
- If replace_existing
- is true, replaces any existing header of this type with this one,
- otherwise adds a second one.
- Thus, to set the header <CODE>To:</CODE> of some MailComponent
component to foo@xxxxxxx, we would do this:
- <BLOCKQUOTE><CODE>
- component->SetHeaderField("To","foo@xxxxxxx");
- </CODE></BLOCKQUOTE>
- The version of the function that takes a BMessage sets a structured
header. These are in the format
- <CODE>unlabeled; key=value; key=value</CODE>. The most common instance of
this is the <CODE>Content-Type</CODE> header,
- where the MIME type is unlabeled, and various other information, such as
character set, is specified in the
- key/value pairs. The format for structured_header is relatively
- simple: simply use <TT>BMessage::AddString(key,value)</TT> for each
key/value pair. The only exception to this
- rule is the unlabeled data. For this, simply use the key unlabeled.
Please note that the charset and encoding arguments
- defined for the text version of <TT>SetHeaderField</TT> is not provided
here because structured headers cannot be encoded.
- Thus, a relatively standard <CODE>Content-Type</CODE> header would be
specified as follows:
- <BLOCKQUOTE><CODE>
- BMessage structured; 
- structured.AddString("unlabeled","text/plain"); 
- structured.AddString("charset","iso-8859-1"); 
- component->SetHeaderField("To",&structured);
- </CODE></BLOCKQUOTE>
- </BLOCKQUOTE>
-
-
-
-<HR>
-
-<A NAME=HeaderField></A><TABLE>
- <TR>
- <TD>
- 
- </TD>
- <TD>
- HeaderField() 
- </TD>
- </TR>
-</TABLE>
-
-
- 
-
-<BLOCKQUOTE><TABLE BORDER=2 BGCOLOR="#550033" WIDTH=1000>
- <TR>
- <TD>
- <TABLE BORDER=1 BGCOLOR="#FFFFFF" CELLPADDING=8 WIDTH=1000>
- <TR>
- <TD>
- const char *
- <TT>HeaderField(</TT>const
- char *key,
- int32 index
- =
- 0<TT>)</TT>
- </TD>
- </TR>
- <TR>
- <TD>
- status_t
- <TT>HeaderField(</TT>
- <BLOCKQUOTE>
- const char *key, 
- BMessage *structured_header, 
- int32 index = 0
-
- <TT>)</TT></BLOCKQUOTE>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
- </TABLE>
-
- Returns the header key.
- If there is more than one header key,
- use index to
- iterate through them. In the event that the specified header does
- not exist, <TT>HeaderField()
- </TT>returns NULL. Thus, to retrieve the contents of the
<CODE>Subject:</CODE> field in
- UTF8 format, you would do this:
- <BLOCKQUOTE><CODE>
- const char *subject = component->HeaderField("Subject");
- </CODE></BLOCKQUOTE>
- The version of this function that takes a BMessage
- decodes whatever structured header may exist in key
- and places it in structured_header according to the
- format laid out in <A HREF="#SetHeaderField">SetHeaderField()</A>. Returns
B_NAME_NOT_FOUND
- if the header key does
not exist. If it does exist,
- but is not structured, no error is returned; the entire contents of the
header are placed in unlabeled.
- 
-
-  </BLOCKQUOTE>
-
-
-
-
-
-<HR>
-
-<A NAME=HeaderAt></A><TABLE>
- <TR>
- <TD>
- 
- </TD>
- <TD>
- HeaderAt() 
- </TD>
- </TR>
-</TABLE>
-
-
- 
-
-<BLOCKQUOTE><TABLE BORDER=2 BGCOLOR="#550033" WIDTH=1000>
- <TR>
- <TD>
- <TABLE BORDER=1 BGCOLOR="#FFFFFF" CELLPADDING=8 WIDTH=1000>
- <TR>
- <TD>
- const char *
- <TT>HeaderAt(</TT>
- int32 index<TT>)</TT>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
- </TABLE>
-
- Returns the key of the header at index.
- Useful for iterating through all the headers. If index
- is out of range, <TT>HeaderAt()</TT> returns NULL.
-
-  </BLOCKQUOTE>
-
- </TABLE>
-
-
-
-
-
-<HR>
-
-<A NAME=RemoveHeader></A><TABLE>
- <TR>
- <TD>
- 
- </TD>
- <TD>
- RemoveHeader() 
- </TD>
- </TR>
-</TABLE>
-
-
- 
-
-<BLOCKQUOTE><TABLE BORDER=2 BGCOLOR="#550033" WIDTH=1000>
- <TR>
- <TD>
- <TABLE BORDER=1 BGCOLOR="#FFFFFF" CELLPADDING=8 WIDTH=1000>
- <TR>
- <TD>
- const char *
- <TT>RemoveHeader(</TT>
- const char *key<TT>)</TT>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
- </TABLE>
-
- Removes all headers with the key key.
-
-  </BLOCKQUOTE>
-
-
-
-<HR NOSHADE>
-
-
-
-<CENTER><TABLE BORDER=2 BGCOLOR="#FFDD88">
- <TR>
- <TD>
- <TABLE BGCOLOR="#550033" CELLPADDING=5>
- <TR>
- <TD>
- <A HREF="../index.html">Mail
- Kit 2 Root</A>
- </TD>
- <TD>
- <A HREF="index.html">The
- Public API</A>
- </TD>
- </TR>
- </TABLE>
- 
- </TD>
- </TR>
-</TABLE>
-</CENTER>
-
-  
-
-
-<CENTER>Mail Daemon 2 API
-Documentation
-
-©2001 Dr. Zoidberg
-Enterprises</CENTER>
-</BODY>
-</HTML>
diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile
index 8ec752b..f690883 100644
--- a/docs/user/Doxyfile
+++ b/docs/user/Doxyfile
@@ -788,6 +788,7 @@ INPUT = . \
 interface \
 keyboard \
 locale \
+ mail \
 media \
 midi \
 midi2 \
@@ -807,6 +808,7 @@ INPUT = . \
 ../../headers/os/interface \
 ../../headers/private/interface \
 ../../headers/os/locale \
+ ../../headers/os/mail \
 ../../headers/os/media \
 ../../headers/os/midi2 \
 ../../headers/os/net \
diff --git a/docs/user/book.dox b/docs/user/book.dox
index af567b9..188f466 100644
--- a/docs/user/book.dox
+++ b/docs/user/book.dox
@@ -43,6 +43,8 @@
 - The \ref locale includes classes to localize your application
to
 different languages, timezones, number formatting
conventions and
 much more.
+ - The \ref mail includes classes to work with e-mail files,
folders,
+ protocols, and filters, as part of Haiku's unique mail
handling system.
 - The \ref media provides a unified and consistent interface
for media
 streams and applications to intercommunicate.
 - The \ref midi2 describes an interface to generating,
processing,
@@ -135,6 +137,9 @@
 \defgroup locale Locale Kit
 \brief Collection of classes for localizing applications.

+ \defgroup mail Mail Kit
+ \brief API for working with e-mail messages and protocols.
+
 \defgroup media Media Kit
 \brief Collection of classes that deal with audio and video.

@@ -453,9 +458,9 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE);

 The Haiku Network Kit consists of:
 - A modular, add-ons based network stack
- - Two shared libraries, libnet.so and libnetapi.so
+ - Two shared libraries, libnetwork.so and libnetapi.so
 - A stack driver, acting as interface between the network stack and
- libnet.so
+ libnetwork.so
 - Basic network apps
 - A modular GUI preflet

diff --git a/docs/user/mail/MailComponent.dox b/docs/user/mail/MailComponent.dox
new file mode 100644
index 0000000..b1bf14c
--- /dev/null
+++ b/docs/user/mail/MailComponent.dox
@@ -0,0 +1,287 @@
+/*
+ * Copyright 2017 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ * Augustin Cavalier <waddlesplash>
+ * Nathan Whitehorn
+ *
+ * Corresponds to:
+ * headers/os/mail/MailComponent.h hrev51708
+ * src/kits/mail/MailComponent.cpp hrev51708
+ */
+
+
+/*!
+ \file MailComponent.h
+ \ingroup mail
+ \brief Provides the BMailComponent and BTextMailComponent classes.
+*/
+
+
+/*!
+ \enum component_type
+ \ingroup mail
+
+ Possible component types
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \var component_type B_MAIL_PLAIN_TEXT_BODY
+
+ The plain text body of a message.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \var component_type B_MAIL_SIMPLE_ATTACHMENT
+
+ Any other kind of multipart component.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \var component_type B_MAIL_ATTRIBUTED_ATTACHMENT
+
+ An attachment that contains BeOS attributes.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \var component_type B_MAIL_MULTIPART_CONTAINER
+
+ A multipart container attachment.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \class BMailComponent
+ \ingroup mail
+ \brief The base class for most of the Mail Kit.
+
+ Note that BMailComponent is not abstract, and is useful
+ by itself. A BMailComponent has the important quality of
+ being able to read the headers of a message or component without
+ instantiating whatever massive quantity of data might lie therein.
+ This is useful primarily to determine the kind of data you are dealing
+ with, so that the user can make a decision as to whether it should be
shown.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn BMailComponent::BMailComponent(uint32 defaultCharSet =
B_MAIL_NULL_CONVERSION)
+ \brief Initializes a new BMailComponent with the specified character
set.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn BMailComponent::~BMailComponent()
+ \brief Destructor.
+*/
+
+
+/*!
+ \fn uint32 BMailComponent::ComponentType()
+ \brief Returns the \c component_type of this object.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn BMailComponent* BMailComponent::WhatIsThis()
+ \brief Employs simple heuristics such as the MIME type to present you
with
+ an instance of a useful subclass.
+
+ You can then use any of BMailComponent's hook functions or RTTI calls to
+ get more information. Bear in mind that the returned component is not
set
+ to any data. You must still Instantiate() it from whatever data this
object
+ was instantiated from.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn bool BMailComponent::IsAttachment()
+ \brief Employs simple heuristics such as the MIME type and the
Content-Disposition: header
+ to determine whether this component is an attachment.
+
+ \returns true if it is an attachment, false if not.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn void BMailComponent::SetHeaderField(const char *key, const char
*value,
+ uint32 charset = B_MAIL_NULL_CONVERSION, mail_encoding encoding
= null_encoding,
+ bool replace_existing = true)
+ \brief Adds the specified header of type \a key and with the \a value
+ to the component.
+
+ Converts any 8 bit-data in \a value to
+ \a charset and encodes it into 7-bit data using \a encoding. If
+ \a replace_existing is true, replaces any existing header of this type
with
+ this one, otherwise adds a second one.
+
+ Thus, to set the header To: of some BMailComponent \a component to
+ foo@xxxxxxxxxxx, we would do this:
+
+\code
+component->SetHeaderField("To","foo@xxxxxxxxxxx");
+\endcode
+
+ If you want to delete a header, pass in a zero length or NULL string
+ for the value field, or use \ref BMailComponent::RemoveHeader.
+
+ \since Haiku R1
+*/
+
+/*!
+ \fn void BMailComponent::SetHeaderField(const char *key,
+ BMessage *structured_header, bool replace_existing = true)
+ \brief Adds a structured header of type \a key to the component.
+
+ Structured headers are in the format unlabeled; key=value; key=value.
The most common
+ instance of this is the Content-Type header, where the MIME type is
+ unlabeled, and various other information, such as character set, is
+ specified in the key/value pairs. The format for structured_header is
+ relatively simple: simply use BMessage::AddString(key,value) for each
+ key/value pair. The only exception to this rule is the unlabeled data.
+ For this, simply use the key unlabeled. Please note that the charset and
+ encoding arguments defined for the text version of SetHeaderField is not
+ provided here because structured headers cannot be encoded.
+
+ Thus, a relatively standard Content-Type header would be specified as
+ follows:
+
+\code
+BMessage structured;
+structured.AddString("unlabeled","text/plain");
+structured.AddString("charset","iso-8859-1");
+component->SetHeaderField("To",&structured);
+\endcode
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn const char* BMailComponent::HeaderAt(int32 index) const
+ \brief Returns the key of the \c header at index.
+
+ Useful for iterating through all the headers. If index is out of range,
+ HeaderAt() returns NULL.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn const char* BMailComponent::HeaderField(const char *key, int32
index = 0) const
+ \brief Returns the header \a key.
+
+ If there is more than one header key, use \a index to iterate through
them.
+ In the event that the specified header does not exist, HeaderField()
+ returns \c NULL. Thus, to retrieve the contents of the
<code>Subject:</code>
+ field, you would do this:
+
+\code
+const char *subject = component->HeaderField("Subject");
+\endcode
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn status_t BMailComponent::HeaderField(const char *key,
+ BMessage *structured_header, int32 index = 0) const
+ \brief Returns the header \a key.
+
+ Decodes whatever
+ structured header may exist in \a key and places it in \a
structured_header
+ according to the format laid out in SetHeaderField(). Returns
+ \c B_NAME_NOT_FOUND if the header key does not exist. If it does exist,
+ but is not structured, no error is returned; the entire contents of the
+ header are placed in <code>unlabeled</code>.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn status_t BMailComponent::RemoveHeader(const char *key) const
+ \brief Removes all headers with the key \a key.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn virtual status_t BMailComponent::GetDecodedData(BPositionIO *data)
+ \brief Retrieves the data contained in this component in canonical
format
+ 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
+ implements this function to do nothing and return \c B_OK.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn virtual status_t BMailComponent::SetDecodedData(BPositionIO *data)
+ \brief Sets the content of this component to the canonical format data
+ contained in data.
+
+ Thus, an attachment subclass would accept a file here and encode it into
+ the specified encoding. BMailComponent implements this function to do
+ nothing and return \c B_OK.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn virtual status_t BMailComponent::SetToRFC822(BPositionIO *data,
+ size_t length, bool parse_now = false)
+ \brief Sets this object from a component in RFC-822 format.
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn virtual status_t BMailComponent::RenderToRFC822(BPositionIO *data)
+ \brief Renders the component into RFC-822 format.
+
+ It places the result in data, starting at data->Position().
+
+ \since Haiku R1
+*/
+
+
+/*!
+ \fn virtual status_t BMailComponent::MIMEType(BMimeType *mime)
+ \brief Places the MIME type of the data into mime.
+
+ \since Haiku R1
+*/
diff --git a/headers/os/mail/MailComponent.h b/headers/os/mail/MailComponent.h
index 91b5b9a..4b08a33 100644
--- a/headers/os/mail/MailComponent.h
+++ b/headers/os/mail/MailComponent.h
@@ -1,9 +1,10 @@
-#ifndef ZOIDBERG_MAIL_COMPONENT_H
-#define ZOIDBERG_MAIL_COMPONENT_H
-/* (Text)Component - message component base class and plain text
-**
-** Copyright 2001 Dr. Zoidberg Enterprises. All rights reserved.
-*/
+/*
+ * Copyright 2001-2003 Dr. Zoidberg Enterprises. All rights reserved.
+ * Copyright 2004-2017, Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ */
+#ifndef _MAIL_COMPONENT_H
+#define _MAIL_COMPONENT_H

#include <UTF8.h>
@@ -12,10 +13,11 @@

#include <mail_encoding.h>

+
class BMimeType;

-extern const char *kHeaderCharsetString;
-extern const char *kHeaderEncodingString;
+extern const char* kHeaderCharsetString;
+extern const char* kHeaderEncodingString;
// Special field names in the headers which specify the character set (int32)
// and encoding (int8) to use when converting the headers from UTF-8 to the
// output e-mail format (rfc2047). For use with SetHeaderField when you pass
@@ -29,48 +31,45 @@ enum component_type {
 B_MAIL_MULTIPART_CONTAINER
};

-class BMailComponent {
- public:
- BMailComponent(uint32 defaultCharSet = B_MAIL_NULL_CONVERSION);
- virtual ~BMailComponent();
-
- //------Info on this component
- uint32 ComponentType();
- BMailComponent *WhatIsThis();
- // Takes any generic MailComponent, and returns an
instance
- // of a MailComponent subclass that applies to this
case,
- // ready for instantiation. Note that you still have to
- // Instantiate() it yourself.
- bool IsAttachment();
- // Returns true if this component is an attachment,
false
- // otherwise
-
- void SetHeaderField(
- const char *key, const char *value,
- uint32 charset = B_MAIL_NULL_CONVERSION,
- mail_encoding encoding = null_encoding,
- bool replace_existing = true);
- // If you want to delete a header, pass in a zero
length or NULL
- // string for the value field, or use RemoveHeader.
- void SetHeaderField(
- const char *key, BMessage *structured_header,
- bool replace_existing = true);
-
- const char *HeaderAt(int32 index) const;
- const char *HeaderField(const char *key, int32 index = 0) const;
- status_t HeaderField(const char *key, BMessage
*structured_header, int32 index = 0) const;
-
- status_t RemoveHeader(const char *key);
-
- virtual status_t GetDecodedData(BPositionIO *data);
- virtual status_t SetDecodedData(BPositionIO *data);
-
- virtual status_t SetToRFC822(BPositionIO *data, size_t length,
bool parse_now = false);
- virtual status_t RenderToRFC822(BPositionIO *render_to);
-
- virtual status_t MIMEType(BMimeType *mime);

- protected:
+class BMailComponent {
+public:
+ BMailComponent(
+ uint32
defaultCharSet = B_MAIL_NULL_CONVERSION);
+ virtual ~BMailComponent();
+
+ uint32 ComponentType();
+ BMailComponent* WhatIsThis();
+ bool IsAttachment();
+
+ void SetHeaderField(const
char *key,
+ const
char *value,
+ uint32
charset = B_MAIL_NULL_CONVERSION,
+
mail_encoding encoding = null_encoding,
+ bool
replace_existing = true);
+ void SetHeaderField(const
char *key,
+
BMessage *structured_header,
+ bool
replace_existing = true);
+
+ const char* HeaderAt(int32 index) const;
+ const char* HeaderField(const char
*key,
+ int32
index = 0) const;
+ status_t HeaderField(const char
*key,
+
BMessage *structured_header,
+ int32
index = 0) const;
+
+ status_t RemoveHeader(const char
*key);
+
+ virtual status_t GetDecodedData(BPositionIO
*data);
+ virtual status_t SetDecodedData(BPositionIO
*data);
+
+ virtual status_t SetToRFC822(BPositionIO *data,
size_t length,
+ bool
parse_now = false);
+ virtual status_t RenderToRFC822(BPositionIO
*render_to);
+
+ virtual status_t MIMEType(BMimeType *mime);
+
+protected:
 uint32 _charSetForTextDecoding;
 // This is the character set to be used for decoding
text
 // components, or if it is B_MAIL_NULL_CONVERSION then
the character
@@ -81,7 +80,7 @@ class BMailComponent {
 // Container, Message, MIME, Text) child components and
ends up
 // being used in the text components.

- private:
+private:
 virtual void _ReservedComponent1();
 virtual void _ReservedComponent2();
 virtual void _ReservedComponent3();
@@ -137,4 +136,4 @@ class BTextMailComponent : public BMailComponent {
 uint32 _reserved[5];
};

-#endif /* ZOIDBERG_MAIL_COMPONENT_H */
+#endif // _MAIL_COMPONENT_H

[haiku-commits] haiku: hrev51709 - API docs/user/mail headers/os/mail

Other related posts: