SeahorseMultiOperation

## SeahorseMultiOperation SeahorseMultiOperation — Contains code for operations and multi operations (container for several operations) |

## Synopsis

    #include <seahorse-operation.h>

                        SeahorseOperation;
    SeahorseOperation*  seahorse_operation_new_complete     (GError *err);
    SeahorseOperation*  seahorse_operation_new_cancelled    ();
    void                seahorse_operation_cancel           (SeahorseOperation *operation);
    #define             seahorse_operation_is_running       (operation)
    #define             seahorse_operation_is_cancelled     (operation)
    #define             seahorse_operation_is_successful    (operation)
    void                seahorse_operation_copy_error       (SeahorseOperation *operation,
                                                             GError **err);
    const GError*       seahorse_operation_get_error        (SeahorseOperation *operation);
    void                seahorse_operation_display_error    (SeahorseOperation *operation,
                                                             const gchar *title,
                                                             GtkWidget *parent);
    void                seahorse_operation_wait             (SeahorseOperation *operation);
    void                (*SeahorseDoneFunc)                 (SeahorseOperation *op,
                                                             gpointer userdata);
    void                (*SeahorseProgressFunc)             (SeahorseOperation *op,
                                                             const gchar *status,
                                                             gdouble progress,
                                                             gpointer userdata);
    void                seahorse_operation_watch            (SeahorseOperation *operation,
                                                             SeahorseDoneFunc done_callback,
                                                             gpointer donedata,
                                                             SeahorseProgressFunc progress_callback,
                                                             gpointer progdata);
    #define             seahorse_operation_get_progress     (op)
    #define             seahorse_operation_get_message      (operation)
    gpointer            seahorse_operation_get_result       (SeahorseOperation *operation);
    GSList*             seahorse_operation_list_add         (GSList *list,
                                                             SeahorseOperation *operation);
    GSList*             seahorse_operation_list_remove      (GSList *list,
                                                             SeahorseOperation *operation);
    void                seahorse_operation_list_cancel      (GSList *list);
    GSList*             seahorse_operation_list_purge       (GSList *list);
    GSList*             seahorse_operation_list_free        (GSList *list);
    #define             SEAHORSE_TYPE_MULTI_OPERATION
    #define             SEAHORSE_MULTI_OPERATION            (obj)
    #define             SEAHORSE_MULTI_OPERATION_CLASS      (klass)
    #define             SEAHORSE_IS_MULTI_OPERATION         (obj)
    #define             SEAHORSE_IS_MULTI_OPERATION_CLASS   (klass)
    #define             SEAHORSE_MULTI_OPERATION_GET_CLASS  (obj)
                        SeahorseMultiOperation;
    GType               seahorse_multi_operation_get_type   ();
    SeahorseMultiOperation* seahorse_multi_operation_new    ();
    void                seahorse_multi_operation_take       (SeahorseMultiOperation *mop,
                                                             SeahorseOperation *op);
    #define             DECLARE_OPERATION                   (Opx,
                                                             opx)
    #define             SEAHORSE_CALC_PROGRESS              (cur,
                                                             tot)
    void                seahorse_operation_mark_start       (SeahorseOperation *operation);
    void                seahorse_operation_mark_done        (SeahorseOperation *operation,
                                                             gboolean cancelled,
                                                             GError *error);
    void                seahorse_operation_mark_progress    (SeahorseOperation *operation,
                                                             const gchar *message,
                                                             gdouble progress);
    void                seahorse_operation_mark_progress_full
                                                            (SeahorseOperation *operation,
                                                             const gchar *message,
                                                             gdouble current,
                                                             gdouble total);
    void                seahorse_operation_mark_result      (SeahorseOperation *operation,
                                                             gpointer result,
                                                             GDestroyNotify notify_func);

## Description

## Details

### SeahorseOperation

    typedef struct {
        GObject parent;

        gchar *message;                /* Progress status details ie: "foobar.jpg" */
        gdouble progress;              /* The current progress position, -1 for indeterminate */

        guint is_running : 1;          /* If the operation is running or not */
        guint is_done : 1;             /* Operation is done or not */
        guint is_cancelled : 1;        /* Operation is cancelled or not */;

        GError *error;
    } SeahorseOperation;

An operation taking place over time.

- Generally this class is derived and a base class actually hooks in and performs the operation, keeps the properties updated etc... - Used all over to represent things like key loading operations, search - SeahorseMultiOperation allows you to combine multiple operations into a single one. Used when searching multiple key servers for example. - Can be tied to a progress bar (see seahorse-progress.h) - Holds a reference to itself while the operation is in progress. - The seahorse_operation_mark_* are used by derived classes to update properties of the operation as things progress.

