From 95c9effd68127df2dce202d5e254a7c86560010a Mon Sep 17 00:00:00 2001 From: Augustin Cavalier Date: Mon, 25 Dec 2017 19:43:51 -0500 Subject: [PATCH] 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.) --- 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 | 85 +-- 5 files changed, 338 insertions(+), 808 deletions(-) delete mode 100644 docs/apps/mail/Public API/MailComponent.html create mode 100644 docs/user/mail/MailComponent.dox diff --git a/docs/apps/mail/Public API/MailComponent.html b/docs/apps/mail/Public API/MailComponent.html deleted file mode 100644 index 70a897e093..0000000000 --- a/docs/apps/mail/Public API/MailComponent.html +++ /dev/null @@ -1,763 +0,0 @@ - - - MailComponent - - -

- -
- - - -
-

- - - - -
-

Mail - Kit 2 Root

- 		-

The - Public API

-
-

-
- -
- -
- -

- -

MailComponent

- -
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.

- -

- -

- -

- -

Constructor -and -Destructor

- -

- -

- - - - - - -
-

- 		-

MailComponent() -

-
-

- -

 

- -
- - - -
-

- - - -
-

MailComponent()

-
-

-
- -

Initializes the MailComponent and does nothing else.

- -

 

- -

- -

- - - - - - -
-

- 		-

~MailComponent() -

-
-

- -

 

- -
- - - -
-

- - - -
-

virtual - ~MailComponent()

-
-

-
- -

Destroys the MailComponent. Does nothing of interest.

- -

- -

- -

- -

Hook -Functions

- -

- -

- - - - - - -
-

- 		-

GetDecodedData ()

-
-

- -

 

- -
- - - -
-

- - - -
-

virtual status_t - GetDecodedData(BPositionIO - *data)

-
-

-
- -

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:

- -
- B_OK if everything succeeds. - -

- Something else in the event of failure.

- -

- -

- - - - - - -
-

- 		-

SetDecodedData ()

-
-

- -

 

- -
- - - -
-

- - - -
-

virtual status_t - SetDecodedData(BPositionIO - *data)

-
-

-
- -

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:

- -
- B_OK if everything succeeds. - -

- Something else in the event of failure.

- -

- -

- - - - - - -
-

- 		-

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. 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 - Instantiate(), and then - subtract the difference between the new position and your cached - value, like this:

- -
off_t cache = data->Position();
- MailComponent::Instantiate(data,length);
- length -= (data->Position() - cache);
- -

Return Value:

- -
- B_OK if everything succeeds. - -

- B_BAD_TYPE if we cannot handle data.

- -

- Something else in the event of another kind of - failure.

- -

- -

- - - - - - -
-

- 		-

Render ()

-
-

- -

 

- -
- - - -
-

- - - -
-

virtual status_t - Render(BPositionIO - *data)

-
-

-
- -

Renders the component into RFC 822 format and places the result - in data, - starting at data - ->Position().

- -

Return Value:

- -
- B_OK if everything succeeds. - -

- Something else in the event of failure.

- -

- -

- - - - - - -
-

- 		-

MIMEType ()

-
-

- -

 

- -
- - - -
-

- - - -
-

virtual status_t - MIMEType(BMimeType - *mime)

-
-

-
- -

Places the MIME type of the data into mime.

- -

Return Value:

- -
- B_OK if everything succeeds. - -

- Something else in the event of failure.

- -

- -

- -

- -

Member -Functions

- -

- -

- - - - - - -
-

- 		-

WhatIsThis()

-
-

- -

 

- -
- - - -
-

- - - -
-

MailComponent* - WhatIsThis()

-
-

-
- -

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 Instantiate() - it from whatever data this object was instantiated from.

- -

- -

- - - - - - -
-

- 		-

IsAttachment()

-
-

- -

 

- -
- - - -
-

- - - -
-

bool - IsAttachment()

-
-

-
- -

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.

- -

- -

- - - - - - -
-

- 		-

SetHeaderField()

-
-

- -

 

- -
- - - -
-

- - - - - - -
-

void - SetHeaderField( - -

- const char *key,
- const char *value,
- uint32 charset = B_ISO1_CONVERSION,
- mail_encoding encoding = quoted_printable,
- bool replace_existing= true - - )

-
-

void - SetHeaderField( - -

- const char *key,
- BMessage *structured_header,
- bool replace_existing= true - - )

-
-

-
- -

Adds the specificed header of type key - and with the UTF8 contents value - to the component. - SetHeaderField() 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 To: of some MailComponent component to foo@bar.com, we would do this:

-
- component->SetHeaderField("To","foo@bar.com"); -
-

The version of the function that takes a BMessage sets a structured header. These 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: -

- BMessage structured;
- structured.AddString("unlabeled","text/plain");
- structured.AddString("charset","iso-8859-1");
- component->SetHeaderField("To",&structured); -
-
- -

- -

- - - - - - -
-

- 		-

HeaderField()

-
-

- -

 

- -
- - - -
-

- - - - - - -
-

const char * - HeaderField(const - char *key, - int32 index - = - 0)

-
-

status_t - HeaderField( -

- const char *key,
- BMessage *structured_header,
- int32 index = 0 - - )

-
-

-
- -

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, HeaderField() - returns NULL. Thus, to retrieve the contents of the Subject: field in - UTF8 format, you would do this:

-
- const char *subject = component->HeaderField("Subject"); -
-

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 SetHeaderField(). 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. -

- -

 

- - - -

- -

- - - - - - -
-

- 		-

HeaderAt()

-
-

- -

 

- -
- - - -
-

- - - -
-

const char * - HeaderAt( - int32 index)

-
-

-
- -

Returns the key of the header at index. - Useful for iterating through all the headers. If index - is out of range, HeaderAt() returns NULL.

- -

 

- -

- - - -

- -

- - - - - - -
-

- 		-

RemoveHeader()

-
-

- -

 

- -
- - - -
-

- - - -
-

const char * - RemoveHeader( - const char *key)

-
-

-
- -

Removes all headers with the key key.

- -

 

- -

- -

- -

- -
- - - -
-

- - - - -
-

Mail - Kit 2 Root

- 		-

The - Public API

-
-

-
-
- -


-

- -
Mail Daemon 2 API -Documentation - -

©2001 Dr. Zoidberg -Enterprises

- - diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile index 8ec752b73a..f690883f87 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 af567b9b40..188f46616c 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 0000000000..b1bf14c71b --- /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 + * 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@example.com, we would do this: + +\code +component->SetHeaderField("To","foo@example.com"); +\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 Subject: + 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 unlabeled. + + \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 91b5b9af1c..4b08a33a2a 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 @@ -12,10 +13,11 @@ #include + 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(); +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 + 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); - // 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); + 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; + 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); + status_t RemoveHeader(const char *key); - virtual status_t GetDecodedData(BPositionIO *data); - virtual status_t SetDecodedData(BPositionIO *data); + 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 SetToRFC822(BPositionIO *data, size_t length, + bool parse_now = false); + virtual status_t RenderToRFC822(BPositionIO *render_to); - virtual status_t MIMEType(BMimeType *mime); + virtual status_t MIMEType(BMimeType *mime); - protected: +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