1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtextendedmail.html
\title Messaging Framework Client Library
\tableofcontents
\section1 Overview
The Messaging Framework Client library provides a set of APIs for accessing messaging data.
Interfaces are provided to create, modify, store, and retrieve messages.
The library does not directly support sending or retrieving messages; these actions are currently supported via a service request mechanism.
The Client library provides unified access to the messaging data on a device including concurrent access to messaging data by multiple applications, and independence from the mechanism used to store the messaging data on the device.
For detailed class information refer to: \l{Messaging Classes}.
The library is augmented by two related, more specific libraries:
\list
\o the \l{Messaging Client Utility Library}{Client utility} library provides classes that assist with building GUI messaging client applications, and
\o the \l{Message Server Support Library}{Server support} library provides classes that assist with creating plugin components for the \l{MessageServer Daemon}{Message Server} daemon.
\endlist
\section1 Composition and Manipulation of Messages
The Client library provides a number of classes to assist with the composition and manipulation of message data.
Messages of all supported types are represented uniformly, although not all transport mechanisms are able to deliver more complex message formulations.
Messages can be composed of multiple parts and constructed hierarchically. The Client library supports composition of multipart messages from individual part objects.
Classes to assist with composition and manipulation of messages:
\table
\header \o Class \o Description
\row \o QMailMessageId \o Represents the mail store identifiers for message records.
\row \o QMailMessageMetaData \o Represents a message stored by the Messaging Framework.
\row \o QMailMessage \o Convenient interface for working with messages.
\row \o QMailMessagePart \o Convenient interface for working with message attachments.
\row \o QMailMessagePartContainer \o Access to a collection of message parts.
\row \o QMailMessageBody \o The body element of a message or message part.
\row \o QMailMessageHeaderField \o Encapsulates the parsing of message header fields.
\row \o QMailMessageContentDisposition \o Encapsulates the parsing of the RFC 2822 'Content-Disposition' header field.
\row \o QMailMessageContentType \o Encapsulates the parsing of the RFC 2822 'Content-Type' header field.
\row \o QMailAddress \o Interface for manipulating message address strings.
\row \o QMailTimeStamp \o Manages message time stamps.
\row \o QMailCodec \o Base class for classes implementing codecs used in message composition.
\endtable
\section1 Message Accounts
The Client Library provides classes for storing information about
messaging accounts both outgoing and incoming.
Classes relating to messaging accounts:
\table
\header \o Class \o Description
\row \o QMailAccountId \o Represents the mail store identifiers for account records.
\row \o QMailAccount \o Stores attributes for a messaging account.
\row \o QMailFolderId \o Represents the mail store identifiers for folder records.
\row \o QMailFolder \o Represents a folder for messages on the mail store.
\row \o QMailMessageRemovalRecord \o Represents a message deleted from the local mail store.
\row \o QMailAccountConfiguration \o Contains the configuration details for an account.
\endtable
\section1 Message threads
The Client Library provides classes for storing information about
message threads (a.k.a. conversations).
Classes relating to message threads:
\table
\header \o Class \o Description
\row \o QMailThreadId \o Represents the mail store identifiers for thread records.
\row \o QMailThread \o Stores attributes for a message thread.
\endtable
\section1 Message Listing
The Client library provides classes to assist with displaying lists of message data. These classes allow clients to
display lists of messages and accounts with minimal effort, and with minimal resource consumption.
Classes to assist with listing messages:
\table
\header \o Class \o Description
\row \o QMailAccountListModel \o Provides a model representing the accounts stored by the Messaging Framework.
\row \o QMailMessageListModel \o Provides a model representing the messages stored by the Messaging Framework.
\endtable
\section1 Message Navigation
The Client library provides classes to assist with partitioning and navigating message data
according to the intrinsic message properties. The classes allow clients to display a hierarchical
taxonomy of message data, using standard or arbitrary categorization criteria.
Classes to assist with navigating messages:
\table
\header \o Class \o Description
\row \o QMailMessageSet \o Provides a representation for a subset of the store's messages, suitable for display in a tree view.
\row \o QMailAccountMessageSet \o Provides a message set implementation grouping messages by their parent account ID.
\row \o QMailFolderMessageSet \o Provides a message set implementation grouping messages by their parent folder ID.
\row \o QMailFilterMessageSet \o Provides a message set implementation grouping messages by arbitrary criteria.
\row \o QMailMessageSetModel \o Provides a model representing arbitrary message sets in a tree arrangement.
\endtable
\section1 Sorting and Searching Functionality
The Client library provides a number of sort and search functions to aid in selecting data most useful to the view requested.
This reduces the burden on the application for managing the messaging data, as well as allowing better use of the underlying storage mechanism.
Sorting is accomplished by providing a sorting key, specifying the sort order, and the message property upon which to sort.
Searching is accomplished by providing a search condition, specifying a value, the message property to match, and the desired relation between the value and the message property.
Search conditions can be combined to produce searches of arbitrary complexity.
Classes to assist with sorting and searching messages:
\table
\header \o Class \o Description
\row \o QMailStore \o Represents the main interface for storage and retrieval of messages and folders on the mail store.
\row \o QMailAccountKey \o Defines the parameters used for querying a subset of all available accounts from the mail store.
\row \o QMailAccountSortKey \o Defines the parameters used for sorting accounts queried from the mail store.
\row \o QMailFolderKey \o Defines the parameters used for querying a subset of all available mail folders from the mail store.
\row \o QMailFolderSortKey \o Defines the parameters used for sorting mail folders queried from the mail store.
\row \o QMailThreadKey \o Defines the parameters used for querying a subset of all available threads from the mail store.
\row \o QMailThreadSortKey \o Defines the parameters used for sorting threads queried from the mail store.
\row \o QMailMessageKey \o Defines the parameters used for querying a subset of all available mail messages from the mail store.
\row \o QMailMessageSortKey \o Defines the parameters used for sorting messages queried from the mail store.
\endtable
\section1 Message Content Management Plugins
The Client library uses a plugin system to register components that provide message content management services.
Message content can be stored externally to the QMailStore that contains the message meta data; plugins can be implemented to provide the Message Library with access to this content.
Classes supporting the use of plugins for message content management:
\table
\header \o Class \o Description
\row \o QMailContentManager \o Defines the interface to objects that provide a message content management service
\row \o QMailContentManagerFactory \o Creates objects implementing the QMailContentManager interface
\row \o QMailContentManagerPlugin \o Defines a base class for implementing message content management plug-ins
\row \o QMailContentManagerPluginInterface \o Defines the interface to plug-ins that provide message content managers
\endtable
\section1 Message Transport Service
The Client library provides the QMailMessageServer class, which provides an interface for a messaging client application to communicate with the system's messaging server.
The messaging server provides services relating to the transmission and retrieval of messages from various sources defined by QMailAccount objects.
Using QMailMessageServer, clients can communicate with the messaging server via local-process signals and slots, without having any direct contact with the server process.
The QMailServiceAction class provides a convenient abstraction above the QMailMessageServer interface, allowing clients to handle only events relating to a specific action requested from the messaging server.
QMailRetrievalAction, QMailTransmitAction, QMailStorageAction, QMailSearchAction and QMailProtocolAction specialize QMailServiceAction to implement specific exchanges between a client application and the messaging server.
\section1 Concurrent Access to Messaging Data
The Client library provides a level of concurrent access to messaging data by multiple applications.
The concurrent access does guarantee that data won't be corrupted by concurrent access, however does not give any guarantees as to performance of messaging data access if accessed concurrently by multiple applications.
\section1 Abstraction of Messaging Data Storage Mechanism
The Client library abstracts the storage method used to store messaging data.
On a device the Client library will only read and write the primary storage mechanism and synchronizing mechanism.
\section1 Performance Characteristics
The performance of the Client library is tested using the reference \c{messageserver} implementation included with the Messaging Framework.
Various tasks are performed using different amounts and sizes of message to determine the effect these parameters have on the library's performance.
Placeholder: The results of these tests would be available <here>, if those results were currently exported.
\section1 Assumptions and Dependencies
The Client library requires SQL support either through the included SQLite or through some other SQL engine.
\section1 Examples
The QMF package contains some example programs that demonstrate how to use the library's functionality.
\table
\header \o Name \o Description
\row \o qtmail \o Demonstrates how to build a mail client application.
\row \o messagingaccounts \o Demonstrates how to build a stand alone accounts configuration application.
\row \o serverobserver \o Demonstrates how to build a stand alone application that observes actions being performed by the messageserver process.
\endtable
\section1 Changes Between Versions
Historical changes in the Client library API are listed in \l{changes-qtopiamail.html}{CHANGES.qdoc}.
*/
|
