lib.h File Reference

Header cache multiplexor. More...

#include <stddef.h>
#include <stdint.h>

Include dependency graph for lib.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	EmailCache
	header cache structure More...
struct	HCacheEntry
	Wrapper for Email retrieved from the header cache. More...

Typedefs
typedef struct EmailCache	header_cache_t
typedef void(*	hcache_namer_t) (const char *path, struct Buffer *dest)
	Prototype for function to compose hcache file names. More...

Functions
header_cache_t *	mutt_hcache_open (const char *path, const char *folder, hcache_namer_t namer)
	open the connection to the header cache More...
void	mutt_hcache_close (header_cache_t *hc)
	close the connection to the header cache More...
int	mutt_hcache_store (header_cache_t *hc, const char *key, size_t keylen, struct Email *e, uint32_t uidvalidity)
	store a Header along with a validity datum More...
struct HCacheEntry	mutt_hcache_fetch (header_cache_t *hc, const char *key, size_t keylen, uint32_t uidvalidity)
	fetch and validate a message's header from the cache More...
int	mutt_hcache_store_raw (header_cache_t *hc, const char *key, size_t keylen, void *data, size_t dlen)
	store a key / data pair More...
void *	mutt_hcache_fetch_raw (header_cache_t *hc, const char *key, size_t keylen, size_t *dlen)
	Fetch a message's header from the cache. More...
void	mutt_hcache_free_raw (header_cache_t *hc, void **data)
	free data fetched with mutt_hcache_fetch_raw() More...
int	mutt_hcache_delete_header (header_cache_t *hc, const char *key, size_t keylen)
	delete a key / data pair More...
bool	config_init_hcache (struct ConfigSet *cs)
	Register hcache config variables. More...

Variables
char *	C_HeaderCache
	Config: (hcache) Directory/file for the header cache database. More...
char *	C_HeaderCacheBackend
	Config: (hcache) Header cache backend to use. More...
short	C_HeaderCacheCompressLevel
	Config: (hcache) Level of compression for method. More...
char *	C_HeaderCacheCompressMethod
	Config: (hcache) Enable generic hcache database compression. More...
bool	C_MaildirHeaderCacheVerify
	Config: (hcache) Check for maildir changes when opening mailbox. More...

Detailed Description

Header cache multiplexor.

Authors

• Thomas Glanzmann
• Tobias Werth
• Brian Fundakowski Feldman
• Pietro Cerutti
• Tino Reichardt

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/.

Definition in file lib.h.

Typedef Documentation

header_cache_t

typedef struct EmailCache header_cache_t

Definition at line 93 of file lib.h.

hcache_namer_t

typedef void(* hcache_namer_t) (const char *path, struct Buffer *dest)

Prototype for function to compose hcache file names.

Parameters

path	Path of message
dest	Buffer for filename

Definition at line 110 of file lib.h.

Function Documentation

mutt_hcache_open()

header_cache_t* mutt_hcache_open	(	const char *	path,
		const char *	folder,
		hcache_namer_t	namer
	)

open the connection to the header cache

Parameters

path	Location of the header cache (often as specified by the user)
folder	Name of the folder containing the messages
namer	Optional (might be NULL) client-specific function to form the final name of the hcache database file.

Return values

ptr	Success, header_cache_t struct
NULL	Otherwise

open the connection to the header cache

Definition at line 321 of file hcache.c.

