## Cancellation

Cancellation — halt in-progress operations

## Synopsis

    GnomeVFSCancellation* gnome_vfs_cancellation_new
                                                (void);
    void        gnome_vfs_cancellation_destroy  (GnomeVFSCancellation *cancellation);
    void        gnome_vfs_cancellation_cancel   (GnomeVFSCancellation *cancellation);
    gboolean    gnome_vfs_cancellation_check    (GnomeVFSCancellation *cancellation);
    void        gnome_vfs_cancellation_ack      (GnomeVFSCancellation *cancellation);
    gint        gnome_vfs_cancellation_get_fd   (GnomeVFSCancellation *cancellation);

## Description

## Details

### gnome_vfs_cancellation_new ()

    GnomeVFSCancellation* gnome_vfs_cancellation_new
                                                (void);

Create a new GnomeVFSCancellation object for reporting cancellation to a GNOME VFS module.

Returns : | A pointer to the new GnomeVFSCancellation object.

### gnome_vfs_cancellation_destroy ()

    void        gnome_vfs_cancellation_destroy  (GnomeVFSCancellation *cancellation);

Destroy `cancellation`.

`cancellation` : | A GnomeVFSCancellation object

### gnome_vfs_cancellation_cancel ()

    void        gnome_vfs_cancellation_cancel   (GnomeVFSCancellation *cancellation);

Send a cancellation request through `cancellation`.

If called on a different thread than the one handling idle callbacks, there is a small race condition where the operation finished callback will be called even if you cancelled the operation. Its the apps responsibility to handle this. See gnome_vfs_async_cancel for more discussion about this.

`cancellation` : | A GnomeVFSCancellation object

### gnome_vfs_cancellation_check ()

    gboolean    gnome_vfs_cancellation_check    (GnomeVFSCancellation *cancellation);

Check for pending cancellation.

`cancellation` : | A GnomeVFSCancellation object
Returns : | `TRUE` if the operation should be interrupted.

### gnome_vfs_cancellation_ack ()

    void        gnome_vfs_cancellation_ack      (GnomeVFSCancellation *cancellation);

Acknowledge a cancellation. This should be called if ``gnome_vfs_cancellation_check()`' returns `TRUE` or if ``select()`' reports that input is available on the file descriptor returned by ``gnome_vfs_cancellation_get_fd()`'.

`cancellation` : | A GnomeVFSCancellation object

### gnome_vfs_cancellation_get_fd ()

    gint        gnome_vfs_cancellation_get_fd   (GnomeVFSCancellation *cancellation);

Get a file descriptor -based notificator for `cancellation`. When `cancellation` receives a cancellation request, a character will be made available on the returned file descriptor for input.

This is very useful for detecting cancellation during I/O operations: you can use the ``select()`' call to check for available input/output on the file you are reading/writing, and on the notificator's file descriptor at the same time. If a data is available on the notificator's file descriptor, you know you have to cancel the read/write operation.

`cancellation` : | A GnomeVFSCancellation object
Returns : | the notificator's file descriptor, or -1 if starved of file descriptors.