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