{
  const struct StoreOps *ops = hcache_get_ops();
  if (!ops)
    return NULL;

  header_cache_t *hc = mutt_mem_calloc(1, sizeof(header_cache_t));

  /* Calculate the current hcache version from dynamic configuration */
  if (hcachever == 0x0)
  {
    union
    {
      unsigned char charval[16];
      unsigned int intval;
    } digest;
    struct Md5Ctx md5ctx;

    hcachever = HCACHEVER;

    mutt_md5_init_ctx(&md5ctx);

    /* Seed with the compiled-in header structure hash */
    mutt_md5_process_bytes(&hcachever, sizeof(hcachever), &md5ctx);

    /* Mix in user's spam list */
    struct Replace *sp = NULL;
    STAILQ_FOREACH(sp, &SpamList, entries)
    {
      mutt_md5_process(sp->regex->pattern, &md5ctx);
      mutt_md5_process(sp->templ, &md5ctx);
    }

    /* Mix in user's nospam list */
    struct RegexNode *np = NULL;
    STAILQ_FOREACH(np, &NoSpamList, entries)
    {
      mutt_md5_process(np->regex->pattern, &md5ctx);
    }

    /* Get a hash and take its bytes as an (unsigned int) hash version */
    mutt_md5_finish_ctx(&md5ctx, digest.charval);
    hcachever = digest.intval;
  }

#ifdef USE_HCACHE_COMPRESSION
  if (C_HeaderCacheCompressMethod)
  {
    const struct ComprOps *cops = compr_get_ops();

    hc->cctx = cops->open(C_HeaderCacheCompressLevel);
    if (!hc->cctx)
    {
      FREE(&hc);
      return NULL;
    }

    /* remember the buffer of database backend */
    mutt_debug(LL_DEBUG3, "Header cache will use %s compression\n", cops->name);
  }
#endif

  hc->folder = get_foldername(folder);
  hc->crc = hcachever;

  if (!path || (path[0] == '\0'))
  {
    FREE(&hc->folder);
    FREE(&hc);
    return NULL;
  }

  struct Buffer *hcpath = mutt_buffer_pool_get();
  hcache_per_folder(hcpath, path, hc->folder, namer);

  hc->ctx = ops->open(mutt_b2s(hcpath));
  if (!hc->ctx)
  {
    /* remove a possibly incompatible version */
    if (unlink(mutt_b2s(hcpath)) == 0)
    {
      hc->ctx = ops->open(mutt_b2s(hcpath));
      if (!hc->ctx)
      {
        FREE(&hc->folder);
        FREE(&hc);
      }
    }
  }

  mutt_buffer_pool_release(&hcpath);
  return hc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_hcache_close()

void mutt_hcache_close

(

header_cache_t *

hc

)

close the connection to the header cache

Parameters

hc	Pointer to the header_cache_t structure got by mutt_hcache_open()

close the connection to the header cache

Definition at line 418 of file hcache.c.

{
  const struct StoreOps *ops = hcache_get_ops();
  if (!hc || !ops)
    return;

#ifdef USE_HCACHE_COMPRESSION
  if (C_HeaderCacheCompressMethod)
    compr_get_ops()->close(&hc->cctx);
#endif

  ops->close(&hc->ctx);
  FREE(&hc->folder);
  FREE(&hc);
}

Here is the caller graph for this function:

mutt_hcache_store()

int mutt_hcache_store	(	header_cache_t *	hc,
		const char *	key,
		size_t	keylen,
		struct Email *	e,
		uint32_t	uidvalidity
	)

store a Header along with a validity datum

Parameters

hc	Pointer to the header_cache_t structure got by mutt_hcache_open()
key	Message identification string
keylen	Length of the key string
e	Email to store
uidvalidity	IMAP-specific UIDVALIDITY value, or 0 to use the current time

Return values

0	Success
num	Generic or backend-specific error code otherwise

store a Header along with a validity datum

Definition at line 525 of file hcache.c.

{
  if (!hc)
    return -1;

  int dlen = 0;
  char *data = dump(hc, e, &dlen, uidvalidity);

#ifdef USE_HCACHE_COMPRESSION
  if (C_HeaderCacheCompressMethod)
  {
    /* We don't compress uidvalidity and the crc, so we can check them before
     * decompressing on fetch().  */
    size_t hlen = header_size();

    const struct ComprOps *cops = compr_get_ops();

    /* data / dlen gets ptr to compressed data here */
    size_t clen = dlen;
    void *cdata = cops->compress(hc->cctx, data + hlen, dlen - hlen, &clen);
    if (!cdata)
    {
      FREE(&data);
      return -1;
    }

    char *whole = mutt_mem_malloc(hlen + clen);
    memcpy(whole, data, hlen);
    memcpy(whole + hlen, cdata, clen);

    FREE(&data);

    data = whole;
    dlen = hlen + clen;
  }
#endif

  /* store uncompressed data */
  struct RealKey *rk = realkey(key, keylen);
  int rc = mutt_hcache_store_raw(hc, rk->key, rk->len, data, dlen);

  FREE(&data);

  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_hcache_fetch()

struct HCacheEntry mutt_hcache_fetch	(	header_cache_t *	hc,
		const char *	key,
		size_t	keylen,
		uint32_t	uidvalidity
	)

fetch and validate a message's header from the cache

Parameters

hc	Pointer to the header_cache_t structure got by mutt_hcache_open()
key	Message identification string
keylen	Length of the string pointed to by key
uidvalidity	Only restore if it matches the stored uidvalidity

Return values

obj	HCacheEntry containing an Email, empty on failure

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.

fetch and validate a message's header from the cache

Definition at line 437 of file hcache.c.

{
  struct RealKey *rk = realkey(key, keylen);
  struct HCacheEntry entry = { 0 };

  size_t dlen;
  void *data = mutt_hcache_fetch_raw(hc, rk->key, rk->len, &dlen);
  void *to_free = data;
  if (!data)
  {
    goto end;
  }

  /* restore uidvalidity and crc */
  size_t hlen = header_size();
  int off = 0;
  serial_restore_uint32_t(&entry.uidvalidity, data, &off);
  serial_restore_int(&entry.crc, data, &off);
  assert((size_t) off == hlen);
  if (entry.crc != hc->crc || ((uidvalidity != 0) && uidvalidity != entry.uidvalidity))
  {
    goto end;
  }

#ifdef USE_HCACHE_COMPRESSION
  if (C_HeaderCacheCompressMethod)
  {
    const struct ComprOps *cops = compr_get_ops();

    void *dblob = cops->decompress(hc->cctx, (char *) data + hlen, dlen - hlen);
    if (!dblob)
    {
      goto end;
    }
    data = (char *) dblob - hlen; /* restore skips uidvalidity and crc */
  }
#endif

  entry.email = restore(data);

end:
  mutt_hcache_free_raw(hc, &to_free);
  return entry;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_hcache_store_raw()

int mutt_hcache_store_raw	(	header_cache_t *	hc,
		const char *	key,
		size_t	keylen,
		void *	data,
		size_t	dlen
	)

store a key / data pair

Parameters

hc	Pointer to the header_cache_t structure got by mutt_hcache_open()
key	Message identification string
keylen	Length of the string pointed to by key
data	Payload to associate with key
dlen	Length of the buffer pointed to by the data parameter

Return values

0	Success
num	Generic or backend-specific error code otherwise

Definition at line 582 of file hcache.c.

{
  const struct StoreOps *ops = hcache_get_ops();

  if (!hc || !ops)
    return -1;

  struct Buffer path = mutt_buffer_make(1024);

  keylen = mutt_buffer_printf(&path, "%s%.*s", hc->folder, (int) keylen, key);
  int rc = ops->store(hc->ctx, mutt_b2s(&path), keylen, data, dlen);
  mutt_buffer_dealloc(&path);

  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_hcache_fetch_raw()

void* mutt_hcache_fetch_raw	(	header_cache_t *	hc,
		const char *	key,
		size_t	keylen,
		size_t *	dlen
	)

Fetch a message's header from the cache.

Parameters

[in]	hc	Pointer to the header_cache_t structure got by mutt_hcache_open()
[in]	key	Message identification string
[in]	keylen	Length of the string pointed to by key
[out]	dlen	Length of the fetched data

Return values

ptr	Success, the data if found
NULL	Otherwise

Note

This function does not perform any check on the validity of the data found.

The returned data must be free with mutt_hcache_free_raw().

Definition at line 495 of file hcache.c.

{
  const struct StoreOps *ops = hcache_get_ops();

  if (!hc || !ops)
    return NULL;

  struct Buffer path = mutt_buffer_make(1024);
  keylen = mutt_buffer_printf(&path, "%s%.*s", hc->folder, (int) keylen, key);
  void *blob = ops->fetch(hc->ctx, mutt_b2s(&path), keylen, dlen);
  mutt_buffer_dealloc(&path);
  return blob;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_hcache_free_raw()

void mutt_hcache_free_raw	(	header_cache_t *	hc,
		void **	data
	)

free data fetched with mutt_hcache_fetch_raw()

Parameters

hc	Pointer to the header_cache_t structure got by mutt_hcache_open()
data	Pointer to the data got using mutt_hcache_fetch_raw

free data fetched with mutt_hcache_fetch_raw()

Definition at line 512 of file hcache.c.

{
  const struct StoreOps *ops = hcache_get_ops();

  if (!hc || !ops || !data || !*data)
    return;

  ops->free(hc->ctx, data);
}

Here is the caller graph for this function:

mutt_hcache_delete_header()

int mutt_hcache_delete_header	(	header_cache_t *	hc,
		const char *	key,
		size_t	keylen
	)

delete a key / data pair

Parameters

hc	Pointer to the header_cache_t structure got by mutt_hcache_open()
key	Message identification string
keylen	Length of the string pointed to by key

Return values

0	Success
num	Generic or backend-specific error code otherwise

delete a key / data pair

Definition at line 602 of file hcache.c.

{
  const struct StoreOps *ops = hcache_get_ops();
  if (!hc)
    return -1;

  struct Buffer path = mutt_buffer_make(1024);

  keylen = mutt_buffer_printf(&path, "%s%s", hc->folder, key);

  int rc = ops->delete_record(hc->ctx, mutt_b2s(&path), keylen);
  mutt_buffer_dealloc(&path);
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

config_init_hcache()

bool config_init_hcache

(

struct ConfigSet *

cs

)

Register hcache config variables.

Definition at line 73 of file config.c.

{
  return cs_register_variables(cs, HcacheVars, 0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

C_HeaderCache

char* C_HeaderCache

Config: (hcache) Directory/file for the header cache database.

Definition at line 37 of file config.c.

C_HeaderCacheBackend

char* C_HeaderCacheBackend

Config: (hcache) Header cache backend to use.

Definition at line 38 of file config.c.

C_HeaderCacheCompressLevel

short C_HeaderCacheCompressLevel

Config: (hcache) Level of compression for method.

Definition at line 40 of file config.c.

C_HeaderCacheCompressMethod

char* C_HeaderCacheCompressMethod

Config: (hcache) Enable generic hcache database compression.

Definition at line 41 of file config.c.

C_MaildirHeaderCacheVerify

bool C_MaildirHeaderCacheVerify

Config: (hcache) Check for maildir changes when opening mailbox.

Definition at line 43 of file config.c.