Signals: done: The operation is complete. progress: The operation has progressed, or changed state somehow.

Properties: result: The 'result' of the operation (if applicable). This depends on the derived operation class. progress: A fraction between 0.0 and 1.0 inclusive representing how far along this operation is. 0.0 = indeterminate, and 1.0 is done. message: A progress message to display to the user.

GObject `parent`; | The parent GObject
gchar *`message`; | Progress status details ie: "foobar.jpg"
gdouble `progress`; | The current progress position, -1 for indeterminate
guint `is_running` : 1; | If the operation is running or not
guint `is_done` : 1; | Operation is done or not
guint `is_cancelled` : 1; | Operation is cancelled or not
GError *`error`; | GError for the operation

### seahorse_operation_new_complete ()

    SeahorseOperation*  seahorse_operation_new_complete     (GError *err);

Creates a new operation and sets it's state to done

`err` : | an optional error to set
Returns : | the operation

### seahorse_operation_new_cancelled ()

    SeahorseOperation*  seahorse_operation_new_cancelled    ();

Creates a new operation and sets in to cancelled state

Returns : | The new operation

### seahorse_operation_cancel ()

    void                seahorse_operation_cancel           (SeahorseOperation *operation);

Cancels the operation

`operation` : |

### seahorse_operation_is_running()

    #define             seahorse_operation_is_running(operation)

`operation` : |

### seahorse_operation_is_cancelled()

    #define             seahorse_operation_is_cancelled(operation)

`operation` : |

### seahorse_operation_is_successful()

    #define             seahorse_operation_is_successful(operation)

`operation` : |

### seahorse_operation_copy_error ()

    void                seahorse_operation_copy_error       (SeahorseOperation *operation,
                                                             GError **err);

Copies an internal error from the SeahorseOperation to `err`

`operation` : |
`err` : | The resulting error

### seahorse_operation_get_error ()

    const GError*       seahorse_operation_get_error        (SeahorseOperation *operation);

Directly return the error from operation

`operation` : |
Returns : | the GError error from the operation

### seahorse_operation_display_error ()

    void                seahorse_operation_display_error    (SeahorseOperation *operation,
                                                             const gchar *title,
                                                             GtkWidget *parent);

Displays an error box if there is an error in the operation

`operation` : | a SeahorseOperation
`title` : | The title of the error box
`parent` : | ignored

### seahorse_operation_wait ()

    void                seahorse_operation_wait             (SeahorseOperation *operation);

Waits till the SeahorseOperation finishes.

`operation` : |

### SeahorseDoneFunc ()

    void                (*SeahorseDoneFunc)                 (SeahorseOperation *op,
                                                             gpointer userdata);

`op` : |
`userdata` : |

### SeahorseProgressFunc ()

    void                (*SeahorseProgressFunc)             (SeahorseOperation *op,
                                                             const gchar *status,
                                                             gdouble progress,
                                                             gpointer userdata);

`op` : |
`status` : |
`progress` : |
`userdata` : |

### seahorse_operation_watch ()

    void                seahorse_operation_watch            (SeahorseOperation *operation,
                                                             SeahorseDoneFunc done_callback,
                                                             gpointer donedata,
                                                             SeahorseProgressFunc progress_callback,
                                                             gpointer progdata);

If the operation already finished, calls the done callback. Does progress handling else.

`operation` : | The operation to watch
`done_callback` : | callback when done
`donedata` : | data for this callback
`progress_callback` : | Callback when in progress mode
`progdata` : | data for this callback

### seahorse_operation_get_progress()

    #define             seahorse_operation_get_progress(op)

`op` : |

### seahorse_operation_get_message()

    #define             seahorse_operation_get_message(operation)

`operation` : |

### seahorse_operation_get_result ()

    gpointer            seahorse_operation_get_result       (SeahorseOperation *operation);

`operation` : |
Returns : | the results of this operation

### seahorse_operation_list_add ()

    GSList*             seahorse_operation_list_add         (GSList *list,
                                                             SeahorseOperation *operation);

Prepends the seahorse operation to the list

`list` : | a GSList
`operation` : | a SeahorseOperation to add to the lit
Returns : | the list

### seahorse_operation_list_remove ()

    GSList*             seahorse_operation_list_remove      (GSList *list,
                                                             SeahorseOperation *operation);

Removes an operation from the list

