CamelIMAP4Engine
3
CAMEL Library

# CamelIMAP4Engine

## Synopsis

                        CamelIMAP4Engine;
    enum                camel_imap4_engine_t;
    enum                camel_imap4_level_t;
    enum                camel_imap4_resp_code_t;
                        CamelIMAP4RespCode;
                        CamelIMAP4Namespace;
                        CamelIMAP4NamespaceList;
    gboolean            (*CamelIMAP4ReconnectFunc)          (CamelIMAP4Engine *engine,
                                                             CamelException *ex);
    CamelIMAP4Engine*   camel_imap4_engine_new              (CamelService *service,
                                                             CamelIMAP4ReconnectFunc reconnect);
    int                 camel_imap4_engine_take_stream      (CamelIMAP4Engine *engine,
                                                             CamelStream *stream,
                                                             CamelException *ex);
    int                 camel_imap4_engine_capability       (CamelIMAP4Engine *engine,
                                                             CamelException *ex);
    int                 camel_imap4_engine_namespace        (CamelIMAP4Engine *engine,
                                                             CamelException *ex);
    int                 camel_imap4_engine_select_folder    (CamelIMAP4Engine *engine,
                                                             CamelFolder *folder,
                                                             CamelException *ex);
    struct _CamelIMAP4Command* camel_imap4_engine_queue     (CamelIMAP4Engine *engine,
                                                             CamelFolder *folder,
                                                             const char *format,
                                                             ...);
    struct _CamelIMAP4Command* camel_imap4_engine_prequeue  (CamelIMAP4Engine *engine,
                                                             CamelFolder *folder,
                                                             const char *format,
                                                             ...);
    void                camel_imap4_engine_dequeue          (CamelIMAP4Engine *engine,
                                                             struct _CamelIMAP4Command *ic);
    int                 camel_imap4_engine_iterate          (CamelIMAP4Engine *engine);
    int                 camel_imap4_engine_handle_untagged_1
                                                            (CamelIMAP4Engine *engine,
                                                             struct _camel_imap4_token_t *token,
                                                             CamelException *ex);
    void                camel_imap4_engine_handle_untagged  (CamelIMAP4Engine *engine,
                                                             CamelException *ex);
    int                 camel_imap4_engine_next_token       (CamelIMAP4Engine *engine,
                                                             struct _camel_imap4_token_t *token,
                                                             CamelException *ex);
    int                 camel_imap4_engine_line             (CamelIMAP4Engine *engine,
                                                             unsigned char **line,
                                                             size_t *len,
                                                             CamelException *ex);
    int                 camel_imap4_engine_literal          (CamelIMAP4Engine *engine,
                                                             unsigned char **literal,
                                                             size_t *len,
                                                             CamelException *ex);
    int                 camel_imap4_engine_nstring          (CamelIMAP4Engine *engine,
                                                             unsigned char **nstring,
                                                             CamelException *ex);
    int                 camel_imap4_engine_eat_line         (CamelIMAP4Engine *engine,
                                                             CamelException *ex);
    int                 camel_imap4_engine_parse_resp_code  (CamelIMAP4Engine *engine,
                                                             CamelException *ex);
    void                camel_imap4_resp_code_free          (CamelIMAP4RespCode *rcode);

## Description

## Details

### CamelIMAP4Engine

    typedef struct {
    	CamelObject parent_object;

    	CamelIMAP4ReconnectFunc reconnect;
    	gboolean reconnecting;

    	CamelSession *session;
    	CamelService *service;
    	CamelURL *url;

    	camel_imap4_engine_t state;
    	camel_imap4_level_t level;
    	guint32 capa;

    	guint32 maxlen:31;
    	guint32 maxlentype:1;

    	CamelIMAP4NamespaceList namespaces;
    	GHashTable *authtypes;                    /* supported authtypes */

    	struct _CamelIMAP4Stream *istream;
    	CamelStream *ostream;

    	unsigned char tagprefix;             /* 'A'..'Z' */
    	unsigned int tag;                    /* next command tag */
    	int nextid;

    	struct _CamelIMAP4Folder *folder;    /* currently selected folder */

    	EDList queue;                          /* queue of waiting commands */
    	struct _CamelIMAP4Command *current;
    } CamelIMAP4Engine;

### enum camel_imap4_engine_t

    typedef enum {
    	CAMEL_IMAP4_ENGINE_DISCONNECTED,
    	CAMEL_IMAP4_ENGINE_CONNECTED,
    	CAMEL_IMAP4_ENGINE_PREAUTH,
    	CAMEL_IMAP4_ENGINE_AUTHENTICATED,
    	CAMEL_IMAP4_ENGINE_SELECTED,
    } camel_imap4_engine_t;

### enum camel_imap4_level_t

    typedef enum {
    	CAMEL_IMAP4_LEVEL_UNKNOWN,
    	CAMEL_IMAP4_LEVEL_IMAP4,
    	CAMEL_IMAP4_LEVEL_IMAP4REV1
    } camel_imap4_level_t;

