aboutsummaryrefslogtreecommitdiffstats
path: root/doc/book
diff options
context:
space:
mode:
Diffstat (limited to 'doc/book')
-rw-r--r--doc/book/basics.tex110
-rw-r--r--doc/book/building.tex43
-rw-r--r--doc/book/msg.tex88
-rw-r--r--doc/book/net.tex80
4 files changed, 186 insertions, 135 deletions
diff --git a/doc/book/basics.tex b/doc/book/basics.tex
index 9c129912..ac66959e 100644
--- a/doc/book/basics.tex
+++ b/doc/book/basics.tex
@@ -6,7 +6,7 @@
\subsection{Introduction} % --------------------------------------------------
Since version 0.7.2cvs, VMime use smart pointers to simplify memory
-management. VMime's smart pointer implementation relies on
+management. Smart pointers rely on
RAII\footnote{Ressource Allocation is Initialisation} so that we do not need
to bother with deleting an object (freeing memory) when it is not used
anymore.
@@ -21,8 +21,20 @@ An object is destroyed as soon as the last strong reference to it is released.
At the same tine, all weak references (if any) are automatically set to point
to \vnull.
-In VMime, these two types of references are known as {\vcode vmime::ref}
-and {\vcode vmime::weak\_ref}, respectively.
+In VMime, these two types of references are known as {\vcode vmime::shared\_ptr}
+and {\vcode vmime::weak\_ptr}, respectively.
+
+\vnote{since November 2013, we switched from an old, intrusive implementation
+of smart pointers to a more standard one: either Boost {\vcode shared\_ptr<>}
+implementation or standard C++ one if we are compiling in C++11. Here are the
+changes:
+
+{\vcode vmime::ref <>} is replaced with {\vcode vmime::shared\_ptr <>}
+
+{\vcode vmime::weak\_ref <>} is replaced with {\vcode vmime::weak\_ptr <>}
+
+{\vcode vmime::create <>} is replaced with {\vcode vmime::make\_shared <>}
+}
\subsection{Instanciating reference-counted objects} % -----------------------
@@ -30,7 +42,7 @@ In VMime, all objects that support reference counting inherit from the
{\vcode vmime::object} class, which is responsible for
incrementing/decrementing the counter and managing the object's life cycle.
If you want to create a smart pointer to a new object instance, you should
-use the function {\vcode vmime::create} instead of the {\vcode new}
+use the function {\vcode vmime::make\_shared} instead of the {\vcode new}
operator.
\begin{lstlisting}[caption={Smarts pointers and creating objects}]
@@ -55,8 +67,8 @@ private:
int main()
{
- vmime::ref <myObject> obj =
- vmime::create <myObject>("world");
+ vmime::shared_ptr <myObject> obj =
+ vmime::make_shared <myObject>("world");
obj->sayHello();
@@ -72,20 +84,20 @@ you would use normal ("raw") C++ pointers (eg. you can write
\lstinline{!ptr, ptr != NULL, ptr->method(), *ptr}...).
Type safety is also guaranteed, and you can type cast smart pointers using
-the {\vcode staticCast()}, {\vcode dynamicCast()} and {\vcode constCast()}
-equivalents on {\vcode vmime::ref} and {\vcode vmime::weak\_ref} objects:
+the {\vcode static\_cast()}, {\vcode dynamic\_cast()} and {\vcode const\_cast()}
+equivalents on {\vcode vmime::shared\_ptr} and {\vcode vmime::weak\_ptr} objects:
\begin{lstlisting}[caption={Casting smart pointers}]
class myBase : public vmime::object { }
class myObject : public myBase { }
-vmime::ref <myObject> obj = vmime::create <myObject>();
+vmime::shared_ptr <myObject> obj = vmime::make_shared <myObject>();
// Implicit downcast
-vmime::ref <myBase> base = obj;
+vmime::shared_ptr <myBase> base = obj;
// Explicit upcast
-vmime::ref <myObject> obj2 = base.dynamicCast <myObject>();
+vmime::shared_ptr <myObject> obj2 = vmime::dynamicCast <myObject>(base);
\end{lstlisting}
Weak references are used to resolve reference cycles (an object which refers
@@ -97,34 +109,34 @@ class parent : public vmime::object
{
public:
- void createChild(vmime::ref <child> c)
+ void createChild(vmime::shared_ptr <child> c)
{
m_child = c;
}
private:
- vmime::ref <child> m_child;
+ vmime::shared_ptr <child> m_child;
};
class child : public vmime::object
{
public:
- child(vmime::ref <parent> p)
+ child(vmime::shared_ptr <parent> p)
: m_parent(p)
{
}
private:
- vmime::ref <parent> m_parent;
+ vmime::shared_ptr <parent> m_parent;
};
int main()
{
- vmime::ref <parent> p = vmime::create <parent>();
- vmime::ref <child> c = vmime::create <child>();
+ vmime::shared_ptr <parent> p = vmime::make_shared <parent>();
+ vmime::shared_ptr <child> c = vmime::make_shared <child>();
p->setChild(c);
}
@@ -136,7 +148,7 @@ exiting {\vcode main()}. That's because {\vcode p} indirectly points to itself
reference to the parent:
\begin{lstlisting}
-vmime::weak_ref <parent> m_parent;
+vmime::weak_ptr <parent> m_parent;
\end{lstlisting}
The decision to make the parent or the child a weak reference is purely
@@ -216,7 +228,7 @@ provides additional functions to get some information about the parsing
process or the structure (methods {\vcode getParsedOffset()},
{\vcode getParsedLength()} and {\vcode getChildComponents()}).
-Vmime also provides a set of classes corresponding to the basic types found
+VMime also provides a set of classes corresponding to the basic types found
in a message; for example a mailbox, a mailbox list, date/time information,
media type, etc. They all inherit from {\vcode component} too.
@@ -284,12 +296,12 @@ an email address (mandatory) and possibly a name. A mailbox group is simply
a named list of mailboxes (see Figure \ref{uml_addr_mbox_mboxgroup}).
\begin{lstlisting}[caption={Using mailboxes and mailbox groups}]
-vmime::ref <vmime::mailbox> mbox1 = vmime::create <vmime::mailbox>
+vmime::shared_ptr <vmime::mailbox> mbox1 = vmime::make_shared <vmime::mailbox>
(/* name */ vmime::text("John Doe"), /* email */ "[email protected]");
-vmime::ref <vmime::mailbox> mbox2 = vmime::create <vmime::mailbox>
+vmime::shared_ptr <vmime::mailbox> mbox2 = vmime::make_shared <vmime::mailbox>
(/* no name, email only */ "[email protected]");
-vmime::ref <vmime::mailboxGroup> grp = vmime::create <vmime::mailboxGroup>();
+vmime::shared_ptr <vmime::mailboxGroup> grp = vmime::make_shared <vmime::mailboxGroup>();
grp->appendMailbox(mbox1);
grp->appendMailbox(mbox2);
\end{lstlisting}
@@ -402,12 +414,11 @@ convert automatically from basic types to text, and \emph{vice versa}. The
following example illustrates it:
\begin{lstlisting}[caption={Getting and setting parameter value in fields}]
-vmime::ref <vmime::parameterizedField> field =
- header->findField("X-Field-That-Contains-Parameters")
- .dynamicCast <vmime::parameterizedField>();
+vmime::shared_ptr <vmime::parameterizedField> field =
+ header->findField <vmime::parameterizedField>("X-Field-That-Contains-Parameters");
// Use setValue() to convert from a basic type to 'text'
-vmime::ref <vmime::parameter> prm = field->getParameter("my-date-param");
+vmime::shared_ptr <vmime::parameter> prm = field->getParameter("my-date-param");
prm->setValue(vmime::datetime::now());
// Use getValueAs() to convert from 'text' to a basic type
@@ -421,12 +432,11 @@ Table \ref{standard-prm-fields}). This avoids finding the parameter and
illustrates how to use it:
\begin{lstlisting}
-vmime::ref <vmime::contentTypeField> field =
- header->getField(vmime::fields::CONTENT_TYPE)
- .dynamicCast <vmime::contentTypeField>();
+vmime::shared_ptr <vmime::contentTypeField> field =
+ header->getField <vmime::contentTypeField>(vmime::fields::CONTENT_TYPE);
// 1. First solution: the "hard" way
-vmime::ref <vmime::parameter> prm = field->findParameter("charset");
+vmime::shared_ptr <vmime::parameter> prm = field->findParameter("charset");
const charset ch1 = prm->getValueAs <vmime::charset>();
// 2. Second solution: the simple way
@@ -541,11 +551,11 @@ writing it to the standard output with charset conversion:
\begin{lstlisting}[caption={Using content handlers to extract body text from
a message}]
// Suppose we already have a message
-vmime::ref <vmime::message> msg;
+vmime::shared_ptr <vmime::message> msg;
// Obtains a reference to the body contents
-vmime::ref <vmime::body> body = msg->getBody();
-vmime::ref <vmime::contentHandler> cts = body->getContents();
+vmime::shared_ptr <vmime::body> body = msg->getBody();
+vmime::shared_ptr <vmime::contentHandler> cts = body->getContents();
vmime::utility::outputStreamAdapter out(std::cout);
cts->extract(out);
@@ -563,11 +573,11 @@ if you want to set the contents of a body part. The following code snippet
shows how to set the body text of a part from a string:
\begin{lstlisting}[caption={Setting the contents of a body part}]
-vmime::ref <vmime::bodyPart> part; // suppose we have a body part
+vmime::shared_ptr <vmime::bodyPart> part; // suppose we have a body part
// Create a new content handler from a string
-vmime::ref <vmime::contentHandler> cth =
- vmime::create <vmime::stringContentHandler>("Put body contents here");
+vmime::shared_ptr <vmime::contentHandler> cth =
+ vmime::make_shared <vmime::stringContentHandler>("Put body contents here");
// Set the contents
part->getBody()->setContents(cth);
@@ -585,18 +595,18 @@ fileStream->open("/home/vincent/paris.jpg", std::ios::binary);
if (!*fileStream)
// handle error
-vmime::ref <utility::stream> dataStream =
- vmime::create <vmime::utility::inputStreamPointerAdapter>(fileStream);
+vmime::shared_ptr <utility::stream> dataStream =
+ vmime::make_shared <vmime::utility::inputStreamPointerAdapter>(fileStream);
// NOTE: 'fileStream' will be automatically deleted
// when 'dataStream' is deleted
// Create a new content handler
-vmime::ref <contentHandler> data =
- vmime::create <vmime::streamContentHandler>(dataStream, 0);
+vmime::shared_ptr <contentHandler> data =
+ vmime::make_shared <vmime::streamContentHandler>(dataStream, 0);
// Now create the attachment
-ref <vmime::attachment> att = vmime::create <vmime::defaultAttachment>
+ref <vmime::attachment> att = vmime::make_shared <vmime::defaultAttachment>
(
/* attachment data */ data,
/* content type */ vmime::mediaType("image/jpeg"),
@@ -627,11 +637,11 @@ to UTF-8 charset:
\begin{lstlisting}[caption={Extracting and converting body contents to a
specified charset}]
-vmime::ref <vmime::message> msg; // we have a message
+vmime::shared_ptr <vmime::message> msg; // we have a message
// Obtain the content handler first
-vmime::ref <vmime::body> body = msg->getBody();
-vmime::ref <const vmime::contentHandler> cth = body->getContents();
+vmime::shared_ptr <vmime::body> body = msg->getBody();
+vmime::shared_ptr <const vmime::contentHandler> cth = body->getContents();
// Then, extract and convert the contents
vmime::utility::outputStreamAdapter out(std::cout);
@@ -676,7 +686,7 @@ outText.createFromString(inText, inCharset);
// . <utf-8> "t�l�phone "
// . <us-ascii> "mobile"
-vmime::ref <vmime::header> header = myMessage->getHeader();
+vmime::shared_ptr <vmime::header> header = myMessage->getHeader();
header->Subject()->setValue(outText);
\end{lstlisting}
@@ -707,7 +717,7 @@ text stored in the Subject field of a message:
\begin{lstlisting}[caption={Converting data in a {\vcode vmime::text} to a
specified charset}]
-vmime::ref <vmime::message> msg; // we have a message
+vmime::shared_ptr <vmime::message> msg; // we have a message
vmime::text subject = msg->getHeader()->Subject()->getValue();
@@ -739,7 +749,7 @@ The following example creates an instance of the Base64 encoder to encode
some data:
\begin{lstlisting}[caption={A simple example of using an encoder}]
-vmime::ref <vmime::utility::encoder::encoder> enc =
+vmime::shared_ptr <vmime::utility::encoder::encoder> enc =
vmime::utility::encoder::encoderFactory::getInstance()->create("base64");
vmime::string inString("Some data to encode");
@@ -761,7 +771,7 @@ an excerpt from {\vexample example6}} enumerates available encoders and the
supported properties for each of them:
\begin{lstlisting}[caption={Enumerating encoders and their properties}]
-vmime::utility::encoder::encoderFactory* ef =
+vmime::shared_ptr <vmime::utility::encoder::encoderFactory> ef =
vmime::utility::encoder::encoderFactory::getInstance();
std::cout << "Available encoders:" << std::endl;
@@ -769,13 +779,13 @@ std::cout << "Available encoders:" << std::endl;
for (int i = 0 ; i < ef->getEncoderCount() ; ++i)
{
// Output encoder name
- vmime::ref <const vmime::utility::encoder::encoderFactory::registeredEncoder>
+ vmime::shared_ptr <const vmime::utility::encoder::encoderFactory::registeredEncoder>
enc = ef->getEncoderAt(i);
std::cout << " * " << enc->getName() << std::endl;
// Create an instance of the encoder to get its properties
- vmime::ref <vmime::utility::encoder::encoder> e = enc->create();
+ vmime::shared_ptr <vmime::utility::encoder::encoder> e = enc->create();
std::vector <vmime::string> props = e->getAvailableProperties();
std::vector <vmime::string>::const_iterator it;
diff --git a/doc/book/building.tex b/doc/book/building.tex
index c96e95db..a34db5ba 100644
--- a/doc/book/building.tex
+++ b/doc/book/building.tex
@@ -16,13 +16,16 @@ To build VMime from the sources, you will need the following:
\item a working C++ compiler with good STL implementation and also a good
support for templates (for example, \href{http://gcc.gnu.org/}{GNU GCC}) ;
\item \href{http://www.cmake.org/}{CMake} build system ;
-\item an usable iconv() implementation (see
+\item either \href{http://www.icu-project.org}{ICU library} or an usable
+{\vcode iconv()} implementation (see
\href{http://www.gnu.org/software/libiconv/}{libiconv of GNU Project}) ;
\item the \href{http://www.gnu.org/software/gsasl/}{GNU SASL Library} if you
want SASL\footnote{Simple Authentication and Security Layer} support ;
\item either the \href{http://www.openssl.org}{OpenSSL library} or the
\href{http://www.gnu.org/software/gnutls/}{GNU TLS Library} if you
want SSL and TLS\footnote{Transport Layer Security} support ;
+\item the \href{http://www.boost.org}{Boost C++ library} if you are not using
+C++11 (or your compiler does not support it), for {\vcode shared\_ptr<>}.
\end{itemize}
% ============================================================================
@@ -113,3 +116,41 @@ the library into the default location (ie: /usr/lib and /usr/include).}
Now, you are done! You can jump to the next chapter to know how to use VMime
in your program...
+% ============================================================================
+\section{Build options}
+
+Some options can be given to CMake to control the build:
+
+\begin{table}[!ht]
+\noindent\begin{tabularx}{1.0\textwidth}{|l|X|}
+\hline
+ {\bf Option name} &
+ {\bf Description} \\
+\hline
+\hline
+VMIME\_BUILD\_SHARED\_LIBRARY &
+Set to ON to build a shared version (.so) of the library (default is ON). \\
+\hline
+VMIME\_BUILD\_STATIC\_LIBRARY &
+Set to ON to build a static version (.a) of the library (default is ON). \\
+\hline
+VMIME\_BUILD\_TESTS &
+Set to ON to build unit tests (default is OFF). \\
+\hline
+VMIME\_TLS\_SUPPORT\_LIB\_IS\_OPENSSL \\ VMIME\_TLS\_SUPPORT\_LIB\_IS\_GNUTLS &
+Set either the one or the other (but not both) to ON to force using either OpenSSL
+or GNU TLS as the SSL library (default depends on which libraries are available on
+your system). \\
+\hline
+VMIME\_CHARSETCONV\_LIB\_IS\_ICONV \\ VMIME\_CHARSETCONV\_LIB\_IS\_ICU &
+Set either the one or the other (but not both) to ON to force using either iconv
+or ICU as the charset conversion library (default depends on which libraries are
+available on your system). \\
+\hline
+CMAKE\_BUILD\_TYPE &
+Set the build type: either "Release" or "Debug". In Debug build, optimizations
+are disabled and debugging information are enabled. \\
+\hline
+\end{tabularx}
+\caption{CMake build options}
+\end{table}
diff --git a/doc/book/msg.tex b/doc/book/msg.tex
index 384aab74..50344b62 100644
--- a/doc/book/msg.tex
+++ b/doc/book/msg.tex
@@ -36,22 +36,22 @@ vmime::utility::outputStreamStringAdapter os(data);
vmime::utility::bufferedStreamCopy(is, os);
// Actually parse the message
-vmime::ref <vmime::message> msg = vmime::create <vmime::message>();
+vmime::shared_ptr <vmime::message> msg = vmime::make_shared <vmime::message>();
msg->parse(data);
-vmime::ref <vmime::header> hdr = msg->getHeader();
-vmime::ref <vmime::body> bdy = msg->getBody();
+vmime::shared_ptr <vmime::header> hdr = msg->getHeader();
+vmime::shared_ptr <vmime::body> bdy = msg->getBody();
// Now, you can extract some of its components
vmime::charset ch(vmime::charsets::UTF_8);
std::cout
<< "The subject of the message is: "
- << hdr->Subject()->getValue().dynamicCast <vmime::text>()->getConvertedText(ch)
+ << hdr->Subject()->getValue <vmime::text>()->getConvertedText(ch)
<< std::endl
<< "It was sent by: "
- << hdr->From()->getValue().dynamicCast <vmime::mailbox>()->getName().getConvertedText(ch)
- << " (email: " << hdr->From()->getValue().dynamicCast<vmime::mailbox>()->getEmail() << ")"
+ << hdr->From()->getValue <vmime::mailbox>()->getName().getConvertedText(ch)
+ << " (email: " << hdr->From()->getValue <vmime::mailbox>()->getEmail() << ")"
<< std::endl;
\end{lstlisting}
@@ -84,7 +84,7 @@ vmime::utility::outputStreamStringAdapter os(data);
vmime::utility::bufferedStreamCopy(is, os);
// Actually parse the message
-vmime::ref <vmime::message> msg = vmime::create <vmime::message>();
+vmime::shared_ptr <vmime::message> msg = vmime::make_shared <vmime::message>();
msg->parse(data);
// Here start the differences with the previous example
@@ -96,7 +96,7 @@ std::cout << "Message has " << mp.getAttachmentCount()
for (int i = 0 ; i < mp.getAttachmentCount() ; ++i)
{
- vmime::ref <const vmime::attachment> att = mp.getAttachmentAt(i);
+ vmime::shared_ptr <const vmime::attachment> att = mp.getAttachmentAt(i);
std::cout << " - " << att->getType().generate() << std::endl;
}
@@ -106,13 +106,13 @@ std::cout << "Message has " << mp.getTextPartCount()
for (int i = 0 ; i < mp.getTextPartCount() ; ++i)
{
- vmime::ref <const vmime::textPart> tp = mp.getTextPartAt(i);
+ vmime::shared_ptr <const vmime::textPart> tp = mp.getTextPartAt(i);
// text/html
if (tp->getType().getSubType() == vmime::mediaTypes::TEXT_HTML)
{
- vmime::ref <const vmime::htmlTextPart> htp =
- tp.dynamicCast <const vmime::htmlTextPart>();
+ vmime::shared_ptr <const vmime::htmlTextPart> htp =
+ vmime::dynamicCast <const vmime::htmlTextPart>(tp);
// HTML text is in tp->getText()
// Plain text is in tp->getPlainText()
@@ -120,7 +120,7 @@ for (int i = 0 ; i < mp.getTextPartCount() ; ++i)
// Enumerate embedded objects
for (int j = 0 ; j < htp->getObjectCount() ; ++j)
{
- vmime::ref <const vmime::htmlTextPart::embeddedObject> obj =
+ vmime::shared_ptr <const vmime::htmlTextPart::embeddedObject> obj =
htp->getObjectAt(j);
// Identifier (Content-Id or Content-Location) is obj->getId()
@@ -146,51 +146,51 @@ objects that compose it (parts, fields, etc.). The following is an example of
how to achieve it:
\begin{lstlisting}[caption={Building a simple message from scratch}]
-vmime::ref <vmime::message> msg = vmime::create <vmime::message>();
+vmime::shared_ptr <vmime::message> msg = vmime::make_shared <vmime::message>();
-vmime::ref <vmime::header> hdr = msg->getHeader();
-vmime::ref <vmime::body> bdy = msg->getBody();
+vmime::shared_ptr <vmime::header> hdr = msg->getHeader();
+vmime::shared_ptr <vmime::body> bdy = msg->getBody();
-vmime::headerFieldFactory* hfFactory =
+vmime::shared_ptr <vmime::headerFieldFactory> hfFactory =
vmime::headerFieldFactory::getInstance();
// Append a 'Date:' field
-vmime::ref <vmime::headerField> dateField =
+vmime::shared_ptr <vmime::headerField> dateField =
hfFactory->create(vmime::fields::DATE);
dateField->setValue(vmime::datetime::now());
hdr->appendField(dateField);
// Append a 'Subject:' field
-vmime::ref <vmime::headerField> subjectField =
+vmime::shared_ptr <vmime::headerField> subjectField =
hfFactory->create(vmime::fields::SUBJECT);
subjectField->setValue(vmime::text("Message subject"));
hdr->appendField(subjectField);
// Append a 'From:' field
-vmime::ref <vmime::headerField> fromField =
+vmime::shared_ptr <vmime::headerField> fromField =
hfFactory->create(vmime::fields::FROM);
fromField->setValue
- (vmime::create <vmime::mailbox>("[email protected]"));
+ (vmime::make_shared <vmime::mailbox>("[email protected]"));
hdr->appendField(fromField);
// Append a 'To:' field
-vmime::ref <vmime::headerField> toField =
+vmime::shared_ptr <vmime::headerField> toField =
hfFactory->create(vmime::fields::TO);
-vmime::ref <vmime::mailboxList> recipients =
- vmime::create <vmime::mailboxList>();
+vmime::shared_ptr <vmime::mailboxList> recipients =
+ vmime::make_shared <vmime::mailboxList>();
recipients->appendMailbox
- (vmime::create <vmime::mailbox>("[email protected]"));
+ (vmime::make_shared <vmime::mailbox>("[email protected]"));
toField->setValue(recipients);
hdr->appendField(toField);
// Set the body contents
-bdy->setContents(vmime::create <vmime::stringContentHandler>
+bdy->setContents(vmime::make_shared <vmime::stringContentHandler>
("This is the text of your message..."));
// Output raw message data to standard output
@@ -215,14 +215,14 @@ try
mb.setSubject(vmime::text("Message subject"));
mb.setExpeditor(vmime::mailbox("[email protected]"));
mb.getRecipients().appendAddress
- (vmime::create <vmime::mailbox>("[email protected]"));
+ (vmime::make_shared <vmime::mailbox>("[email protected]"));
mb.getTextPart()->setCharset(vmime::charsets::ISO8859_15);
- mb.getTextPart()->setText(vmime::create <vmime::stringContentHandler>
+ mb.getTextPart()->setText(vmime::make_shared <vmime::stringContentHandler>
("This is the text of your message..."));
// Message construction
- vmime::ref <vmime::message> msg = mb.construct();
+ vmime::shared_ptr <vmime::message> msg = mb.construct();
// Output raw message data to standard output
vmime::utility::outputStreamAdapter out(std::cout);
@@ -249,8 +249,8 @@ previous example to attach a file to the message:
\begin{lstlisting}[caption={Building a message with an attachment using
{\vcode vmime::messageBuilder}}]
// Create an attachment
-vmime::ref <vmime::fileAttachment> att =
- vmime::create <vmime::fileAttachment>
+vmime::shared_ptr <vmime::fileAttachment> att =
+ vmime::make_shared <vmime::fileAttachment>
(
/* full path to file */ "/home/vincent/paris.jpg",
/* content type */ vmime::mediaType("image/jpeg),
@@ -284,7 +284,7 @@ using the {\vcode vmime::messageBuilder}}]
mb.setSubject(vmime::text("An HTML message"));
mb.setExpeditor(vmime::mailbox("[email protected]"));
mb.getRecipients().appendAddress
- (vmime::create <vmime::mailbox>("[email protected]"));
+ (vmime::make_shared <vmime::mailbox>("[email protected]"));
// Set the content-type to "text/html": a text part factory must be
// available for the type you are using. The following code will make
@@ -294,8 +294,8 @@ mb.constructTextPart(vmime::mediaType
// Set contents of the text parts; the message is available in two formats:
// HTML and plain text. The HTML format also includes an embedded image.
-vmime::ref <vmime::htmlTextPart> textPart =
- mb.getTextPart().dynamicCast <vmime::htmlTextPart>();
+vmime::shared_ptr <vmime::htmlTextPart> textPart =
+ vmime::dynamicCast <vmime::htmlTextPart>(mb.getTextPart());
// -- Add the JPEG image (the returned identifier is used to identify the
// -- embedded object in the HTML text, the famous "CID", or "Content-Id").
@@ -306,11 +306,11 @@ const vmime::string id = textPart->addObject("<...image data...>",
// -- Set the text
textPart->setCharset(vmime::charsets::ISO8859_15);
-textPart->setText(vmime::create <vmime::stringContentHandler>
+textPart->setText(vmime::make_shared <vmime::stringContentHandler>
("This is the <b>HTML text</b>, and the image:<br/>"
"<img src=\"") + id + vmime::string("\"/>"));
-textPart->setPlainText(vmime::create <vmime::stringContentHandler>
+textPart->setPlainText(vmime::make_shared <vmime::stringContentHandler>
("This is the plain text."));
\end{lstlisting}
@@ -332,11 +332,11 @@ input stream, then add an embedded object:
vmime::utility::fileSystemFactory* fs =
vmime::platform::getHandler()->getFileSystemFactory();
-vmime::ref <vmime::utility::file> imageFile =
+vmime::shared_ptr <vmime::utility::file> imageFile =
fs->create(fs->stringToPath("/path/to/image.jpg"));
-vmime::ref <vmime::contentHandler> imageCts =
- vmime::create <vmime::streamContentHandler>
+vmime::shared_ptr <vmime::contentHandler> imageCts =
+ vmime::make_shared <vmime::streamContentHandler>
(imageFile->getFileReader()->getInputStream(), imageFile->getLength());
const vmime::string cid = textPart.addObject(imageCts,
@@ -359,12 +359,12 @@ The following code snippet tests if a body part is an attachment, and if so,
extract its contents to the standard output:
\begin{lstlisting}[caption={Testing if a body part is an attachment}]
-vmime::ref <vmime::bodyPart> part; // suppose we have a body part
+vmime::shared_ptr <vmime::bodyPart> part; // suppose we have a body part
if (vmime::attachmentHelper::isBodyPartAnAttachment(part))
{
// The body part contains an attachment, get it
- vmime::ref <const vmime::attachment> attach =
+ vmime::shared_ptr <const vmime::attachment> attach =
attachmentHelper::getBodyPartAttachment(part);
// Extract attachment data to standard output
@@ -376,7 +376,7 @@ if (vmime::attachmentHelper::isBodyPartAnAttachment(part))
You can also easily extract all attachments from a message:
\begin{lstlisting}[caption={Extracting all attachments from a message}]
-vmime::ref <vmime::message> msg; // suppose we have a message
+vmime::shared_ptr <vmime::message> msg; // suppose we have a message
const std::vector <ref <const attachment> > atts =
attachmentHelper::findAttachmentsInMessage(msg);
@@ -390,11 +390,11 @@ exists in the message). Simply call the {\vcode addAttachment}
function:
\begin{lstlisting}[caption={Adding an attachment to an existing message}]
-vmime::ref <vmime::message> msg; // suppose we have a message
+vmime::shared_ptr <vmime::message> msg; // suppose we have a message
// Create an attachment
-vmime::ref <vmime::fileAttachment> att =
- vmime::create <vmime::fileAttachment>
+vmime::shared_ptr <vmime::fileAttachment> att =
+ vmime::make_shared <vmime::fileAttachment>
(
/* full path to file */ "/home/vincent/paris.jpg",
/* content type */ vmime::mediaType("image/jpeg),
diff --git a/doc/book/net.tex b/doc/book/net.tex
index 88249c1c..05145cf5 100644
--- a/doc/book/net.tex
+++ b/doc/book/net.tex
@@ -68,7 +68,7 @@ services. Before using a messaging service, you must create and
initialize a session object:
\begin{lstlisting}
-vmime::ref <net::session> theSession = vmime::create <net::session>();
+vmime::shared_ptr <net::session> theSession = vmime::make_shared <net::session>();
\end{lstlisting}
Session properties include:
@@ -251,14 +251,14 @@ Depending on the type of service, you will use either {\vcode getStore()} or
\begin{lstlisting}
vmime::utility:url url("imap://user:[email protected]");
-vmime::ref <vmime::net::store> st = sess->getStore(url);
+vmime::shared_ptr <vmime::net::store> st = sess->getStore(url);
\end{lstlisting}
and for transport services:
\begin{lstlisting}
vmime::utility:url url("smtp://smtp.example.com");
-vmime::ref <vmime::net::transport> tr = sess->getTransport(url);
+vmime::shared_ptr <vmime::net::transport> tr = sess->getTransport(url);
\end{lstlisting}
@@ -271,7 +271,7 @@ properties or by using a custom authenticator (callback).
\begin{lstlisting}[caption={Setting user credentials using session
properties}]
-vmime::ref <vmime::net::session> sess; // Suppose we have a session
+vmime::shared_ptr <vmime::net::session> sess; // Suppose we have a session
sess->getProperties()["store.imap.auth.username"] = "vincent";
sess->getProperties()["store.imap.auth.password"] = "my-password";
@@ -328,13 +328,13 @@ This is how to use it:
\begin{lstlisting}
// First, create a session
-vmime::ref <vmime::net::session> sess =
- vmime::create <vmime::net::session>();
+vmime::shared_ptr <vmime::net::session> sess =
+ vmime::make_shared <vmime::net::session>();
// Next, initialize a service which will use our authenticator
-vmime::ref <vmime::net::store> st =
+vmime::shared_ptr <vmime::net::store> st =
sess->getStore(vmime::utility::url("imap://imap.example.com"),
- /* use our authenticator */ vmime::create <myAuthenticator>());
+ /* use our authenticator */ vmime::make_shared <myAuthenticator>());
\end{lstlisting}
\vnote{An authenticator object should be used with one and only one service
@@ -359,9 +359,9 @@ class mySASLAuthenticator : public vmime::security::sasl::defaultSASLAuthenticat
{
typedef vmime::security::sasl::SASLMechanism mechanism; // save us typing
- const std::vector <vmime::ref <mechanism > getAcceptableMechanisms
- (const std::vector <vmime::ref <mechanism> >& available,
- vmime::ref <mechanism> suggested) const
+ const std::vector <vmime::shared_ptr <mechanism> > getAcceptableMechanisms
+ (const std::vector <vmime::shared_ptr <mechanism> >& available,
+ vmime::shared_ptr <mechanism> suggested) const
{
// Here, you can sort the SASL mechanisms in the order they will be
// tried. If no SASL mechanism is acceptable (ie. for example, not
@@ -373,7 +373,7 @@ class mySASLAuthenticator : public vmime::security::sasl::defaultSASLAuthenticat
getAcceptableMechanisms(available, suggested);
}
- void setSASLMechanism(vmime::ref <mechanism> mech)
+ void setSASLMechanism(vmime::shared_ptr <mechanism> mech)
{
// This is called when the authentication process is going to
// try the specified mechanism.
@@ -417,11 +417,11 @@ const vmime::string msgData =
// Create a new session
vmime::utility::url url("smtp://example.com");
-vmime::ref <vmime::net::session> sess =
- vmime::create <vmime::net::session>();
+vmime::shared_ptr <vmime::net::session> sess =
+ vmime::make_shared <vmime::net::session>();
// Create an instance of the transport service
-vmime::ref <vmime::net::transport> tr = sess->getTransport(url);
+vmime::shared_ptr <vmime::net::transport> tr = sess->getTransport(url);
// Connect it
tr->connect();
@@ -431,7 +431,7 @@ vmime::utility::inputStreamStringAdapter is(msgData);
vmime::mailbox from("[email protected]");
vmime::mailboxList to;
-to.appendMailbox(vmime::create <vmime::mailbox>("[email protected]"));
+to.appendMailbox(vmime::make_shared <vmime::mailbox>("[email protected]"));
tr->send(
/* expeditor */ from,
@@ -471,11 +471,11 @@ store service:
// Create a new session
vmime::utility::url url("imap://vincent:password@imap:example.org");
-vmime::ref <vmime::net::session> sess =
- vmime::create <vmime::net::session>();
+vmime::shared_ptr <vmime::net::session> sess =
+ vmime::make_shared <vmime::net::session>();
// Create an instance of the transport service
-vmime::ref <vmime::net::store> store = sess->getStore(url);
+vmime::shared_ptr <vmime::net::store> store = sess->getStore(url);
// Connect it
store->connect();
@@ -514,7 +514,7 @@ vmime::net::folder::path path;
path /= vmime::net::folder::path::component("foo");
path /= vmime::net::folder::path::component("bar");
-vmime::ref <vmime::net::folder> fld = store->getFolder(path);
+vmime::shared_ptr <vmime::net::folder> fld = store->getFolder(path);
fld->open(vmime::net::folder::MODE_READ_WRITE);
\end{lstlisting}
@@ -565,7 +565,7 @@ folder->fetchMessages(allMessages,
for (unsigned int i = 0 ; i < allMessages.size() ; ++i)
{
- vmime::ref <vmime::net::message> msg = allMessages[i];
+ vmime::shared_ptr <vmime::net::message> msg = allMessages[i];
const int flags = msg->getFlags();
@@ -576,7 +576,7 @@ for (unsigned int i = 0 ; i < allMessages.size() ; ++i)
if (flags & vmime::net::message::FLAG_DELETED)
std::cout << " - is deleted" << std::endl;
- vmime::ref <const vmime::header> hdr = msg->getHeader();
+ vmime::shared_ptr <const vmime::header> hdr = msg->getHeader();
std::cout << " - sent on " << hdr->Date()->generate() << std::endl;
std::cout << " - sent by " << hdr->From()->generate() << std::endl;
@@ -606,8 +606,8 @@ following example extracts the first message in the default folder:
\begin{lstlisting}[caption={Extracting messages}]
// Get a reference to the folder and to its first message
-vmime::ref <vmime::net::folder> folder = store->getDefaultFolder();
-vmime::ref <vmime::net::message> msg = folder->getMessage(1);
+vmime::shared_ptr <vmime::net::folder> folder = store->getDefaultFolder();
+vmime::shared_ptr <vmime::net::message> msg = folder->getMessage(1);
// Write the message contents to the standard output
vmime::utility::outputStreamAdapter out(std::cout);
@@ -643,7 +643,7 @@ The following example will delete the second and the third message from the
store.
\begin{lstlisting}[caption={Deleting messages}]
-vmime::ref <vmime::net::folder> folder = store->getDefaultFolder();
+vmime::shared_ptr <vmime::net::folder> folder = store->getDefaultFolder();
folder->deleteMessages(vmime::net::messageSet::byNumber(/* from */ 2, /* to */ 3));
@@ -785,7 +785,7 @@ public:
ref <timeoutHandler> create()
{
- return vmime::create <myTimeoutHandler>();
+ return vmime::make_shared <myTimeoutHandler>();
}
};
\end{lstlisting}
@@ -794,7 +794,7 @@ Then, call the {\vcode setTimeoutHandlerFactory()} method on the service object
to set the time-out handler factory to use during the session:
\begin{lstlisting}
-theService->setTimeoutHandlerFactory(vmime::create <myTimeoutHandlerFactory>());
+theService->setTimeoutHandlerFactory(vmime::make_shared <myTimeoutHandlerFactory>());
\end{lstlisting}
@@ -846,7 +846,7 @@ to connect to the server (eg. \emph{imaps} instead of \emph{imap}). This is
currently available for SMTP, POP3 and IMAP.
\begin{lstlisting}
-vmime::ref <vmime::net::store> store =
+vmime::shared_ptr <vmime::net::store> store =
theSession->getStore(vmime::utility::url("imaps://example.org"));
\end{lstlisting}
@@ -913,7 +913,7 @@ at the current time;
First, we need some code to load existing X.509 certificates:
\begin{lstlisting}[caption={Reading a X.509 certificate from a file}]
-vmime::ref <vmime::security::cert::X509Certificate>
+vmime::shared_ptr <vmime::security::cert::X509Certificate>
loadX509CertificateFromFile(const std::string& path)
{
std::ifstream certFile;
@@ -925,7 +925,7 @@ vmime::ref <vmime::security::cert::X509Certificate>
}
vmime::utility::inputStreamAdapter is(certFile);
- vmime::ref <vmime::security::cert::X509Certificate> cert;
+ vmime::shared_ptr <vmime::security::cert::X509Certificate> cert;
// Try DER format
cert = vmime::security::cert::X509Certificate::import
@@ -947,11 +947,11 @@ Then, we can use the {\vcode loadX509CertificateFromFile} function to load
certificates and initialize the certificate verifier:
\begin{lstlisting}[caption={Using the default certificate verifier}]
-vmime::ref <vmime::security::cert::defaultCertificateVerifier> vrf =
- vmime::create <vmime::security::cert::defaultCertificateVerifier>();
+vmime::shared_ptr <vmime::security::cert::defaultCertificateVerifier> vrf =
+ vmime::make_shared <vmime::security::cert::defaultCertificateVerifier>();
// Load root CAs (such as Verisign or Thawte)
-std::vector <vmime::ref <vmime::security::cert::X509Certificate> > rootCAs;
+std::vector <vmime::shared_ptr <vmime::security::cert::X509Certificate> > rootCAs;
rootCAs.push_back(loadX509CertificateFromFile("/path/to/root-ca1.cer");
rootCAs.push_back(loadX509CertificateFromFile("/path/to/root-ca2.cer");
@@ -960,7 +960,7 @@ rootCAs.push_back(loadX509CertificateFromFile("/path/to/root-ca3.cer");
vrf->setX509RootCAs(rootCAs);
// Then, load certificates that the user explicitely chose to trust
-std::vector <vmime::ref <vmime::security::cert::X509Certificate> > trusted;
+std::vector <vmime::shared_ptr <vmime::security::cert::X509Certificate> > trusted;
trusted.push_back(loadX509CertificateFromFile("/path/to/trusted-site1.cer");
trusted.push_back(loadX509CertificateFromFile("/path/to/trusted-site2.cer");
@@ -988,10 +988,10 @@ class myCertVerifier : public vmime::security::cert::certificateVerifier
{
public:
- void verify(vmime::ref <certificateChain> certs)
+ void verify(vmime::shared_ptr <certificateChain> certs)
{
// Obtain the subject's certificate
- vmime::ref <vmime::security::cert::certificate> cert = chain->getAt(0);
+ vmime::shared_ptr <vmime::security::cert::certificate> cert = chain->getAt(0);
std::cout << std::endl;
std::cout << "Server sent a '" << cert->getType() << "'"
@@ -1018,7 +1018,7 @@ a basic cache implementation.}
Finally, to make the service use your own certificate verifier, simply write:
\begin{lstlisting}
-theService->setCertificateVerifier(vmime::create <myCertVerifier>());
+theService->setCertificateVerifier(vmime::make_shared <myCertVerifier>());
\end{lstlisting}
\subsection{SSL/TLS Properties} % --------------------------------------------
@@ -1032,10 +1032,10 @@ the session), or they will not be used.
The following example shows how to set the cipher suite preferences for TLS:
\begin{lstlisting}[caption={Setting TLS cipher suite preferences}]
-vmime::ref <vmime::net::session> sess = /* ... */;
+vmime::shared_ptr <vmime::net::session> sess = /* ... */;
-vmime::ref <vmime::net::tls::TLSProperties> tlsProps =
- vmime::create <vmime::net::tls::TLSProperties>();
+vmime::shared_ptr <vmime::net::tls::TLSProperties> tlsProps =
+ vmime::make_shared <vmime::net::tls::TLSProperties>();
// for OpenSSL
tlsProps->setCipherString("HIGH:!ADH:@STRENGTH");
generated by cgit v1.2.3 (git 2.25.1) at 2025-04-28 13:02:08 +0000