FmFileOpsJob

## FmFileOpsJob FmFileOpsJob — Job to do something with files. |

## Synopsis

    #define             FM_FILE_OPS_JOB_TYPE
    enum                FmFileOpOption;
    enum                FmFileOpType;
    struct              FmFileOpsJob;
    struct              FmFileOpsJobClass;
    FmFileOpOption      fm_file_ops_job_ask_rename          (FmFileOpsJob *job,
                                                             GFile *src,
                                                             GFileInfo *src_inf,
                                                             GFile *dest,
                                                             GFile **new_dest);
    void                fm_file_ops_job_emit_cur_file       (FmFileOpsJob *job,
                                                             const char *cur_file);
    void                fm_file_ops_job_emit_percent        (FmFileOpsJob *job);
    void                fm_file_ops_job_emit_prepared       (FmFileOpsJob *job);
    FmPath *            fm_file_ops_job_get_dest            (FmFileOpsJob *job);
    FmFileOpOption      fm_file_ops_job_get_options         (FmFileOpsJob *job);
    FmFileOpsJob *      fm_file_ops_job_new                 (FmFileOpType type,
                                                             FmPathList *files);
    void                fm_file_ops_job_set_chmod           (FmFileOpsJob *job,
                                                             mode_t new_mode,
                                                             mode_t new_mode_mask);
    void                fm_file_ops_job_set_chown           (FmFileOpsJob *job,
                                                             gint uid,
                                                             gint gid);
    void                fm_file_ops_job_set_dest            (FmFileOpsJob *job,
                                                             FmPath *dest);
    void                fm_file_ops_job_set_display_name    (FmFileOpsJob *job,
                                                             const char *name);
    void                fm_file_ops_job_set_hidden          (FmFileOpsJob *job,
                                                             gboolean hidden);
    void                fm_file_ops_job_set_icon            (FmFileOpsJob *job,
                                                             GIcon *icon);
    void                fm_file_ops_job_set_recursive       (FmFileOpsJob *job,
                                                             gboolean recursive);
    void                fm_file_ops_job_set_target          (FmFileOpsJob *job,
                                                             const char *url);

## Object Hierarchy

      GObject
       +----FmJob
             +----FmFileOpsJob

## Signals

      "ask-rename"                                     : Run Last
      "cur-file"                                       : Run First
      "percent"                                        : Run First
      "prepared"                                       : Run First

## Description

`include`: libfm/fm.h

The FmFileOpsJob can be used to do some file operation such as move, copy, delete, change file attributes, etc.

## Details

### FM_FILE_OPS_JOB_TYPE

    #define FM_FILE_OPS_JOB_TYPE                (fm_file_ops_job_get_type())

### enum FmFileOpOption

    typedef enum {
        FM_FILE_OP_CANCEL = 0,
        FM_FILE_OP_OVERWRITE = 1<<0,
        FM_FILE_OP_RENAME = 1<<1,
        FM_FILE_OP_SKIP = 1<<2,
        FM_FILE_OP_SKIP_ERROR = 1<<3
    } FmFileOpOption;

Operation selection on error.

`FM_FILE_OP_CANCEL` | cancel operation
`FM_FILE_OP_OVERWRITE` | overwrite existing file
`FM_FILE_OP_RENAME` | change name and continue
`FM_FILE_OP_SKIP` | skip this file
`FM_FILE_OP_SKIP_ERROR` | not supported

### enum FmFileOpType

    typedef enum {
        FM_FILE_OP_NONE,
        FM_FILE_OP_MOVE,
        FM_FILE_OP_COPY,
        FM_FILE_OP_TRASH,
        FM_FILE_OP_UNTRASH,
        FM_FILE_OP_DELETE,
        FM_FILE_OP_LINK,
        FM_FILE_OP_CHANGE_ATTR
    } FmFileOpType;

Operation for FmFileOpsJob

`FM_FILE_OP_NONE` | dummy
`FM_FILE_OP_MOVE` | move file
`FM_FILE_OP_COPY` | copy file
`FM_FILE_OP_TRASH` | move file to trash can
`FM_FILE_OP_UNTRASH` | restore file from trash can
`FM_FILE_OP_DELETE` | erase file
`FM_FILE_OP_LINK` | create symbolic link
`FM_FILE_OP_CHANGE_ATTR` | change file owner and attributes

### struct FmFileOpsJob

    struct FmFileOpsJob;

### struct FmFileOpsJobClass

    struct FmFileOpsJobClass {
        FmJobClass parent_class;
        void (*prepared)(FmFileOpsJob* job);
        void (*cur_file)(FmFileOpsJob* job, const char* file);
        void (*percent)(FmFileOpsJob* job, guint percent);
        FmFileOpOption (*ask_rename)(FmFileOpsJob* job, FmFileInfo* src, FmFileInfo* dest, char** new_name);
    };