### enum camel_imap4_resp_code_t

    typedef enum {
    	CAMEL_IMAP4_RESP_CODE_ALERT,
    	CAMEL_IMAP4_RESP_CODE_BADCHARSET,
    	CAMEL_IMAP4_RESP_CODE_CAPABILITY,
    	CAMEL_IMAP4_RESP_CODE_PARSE,
    	CAMEL_IMAP4_RESP_CODE_PERM_FLAGS,
    	CAMEL_IMAP4_RESP_CODE_READONLY,
    	CAMEL_IMAP4_RESP_CODE_READWRITE,
    	CAMEL_IMAP4_RESP_CODE_TRYCREATE,
    	CAMEL_IMAP4_RESP_CODE_UIDNEXT,
    	CAMEL_IMAP4_RESP_CODE_UIDVALIDITY,
    	CAMEL_IMAP4_RESP_CODE_UNSEEN,
    	CAMEL_IMAP4_RESP_CODE_NEWNAME,
    	CAMEL_IMAP4_RESP_CODE_APPENDUID,
    	CAMEL_IMAP4_RESP_CODE_COPYUID,
    	CAMEL_IMAP4_RESP_CODE_UNKNOWN,
    } camel_imap4_resp_code_t;

### CamelIMAP4RespCode

    typedef struct {
    	camel_imap4_resp_code_t code;
    	union {
    		guint32 flags;
    		char *parse;
    		guint32 uidnext;
    		guint32 uidvalidity;
    		guint32 unseen;
    		char *newname[2];
    		struct {
    			guint32 uidvalidity;
    			guint32 uid;
    		} appenduid;
    		struct {
    			guint32 uidvalidity;
    			char *srcset;
    			char *destset;
    		} copyuid;
    	} v;
    } CamelIMAP4RespCode;

### CamelIMAP4Namespace

    typedef struct {
    	struct _CamelIMAP4Namespace *next;
    	char *path;
    	char sep;
    } CamelIMAP4Namespace;

### CamelIMAP4NamespaceList

    typedef struct {
    	CamelIMAP4Namespace *personal;
    	CamelIMAP4Namespace *other;
    	CamelIMAP4Namespace *shared;
    } CamelIMAP4NamespaceList;

### CamelIMAP4ReconnectFunc ()

    gboolean            (*CamelIMAP4ReconnectFunc)          (CamelIMAP4Engine *engine,
                                                             CamelException *ex);

`engine` :

`ex` :

Returns :

### camel_imap4_engine_new ()

    CamelIMAP4Engine*   camel_imap4_engine_new              (CamelService *service,
                                                             CamelIMAP4ReconnectFunc reconnect);

`service` :

  service

`reconnect` :

  reconnect callback function

Returns :

  a new imap4 engine

### camel_imap4_engine_take_stream ()

    int                 camel_imap4_engine_take_stream      (CamelIMAP4Engine *engine,
                                                             CamelStream *stream,
                                                             CamelException *ex);

Gives ownership of `stream` to `engine` and reads the greeting from the stream.

`engine` :

  imap4 engine

`stream` :

  tcp stream

`ex` :

  exception

Returns :

  0 on success or -1 on fail.

  Note: on error, `stream` will be unref'd.

### camel_imap4_engine_capability ()

    int                 camel_imap4_engine_capability       (CamelIMAP4Engine *engine,
                                                             CamelException *ex);

Forces the IMAP4 engine to query the IMAP4 server for a list of capabilities.

`engine` :

  IMAP4 engine

`ex` :

  exception

Returns :

  0 on success or -1 on fail.

### camel_imap4_engine_namespace ()

    int                 camel_imap4_engine_namespace        (CamelIMAP4Engine *engine,
                                                             CamelException *ex);

Forces the IMAP4 engine to query the IMAP4 server for a list of namespaces.

`engine` :

  IMAP4 engine

`ex` :

  exception

Returns :

  0 on success or -1 on fail.

### camel_imap4_engine_select_folder ()

    int                 camel_imap4_engine_select_folder    (CamelIMAP4Engine *engine,
                                                             CamelFolder *folder,
                                                             CamelException *ex);

Convenience function to select `folder`.

`engine` :

  IMAP4 engine

`folder` :

  folder to select

`ex` :

  exception

Returns :

  0 on success or -1 on fail.

### camel_imap4_engine_queue ()

    struct _CamelIMAP4Command* camel_imap4_engine_queue     (CamelIMAP4Engine *engine,
                                                             CamelFolder *folder,
                                                             const char *format,
                                                             ...);

Basically the same as `camel_imap4_command_new()` except that this function also places the command in the engine queue.

`engine` :

  IMAP4 engine

