## camel-operation

camel-operation

## Synopsis

                        CamelOperation;
    GCancellable *      camel_operation_new                 (void);
    void                camel_operation_cancel              (CamelOperation *operation);
    void                camel_operation_uncancel            (CamelOperation *operation);
    gboolean            camel_operation_cancel_check        (CamelOperation *operation);
    gint                camel_operation_cancel_fd           (CamelOperation *operation);
    struct PRFileDesc * camel_operation_cancel_prfd         (CamelOperation *operation);
    void                camel_operation_push_message        (GCancellable *cancellable,
                                                             const gchar *format,
                                                             ...);
    void                camel_operation_pop_message         (GCancellable *cancellable);
    void                camel_operation_progress            (GCancellable *cancellable,
                                                             gint percent);

## Description

## Details

### CamelOperation

    typedef struct {
    	GCancellable parent;
    	CamelOperationPrivate *priv;
    } CamelOperation;

### camel_operation_new ()

    GCancellable *      camel_operation_new                 (void);

Create a new camel operation handle. Camel operation handles can be used in a multithreaded application (or a single operation handle can be used in a non threaded appliation) to cancel running operations and to obtain notification messages of the internal status of messages.

Returns : | A new operation handle.

### camel_operation_cancel ()

    void                camel_operation_cancel              (CamelOperation *operation);

Cancel a given operation. If `operation` is `NULL` then all outstanding operations are cancelled.

`operation` : | a CamelOperation

### camel_operation_uncancel ()

    void                camel_operation_uncancel            (CamelOperation *operation);

Uncancel a cancelled operation.

This is useful, if e.g. you need to do some cleaning up where a cancellation lying around in the same thread will abort any processing.

`operation` : | a CamelOperation

### camel_operation_cancel_check ()

    gboolean            camel_operation_cancel_check        (CamelOperation *operation);

Check if cancellation has been applied to `operation`.

`operation` : | a CamelOperation
Returns : | `TRUE` if the operation has been cancelled

### camel_operation_cancel_fd ()

    gint                camel_operation_cancel_fd           (CamelOperation *operation);

Retrieve a file descriptor that can be waited on (select, or poll) for read, to asynchronously detect cancellation.

`operation` : | a CamelOperation
Returns : | The fd, or -1 if cancellation has not been registered for this thread.

### camel_operation_cancel_prfd ()

    struct PRFileDesc * camel_operation_cancel_prfd         (CamelOperation *operation);

Retrieve a file descriptor that can be waited on (select, or poll) for read, to asynchronously detect cancellation.

`operation` : | a CamelOperation
Returns : | The fd, or `NULL` if cancellation has not been registered for this thread.

### camel_operation_push_message ()

    void                camel_operation_push_message        (GCancellable *cancellable,
                                                             const gchar *format,
                                                             ...);

Call this function to describe an operation being performed. Call `camel_operation_progress()` to report progress on the operation. Call `camel_operation_pop_message()` when the operation is complete.

This function only works if `cancellable` is a CamelOperation cast as a GCancellable. If `cancellable` is a plain GCancellable or `NULL`, the function does nothing and returns silently.

`cancellable` : | a GCancellable or `NULL`
`format` : | a standard `printf()` format string
`...` : | the parameters to insert into the format string

### camel_operation_pop_message ()

    void                camel_operation_pop_message         (GCancellable *cancellable);

Pops the most recently pushed message.

This function only works if `cancellable` is a CamelOperation cast as a GCancellable. If `cancellable` is a plain GCancellable or `NULL`, the function does nothing and returns silently.

`cancellable` : | a GCancellable

### camel_operation_progress ()

    void                camel_operation_progress            (GCancellable *cancellable,
                                                             gint percent);

Report progress on the current operation. `percent` reports the current percentage of completion, which should be in the range of 0 to 100.

This function only works if `cancellable` is a CamelOperation cast as a GCancellable. If `cancellable` is a plain GCancellable or `NULL`, the function does nothing and returns silently.

`cancellable` : | a GCancellable or `NULL`
`percent` : | percent complete, 0 to 100.