-
Notifications
You must be signed in to change notification settings - Fork 388
/
mu-msg-iter.h
167 lines (138 loc) · 4.52 KB
/
mu-msg-iter.h
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
/*
** Copyright (C) 2008-2010 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
**
** This program is free software; you can redistribute it and/or modify
** it under the terms of the GNU General Public License as published by
** the Free Software Foundation; either version 3 of the License, or
** (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
** GNU General Public License for more details.
**
** You should have received a copy of the GNU General Public License
** along with this program; if not, write to the Free Software Foundation,
** Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
**
*/
#ifndef __MU_MSG_ITER_H__
#define __MU_MSG_ITER_H__
#include <glib.h>
#include <mu-msg.h>
G_BEGIN_DECLS
/**
* MuMsgIter is a structure to iterate over the results of a
* query. You can iterate only in one-direction, and you can do it
* only once.
*
*/
struct _MuMsgIter;
typedef struct _MuMsgIter MuMsgIter;
/**
* create a new MuMsgIter -- basically, an iterator over the search
* results
*
* @param enq a Xapian::Enquire* cast to XapianEnquire* (because this
* is C, not C++),providing access to search results
* @param batchsize how many results to retrieve at once
* @param threads whether to calculate threads
* @param sorting field when using threads; note, when 'threads' is
* FALSE, this should be MU_MSG_FIELD_ID_NONE
* @param if TRUE, revert the sorting order
*
* @return a new MuMsgIter, or NULL in case of error
*/
MuMsgIter *mu_msg_iter_new (XapianEnquire *enq,
size_t batchsize, gboolean threads,
MuMsgFieldId threadsortfield,
gboolean revert) G_GNUC_WARN_UNUSED_RESULT;
/**
* get the next message (which you got from
* e.g. mu_query_run)
*
* @param iter a valid MuMsgIter iterator
*
* @return TRUE if it succeeded, FALSE otherwise (e.g., because there
* are no more messages in the query result)
*/
gboolean mu_msg_iter_next (MuMsgIter *iter);
/**
* reset the iterator to the beginning
*
* @param iter a valid MuMsgIter iterator
*
* @return TRUE if it succeeded, FALSE otherwise
*/
gboolean mu_msg_iter_reset (MuMsgIter *iter);
/**
* does this iterator point past the end of the list?
*
* @param iter a valid MuMsgIter iterator
*
* @return TRUE if the iter points past end of the list, FALSE
* otherwise
*/
gboolean mu_msg_iter_is_done (MuMsgIter *iter);
/**
* destroy the sequence of messages; ie. /all/ of them
*
* @param msg a valid MuMsgIter message or NULL
*/
void mu_msg_iter_destroy (MuMsgIter *iter);
/**
* get the corresponding MuMsg for this iter; this instance is owned
* by MuMsgIter, and becomes invalid after either mu_msg_iter_destroy
* or mu_msg_iter_next. _do not_ unref it; it's a floating reference.
*
* @param iter a valid MuMsgIter instance*
*
* @return a MuMsg instance, or NULL in case of error
*/
MuMsg* mu_msg_iter_get_msg_floating (MuMsgIter *iter)
G_GNUC_MALLOC G_GNUC_WARN_UNUSED_RESULT;
/**
* get the document id for the current message
*
* @param iter a valid MuMsgIter iterator
*
* @return the docid or (unsigned int)-1 in case of error
*/
unsigned int mu_msg_iter_get_docid (MuMsgIter *iter);
/**
* calculate the message threads
*
* @param iter a valid MuMsgIter iterator
*
* @return TRUE if it worked, FALSE otherwsie.
*/
gboolean mu_msg_iter_calculate_threads (MuMsgIter *iter);
enum _MuMsgIterThreadProp {
MU_MSG_ITER_THREAD_PROP_ROOT = 1 << 0,
MU_MSG_ITER_THREAD_PROP_FIRST_CHILD = 1 << 1,
MU_MSG_ITER_THREAD_PROP_EMPTY_PARENT = 1 << 2,
MU_MSG_ITER_THREAD_PROP_DUP = 1 << 3,
MU_MSG_ITER_THREAD_PROP_HAS_CHILD = 1 << 4
};
typedef guint8 MuMsgIterThreadProp;
struct _MuMsgIterThreadInfo {
gchar *threadpath; /* a string decribing the thread-path in
* such a way that we can sort by this
* string to get the right order. */
guint level; /* thread-depth -- [0...] */
MuMsgIterThreadProp prop;
};
typedef struct _MuMsgIterThreadInfo MuMsgIterThreadInfo;
/**
* get a the MuMsgThreaderInfo struct for this message; this only
* works when you created the mu-msg-iter with threading enabled
*
* @param iter a valid MuMsgIter iterator
*
* @return an info struct
*/
const MuMsgIterThreadInfo* mu_msg_iter_get_thread_info (MuMsgIter *iter);
/* FIXME */
const char* mu_msg_iter_get_path (MuMsgIter *iter);
G_END_DECLS
#endif /*__MU_MSG_ITER_H__*/