camel-operation
3
CAMEL Library

# camel-operation

## Synopsis

                        CamelOperation;
    void                (*CamelOperationStatusFunc)         (struct _CamelOperation *op,
                                                             const char *what,
                                                             int pc,
                                                             void *data);
    enum                camel_operation_status_t;
    CamelOperation*     camel_operation_new                 (CamelOperationStatusFunc status,
                                                             void *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);
    int                 camel_operation_cancel_check        (CamelOperation *cc);
    int                 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,
                                                             char *what,
                                                             ...);
    void                camel_operation_start_transient     (CamelOperation *cc,
                                                             char *what,
                                                             ...);
    void                camel_operation_progress            (CamelOperation *cc,
                                                             int pc);
    void                camel_operation_progress_count      (CamelOperation *cc,
                                                             int sofar);
    void                camel_operation_end                 (CamelOperation *cc);

## Description

## Details

### CamelOperation

    typedef struct _CamelOperation CamelOperation;

### CamelOperationStatusFunc ()

    void                (*CamelOperationStatusFunc)         (struct _CamelOperation *op,
                                                             const char *what,
                                                             int pc,
                                                             void *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,
                                                             void *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 :

  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 ()

    int                 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 ()

    int                 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,
                                                             char *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,
                                                             char *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,
                                                             int 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,
                                                             int 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