CamelFilterDriver: Camel Reference Manual

## CamelFilterDriver CamelFilterDriver |

## Functions

CamelFolder * | (*CamelFilterGetFolderFunc) ()
void | (*CamelFilterStatusFunc) ()
void | (*CamelFilterShellFunc) ()
void | (*CamelFilterPlaySoundFunc) ()
void | (*CamelFilterSystemBeepFunc) ()
CamelFilterDriver * | camel_filter_driver_new ()
void | camel_filter_driver_set_logfile ()
void | camel_filter_driver_set_status_func ()
void | camel_filter_driver_set_shell_func ()
void | camel_filter_driver_set_play_sound_func ()
void | camel_filter_driver_set_system_beep_func ()
void | camel_filter_driver_set_folder_func ()
void | camel_filter_driver_set_default_folder ()
void | camel_filter_driver_add_rule ()
gboolean | camel_filter_driver_remove_rule_by_name ()
void | camel_filter_driver_flush ()
gint | camel_filter_driver_filter_message ()
gint | camel_filter_driver_filter_mbox ()
gint | camel_filter_driver_filter_folder ()
void | camel_filter_driver_log_info ()

## Types and Values

enum | camel_filter_status_t

## Object Hierarchy

        GObject
        ╰── CamelFilterDriver

## Description

## Functions

### CamelFilterGetFolderFunc ()

    CamelFolder *
    (*CamelFilterGetFolderFunc) (CamelFilterDriver *driver,
                                 const gchar *uri,
                                 gpointer user_data,
                                 GError **error);

### CamelFilterStatusFunc ()

    void
    (*CamelFilterStatusFunc) (CamelFilterDriver *driver,
                              enum camel_filter_status_t status,
                              gint pc,
                              const gchar *desc,
                              gpointer user_data);

### CamelFilterShellFunc ()

    void
    (*CamelFilterShellFunc) (CamelFilterDriver *driver,
                             gint argc,
                             gchar **argv,
                             gpointer user_data);

### CamelFilterPlaySoundFunc ()

    void
    (*CamelFilterPlaySoundFunc) (CamelFilterDriver *driver,
                                 const gchar *filename,
                                 gpointer user_data);

### CamelFilterSystemBeepFunc ()

    void
    (*CamelFilterSystemBeepFunc) (CamelFilterDriver *driver,
                                  gpointer user_data);

### camel_filter_driver_new ()

    CamelFilterDriver *
    camel_filter_driver_new (struct _CamelSession *session);

#### Parameters

session | . | [type CamelSession]

#### Returns

A new CamelFilterDriver object

### camel_filter_driver_set_logfile ()

    void
    camel_filter_driver_set_logfile (CamelFilterDriver *d,
                                     FILE *logfile);

Sets a log file to use for logging.

#### Parameters

d | a CamelFilterDriver |
logfile | a FILE handle where to write logging. | [nullable]

### camel_filter_driver_set_status_func ()

    void
    camel_filter_driver_set_status_func (CamelFilterDriver *d,
                                         CamelFilterStatusFunc func,
                                         gpointer user_data);

Sets a status callback, which is used to report progress/status.

#### Parameters

d | a CamelFilterDriver |
func | a callback to report progress. | [scope call][closure user_data]
user_data | user data to pass to `func` |

### camel_filter_driver_set_shell_func ()

    void
    camel_filter_driver_set_shell_func (CamelFilterDriver *d,
                                        CamelFilterShellFunc func,
                                        gpointer user_data);

Sets a shell command callback, which is called when a shell command execution is requested.

#### Parameters

d | a CamelFilterDriver |
func | a shell command callback. | [scope call][closure user_data]
user_data | user data to pass to `func` |

### camel_filter_driver_set_play_sound_func ()

    void
    camel_filter_driver_set_play_sound_func
                                   (CamelFilterDriver *d,
                                    CamelFilterPlaySoundFunc func,
                                    gpointer user_data);

Sets a callback to call when a play of a sound is requested.

#### Parameters

d | a CamelFilterDriver |
func | a callback to play a sound. | [scope call][closure user_data]
user_data | user data to pass to `func` |

### camel_filter_driver_set_system_beep_func ()

    void
    camel_filter_driver_set_system_beep_func
                                   (CamelFilterDriver *d,
                                    CamelFilterSystemBeepFunc func,
                                    gpointer user_data);

Sets a callback to use for system beep.

#### Parameters

d | a CamelFilterDriver |
func | a system beep callback. | [scope call][closure user_data]
user_data | user data to pass to `func` |

### camel_filter_driver_set_folder_func ()

    void
    camel_filter_driver_set_folder_func (CamelFilterDriver *d,
                                         CamelFilterGetFolderFunc get_folder,
                                         gpointer user_data);

Sets a callback (of type CamelFilterGetFolderFunc) to get a folder.

