lib.h File Reference

Header cache multiplexor. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "compress/lib.h"
#include "store/lib.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	HeaderCache
	Header Cache. More...
struct	HCacheEntry
	Wrapper for Email retrieved from the header cache. More...

Macros
#define	hcache_fetch_raw_obj(hc, key, keylen, dst)   hcache_fetch_raw_obj_full(hc, key, keylen, dst, sizeof(*dst))

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

Functions
struct HeaderCache *	hcache_open (const char *path, const char *folder, hcache_namer_t namer, bool create)
	Open the connection to the header cache.
void	hcache_close (struct HeaderCache **ptr)
	Close the connection to the header cache.
int	hcache_store_email (struct HeaderCache *hc, const char *key, size_t keylen, struct Email *e, uint32_t uidvalidity)
	Store a Header along with a validity datum.
struct HCacheEntry	hcache_fetch_email (struct HeaderCache *hc, const char *key, size_t keylen, uint32_t uidvalidity)
	Fetch and validate a message's header from the cache.
char *	hcache_fetch_raw_str (struct HeaderCache *hc, const char *key, size_t keylen)
	Fetch a string from the cache.
bool	hcache_fetch_raw_obj_full (struct HeaderCache *hc, const char *key, size_t keylen, void *dst, size_t dstlen)
	Fetch a message's header from the cache into a destination object.
int	hcache_store_raw (struct HeaderCache *hc, const char *key, size_t keylen, void *data, size_t dlen)
	Store a key / data pair.
int	hcache_delete_email (struct HeaderCache *hc, const char *key, size_t keylen)
	Delete a key / data pair.
int	hcache_delete_raw (struct HeaderCache *hc, const char *key, size_t keylen)
	Delete a key / data pair.

Detailed Description

Header cache multiplexor.

Authors

• Richard Russon
• 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.

Macro Definition Documentation

hcache_fetch_raw_obj

#define hcache_fetch_raw_obj	(		hc,
			key,
			keylen,
			dst
	)		hcache_fetch_raw_obj_full(hc, key, keylen, dst, sizeof(*dst))

Definition at line 162 of file lib.h.

Typedef Documentation

hcache_namer_t

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

Definition at line 113 of file lib.h.

Function Documentation

hcache_open()

struct HeaderCache * hcache_open	(	const char *	path,
		const char *	folder,
		hcache_namer_t	namer,
		bool	create
	)

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.
create	Create the file if it's not there?

Return values

ptr	Success, struct HeaderCache struct
NULL	Otherwise

Open the connection to the header cache.

Definition at line 471 of file hcache.c.

