camel-imap-utils
3
CAMEL Library

# camel-imap-utils

## Synopsis

    const char*         imap_next_word                      (const char *buf);
    struct              namespace;
    struct              namespaces;
    void                imap_namespaces_destroy             (struct _namespaces *namespaces);
    char*               imap_parse_string_generic           (const char **str_p,
                                                             size_t *len,
                                                             int type);
    #define             imap_parse_string                   (str_p, len_p)
    #define             imap_parse_nstring                  (str_p, len_p)
    #define             imap_parse_astring                  (str_p, len_p)
    void                imap_parse_body                     (const char **body_p,
                                                             CamelFolder *folder,
                                                             CamelMessageContentInfo *ci);
    gboolean            imap_is_atom                        (const char *in);
    char*               imap_quote_string                   (const char *str);
    void                imap_skip_list                      (const char **str_p);
    char*               imap_uid_array_to_set               (CamelFolderSummary *summary,
                                                             GPtrArray *uids,
                                                             int uid,
                                                             ssize_t maxlen,
                                                             int *lastuid);
    GPtrArray*          imap_uid_set_to_array               (CamelFolderSummary *summary,
                                                             const char *uids);
    void                imap_uid_array_free                 (GPtrArray *arr);
    char*               imap_concat                         (CamelImapStore *imap_store,
                                                             const char *prefix,
                                                             const char *suffix);
    char*               imap_namespace_concat               (CamelImapStore *store,
                                                             const char *name);
    char*               imap_mailbox_encode                 (unsigned char *in,
                                                             size_t inlen);
    char*               imap_mailbox_decode                 (unsigned char *in,
                                                             size_t inlen);
    gboolean            (*IMAPPathFindFoldersCallback)      (const char *physical_path,
                                                             const char *path,
                                                             gpointer user_data);
    char*               imap_path_to_physical               (const char *prefix,
                                                             const char *vpath);
    gboolean            imap_path_find_folders              (const char *prefix,
                                                             IMAPPathFindFoldersCallback callback,
                                                             gpointer data);

## Description

## Details

### imap_next_word ()

    const char*         imap_next_word                      (const char *buf);

`buf` :

Returns :

### struct namespace

    struct namespace {
    	struct _namespace *next;
    	char *prefix;
    	char delim;
    };

### struct namespaces

    struct namespaces {
    	struct _namespace *personal;
    	struct _namespace *other;
    	struct _namespace *shared;
    };

### imap_namespaces_destroy ()

    void                imap_namespaces_destroy             (struct _namespaces *namespaces);

`namespaces` :

### imap_parse_string_generic ()

    char*               imap_parse_string_generic           (const char **str_p,
                                                             size_t *len,
                                                             int type);

This parses an IMAP "string" (quoted string or literal), "nstring" (NIL or string), or "astring" (atom or string) starting at *`str_p`. On success, *`str_p` will point to the first character after the end of the string, and *`len` will contain the length of the returned string. On failure, *`str_p` will be set to `NULL`.

This assumes that the string is in the form returned by `camel_imap_command()`: that line breaks are indicated by LF rather than CRLF.

`str_p` :

  a pointer to a string

`len` :

  a pointer to a size_t to return the length in

`type` :

  type of string (IMAP_STRING, IMAP_ASTRING, or IMAP_NSTRING) to parse.

Returns :

  the parsed string, or `NULL` if a NIL or no string was parsed. (In the former case, *`str_p` will be `NULL`; in the latter, it will point to the character after the NIL.)

### imap_parse_string()

    #define             imap_parse_string(str_p, len_p)

`str_p` :

`len_p` :

### imap_parse_nstring()

    #define             imap_parse_nstring(str_p, len_p)

`str_p` :

`len_p` :

### imap_parse_astring()

    #define             imap_parse_astring(str_p, len_p)

`str_p` :

`len_p` :

### imap_parse_body ()

    void                imap_parse_body                     (const char **body_p,
                                                             CamelFolder *folder,
                                                             CamelMessageContentInfo *ci);

