Media Mover File Object

The Media Mover file object's data looks something like this:

$file->mmfid: integer, unique Media Mover file id 
$file->cid:  string, configuration id this file was created with
$file->step_order: integer, step this file is currently on
$file->source_uri string: string, file originally harvested, helpful for uniqueness checking
$file->uri: string, current path to file- whether the file that will be operated on next, or the final file produced by the configuration
$file->status: string,is this file locked, ready, finished,  error, or other. Custom statuses can be provided for additional workflow
$file->data: array, additional data (eg: files, steps, meta, node, user, etc) attached to the file
$file->passthrough: boolean, if you are programatically passing a file through Media Mover, use this to not save data to the database. You would use this if you create a custom module that you want to process files with but utilize Media Mover storage

Saving Files
You can create a new file with $file->save() if $file->mmfid is not set. Otherwise this will update the file. If $file->passthrough is set, the file will not be saved. NOTE $file->status is not saved on $file->save if the file is currently locked- meaning that Media Mover will not update a file which is owned by another process. It is only saved when $file->unlock() is called to keep files thread safe. Modules that need to modify the file before saving can use hook_media_mover_file_save($file)

$file->data[]
$file->data_get(), $file->data_set(), $file->data_remove() exist to assist you in adding additional data to the $file object. This stored data is persistent. You can also add data to a media mover file on load with hook_media_mover_file_load($file). You will need to handle saving data that does not use the data_get/set/delete methods

Operating On Files
Always check that $file->lock() was successful before performing any operation on a file. Once you are finished with your file, you can call $file->unlock() with a new $file->status

Deleting Files
You can use hook_media_mover_file_delete(&$file, &$step) to perform any additional file deletion operations. You should set $step->filepath to FALSE if your module uses files outside of the drupal installation after you have deleted them.

Loading Media Mover Files
By default, Media Mover files are loaded from a cache if the file exists in the cache. If you need to alter the file after it is loaded hook_media_mover_file_load() is called after the file is pulled from cache. You can always load a file without the cache with $file->load($mmfid, FALSE). You can tell if a file is loaded from cache by $file->cached == TRUE