[gthumb-list] FileData: the untold story

["Dr. Michael J. Chudobiak" <mjc avtechpulse com>]

Handling filenames correctly is surprisingly hard, and anyone who wants 
to hack on gThumb should read this to learn the "right way".

The basic problems are that filenames can be stored in a unescaped form 
or an escaped form, the filesystem may or may not be using UTF8, and 
some functions support remote schemes like "sftp://host/foo/bar"; and 
some expect "normal" paths like "/foo/bar".

There are quite a few bugs in gThumb 2.10.x relating to these issues, so 
a major goal of 2.11.x is to fix them.

Most file information in gThumb is accessed using the FileData struct, 
which has been expanded and improved in trunk. A new FileData is 
generated using:

fd = file_data_new (path)

The "path" argument is very forgiving - it will accept escaped or 
unescaped local paths and URIs.

The FileData struct contains SIX different representations of the 
filename! These are:


fd->path: This is the path argument passed to file_data_new, with 
"file://" prepended to paths with no scheme. This may or may not be in 
UTF8, and may or may not be escaped. Because of this uncertainty, IT 
SHOULD NOT BE USED in new code.

fd->name: This is a pointer to the last part of fd->path (the filename, 
with no directory names). For the same reasons as above, IT SHOULD NOT 
BE USED in new code.


fd->utf8_path: This is the full filename, guaranteed to be in UTF8 
format, and guaranteed to be understandable by gfile functions. Thus, 
this is is suitable for all display and most code use, except functions 
that only support local paths. This will always have a scheme.

fd->utf8_name: This is a pointer to the last part of fd->utf8_path (the 
filename, with no directory names). This is is suitable for all display 
and most code use.


fd->local_path: Most external libraries take a local path as an 
argument, and do not accept arguments with gfile/gnomevfs schemes (like 
"sftp://";). If the gvfs daemon is active, it creates a local mount point 
for these remote files under ~/.gvfs/. fd->local_path is what you should 
pass to these functions, after checking that this mount point exists* 
with file_data_has_local_path.


fd->uri: This is a symlink-resolved escaped URI. The only real use for 
this is for generating the names for shared thumbnails. DO NOT USE for 
anything else, unless there is a very good reason.


* If the gvfs daemon has not mounted the remote location, we normally 
abort the operation and provide an error message. In the future, we 
could modify file_data_has_local_path to add code to try to mount the 
remote point. This would be useful for situations where a remote URI has 
been bookmarked, for example.


Other wrinkles: If you pass a filename to a shell command, you may still 
need to perform shell escaping.


- Mike