camel-imap-command
3
CAMEL Library

# camel-imap-command

## Synopsis

    enum                CamelImapResponseType;
    struct              CamelImapResponse;
    CamelImapResponse*  camel_imap_command                  (CamelImapStore *store,
                                                             CamelFolder *folder,
                                                             CamelException *ex,
                                                             const char *fmt,
                                                             ...);
    CamelImapResponse*  camel_imap_command_continuation     (CamelImapStore *store,
                                                             const char *cmd,
                                                             size_t cmdlen,
                                                             CamelException *ex);
    void                camel_imap_response_free            (CamelImapStore *store,
                                                             CamelImapResponse *response);
    void                camel_imap_response_free_without_processing
                                                            (CamelImapStore *store,
                                                             CamelImapResponse *response);
    char*               camel_imap_response_extract         (CamelImapStore *store,
                                                             CamelImapResponse *response,
                                                             const char *type,
                                                             CamelException *ex);
    char*               camel_imap_response_extract_continuation
                                                            (CamelImapStore *store,
                                                             CamelImapResponse *response,
                                                             CamelException *ex);
    gboolean            camel_imap_command_start            (CamelImapStore *store,
                                                             CamelFolder *folder,
                                                             CamelException *ex,
                                                             const char *fmt,
                                                             ...);
    CamelImapResponseType camel_imap_command_response       (CamelImapStore *store,
                                                             char **respbuf,
                                                             CamelException *ex);

## Description

## Details

### enum CamelImapResponseType

    typedef enum {
    	CAMEL_IMAP_RESPONSE_ERROR,
    	CAMEL_IMAP_RESPONSE_CONTINUATION,
    	CAMEL_IMAP_RESPONSE_UNTAGGED,
    	CAMEL_IMAP_RESPONSE_TAGGED
    } CamelImapResponseType;

### struct CamelImapResponse

    struct CamelImapResponse {
    	CamelFolder *folder;
    	GPtrArray *untagged;
    	char *status;
    };

### camel_imap_command ()

    CamelImapResponse*  camel_imap_command                  (CamelImapStore *store,
                                                             CamelFolder *folder,
                                                             CamelException *ex,
                                                             const char *fmt,
                                                             ...);

This function calls `camel_imap_command_start()` to send the command, then reads the complete response to it using `camel_imap_command_response()` and returns a CamelImapResponse structure.

As a special case, if `fmt` is `NULL`, it will just select `folder` and return the response from doing so.

See `camel_imap_command_start()` for details on `fmt`.

On success, the store's connect_lock will be locked. It will be freed when you call camel_imap_response_free. (The lock is recursive, so callers can grab and release it themselves if they need to run multiple commands atomically.)

`store` :

  the IMAP store

`folder` :

  The folder to perform the operation in (or `NULL` if not relevant).

`ex` :

  a CamelException

`fmt` :

  a sort of printf-style format string, followed by arguments

`...` :

Returns :

  `NULL` if an error occurred (in which case `ex` will be set). Otherwise, a CamelImapResponse describing the server's response, which the caller must free with `camel_imap_response_free()`.

### camel_imap_command_continuation ()

    CamelImapResponse*  camel_imap_command_continuation     (CamelImapStore *store,
                                                             const char *cmd,
                                                             size_t cmdlen,
                                                             CamelException *ex);

This method is for sending continuing responses to the IMAP server after `camel_imap_command()` or `camel_imap_command_response()` returns a continuation response.

This function assumes you have an exclusive lock on the imap stream.

`store` :

  the IMAP store

`cmd` :

  buffer containing the response/request data

`cmdlen` :

  command length

`ex` :

  a CamelException

Returns :

  as for `camel_imap_command()`. On failure, the store's connect_lock will be released.

### camel_imap_response_free ()

    void                camel_imap_response_free            (CamelImapStore *store,
                                                             CamelImapResponse *response);

