camel-operation

camel-operation

Synopsis

struct              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

struct CamelOperation

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


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

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.