This fills in `ci` with data from *`body_p`. On success *`body_p` will point to the character after the body. On failure, it will be set to `NULL` and `ci` will be unchanged.

`body_p` :

  pointer to the start of an IMAP "body"

`folder` :

  an imap folder

`ci` :

  a CamelMessageContentInfo to fill in

### imap_is_atom ()

    gboolean            imap_is_atom                        (const char *in);

`in` :

Returns :

### imap_quote_string ()

    char*               imap_quote_string                   (const char *str);

`str` :

  the string to quote, which must not contain CR or LF

Returns :

  an IMAP "quoted" corresponding to the string, which the caller must free.

### imap_skip_list ()

    void                imap_skip_list                      (const char **str_p);

`str_p` :

### imap_uid_array_to_set ()

    char*               imap_uid_array_to_set               (CamelFolderSummary *summary,
                                                             GPtrArray *uids,
                                                             int uid,
                                                             ssize_t maxlen,
                                                             int *lastuid);

Creates an IMAP "set" up to `maxlen` bytes long, covering the listed UIDs starting at index `uid` and not covering any UIDs that are in `summary` but not in `uids`. It doesn't actually require that all (or any) of the UIDs be in `summary`.

After calling, `lastuid` will be set the index of the first uid *not* included in the returned set string.

Note: `uids` MUST be in sorted order for this code to work properly.

`summary` :

  summary for the folder the UIDs come from

`uids` :

  a (sorted) array of UIDs

`uid` :

  uid index to start at

`maxlen` :

  max length of the set string (or -1 for infinite)

`lastuid` :

  index offset of the last uid used

Returns :

  the set, which the caller must free with `g_free()`

### imap_uid_set_to_array ()

    GPtrArray*          imap_uid_set_to_array               (CamelFolderSummary *summary,
                                                             const char *uids);

Fills an array with the UIDs corresponding to `uids` and `summary`. There can be text after the uid set in `uids`, which will be ignored.

If `uids` specifies a range of UIDs that extends outside the range of `summary`, the function will assume that all of the "missing" UIDs do exist.

`summary` :

  summary for the folder the UIDs come from

`uids` :

  a pointer to the start of an IMAP "set" of UIDs

Returns :

  the array of uids, which the caller must free with `imap_uid_array_free()`. (Or `NULL` if the uid set can't be parsed.)

### imap_uid_array_free ()

    void                imap_uid_array_free                 (GPtrArray *arr);

Frees `arr`

`arr` :

  an array returned from `imap_uid_set_to_array()`

### imap_concat ()

    char*               imap_concat                         (CamelImapStore *imap_store,
                                                             const char *prefix,
                                                             const char *suffix);

`imap_store` :

`prefix` :

`suffix` :

Returns :

### imap_namespace_concat ()

    char*               imap_namespace_concat               (CamelImapStore *store,
                                                             const char *name);

`store` :

`name` :

Returns :

### imap_mailbox_encode ()

    char*               imap_mailbox_encode                 (unsigned char *in,
                                                             size_t inlen);

`in` :

`inlen` :

Returns :

### imap_mailbox_decode ()

    char*               imap_mailbox_decode                 (unsigned char *in,
                                                             size_t inlen);

`in` :

`inlen` :

Returns :

### IMAPPathFindFoldersCallback ()

    gboolean            (*IMAPPathFindFoldersCallback)      (const char *physical_path,
                                                             const char *path,
                                                             gpointer user_data);

`physical_path` :

`path` :

`user_data` :

Returns :

### imap_path_to_physical ()

    char*               imap_path_to_physical               (const char *prefix,
                                                             const char *vpath);

`prefix` :

`vpath` :

Returns :

### imap_path_find_folders ()

    gboolean            imap_path_find_folders              (const char *prefix,
                                                             IMAPPathFindFoldersCallback callback,
                                                             gpointer data);

Walks the folder tree starting at `prefix` and calls `callback` on each folder.

`prefix` :

  directory to start from

`callback` :

  Callback to invoke on each folder

`data` :

  Data for `callback`

Returns :

  `TRUE` on success, `FALSE` if an error occurs at any point