Frees all of the data in `response` and processes any untagged EXPUNGE and EXISTS responses in it. Releases `store`'s connect_lock.

`store` :

  the CamelImapStore the response is from

`response` :

  a CamelImapResponse

### camel_imap_response_free_without_processing ()

    void                camel_imap_response_free_without_processing
                                                            (CamelImapStore *store,
                                                             CamelImapResponse *response);

Frees all of the data in `response` without processing any untagged responses. Releases `store`'s command lock.

`store` :

  the CamelImapStore the response is from.

`response` :

  a CamelImapResponse:

### camel_imap_response_extract ()

    char*               camel_imap_response_extract         (CamelImapStore *store,
                                                             CamelImapResponse *response,
                                                             const char *type,
                                                             CamelException *ex);

This checks that `response` contains a single untagged response of type `type` and returns just that response data. If `response` doesn't contain the right information, the function will set `ex` and return `NULL`. Either way, `response` will be freed and the store's connect_lock released.

`store` :

  the store the response came from

`response` :

  the response data returned from camel_imap_command

`type` :

  the response type to extract

`ex` :

  a CamelException

Returns :

  the desired response string, which the caller must free.

### camel_imap_response_extract_continuation ()

    char*               camel_imap_response_extract_continuation
                                                            (CamelImapStore *store,
                                                             CamelImapResponse *response,
                                                             CamelException *ex);

This checks that `response` contains a continuation response, and returns just that data. If `response` doesn't contain a continuation response, the function will set `ex`, release `store`'s connect_lock, and return `NULL`. Either way, `response` will be freed.

`store` :

  the store the response came from

`response` :

  the response data returned from camel_imap_command

`ex` :

  a CamelException

Returns :

  the desired response string, which the caller must free.

### camel_imap_command_start ()

    gboolean            camel_imap_command_start            (CamelImapStore *store,
                                                             CamelFolder *folder,
                                                             CamelException *ex,
                                                             const char *fmt,
                                                             ...);

This function makes sure that `folder` (if non-`NULL`) is the currently-selected folder on `store` and then sends the IMAP command specified by `fmt` and the following arguments.

`fmt` can include the following `-escapes` ONLY: `s`, `d`, %%: as with printf `S`: an IMAP "string" (quoted string or literal) `F`: an IMAP folder name `G`: an IMAP folder name, with namespace already prepended

`S` strings will be passed as literals if the server supports LITERAL+ and quoted strings otherwise. (`S` does not support strings that contain newlines.)

`F` will have the imap store's namespace prepended; `F` and `G` will then be converted to UTF-7 and processed like `S`.

On success, the store's connect_lock will be locked. It will be freed when `CAMEL_IMAP_RESPONSE_TAGGED` or `CAMEL_IMAP_RESPONSE_ERROR` is returned from `camel_imap_command_response()`. (The lock is recursive, so callers can grab and release it themselves if they need to run multiple commands atomically.)

`store` :

  the IMAP store

`folder` :

  The folder to perform the operation in (or `NULL` if not relevant).

`ex` :

  a CamelException

`fmt` :

  a sort of printf-style format string, followed by arguments

`...` :

Returns :

  `TRUE` if the command was sent successfully, `FALSE` if an error occurred (in which case `ex` will be set).

### camel_imap_command_response ()

    CamelImapResponseType camel_imap_command_response       (CamelImapStore *store,
                                                             char **respbuf,
                                                             CamelException *ex);

This reads a single tagged, untagged, or continuation response from `store` into *`response`. The caller must free the string when it is done with it.

`store` :

  the IMAP store

`respbuf` :

`ex` :

  a CamelException

Returns :

  One of `CAMEL_IMAP_RESPONSE_CONTINUATION`, `CAMEL_IMAP_RESPONSE_UNTAGGED`, `CAMEL_IMAP_RESPONSE_TAGGED`, or `CAMEL_IMAP_RESPONSE_ERROR`. If either of the last two, `store`'s command lock will be unlocked.