CamelKeyFile

CamelKeyFile

Functions

Types and Values

Object Hierarchy

    GObject
    ├── CamelBlockFile
    ╰── CamelKeyFile

Description

Functions

camel_block_file_new ()

CamelBlockFile *
camel_block_file_new (const gchar *path,
                      gint flags,
                      const gchar version[8],
                      gsize block_size);

Allocate a new block file, stored at path . version contains an 8 character version string which must match the head of the file, or the file will be intitialised.

block_size is currently ignored and is set to CAMEL_BLOCK_SIZE.

Parameters

path

a path with file name of the new CamelBlockFile

 

flags

file open flags to use

 

version

a version string

 

block_size

block size, currently ignored

 

Returns

The new block file, or NULL if it could not be created.


camel_block_file_get_root ()

CamelBlockRoot *
camel_block_file_get_root (CamelBlockFile *bs);

Parameters

bs

a CamelBlockFile

 

Returns

A CamelBlockRoot of bs .

[transfer none]

Since: 3.24


camel_block_file_get_root_block ()

CamelBlock *
camel_block_file_get_root_block (CamelBlockFile *bs);

Parameters

bs

a CamelBlockFile

 

Returns

A root CamelBlock of bs .

[transfer none]

Since: 3.24


camel_block_file_get_cache_limit ()

gint
camel_block_file_get_cache_limit (CamelBlockFile *bs);

Parameters

bs

a CamelBlockFile

 

Returns

Current block cache limit of bs .

Since: 3.24


camel_block_file_set_cache_limit ()

void
camel_block_file_set_cache_limit (CamelBlockFile *bs,
                                  gint block_cache_limit);

Sets a new block cache limit for bs .

Parameters

bs

a CamelBlockFile

 

block_cache_limit

a new block cache limit to set

 

Since: 3.24


camel_block_file_rename ()

gint
camel_block_file_rename (CamelBlockFile *bs,
                         const gchar *path);

Renames existing block file to a new path .

Parameters

bs

a CamelBlockFile

 

path

path with filename to rename to

 

Returns

0 on success, -1 on error; errno is set on failure


camel_block_file_delete ()

gint
camel_block_file_delete (CamelBlockFile *bs);

Deletes existing block file.

Parameters

bs

a CamelBlockFile

 

Returns

0 on success, -1 on error.


camel_block_file_new_block ()

CamelBlock *
camel_block_file_new_block (CamelBlockFile *bs);

Allocate a new block, return a pointer to it. Old blocks may be flushed to disk during this call.

[skip]

Parameters

bs

a CamelBlockFile

 

Returns

The block, or NULL if an error occurred.


camel_block_file_free_block ()

gint
camel_block_file_free_block (CamelBlockFile *bs,
                             camel_block_t id);

Parameters

bs

a CamelBlockFile

 

id

a camel_block_t

 

camel_block_file_get_block ()

CamelBlock *
camel_block_file_get_block (CamelBlockFile *bs,
                            camel_block_t id);

Retreive a block id .

[skip]

Parameters

bs

a CamelBlockFile

 

id

a camel_block_t

 

Returns

The block, or NULL if blockid is invalid or a file error occurred.


camel_block_file_detach_block ()

void
camel_block_file_detach_block (CamelBlockFile *bs,
                               CamelBlock *bl);

Detatch a block from the block file's cache. The block should be unref'd or attached when finished with. The block file will perform no writes of this block or flushing of it if the cache fills.

Parameters

bs

a CamelBlockFile

 

bl

a CamelBlock

 

camel_block_file_attach_block ()

void
camel_block_file_attach_block (CamelBlockFile *bs,
                               CamelBlock *bl);

Reattach a block that has been detached.

Parameters

bs

a CamelBlockFile

 

bl

a CamelBlock

 

camel_block_file_touch_block ()

void
camel_block_file_touch_block (CamelBlockFile *bs,
                              CamelBlock *bl);

Mark a block as dirty. The block will be written to disk if it ever expires from the cache.

