forked from neomutt/neomutt
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathhcache.h
211 lines (190 loc) · 7.39 KB
/
hcache.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
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
/**
* @file
* Header cache multiplexor
*
* @authors
* Copyright (C) 2004 Thomas Glanzmann <[email protected]>
* Copyright (C) 2004 Tobias Werth <[email protected]>
* Copyright (C) 2004 Brian Fundakowski Feldman <[email protected]>
* Copyright (C) 2016 Pietro Cerutti <[email protected]>
*
* @copyright
* 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 2 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, see <http://www.gnu.org/licenses/>.
*/
/**
* @page hcache HCACHE: Header cache API
*
* This module defines the user-visible header cache API, which is used within
* neomutt to cache and restore mail header data.
*
* @subpage hc_serial
*
* @subpage hc_hcache
*
* Backends:
*
* | File | Description |
* | :------------ | :--------------- |
* | hcache/bdb.c | @subpage hc_bdb |
* | hcache/gdbm.c | @subpage hc_gdbm |
* | hcache/kc.c | @subpage hc_kc |
* | hcache/lmdb.c | @subpage hc_lmdb |
* | hcache/qdbm.c | @subpage hc_qdbm |
* | hcache/tc.c | @subpage hc_tc |
*/
#ifndef _MUTT_HCACHE_H
#define _MUTT_HCACHE_H
#include <stdbool.h>
#include <stddef.h>
#include <sys/time.h>
struct Header;
/**
* struct HeaderCache - header cache structure
*
* This struct holds both the backend-agnostic and the backend-specific parts
* of the header cache. Backend code MUST initialize the fetch, store,
* delete and close function pointers in hcache_open, and MAY store
* backend-specific context in the ctx pointer.
*/
struct HeaderCache
{
char *folder;
unsigned int crc;
void *ctx;
};
typedef struct HeaderCache header_cache_t;
/**
* typedef hcache_namer_t - Prototype for function to compose hcache file names
* @param path Path of message
* @param dest Buffer for filename
* @param destlen Length of buffer
* @retval num Characters written to buffer
*/
typedef int (*hcache_namer_t)(const char *path, char *dest, size_t dlen);
/**
* union Validate - Header cache validity
*/
union Validate {
struct timeval timeval;
unsigned int uidvalidity;
};
/* These Config Variables are only used in hcache/hcache.c */
extern char *HeaderCacheBackend;
/**
* mutt_hcache_open - open the connection to the header cache
* @param path Location of the header cache (often as specified by the user)
* @param folder Name of the folder containing the messages
* @param namer Optional (might be NULL) client-specific function to form the
* final name of the hcache database file.
* @retval ptr Success, header_cache_t struct
* @retval NULL Otherwise
*/
header_cache_t *mutt_hcache_open(const char *path, const char *folder, hcache_namer_t namer);
/**
* mutt_hcache_close - close the connection to the header cache
* @param h Pointer to the header_cache_t structure got by mutt_hcache_open
*/
void mutt_hcache_close(header_cache_t *h);
/**
* mutt_hcache_fetch - fetch and validate a message's header from the cache
* @param h Pointer to the header_cache_t structure got by mutt_hcache_open
* @param key Message identification string
* @param keylen Length of the string pointed to by key
* @retval ptr Succees, data if found and valid
* @retval NULL Otherwise
*
* @note This function performs a check on the validity of the data found by
* comparing it with the crc value of the header_cache_t structure.
*
* @note The returned pointer must be freed by calling mutt_hcache_free. This
* must be done before closing the header cache with mutt_hcache_close.
*/
void *mutt_hcache_fetch(header_cache_t *h, const char *key, size_t keylen);
/**
* mutt_hcache_fetch_raw - fetch a message's header from the cache
* @param h Pointer to the header_cache_t structure got by mutt_hcache_open
* @param key Message identification string
* @param keylen Length of the string pointed to by key
* @retval ptr Success, the data if found
* @retval NULL Otherwise
*
* @note This function does not perform any check on the validity of the data
* found.
* @note The returned pointer must be freed by calling mutt_hcache_free. This
* must be done before closing the header cache with mutt_hcache_close.
*/
void *mutt_hcache_fetch_raw(header_cache_t *h, const char *key, size_t keylen);
/**
* mutt_hcache_free - free previously fetched data
* @param h Pointer to the header_cache_t structure got by mutt_hcache_open
* @param data Pointer to the data got using hcache_fetch or hcache_fetch_raw
*/
void mutt_hcache_free(header_cache_t *h, void **data);
/**
* mutt_hcache_restore - restore a Header from data retrieved from the cache
* @param d Data retrieved using mutt_hcache_fetch or mutt_hcache_fetch_raw
* @retval ptr Success, the restored header (cannot be NULL)
*
* @note The returned Header must be free'd by caller code with
* mutt_header_free().
*/
struct Header *mutt_hcache_restore(const unsigned char *d);
/**
* mutt_hcache_store - store a Header along with a validity datum
* @param h Pointer to the header_cache_t structure got by mutt_hcache_open
* @param key Message identification string
* @param keylen Length of the string pointed to by key
* @param header Message header to store
* @param uidvalidity IMAP-specific UIDVALIDITY value, or 0 to use the current time
* @retval 0 Success
* @retval num Generic or backend-specific error code otherwise
*/
int mutt_hcache_store(header_cache_t *h, const char *key, size_t keylen,
struct Header *header, unsigned int uidvalidity);
/**
* mutt_hcache_store_raw - store a key / data pair
* @param h Pointer to the header_cache_t structure got by mutt_hcache_open
* @param key Message identification string
* @param keylen Length of the string pointed to by key
* @param data Payload to associate with key
* @param dlen Length of the buffer pointed to by the @a data parameter
* @retval 0 success
* @retval num Generic or backend-specific error code otherwise
*/
int mutt_hcache_store_raw(header_cache_t *h, const char *key, size_t keylen,
void *data, size_t dlen);
/**
* mutt_hcache_delete - delete a key / data pair
* @param h Pointer to the header_cache_t structure got by mutt_hcache_open
* @param key Message identification string
* @param keylen Length of the string pointed to by key
* @retval 0 Success
* @retval num Generic or backend-specific error code otherwise
*/
int mutt_hcache_delete(header_cache_t *h, const char *key, size_t keylen);
/**
* mutt_hcache_backend_list - get a list of backend identification strings
* @retval ptr Comma separated string describing the compiled-in backends
*
* @note The returned string must be free'd by the caller
*/
const char *mutt_hcache_backend_list(void);
/**
* mutt_hcache_is_valid_backend - Is the string a valid hcache backend
* @param s String identifying a backend
* @retval true s is recognized as a valid backend
* @retval false otherwise
*/
bool mutt_hcache_is_valid_backend(const char *s);
#endif /* _MUTT_HCACHE_H */