FmJobClass `parent_class`; | the parent class
`prepared` () | the class closure for the "prepared" signal
`cur_file` () | the class closure for the "cur-file" signal
`percent` () | the class closure for the "percent" signal
`ask_rename` () | the class closure for the "ask-rename" signal

### fm_file_ops_job_ask_rename ()

    FmFileOpOption      fm_file_ops_job_ask_rename          (FmFileOpsJob *job,
                                                             GFile *src,
                                                             GFileInfo *src_inf,
                                                             GFile *dest,
                                                             GFile **new_dest);

Asks the user in main thread how to resolve conflict if file being copied or moved already exists in destination directory. Ask is done by emitting the "ask-rename" signal.

This API is private to FmFileOpsJob and should not be used outside of libfm implementation.

`job` : | a job which asked
`src` : | source file descriptor
`src_inf` : | source file information
`dest` : | destination descriptor
`new_dest` : | pointer to get new destination
Returns : | a decision how to resolve conflict.

Since 0.1.0

### fm_file_ops_job_emit_cur_file ()

    void                fm_file_ops_job_emit_cur_file       (FmFileOpsJob *job,
                                                             const char *cur_file);

Emits the "cur-file" signal in main thread.

This API is private to FmFileOpsJob and should not be used outside of libfm implementation.

`job` : | the job to emit signal
`cur_file` : | the data to emit

Since 0.1.0

### fm_file_ops_job_emit_percent ()

    void                fm_file_ops_job_emit_percent        (FmFileOpsJob *job);

Emits the "percent" signal in main thread.

This API is private to FmFileOpsJob and should not be used outside of libfm implementation.

`job` : | the job to emit signal

Since 0.1.0

### fm_file_ops_job_emit_prepared ()

    void                fm_file_ops_job_emit_prepared       (FmFileOpsJob *job);

Emits the "prepared" signal in main thread.

This API is private to FmFileOpsJob and should not be used outside of libfm implementation.

`job` : | the job to emit signal

Since 0.1.10

### fm_file_ops_job_get_dest ()

    FmPath *            fm_file_ops_job_get_dest            (FmFileOpsJob *job);

Retrieves the destination path for operation. If type of operation in not FM_FILE_OP_MOVE, FM_FILE_OP_COPY, or FM_FILE_OP_LINK then result of this call is undefined. The returned value is owned by `job` and should be not freed by caller.

`job` : | a job to inspect
Returns : | the FmPath which was set by previous call to `fm_file_ops_job_set_dest()`. [transfer none]

Since 0.1.0

### fm_file_ops_job_get_options ()

    FmFileOpOption      fm_file_ops_job_get_options         (FmFileOpsJob *job);

Retrieves bitmask set of options that are supported as return of the "ask-rename" signal handler.

`job` : | a job to set
Returns : | list of options.

Since 1.2.0

### fm_file_ops_job_new ()

    FmFileOpsJob *      fm_file_ops_job_new                 (FmFileOpType type,
                                                             FmPathList *files);

Creates new FmFileOpsJob which can be used in FmJob API.

`type` : | type of file operation the new job will handle
`files` : | list of source files to perform operation
Returns : | a new FmFileOpsJob object.

Since 0.1.0

### fm_file_ops_job_set_chmod ()

    void                fm_file_ops_job_set_chmod           (FmFileOpsJob *job,
                                                             mode_t new_mode,
                                                             mode_t new_mode_mask);

Sets that files for file operation FM_FILE_OP_CHANGE_ATTR should have file mode changed according to `new_mode_mask` and `new_mode`: bits that are present only in `new_mode_mask` will be set to 0, and bits that are present in both `new_mode_mask` and `new_mode` will be set to 1.

This API may be used only before `job` is started.

`job` : | a job to set
`new_mode` : | which bits of file mode should be set
`new_mode_mask` : | which bits of file mode should be reset

Since 0.1.0

### fm_file_ops_job_set_chown ()

    void                fm_file_ops_job_set_chown           (FmFileOpsJob *job,
                                                             gint uid,
                                                             gint gid);

Sets that files for file operation FM_FILE_OP_CHANGE_ATTR should have owner or group changed. If `uid` >= 0 then `job` will try to change owner of files. If `gid` >= 0 then `job` will try to change group of files.

This API may be used only before `job` is started.

`job` : | a job to set
`uid` : | user id to set as file owner
`gid` : | group id to set as file group

Since 0.1.0

