FmFileOpsJob: Libfm Reference Manual

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

## Functions

FmFileOpOption | fm_file_ops_job_ask_rename ()
void | fm_file_ops_job_emit_cur_file ()
void | fm_file_ops_job_emit_percent ()
void | fm_file_ops_job_emit_prepared ()
FmPath * | fm_file_ops_job_get_dest ()
FmFileOpOption | fm_file_ops_job_get_options ()
FmFileOpsJob * | fm_file_ops_job_new ()
void | fm_file_ops_job_set_chmod ()
void | fm_file_ops_job_set_chown ()
void | fm_file_ops_job_set_dest ()
void | fm_file_ops_job_set_display_name ()
void | fm_file_ops_job_set_hidden ()
void | fm_file_ops_job_set_icon ()
void | fm_file_ops_job_set_recursive ()
void | fm_file_ops_job_set_target ()

## Signals

gint | ask-rename | Run Last
void | cur-file | Run First
void | percent | Run First
void | prepared | Run First

## Types and Values

#define | FM_FILE_OPS_JOB_TYPE
enum | FmFileOpOption
enum | FmFileOpType
struct | FmFileOpsJob
struct | FmFileOpsJobClass

## Object Hierarchy

        GObject
        ╰── FmJob
            ╰── FmFileOpsJob

## Description

`include` : libfm/fm.h

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

## Functions

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

Since: 1.2.0

## Types and Values

### FM_FILE_OPS_JOB_TYPE

    #define FM_FILE_OPS_JOB_TYPE                (fm_file_ops_job_get_type())

### enum FmFileOpOption

Operation selection on error.

#### Members

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

Operation for FmFileOpsJob

#### Members

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);
    };

#### Members

`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 |

## Signal Details

### The `“ask-rename”` signal

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

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.

#### Parameters

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.

Flags: Run Last

Since: 0.1.0

### The `“cur-file”` signal

    void
    user_function (FmFileOpsJob *job,
                   gpointer      file,
                   gpointer      user_data)

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

#### Parameters

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. |

Flags: Run First

Since: 0.1.0

### The `“percent”` signal

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

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

#### Parameters

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. |

Flags: Run First

Since: 0.1.0

### The `“prepared”` signal

    void
    user_function (FmFileOpsJob *job,
                   gpointer      user_data)

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

#### Parameters

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

Flags: Run First

Since: 0.1.10