camel-operation

## camel-operation camel-operation |

## Synopsis

                        CamelOperation;
    void                (*CamelOperationStatusFunc)         (struct _CamelOperation *op,
                                                             const gchar *what,
                                                             gint pc,
                                                             gpointer data);
    enum                camel_operation_status_t;
    CamelOperation *    camel_operation_new                 (CamelOperationStatusFunc status,
                                                             gpointer status_data);
    void                camel_operation_mute                (CamelOperation *cc);
    void                camel_operation_ref                 (CamelOperation *cc);
    void                camel_operation_unref               (CamelOperation *cc);
    void                camel_operation_cancel              (CamelOperation *cc);
    void                camel_operation_uncancel            (CamelOperation *cc);
    CamelOperation *    camel_operation_register            (CamelOperation *cc);
    void                camel_operation_unregister          (CamelOperation *cc);
    void                camel_operation_cancel_block        (CamelOperation *cc);
    void                camel_operation_cancel_unblock      (CamelOperation *cc);
    gint                camel_operation_cancel_check        (CamelOperation *cc);
    gint                camel_operation_cancel_fd           (CamelOperation *cc);
    struct PRFileDesc * camel_operation_cancel_prfd         (CamelOperation *cc);
    CamelOperation *    camel_operation_registered          (void);
    void                camel_operation_start               (CamelOperation *cc,
                                                             const gchar *what,
                                                             ...);
    void                camel_operation_start_transient     (CamelOperation *cc,
                                                             const gchar *what,
                                                             ...);
    void                camel_operation_progress            (CamelOperation *cc,
                                                             gint pc);
    void                camel_operation_progress_count      (CamelOperation *cc,
                                                             gint sofar);
    void                camel_operation_end                 (CamelOperation *cc);

## Description

## Details

### CamelOperation

    typedef struct _CamelOperation CamelOperation;

### CamelOperationStatusFunc ()

    void                (*CamelOperationStatusFunc)         (struct _CamelOperation *op,
                                                             const gchar *what,
                                                             gint pc,
                                                             gpointer data);

`op` : |
`what` : |
`pc` : |
`data` : |

### enum camel_operation_status_t

    typedef enum _camel_operation_status_t {
    	CAMEL_OPERATION_START = -1,
    	CAMEL_OPERATION_END = -2
    } camel_operation_status_t;

### camel_operation_new ()

    CamelOperation *    camel_operation_new                 (CamelOperationStatusFunc status,
                                                             gpointer status_data);

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.

`status` : | Callback for receiving status messages. This will always be called with an internal lock held.
`status_data` : | User data.
Returns : | A new operation handle.

### camel_operation_mute ()

    void                camel_operation_mute                (CamelOperation *cc);

mutes a camel operation permanently. from this point on you will never receive operation updates, even if more are sent.

`cc` : |

### camel_operation_ref ()

    void                camel_operation_ref                 (CamelOperation *cc);

Add a reference to the CamelOperation `cc`.

`cc` : | operation context

### camel_operation_unref ()

    void                camel_operation_unref               (CamelOperation *cc);

Unref and potentially free `cc`.

`cc` : | operation context

### camel_operation_cancel ()

    void                camel_operation_cancel              (CamelOperation *cc);

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

`cc` : | operation context

### camel_operation_uncancel ()

    void                camel_operation_uncancel            (CamelOperation *cc);

Uncancel a cancelled operation. If `cc` is NULL then the current operation is uncancelled.

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.

`cc` : | operation context

### camel_operation_register ()

    CamelOperation *    camel_operation_register            (CamelOperation *cc);

Register a thread or the main thread for cancellation through `cc`. If `cc` is NULL, then a new cancellation is created for this thread.

All calls to `operation_register()` should save their value and call operation_register again with that, to automatically stack registrations.

`cc` : | operation context
Returns : | the previously registered operatoin.

### camel_operation_unregister ()

    void                camel_operation_unregister          (CamelOperation *cc);

Unregister the current thread for all cancellations.

`cc` : | operation context

### camel_operation_cancel_block ()

    void                camel_operation_cancel_block        (CamelOperation *cc);

Block cancellation for this operation. If `cc` is NULL, then the current thread is blocked.

`cc` : | operation context

### camel_operation_cancel_unblock ()

    void                camel_operation_cancel_unblock      (CamelOperation *cc);

Unblock cancellation, when the unblock count reaches the block count, then this operation can be cancelled. If `cc` is NULL, then the current thread is unblocked.

`cc` : | operation context

### camel_operation_cancel_check ()

    gint                camel_operation_cancel_check        (CamelOperation *cc);

Check if cancellation has been applied to `cc`. If `cc` is NULL, then the CamelOperation registered for the current thread is used.

`cc` : | operation context
Returns : | TRUE if the operation has been cancelled.

### camel_operation_cancel_fd ()

    gint                camel_operation_cancel_fd           (CamelOperation *cc);

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

`cc` : | operation context
Returns : | The fd, or -1 if cancellation is not available (blocked, or has not been registered for this thread).

### camel_operation_cancel_prfd ()

    struct PRFileDesc * camel_operation_cancel_prfd         (CamelOperation *cc);

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

`cc` : | operation context
Returns : | The fd, or NULL if cancellation is not available (blocked, or has not been registered for this thread).

### camel_operation_registered ()

    CamelOperation *    camel_operation_registered          (void);

Returns : | the registered operation, or `NULL` if none registered.

### camel_operation_start ()

    void                camel_operation_start               (CamelOperation *cc,
                                                             const gchar *what,
                                                             ...);

Report the start of an operation. All start operations should have similar end operations.

`cc` : | operation context
`what` : | action being performed (printf-style format string)
`...` : | varargs

### camel_operation_start_transient ()

    void                camel_operation_start_transient     (CamelOperation *cc,
                                                             const gchar *what,
                                                             ...);

Start a transient event. We only update this to the display if it takes very long to process, and if we do, we then go back to the previous state when finished.

`cc` : | operation context
`what` : | printf-style format string describing the action being performed
`...` : | varargs

### camel_operation_progress ()

    void                camel_operation_progress            (CamelOperation *cc,
                                                             gint pc);

Report progress on the current operation. If `cc` is NULL, then the currently registered operation is used. `pc` reports the current percentage of completion, which should be in the range of 0 to 100.

If the total percentage is not know, then use `camel_operation_progress_count()`.

`cc` : | Operation to report to.
`pc` : | Percent complete, 0 to 100.

### camel_operation_progress_count ()

    void                camel_operation_progress_count      (CamelOperation *cc,
                                                             gint sofar);

`cc` : | operation context
`sofar` : |

### camel_operation_end ()

    void                camel_operation_end                 (CamelOperation *cc);

Report the end of an operation. If `cc` is NULL, then the currently registered operation is notified.

`cc` : | operation context