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
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\module QtMessaging
\title QtMessaging Module
\brief The QtMessaging module provides access to messaging services.
The module enables access to messaging services to search and sort
messages, send messages, retrieve message data, and launch the preferred
messaging client on the system to either display an existing message,
compose a new message, or respond to an existing message.
*/
/*!
\page messaging.html
\ingroup mobility
\title Messaging
\brief The Messaging API enables access to messaging services.
The Qt Messaging API enables access to messaging services to
search and sort messages, send messages, retrieve message
data, and launch the preferred messaging client on the system
to either display an existing message, compose a new message,
or respond to an existing message.
\tableofcontents
\section1 Namespace
The QtMobility APIs are placed into the \i{QtMobility} namespace. This is done
to facilitate the future migration of QtMobility APIs into Qt. See the
\l {Quickstart Example}{Quickstart guide} for an example on how the
namespace impacts on application development.
\section1 Overview
The messaging library provides a set of APIs for accessing messaging data.
Interfaces are provided to retrieve and query messages, folders and
accounts, also interfaces to create, modify, and store messages are
provided. A unified interface for manipulation and storage of SMS, MMS,
MIME Email and TNEF Email messages is provided. Handling of
messages that have only been partially retrieved is supported.
An API to access messaging services to send messages and retrieve message
data is provided, as well as messaging services to compose, reply to,
forward and show messages using a native application.
Notifications of addition, removal and updating of stored messages can be
enabled.
The 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.
On Microsoft Windows, MAPI header files are required to be installed,
we recommend installing Visual Studio Express for this purpose.
On Linux QMF 2010W41 or newer is required to be installed and the QMF_INCLUDEDIR and
QMF_LIBDIR environment variables set to the
messagingframework/src/libraries/qmfclient
and build/messagingframework/image/lib directories respectively, and
for the LD_LIBRARY_PATH to include the build/messagingframework/image/lib directory.
\section1 Reference documentation
\section2 Main classes
\annotatedlist messaging
\section1 Composition and Manipulation of Messages
The library provides a number of classes to assist with the composition
and manipulation of message data. Messages of all supported types are
represented uniformly. Messages can be composed of multiple parts.
Classes to assist with composition and manipulation of messages:
\table
\header \o Class \o Description
\row \o QMessageId \o Represents the messaging store identifiers for messages.
\row \o QMessage \o Convenient interface for working with messages.
\row \o QMessageContentContainer \o Interface for an internet media (MIME) entity.
\row \o QMessageAddress \o Interface for manipulating message address strings.
\endtable
\section1 Message Accounts
The library provides classes for accessing information about messaging
accounts both outgoing and incoming.
Classes relating to messaging accounts:
\table
\header \o Class \o Description
\row \o QMessageAccountId \o Represents the messaging store identifiers for accounts.
\row \o QMessageAccount \o Stores attributes for a messaging account.
\row \o QMessageFolderId \o Represents the messaging store identifiers for folders.
\row \o QMessageFolder \o Represents a folder of messages on the messaging store.
\endtable
\section1 Sorting and Filtering Functionality
The library provides a number of sort and filter functions to aid in
selecting a useful view of data. This reduces the burden on the client
of the library for managing the messaging data, as well as allowing
better use of the underlying storage mechanism.
Sorting is accomplished by providing a sorting object, specifying the sort
order, and the message property upon which to order.
Filtering is accomplished by providing a filtering condition, specifying a
value, the property to match, and the desired relation between the value
and the property.
Filters can be combined using boolean operators to produce filters of
arbitrary complexity.
Classes to assist with sorting and filtering messages:
\table
\header \o Class \o Description
\row \o QMessageManager \o Represents the main interface for storage and retrieval of messages, folders and accounts from the messaging store.
\row \o QMessageFilter \o Defines the parameters used for querying a subset of all available messages from the messaging store.
\row \o QMessageSortOrder \o Defines the parameters used for sorting messages queried from the messaging store.
\row \o QMessageFolderFilter \o Defines the parameters used for querying a subset of all available message folders from the messaging store.
\row \o QMessageFolderSortOrder \o Defines the parameters used for sorting message folders queried from the messaging store.
\row \o QMessageAccountFilter \o Defines the parameters used for querying a subset of all available accounts from the messaging store.
\row \o QMessageAccountSortOrder \o Defines the parameters used for sorting accounts queried from the messaging store.
\endtable
\section2 Using the Ordering Functions
An example of the use of Ordering functions can be found in the Send Message
example.
\code
QMessageIdList ids = QMessageManager().queryMessages(QMessageFilter(),
QMessageSortOrder::byReceptionTimeStamp(Qt::DescendingOrder), 100, 0);
\endcode
\section2 Using the Filter Functions
The following code is taken from the Keep In Touch example, it
demonstrates the use of filters to achieve desired effects. You can
also see how the filters once constructed can be operated on by typical
boolean operators, in the same way you would manipulate bit settings in C.
In this way we can build more complex conditions.
\code
QMessageFilter includeFilter(QMessageFilter::byTimeStamp(minimumDate,
QMessageDataComparator::GreaterThanEqual));
QMessageFilter excludeFilter(QMessageFilter::byTimeStamp(maximumDate,
QMessageDataComparator::GreaterThanEqual));
QMessageFilter outgoingFilter(QMessageFilter::byStatus(QMessage::Incoming,
QMessageDataComparator::Excludes));
// Search for messages containing addresses to exclude
service.queryMessages(outgoingFilter & excludeFilter);
// Create the filter needed to locate messages to search for addresses
inclusionFilter = (outgoingFilter & includeFilter & ~excludeFilter);
\endcode
\section1 Messaging Services
The library provides the QMessageService class, which provides an
interface to communicate with the system's native messaging services,
including sending messages, retrieving message data, and composing or
showing a message using a native application.
Service actions communciate their operational status by emitting signals.
Functions outside the QMessageService class should not invoke network activity.
That is, only QMessageService functions should be responsible for initiating
network activity (Note: this is not true for the Windows desktop and mobile
platforms, where network activity can occur outside the client's control).
\section1 Concurrent Access to Messaging Data
The library provides a level of concurrent access to messaging data by
multiple clients.
The concurrent access does guarantee that data won't be corrupted by
concurrent access, however it does not give any guarantees as to
performance of messaging data access if accessed concurrently by
multiple clients.
A single client may access the messaging data from multiple threads, but
only one thread may access the data concurrently.
\section1 Abstraction of Messaging Data Storage Mechanism
The library abstracts the storage method used to store messaging data.
\section1 QML Messaging Elements
\list
\o \l MessageModel
\o \l MessageFilter
\o \l MessageUnionFilter
\o \l MessageIntersectionFilter
\endlist
\section1 Examples
\section2 Keep In Touch
The \l {keepintouch}{Keep In Touch} example shows how to extract useful
information from the messages stored by the system.
\section2 Service Actions
The \l {serviceactions}{Service Actions} example is a program to demonstrate
how to compose, send, show, query and retrieve messages, and also react to
message store events using the QtMobility Messaging API.
*/
|
