NAME

fci.pl - file control interface for WIRM

SYNOPSIS

  require "fci.pl";

  # Most common methods shown here.  See METHODS for others.

  # import a file to a custom location
  open(FH $fname);
  file_import_custom($registered_id, FH, "P35/images/photo.gif");

  # import a file to a default location
  open(FH, $fname);
  file_import_default($registered_id, FH, "gif");

  # lookup the path of a file by id
  $fdest = file_path($registered_id2);

  $mime_type = file_mime_type($filename);

REQUIRES

wrm.pl

DESCRIPTION

The fci.pl API provides access to the internal File Storage Area (FSA). Files may be copied into the storage area from a filehandle, and file locations may be looked up based on file id. Other than file location, the fci.pl interface does not maintain any file metadata. That task is managed by the repository object interface (repo.pl), which builds an additional level of abstraction on top of fci.pl, allowing the CGI programmer to treat files as objects complete with metadata rather than just blobs in the file system.

CGI programmers will not normally access these functions directly. Instead, they should use repo_import_file, repo_register_file, etc. in repo.pl, or the higher-level file visualization methods in gateway.pl.

The FSA has two partitions: the Custom area and the Default area. In the Default area, files are assigned a location based on their file id (hashed across multiple directories to avoid the inefficiency of having thousands of files in a single directory). This frees the programmer from having to identify a unique name for every file registered in the system. In the Custom area, files are organized in human-readable paths defined by the programmer who submits the file. This allows the user to keep some metadata redundant in the file path, which allows files to be recognized without the accompanying metadata in the database.

Uses DBM file WRM_FSA_INDEX to associate File object IDs with file pathnames.

METHODS

file_import_custom($fid, $fh, $custom_dest)

Copies binary data from filehandle $fh into File Storage Area, using $custom_dest as the destination location, rooted in the FSA custom area. Saves the location in the WRM_FSA_INDEX dbm file. Returns FSA destination of imported file. Creates subdirs in custom FSA area as needed.

Returns 0 if import fails.

Parameter $fid will become the lookup key for retrieving the file contents, stored in WRM_FSA_INDEX. The $fid value should have been generated from repo_register_file (see repo.pl), which must be exectued BEFORE calling file_import.

file_import_default($fid, $fh, $ext)

Same as file_import_custom, except it imports file into a default location within the FSA, based on hashing the $id value. The file extension ($ext) must be supplied.

file_path($fid)

Returns the full path (location + filename) to the file with the specified $fid. Note: this is currently just a lookup in the WRM_FSA_INDEX dbm file, but the file_path function will allow this method to change transparently if necessary.

file_default_dir($fid)

Specifies the default location for a file with the specified $fid. Note that this does not necessarily mean that the file actually resides there.

file_bucket($fid)

Encapsulates the hash function for computing the default location of a file. This is currently the file id divided by the value $FILE_BUCKET_SIZE. This allows files to be distributed across multiple directories, rather than having one single directory containing all files, which would become inefficient in some file systems.

file_mime_type($filename)

Returns the mime-type of the named file (based on the explicit file extension). First looks for recognized mime type in the repository's custom mime directory, then looks for it in the standard mime directory. Both are specified in the CONFIG file.

AUTHOR