Camel.Operation
Description: Reference for Camel.Operation

### Class

# CamelOperation

#### Description [src]

    class Camel.Operation : Gio.Cancellable
    {
      CamelOperationPrivate* priv
    }

Progress reporting and cancellation for long-running tasks.

`CamelOperation` is a bi-directional rendezvous mechanism used to communicate status information from long-running Camel tasks back to the calling application, and to allow the application to cancel those tasks.

The typical usage pattern is:

1. Create a `CamelOperation` with a status callback.
2. Push it onto the current thread with `camel_operation_push_message()` / or use it as a `GCancellable` passed to async operations.
3. Long-running Camel functions report progress via `camel_operation_progress()` and check for cancellation via the `GCancellable` interface.
4. The client can cancel the operation by calling `g_cancellable_cancel()` on the `CamelOperation` (which is a `GCancellable` subclass).

Status messages follow a push/pop model: `camel_operation_push_message()` starts a new operation description (emitting the “status” signal), and `camel_operation_pop_message()` ends it, restoring the previous description. `camel_operation_progress()` reports percentage-based progress within the current message.

#### Hierarchy

#### Ancestors

- GCancellable
- GObject

#### Constructors

###### camel_operation_new

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.

###### camel_operation_new_proxy

Proxies the `cancellable` in a way that if it is cancelled, then the returned cancellable is also cancelled, but when the returned cancellable is cancelled, then it doesn’t influence the original cancellable. Other CamelOperation actions being done on the returned cancellable are also propagated to the `cancellable`.

since: 3.24

#### Functions

###### camel_operation_cancel_all

Cancel all outstanding operations.

###### camel_operation_dup_message

Duplicates current operation message, or returns `NULL`, if no such is available. The message as the last text set by camel_operation_push_message().

since: 3.52

###### camel_operation_pop_message

Pops the most recently pushed message.

###### camel_operation_progress

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

###### camel_operation_push_message

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.

#### Instance methods

##### Methods inherited from GCancellable (12)

###### g_cancellable_cancel

Will set `cancellable` to cancelled, and will emit the `GCancellable::cancelled` signal. (However, see the warning about race conditions in the documentation for that signal if you are planning to connect to it.).

###### g_cancellable_connect

Convenience function to connect to the `GCancellable::cancelled` signal. Also handles the race condition that may happen if the cancellable is cancelled right before connecting.

###### g_cancellable_disconnect

Disconnects a handler from a cancellable instance similar to g_signal_handler_disconnect(). Additionally, in the event that a signal handler is currently running, this call will block until the handler has finished. Calling this function from a `GCancellable::cancelled` signal handler will therefore result in a deadlock.

###### g_cancellable_get_fd

Gets the file descriptor for a cancellable job. This can be used to implement cancellable operations on Unix systems. The returned fd will turn readable when `cancellable` is cancelled.

###### g_cancellable_is_cancelled

Checks if a cancellable job has been cancelled.

###### g_cancellable_make_pollfd

Creates a `GPollFD` corresponding to `cancellable`; this can be passed to `g_poll()` and used to poll for cancellation. This is useful both for unix systems without a native poll and for portability to windows.

###### g_cancellable_pop_current

Pops `cancellable` off the cancellable stack (verifying that `cancellable` is on the top of the stack).

###### g_cancellable_push_current

Pushes `cancellable` onto the cancellable stack. The current cancellable can then be received using g_cancellable_get_current().

###### g_cancellable_release_fd

Releases a resources previously allocated by `g_cancellable_get_fd()` or g_cancellable_make_pollfd().

###### g_cancellable_reset

Resets `cancellable` to its uncancelled state.

###### g_cancellable_set_error_if_cancelled

If the `cancellable` is cancelled, sets the error to notify that the operation was cancelled.

###### g_cancellable_source_new

Creates a source that triggers if `cancellable` is cancelled and calls its callback of type `GCancellableSourceFunc`. This is primarily useful for attaching to another (non-cancellable) source with `g_source_add_child_source()` to add cancellability to it.

##### Methods inherited from GObject (43)

Please see GObject for a full list of methods.

#### Signals

###### Camel.Operation::pop-message

No description available.

###### Camel.Operation::progress

No description available.

###### Camel.Operation::push-message

No description available.

###### Camel.Operation::status

No description available.

##### Signals inherited from GCancellable (1)

###### GCancellable::cancelled

Emitted when the operation has been cancelled.

##### Signals inherited from GObject (1)

###### GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

#### Class structure

    struct CamelOperationClass {
      GCancellableClass parent_class;
      void (* status) (
        CamelOperation* operation,
        const gchar* what,
        gint pc
      );
      gpointer reserved;

    }

No description available.

###### Class members

`parent_class: GCancellableClass`

  No description available.

`status: void (* status) ( CamelOperation* operation, const gchar* what, gint pc )`

  No description available.

`reserved: gpointer`

  No description available.

#### Virtual methods

###### Camel.OperationClass.status

No description available.