`list` : | A list to remove an operation from
`operation` : | the operation to remove
Returns : | The new list

### seahorse_operation_list_cancel ()

    void                seahorse_operation_list_cancel      (GSList *list);

Cancels every operation in the list

`list` : | a list of Seahorse operations

### seahorse_operation_list_purge ()

    GSList*             seahorse_operation_list_purge       (GSList *list);

Purges a list of Seahorse operations

`list` : | A list of operations
Returns : | the purged list

### seahorse_operation_list_free ()

    GSList*             seahorse_operation_list_free        (GSList *list);

Frees the list of seahorse operations

`list` : | A GSList of SEAHORSE_OPERATION s
Returns : | NULL

### SEAHORSE_TYPE_MULTI_OPERATION

    #define SEAHORSE_TYPE_MULTI_OPERATION            (seahorse_multi_operation_get_type ())

### SEAHORSE_MULTI_OPERATION()

    #define SEAHORSE_MULTI_OPERATION(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), SEAHORSE_TYPE_MULTI_OPERATION, SeahorseMultiOperation))

`obj` : |

### SEAHORSE_MULTI_OPERATION_CLASS()

    #define SEAHORSE_MULTI_OPERATION_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), SEAHORSE_TYPE_MULTI_OPERATION, SeahorseMultiOperationClass))

`klass` : |

### SEAHORSE_IS_MULTI_OPERATION()

    #define SEAHORSE_IS_MULTI_OPERATION(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), SEAHORSE_TYPE_MULTI_OPERATION))

`obj` : |

### SEAHORSE_IS_MULTI_OPERATION_CLASS()

    #define SEAHORSE_IS_MULTI_OPERATION_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), SEAHORSE_TYPE_MULTI_OPERATION))

`klass` : |

### SEAHORSE_MULTI_OPERATION_GET_CLASS()

    #define SEAHORSE_MULTI_OPERATION_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), SEAHORSE_TYPE_MULTI_OPERATION, SeahorseMultiOperationClass))

`obj` : |

### SeahorseMultiOperation

    typedef struct {
        SeahorseOperation parent;

        GSList *operations;
    } SeahorseMultiOperation;

### seahorse_multi_operation_get_type ()

    GType               seahorse_multi_operation_get_type   ();

Returns : |

### seahorse_multi_operation_new ()

    SeahorseMultiOperation* seahorse_multi_operation_new    ();

Creates a new multi operation

Returns : | the new multi operation

### seahorse_multi_operation_take ()

    void                seahorse_multi_operation_take       (SeahorseMultiOperation *mop,
                                                             SeahorseOperation *op);

Adds `op` to `mop`

`mop` : | the multi operation container
`op` : | an operation to add

### DECLARE_OPERATION()

    #define             DECLARE_OPERATION(Opx, opx)

`Opx` : |
`opx` : |

### SEAHORSE_CALC_PROGRESS()

    #define SEAHORSE_CALC_PROGRESS(cur, tot)

`cur` : |
`tot` : |

### seahorse_operation_mark_start ()

    void                seahorse_operation_mark_start       (SeahorseOperation *operation);

Sets everything in the seahorse operation to the start state

`operation` : |

### seahorse_operation_mark_done ()

    void                seahorse_operation_mark_done        (SeahorseOperation *operation,
                                                             gboolean cancelled,
                                                             GError *error);

Sets everything in the seahorse operation to the end state

`operation` : |
`cancelled` : | TRUE if this operation was cancelled
`error` : | An error to set

### seahorse_operation_mark_progress ()

    void                seahorse_operation_mark_progress    (SeahorseOperation *operation,
                                                             const gchar *message,
                                                             gdouble progress);

Sets the new message and the new progress. After a change it emits the progress signal

`operation` : |
`message` : | The new message of the operation, Can be NULL
`progress` : | the new progress of the operation

### seahorse_operation_mark_progress_full ()

    void                seahorse_operation_mark_progress_full
                                                            (SeahorseOperation *operation,
                                                             const gchar *message,
                                                             gdouble current,
                                                             gdouble total);

`operation` : |
`message` : | an optional message (can be NULL)
`current` : | the current value of the progress
`total` : | the max. value of the progress

### seahorse_operation_mark_result ()

    void                seahorse_operation_mark_result      (SeahorseOperation *operation,
                                                             gpointer result,
                                                             GDestroyNotify notify_func);

If `op` already has a result and a destroy function, the function is called. If there is none, it will be set to `result` and `destroy_func`

`operation` : |
`result` : | a result
`notify_func` : |