`folder` :

  IMAP4 folder that the command will affect (or `NULL` if it doesn't matter)

`format` :

  command format

`...` :

  arguments

Returns :

  the CamelIMAP4Command.

### camel_imap4_engine_prequeue ()

    struct _CamelIMAP4Command* camel_imap4_engine_prequeue  (CamelIMAP4Engine *engine,
                                                             CamelFolder *folder,
                                                             const char *format,
                                                             ...);

Same as `camel_imap4_engine_queue()` except this places the new command at the head of the queue.

`engine` :

  IMAP4 engine

`folder` :

  IMAP4 folder that the command will affect (or `NULL` if it doesn't matter)

`format` :

  command format

`...` :

  arguments

Returns :

  the CamelIMAP4Command.

### camel_imap4_engine_dequeue ()

    void                camel_imap4_engine_dequeue          (CamelIMAP4Engine *engine,
                                                             struct _CamelIMAP4Command *ic);

Removes `ic` from the processing queue.

`engine` :

  IMAP4 engine

`ic` :

  IMAP4 command

### camel_imap4_engine_iterate ()

    int                 camel_imap4_engine_iterate          (CamelIMAP4Engine *engine);

Processes the first command in the queue.

`engine` :

  IMAP4 engine

Returns :

  the id of the processed command, `0` if there were no commands to process, or `-1` on error.

  Note: more details on the error will be held on the CamelIMAP4Command that failed.

### camel_imap4_engine_handle_untagged_1 ()

    int                 camel_imap4_engine_handle_untagged_1
                                                            (CamelIMAP4Engine *engine,
                                                             struct _camel_imap4_token_t *token,
                                                             CamelException *ex);

Handles a single untagged response

`engine` :

  IMAP4 engine

`token` :

  IMAP4 token

`ex` :

  exception

Returns :

  -1 on error or one of CAMEL_IMAP4_UNTAGGED_[OK,NO,BAD,PREAUTH,HANDLED] on success

### camel_imap4_engine_handle_untagged ()

    void                camel_imap4_engine_handle_untagged  (CamelIMAP4Engine *engine,
                                                             CamelException *ex);

Handle a stream of untagged responses.

`engine` :

  IMAP4 engine

`ex` :

  exception

### camel_imap4_engine_next_token ()

    int                 camel_imap4_engine_next_token       (CamelIMAP4Engine *engine,
                                                             struct _camel_imap4_token_t *token,
                                                             CamelException *ex);

Wraps `camel_imap4_stream_next_token()` to set an exception on failure and updates the engine state to DISCONNECTED if the stream gets disconencted.

`engine` :

  IMAP4 engine

`token` :

  IMAP4 token

`ex` :

  exception

Returns :

  0 on success or -1 on fail.

### camel_imap4_engine_line ()

    int                 camel_imap4_engine_line             (CamelIMAP4Engine *engine,
                                                             unsigned char **line,
                                                             size_t *len,
                                                             CamelException *ex);

Reads in a single line of input from the IMAP4 server and updates `line` to point to the line buffer. `len` is set to the length of the line buffer. `line` must be free'd using `g_free()`.

`engine` :

  IMAP4 engine

`line` :

  line pointer

`len` :

  length pointer

`ex` :

  exception

Returns :

  0 on success or -1 on fail

### camel_imap4_engine_literal ()

    int                 camel_imap4_engine_literal          (CamelIMAP4Engine *engine,
                                                             unsigned char **literal,
                                                             size_t *len,
                                                             CamelException *ex);

Reads in an entire literal string and updates `literal` to point to it. `len` is set to the length of the literal. `literal` will also conveniently be terminated with a nul-byte. `literal` must be free'd using `g_free()`.

`engine` :

  IMAP4 engine

`literal` :

  literal pointer

`len` :

  len pointer

`ex` :

  exception

Returns :

  0 on success or -1 on fail.

### camel_imap4_engine_nstring ()

    int                 camel_imap4_engine_nstring          (CamelIMAP4Engine *engine,
                                                             unsigned char **nstring,
                                                             CamelException *ex);

Reads in an nstring (NIL, atom, qstring or literal) and updates `nstring` to point to it. `nstring` must be free'd using `g_free()`.

`engine` :

  IMAP4 engine

`nstring` :

  nstring pointer

`ex` :

  exception

Returns :

  0 on success or -1 on fail.

### camel_imap4_engine_eat_line ()

    int                 camel_imap4_engine_eat_line         (CamelIMAP4Engine *engine,
                                                             CamelException *ex);

Gobbles up the remainder of the response line.

`engine` :

  IMAP4 engine

`ex` :

  exception

Returns :

  0 on success or -1 on fail

### camel_imap4_engine_parse_resp_code ()

    int                 camel_imap4_engine_parse_resp_code  (CamelIMAP4Engine *engine,
                                                             CamelException *ex);

Parses a RESP-CODE

`engine` :

  IMAP4 engine

`ex` :

  exception

Returns :

  0 on success or -1 on fail.

### camel_imap4_resp_code_free ()

    void                camel_imap4_resp_code_free          (CamelIMAP4RespCode *rcode);

Free's the RESP-CODE

`rcode` :

  RESP-CODE