Parameters

bs

a CamelBlockFile

 

bl

a CamelBlock

 

camel_block_file_unref_block ()

void
camel_block_file_unref_block (CamelBlockFile *bs,
                              CamelBlock *bl);

Mark a block as unused. If a block is used it will not be written to disk, or flushed from memory.

If a block is detatched and this is the last reference, the block will be freed.

Parameters

bs

a CamelBlockFile

 

bl

a CamelBlock

 

camel_block_file_sync_block ()

gint
camel_block_file_sync_block (CamelBlockFile *bs,
                             CamelBlock *bl);

Flush a block to disk immediately. The block will only be flushed to disk if it is marked as dirty (touched).

Parameters

bs

a CamelBlockFile

 

bl

a CamelBlock

 

Returns

-1 on io error.


camel_block_file_sync ()

gint
camel_block_file_sync (CamelBlockFile *bs);

Sync all dirty blocks to disk, including the root block.

Parameters

bs

a CamelBlockFile

 

Returns

-1 on io error.


camel_key_file_new ()

CamelKeyFile *
camel_key_file_new (const gchar *path,
                    gint flags,
                    const gchar version[8]);

Create a new key file. A linked list of record blocks.

Parameters

path

a filename with path of the CamelKeyFile to create

 

flags

open flags

 

version

Version string (header) of file. Currently written but not checked.

 

Returns

A new key file, or NULL if the file could not be opened/created/initialised.


camel_key_file_rename ()

gint
camel_key_file_rename (CamelKeyFile *kf,
                       const gchar *path);

camel_key_file_delete ()

gint
camel_key_file_delete (CamelKeyFile *kf);

camel_key_file_write ()

gint
camel_key_file_write (CamelKeyFile *kf,
                      camel_block_t *parent,
                      gsize len,
                      camel_key_t *records);

Write a new list of records to the key file.

Parameters

kf

a CamelKeyFile

 

parent

a camel_block_t

 

len

how many records to write

 

records

an array of camel_key_t to write.

[array length=len]

Returns

-1 on io error. The key file will remain unchanged.


camel_key_file_read ()

gint
camel_key_file_read (CamelKeyFile *kf,
                     camel_block_t *start,
                     gsize *len,
                     camel_key_t **records);

Read the next block of data from the key file. Returns the number of records.

Parameters

kf

a CamelKeyFile

 

start

The record pointer. This will be set to the next record pointer on success.

 

len

Number of records read, if != NULL.

 

records

Records, allocated, must be freed with g_free, if != NULL.

[array length=len][nullable]

Returns

-1 on io error.

Types and Values

camel_block_t

typedef guint32 camel_block_t; /* block offset, absolute, bottom BLOCK_SIZE_BITS always 0 */

camel_key_t

typedef guint32 camel_key_t; /* this is a bitfield of (block offset:BLOCK_SIZE_BITS) */

enum CamelBlockFileFlags

Members

CAMEL_BLOCK_FILE_SYNC

   

CAMEL_BLOCK_SIZE

#define CAMEL_BLOCK_SIZE (1024)

CAMEL_BLOCK_SIZE_BITS

#define CAMEL_BLOCK_SIZE_BITS (10) /* # bits to contain block_size bytes */

enum CamelBlockFlags

Members

CAMEL_BLOCK_DIRTY

   

CAMEL_BLOCK_DETACHED

   

struct CamelBlockRoot

struct CamelBlockRoot {
	gchar version[8]; /* version number */

	guint32 flags;		/* flags for file */
	guint32 block_size; /* block size of this file */
	camel_block_t free; /* free block list */
	camel_block_t last; /* pointer to end of blocks */

	/* subclasses tack on, but no more than CAMEL_BLOCK_SIZE! */
};

struct CamelBlock

struct CamelBlock {
	camel_block_t id;
	CamelBlockFlags flags;
	guint32 refcount;
	guint32 align00;

	guchar data[CAMEL_BLOCK_SIZE];
};