#### Parameters

d | a CamelFilterDriver |
get_folder | a callback to get a folder. | [scope call][closure user_data]
user_data | user data to pass to `get_folder` |

### camel_filter_driver_set_default_folder ()

    void
    camel_filter_driver_set_default_folder
                                   (CamelFilterDriver *d,
                                    CamelFolder *def);

Sets a default folder for the driver. The function adds its own reference for the folder.

#### Parameters

d | a CamelFilterDriver |
def | a default CamelFolder. | [nullable]

### camel_filter_driver_add_rule ()

    void
    camel_filter_driver_add_rule (CamelFilterDriver *d,
                                  const gchar *name,
                                  const gchar *match,
                                  const gchar *action);

Adds a new rule to set of rules to process by the filter driver.

#### Parameters

d | a CamelFilterDriver |
name | name of the rule |
match | a code (CamelSExp) to execute to check whether the rule can be applied |
action | an action code (CamelSExp) to execute, when the `match` evaluates to `TRUE` |

### camel_filter_driver_remove_rule_by_name ()

    gboolean
    camel_filter_driver_remove_rule_by_name
                                   (CamelFilterDriver *d,
                                    const gchar *name);

Removes a rule by name, added by `camel_filter_driver_add_rule()`.

#### Parameters

d | a CamelFilterDriver |
name | rule name |

#### Returns

Whether the rule had been found and removed.

### camel_filter_driver_flush ()

    void
    camel_filter_driver_flush (CamelFilterDriver *driver,
                               GError **error);

Flush all of the only-once filter actions.

#### Parameters

driver | a CamelFilterDriver |
error | return location for a GError, or `NULL` |

### camel_filter_driver_filter_message ()

    gint
    camel_filter_driver_filter_message (CamelFilterDriver *driver,
                                        CamelMimeMessage *message,
                                        CamelMessageInfo *info,
                                        const gchar *uid,
                                        CamelFolder *source,
                                        const gchar *store_uid,
                                        const gchar *original_store_uid,
                                        GCancellable *cancellable,
                                        GError **error);

Filters a message based on rules defined in the FilterDriver object. If the source folder (`source` ) and the uid (`uid` ) are provided, the filter will operate on the CamelFolder (which in certain cases is more efficient than using the default `camel_folder_append_message()` function).

#### Parameters

driver | CamelFilterDriver |
message | message to filter or NULL |
info | message info or NULL |
uid | message uid or NULL |
source | source folder or NULL |
store_uid | UID of source store, or `NULL` |
original_store_uid | UID of source store (pre-movemail), or `NULL` |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

-1 if errors were encountered during filtering, otherwise returns 0.

### camel_filter_driver_filter_mbox ()

    gint
    camel_filter_driver_filter_mbox (CamelFilterDriver *driver,
                                     const gchar *mbox,
                                     const gchar *original_source_url,
                                     GCancellable *cancellable,
                                     GError **error);

Filters an mbox file based on rules defined in the FilterDriver object. Is more efficient as it doesn't need to open the folder through Camel directly.

#### Parameters

driver | CamelFilterDriver |
mbox | mbox filename to be filtered |
original_source_url | URI of the `mbox` , or `NULL`. | [nullable]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

-1 if errors were encountered during filtering, otherwise returns 0.

### camel_filter_driver_filter_folder ()

    gint
    camel_filter_driver_filter_folder (CamelFilterDriver *driver,
                                       CamelFolder *folder,
                                       CamelUIDCache *cache,
                                       GPtrArray *uids,
                                       gboolean remove,
                                       GCancellable *cancellable,
                                       GError **error);

Filters a folder based on rules defined in the FilterDriver object.

#### Parameters

driver | CamelFilterDriver |
folder | CamelFolder to be filtered |
cache | UID cache (needed for POP folders) |
uids | message uids to be filtered or NULL (as a shortcut to filter all messages). | [element-type utf8]
remove | TRUE to mark filtered messages as deleted |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

-1 if errors were encountered during filtering, otherwise returns 0.

### camel_filter_driver_log_info ()

    void
    camel_filter_driver_log_info (CamelFilterDriver *driver,
                                  const gchar *format,
                                  ...);

Logs an informational message to a filter log. The function does nothing when `driver` is `NULL` or when there is no log file being set in `driver` .

#### Parameters

driver | a CamelFilterDriver, or `NULL`. | [nullable]
format | a printf-like format to use for the informational log entry |
... | arguments for `format` |

Since: 3.24

## Types and Values

### enum camel_filter_status_t

#### Members

CAMEL_FILTER_STATUS_NONE |  |
CAMEL_FILTER_STATUS_START |  |
CAMEL_FILTER_STATUS_ACTION |  |
CAMEL_FILTER_STATUS_PROGRESS |  |
CAMEL_FILTER_STATUS_END |  |