### fm_file_ops_job_set_dest ()

    void                fm_file_ops_job_set_dest            (FmFileOpsJob *job,
                                                             FmPath *dest);

Sets destination path for operations FM_FILE_OP_MOVE, FM_FILE_OP_COPY, or FM_FILE_OP_LINK.

This API may be used only before `job` is started.

`job` : | a job to set
`dest` : | destination path

Since 0.1.0

### fm_file_ops_job_set_display_name ()

    void                fm_file_ops_job_set_display_name    (FmFileOpsJob *job,
                                                             const char *name);

Sets that file for file operation FM_FILE_OP_CHANGE_ATTR should have display name changed according to `name`. The job will fail if it will be started for more than one file or if file doesn't support display name change.

This API may be used only before `job` is started.

`job` : | a job to set
`name` : | new display name

Since 1.2.0

### fm_file_ops_job_set_hidden ()

    void                fm_file_ops_job_set_hidden          (FmFileOpsJob *job,
                                                             gboolean hidden);

Sets that files for file operation FM_FILE_OP_CHANGE_ATTR should have 'hidden' attribute changed according to value `hidden`. Error will be generated if some of the files doesn't support such change.

This API may be used only before `job` is started.

`job` : | a job to set
`hidden` : | new hidden attribute

Since 1.2.0

### fm_file_ops_job_set_icon ()

    void                fm_file_ops_job_set_icon            (FmFileOpsJob *job,
                                                             GIcon *icon);

Sets that files for file operation FM_FILE_OP_CHANGE_ATTR should have associated icon changed according to `icon`. Error will be generated if some of the files doesn't support icon change.

This API may be used only before `job` is started.

`job` : | a job to set
`icon` : | new icon

Since 1.2.0

### fm_file_ops_job_set_recursive ()

    void                fm_file_ops_job_set_recursive       (FmFileOpsJob *job,
                                                             gboolean recursive);

Sets 'recursive' attribute for file operation according to `recursive`. If `recursive` is `TRUE` then file operation `job` will try to do all operations recursively.

This API may be used only before `job` is started.

`job` : | a job to set
`recursive` : | recursion attribute to set

Since 0.1.0

### fm_file_ops_job_set_target ()

    void                fm_file_ops_job_set_target          (FmFileOpsJob *job,
                                                             const char *url);

Sets that shortcut file for file operation FM_FILE_OP_CHANGE_ATTR should have its target URL changed according to `url`. The job will fail if it will be started for more than one file or if file doesn't support target change.

This API may be used only before `job` is started.

`job` : | a job to set
`url` : | new URL for shortcut

Since 1.2.0

## Signal Details

### The `"ask-rename"` signal

    gint                user_function                      (FmFileOpsJob *job,
                                                            gpointer      src,
                                                            gpointer      dest,
                                                            gpointer      new_name,
                                                            gpointer      user_data)      : Run Last

The "ask-rename" signal is emitted when file operation raises a conflict because file with the same name already exists in the directory `dest`. Signal handler should find a decision how to resolve the situation. If there is more than one handler connected to the signal then only one of them will receive it. Implementations are expected to inspect supported options for the decision calling `fm_file_ops_job_get_options()`. Behavior when handler returns unsupported option is undefined.

`job` : | a job object which emitted the signal
`src` : | (FmFileInfo *) source file
`dest` : | (FmFileInfo *) destination directory
`new_name` : | (char **) pointer to receive new name
`user_data` : | user data set when the signal handler was connected.
Returns : | a FmFileOpOption decision.

Since 0.1.0

### The `"cur-file"` signal

    void                user_function                      (FmFileOpsJob *job,
                                                            gpointer      file,
                                                            gpointer      user_data)      : Run First

The "cur-file" signal is emitted when `job` is about to start operation on the `file`.

`job` : | a job object which emitted the signal
`file` : | (const char *) file which is processing
`user_data` : | user data set when the signal handler was connected.

Since 0.1.0

### The `"percent"` signal

    void                user_function                      (FmFileOpsJob *job,
                                                            guint         percent,
                                                            gpointer      user_data)      : Run First

The "percent" signal is emitted when one more file operation is completed.

`job` : | a job object which emitted the signal
`percent` : | current ratio of completed job size to full job size
`user_data` : | user data set when the signal handler was connected.

Since 0.1.0

### The `"prepared"` signal

    void                user_function                      (FmFileOpsJob *job,
                                                            gpointer      user_data)      : Run First

The "prepared" signal is emitted when preparation of the file operation is done and `job` is ready to start copying/deleting...

`job` : | a job object which emitted the signal
`user_data` : | user data set when the signal handler was connected.

Since 0.1.10