{
  if (!path || (path[0] == '\0'))
    return NULL;
 
  if (HcacheVer == 0x0)
    HcacheVer = generate_hcachever();
 
  struct HeaderCache *hc = hcache_new();
 
  hc->folder = get_foldername(folder);
  hc->crc = HcacheVer;
 
  const char *const c_header_cache_backend = cs_subset_string(NeoMutt->sub, "header_cache_backend");
  hc->store_ops = store_get_backend_ops(c_header_cache_backend);
  if (!hc->store_ops)
  {
    hcache_free(&hc);
    return NULL;
  }
 
#ifdef USE_HCACHE_COMPRESSION
  const char *const c_header_cache_compress_method = cs_subset_string(NeoMutt->sub, "header_cache_compress_method");
  if (c_header_cache_compress_method)
  {
    hc->compr_ops = compress_get_ops(c_header_cache_compress_method);
 
    const short c_header_cache_compress_level = cs_subset_number(NeoMutt->sub, "header_cache_compress_level");
    hc->compr_handle = hc->compr_ops->open(c_header_cache_compress_level);
    if (!hc->compr_handle)
    {
      hcache_free(&hc);
      return NULL;
    }
 
    /* remember the buffer of database backend */
    mutt_debug(LL_DEBUG3, "Header cache will use %s compression\n",
               hc->compr_ops->name);
  }
#endif
 
  struct Buffer *hcpath = buf_pool_get();
  hcache_per_folder(hc, hcpath, path, namer);
 
  hc->store_handle = hc->store_ops->open(buf_string(hcpath), create);
  if (!hc->store_handle)
  {
    /* remove a possibly incompatible version */
    if (unlink(buf_string(hcpath)) == 0)
    {
      hc->store_handle = hc->store_ops->open(buf_string(hcpath), create);
      if (!hc->store_handle)
      {
        if (hc->compr_ops)
        {
          hc->compr_ops->close(&hc->compr_handle);
        }
        hcache_free(&hc);
      }
    }
    else
    {
      hcache_free(&hc);
    }
  }
 
  buf_pool_release(&hcpath);
  return hc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

hcache_close()

void hcache_close

(

struct HeaderCache **

ptr

)

Close the connection to the header cache.

Parameters

ptr	Pointer to the struct HeaderCache structure got by hcache_open()

Note

The pointer will be set to NULL

Close the connection to the header cache.

Definition at line 545 of file hcache.c.

{
  if (!ptr || !*ptr)
    return;
 
  struct HeaderCache *hc = *ptr;
 
#ifdef USE_HCACHE_COMPRESSION
  if (hc->compr_ops)
    hc->compr_ops->close(&hc->compr_handle);
#endif
 
  hc->store_ops->close(&hc->store_handle);
 
  hcache_free(ptr);
}

Here is the call graph for this function:

Here is the caller graph for this function:

hcache_store_email()

int hcache_store_email	(	struct HeaderCache *	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 struct HeaderCache structure got by 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 673 of file hcache.c.

{
  if (!hc)
    return -1;
 
  int dlen = 0;
  char *data = dump_email(hc, e, &dlen, uidvalidity);
 
#ifdef USE_HCACHE_COMPRESSION
  if (hc->compr_ops)
  {
    /* We don't compress uidvalidity and the crc, so we can check them before
     * decompressing on fetch().  */
    size_t hlen = header_size();
 
    /* data / dlen gets ptr to compressed data here */
    size_t clen = dlen;
    void *cdata = hc->compr_ops->compress(hc->compr_handle, 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
 
  struct RealKey *rk = realkey(hc, key, keylen, true);
  int rc = hc->store_ops->store(hc->store_handle, rk->key, rk->keylen, data, dlen);
 
  FREE(&data);
 
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

hcache_fetch_email()

struct HCacheEntry hcache_fetch_email	(	struct HeaderCache *	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 struct HeaderCache structure got by 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 struct HeaderCache structure.

Fetch and validate a message's header from the cache.

Definition at line 565 of file hcache.c.

{
  struct HCacheEntry hce = { 0 };
  if (!hc)
    return hce;
 
  size_t dlen = 0;
  struct RealKey *rk = realkey(hc, key, keylen, true);
  void *data = hc->store_ops->fetch(hc->store_handle, rk->key, rk->keylen, &dlen);
  void *to_free = data;
  if (!data)
  {
    goto end;
  }
 
  /* restore uidvalidity and crc */
  size_t hlen = header_size();
  if (hlen > dlen)
  {
    goto end;
  }
  int off = 0;
  serial_restore_uint32_t(&hce.uidvalidity, data, &off);
  serial_restore_int(&hce.crc, data, &off);
  ASSERT((size_t) off == hlen);
  if ((hce.crc != hc->crc) || ((uidvalidity != 0) && (uidvalidity != hce.uidvalidity)))
  {
    goto end;
  }
 
#ifdef USE_HCACHE_COMPRESSION
  if (hc->compr_ops)
  {
    void *dblob = hc->compr_ops->decompress(hc->compr_handle,
                                            (char *) data + hlen, dlen - hlen);
    if (!dblob)
    {
      goto end;
    }
    data = (char *) dblob - hlen; /* restore skips uidvalidity and crc */
  }
#endif
 
  hce.email = restore_email(data);
 
end:
  free_raw(hc, &to_free);
  return hce;
}

Here is the call graph for this function:

Here is the caller graph for this function:

hcache_fetch_raw_str()

char * hcache_fetch_raw_str	(	struct HeaderCache *	hc,
		const char *	key,
		size_t	keylen
	)

Fetch a string from the cache.

Parameters

[in]	hc	Pointer to the struct HeaderCache structure got by hcache_open()
[in]	key	Message identification string
[in]	keylen	Length of the string pointed to by key

Return values

ptr	Success, the data if found
NULL	Otherwise

Definition at line 655 of file hcache.c.

{
  char *res = NULL;
  size_t dlen = 0;
 
  struct RealKey *rk = realkey(hc, key, keylen, false);
  void *data = hc->store_ops->fetch(hc->store_handle, rk->key, rk->keylen, &dlen);
  if (data)
  {
    res = mutt_strn_dup(data, dlen);
    free_raw(hc, &data);
  }
  return res;
}

Here is the call graph for this function:

Here is the caller graph for this function:

hcache_fetch_raw_obj_full()

bool hcache_fetch_raw_obj_full	(	struct HeaderCache *	hc,
		const char *	key,
		size_t	keylen,
		void *	dst,
		size_t	dstlen
	)

Fetch a message's header from the cache into a destination object.

Parameters

[in]	hc	Pointer to the struct HeaderCache structure got by hcache_open()
[in]	key	Message identification string
[in]	keylen	Length of the string pointed to by key
[out]	dst	Pointer to the destination object
[in]	dstlen	Size of the destination object

Return values

true	Success, the data was found and the length matches
false	Otherwise

Definition at line 626 of file hcache.c.

{
  bool rc = true;
  size_t srclen = 0;
 
  struct RealKey *rk = realkey(hc, key, keylen, false);
  void *src = hc->store_ops->fetch(hc->store_handle, rk->key, rk->keylen, &srclen);
 
  if (src && (srclen == dstlen))
  {
    memcpy(dst, src, dstlen);
  }
  else
  {
    rc = false;
  }
  free_raw(hc, &src);
  return rc;
}

Here is the call graph for this function:

hcache_store_raw()

int hcache_store_raw	(	struct HeaderCache *	hc,
		const char *	key,
		size_t	keylen,
		void *	data,
		size_t	dlen
	)

Store a key / data pair.

Parameters

hc	Pointer to the struct HeaderCache structure got by 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 727 of file hcache.c.

{
  if (!hc)
    return -1;
 
  struct RealKey *rk = realkey(hc, key, keylen, false);
  int rc = hc->store_ops->store(hc->store_handle, rk->key, rk->keylen, data, dlen);
 
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

hcache_delete_email()

int hcache_delete_email	(	struct HeaderCache *	hc,
		const char *	key,
		size_t	keylen
	)

Delete a key / data pair.

Parameters

hc	Pointer to the struct HeaderCache structure got by 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 742 of file hcache.c.

{
  if (!hc)
    return -1;
 
  struct RealKey *rk = realkey(hc, key, keylen, true);
 
  return hc->store_ops->delete_record(hc->store_handle, rk->key, rk->keylen);
}

Here is the call graph for this function:

Here is the caller graph for this function:

hcache_delete_raw()

int hcache_delete_raw	(	struct HeaderCache *	hc,
		const char *	key,
		size_t	keylen
	)

Delete a key / data pair.

Parameters

hc	Pointer to the struct HeaderCache structure got by 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 755 of file hcache.c.

{
  if (!hc)
    return -1;
 
  struct RealKey *rk = realkey(hc, key, keylen, false);
 
  return hc->store_ops->delete_record(hc->store_handle, rk->key, rk->keylen);
}

Here is the call graph for this function:

Here is the caller graph for this function: