egroupware/phpgwapi/doc/vfs/vfs_functions.sgml
2001-06-20 08:16:13 +00:00

637 lines
12 KiB
Plaintext

<!doctype linuxdoc system>
<!-- LyX 1.1 created this file. For more info see http://www.lyx.org/ -->
<article>
<title>
VFS class functions
</title>
<author>
Jason Wies
</author>
<date>
June 2001
</date>
<abstract>
</abstract>
<sect>
VFS class functions
<sect1>
class vfs<label id="sec: class vfs" >
<p>
abstract: virtual file system
</p>
<p>
description: Authors: Zone, Seek3r
</p>
<sect1>
class path_class<label id="sec: class path_class" >
<p>
abstract: helper class for path_parts
</p>
<sect1>
vfs<label id="sec: vfs" >
<p>
abstract: constructor, sets up variables
</p>
<p>
<verb>
function vfs ()
</verb>
</p><sect1>
set_relative<label id="sec: set_relative" >
<p>
abstract: Set path relativity
</p>
<p>
param: &dollar;mask Relative bitmask (see RELATIVE_ defines)
</p>
<p>
<verb>
function set_relative (&dollar;mask)
</verb>
</p><sect1>
get_relative<label id="sec: get_relative" >
<p>
abstract: Return relativity bitmask
</p>
<p>
discussion: Returns relativity bitmask, or the default of &quot;completely
relative&quot; if unset
</p>
<p>
<verb>
function get_relative ()
</verb>
</p><sect1>
sanitize<label id="sec: sanitize" >
<p>
abstract: Removes leading .'s from &dollar;string
</p>
<p>
discussion: You should not pass all filenames through sanitize () unless
you plan on rejecting
</p>
<p>
.files. Instead, pass the name through securitycheck () first, and if
it fails,
</p>
<p>
pass it through sanitize
</p>
<p>
param: &dollar;string string to sanitize
</p>
<p>
result: &dollar;string without it's leading .'s
</p>
<p>
<verb>
function sanitize (&dollar;string)
</verb>
</p><sect1>
securitycheck<label id="sec: securitycheck" >
<p>
abstract: Security check function
</p>
<p>
discussion: Checks for basic violations such as ..
</p>
<p>
If securitycheck () fails, run your string through vfs-&gt;sanitize ()
</p>
<p>
param: &dollar;string string to check security of
</p>
<p>
result: Boolean True/False. True means secure, False means insecure
</p>
<p>
<verb>
function securitycheck (&dollar;string)
</verb>
</p><sect1>
db_clean<label id="sec: db_clean" >
<p>
abstract: Clean &dollar;string for use in database queries
</p>
<p>
param: &dollar;string String to clean
</p>
<p>
result: Cleaned version of &dollar;string
</p>
<p>
<verb>
function db_clean (&dollar;string)
</verb>
</p><sect1>
path_parts<label id="sec: path_parts" >
<p>
abstract: take a real or fake pathname and return an array of its component
parts
</p>
<p>
param: &dollar;string full real or fake path
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
param: &dollar;object True returns an object instead of an array
</p>
<p>
result: &dollar;rarray/&dollar;robject Array or object containing the fake
and real component parts of the path
</p>
<p>
discussion: Returned values are:
</p>
<p>
mask
</p>
<p>
outside
</p>
<p>
fake_full_path
</p>
<p>
fake_leading_dirs
</p>
<p>
fake_extra_path
</p>
<p>
fake_name
</p>
<p>
real_full_path
</p>
<p>
real_leading_dirs
</p>
<p>
real_extra_path
</p>
<p>
real_name
</p>
<p>
fake_full_path_clean
</p>
<p>
fake_leading_dirs_clean
</p>
<p>
fake_extra_path_clean
</p>
<p>
fake_name_clean
</p>
<p>
real_full_path_clean
</p>
<p>
real_leading_dirs_clean
</p>
<p>
real_extra_path_clean
</p>
<p>
real_name_clean
</p>
<p>
&quot;clean&quot; values are run through vfs-&gt;db_clean () and
</p>
<p>
are safe for use in SQL queries that use key='value'
</p>
<p>
They should be used ONLY for SQL queries, so are used
</p>
<p>
mostly internally
</p>
<p>
mask is either RELATIVE_NONE or RELATIVE_NONE|VFS_REAL,
</p>
<p>
and is used internally
</p>
<p>
outside is boolean, True if &dollar;relatives contains VFS_REAL
</p>
<p>
<verb>
function path_parts (&dollar;string, &dollar;relatives = array (RELATIVE_CURRENT), &dollar;object = True)
</verb>
</p><sect1>
getabsolutepath<label id="sec: getabsolutepath" >
<p>
abstract: get the absolute path
</p>
<p>
param: &dollar;target defaults to False, directory/file to get path of,
relative to &dollar;relatives&lsqb;0&rsqb;
</p>
<p>
param: &dollar;mask Relativity bitmask (see RELATIVE_ defines). RELATIVE_CURRENT
means use &dollar;this-&gt;relative
</p>
<p>
param: &dollar;fake Returns the &quot;fake&quot; path, ie /home/user/dir/file
(not always possible. use path_parts () instead)
</p>
<p>
result: &dollar;basedir Full fake or real path
</p>
<p>
<verb>
function getabsolutepath (&dollar;target = False, &dollar;relatives = array (RELATIVE_CURRENT), &dollar;fake = True)
</verb>
</p><sect1>
cd<label id="sec: cd" >
<p>
abstract: Change directory
</p>
<p>
discussion: To cd to the files root &quot;/&quot;, use cd (&quot;/&quot;,
False, array (RELATIVE_NONE));
</p>
<p>
param: &dollar;target default &quot;/&quot;. directory to cd into. if
&quot;/&quot; and &dollar;relative is True, uses &quot;/home/&lt;working_lid&gt;&quot;;
</p>
<p>
param: &dollar;relative default True/relative means add target to current
path, else pass &dollar;relative as mask to getabsolutepath()
</p>
<p>
<verb>
function cd (&dollar;target = &quot;/&quot;, &dollar;relative = True, &dollar;relatives = array (RELATIVE_CURRENT))
</verb>
</p><sect1>
pwd<label id="sec: pwd" >
<p>
abstract: current working dir
</p>
<p>
param: &dollar;full default True returns full fake path, else just the
extra dirs (false strips the leading /)
</p>
<p>
result: &dollar;currentdir currentdir
</p>
<p>
<verb>
function pwd (&dollar;full = True)
</verb>
</p><sect1>
read<label id="sec: read" >
<p>
abstract: return file contents
</p>
<p>
param: &dollar;file filename
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
result: &dollar;contents Contents of &dollar;file, or False if file cannot
be read
</p>
<p>
<verb>
function read (&dollar;file, &dollar;relatives = array (RELATIVE_CURRENT))
</verb>
</p><sect1>
write<label id="sec: write" >
<p>
abstract: write to a file
</p>
<p>
param: &dollar;file file name
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
param: &dollar;contents contents
</p>
<p>
result: Boolean True/False
</p>
<p>
<verb>
function write (&dollar;file, &dollar;relatives = array (RELATIVE_CURRENT), &dollar;contents)
</verb>
</p><sect1>
touch<label id="sec: touch" >
<p>
abstract: Create blank file &dollar;file or set the modification time and
modified by of &dollar;file to current time and user
</p>
<p>
param: &dollar;file File to touch or set modifies
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
result: Boolean True/False
</p>
<p>
<verb>
function touch (&dollar;file, &dollar;relatives = array (RELATIVE_CURRENT))
</verb>
</p><sect1>
cp<label id="sec: cp" >
<p>
abstract: copy file
</p>
<p>
param: &dollar;from from file/directory
</p>
<p>
param: &dollar;to to file/directory
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
result: boolean True/False
</p>
<p>
<verb>
function cp (&dollar;from, &dollar;to, &dollar;relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
</verb>
</p><sect1>
mv<label id="sec: mv" >
<p>
abstract: move file/directory
</p>
<p>
param: &dollar;from from file/directory
</p>
<p>
param: &dollar;to to file/directory
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
result: boolean True/False
</p>
<p>
<verb>
function mv (&dollar;from, &dollar;to, &dollar;relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
</verb>
</p><sect1>
move<label id="sec: move" >
<p>
abstract: shortcut to mv
</p>
<p>
<verb>
function move (&dollar;from, &dollar;to, &dollar;relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
</verb>
</p><sect1>
rm<label id="sec: rm" >
<p>
abstract: delete file/directory
</p>
<p>
param: &dollar;string file/directory to delete
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
result: boolean True/False
</p>
<p>
<verb>
function rm (&dollar;string, &dollar;relatives = array (RELATIVE_CURRENT))
</verb>
</p><sect1>
delete<label id="sec: delete" >
<p>
abstract: shortcut to rm
</p>
<p>
<verb>
function delete (&dollar;string, &dollar;relatives = array (RELATIVE_CURRENT))
</verb>
</p><sect1>
mkdir<label id="sec: mkdir" >
<p>
abstract: make a new directory
</p>
<p>
param: &dollar;dir Directory name
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
result: boolean True on success
</p>
<p>
<verb>
function mkdir (&dollar;dir, &dollar;relatives = array (RELATIVE_CURRENT))
</verb>
</p><sect1>
set_attributes<label id="sec: set_attributes" >
<p>
abstract: Update database entry for &dollar;file with the attributes in
&dollar;attributes
</p>
<p>
param: &dollar;file file/directory to update
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
param: &dollar;attributes keyed array of attributes. key is attribute
name, value is attribute value
</p>
<p>
result: Boolean True/False
</p>
<p>
discussion: Valid attributes are:
</p>
<p>
owner_id
</p>
<p>
createdby_id
</p>
<p>
modifiedby_id
</p>
<p>
created
</p>
<p>
modified
</p>
<p>
size
</p>
<p>
mime_type
</p>
<p>
deleteable
</p>
<p>
comment
</p>
<p>
app
</p>
<p>
<verb>
function set_attributes (&dollar;file, &dollar;relatives = array (RELATIVE_CURRENT), &dollar;attributes = array ())
</verb>
</p><sect1>
correct_attributes<label id="sec: correct_attributes" >
<p>
abstract: Set the correct attributes for &dollar;string (e.g. owner)
</p>
<p>
param: &dollar;string File/directory to correct attributes of
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
result: Boolean True/False
</p>
<p>
<verb>
function correct_attributes (&dollar;string, &dollar;relatives = array (RELATIVE_CURRENT))
</verb>
</p><sect1>
file_type<label id="sec: file_type" >
<p>
abstract: return file/dir type (MIME or other)
</p>
<p>
param: &dollar;file File or directory path (/home/user/dir/dir2/dir3, /home/user/dir/dir2/file)
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
result: MIME type, &quot;Directory&quot;, or nothing if MIME type is not
known
</p>
<p>
<verb>
function file_type (&dollar;file, &dollar;relatives = array (RELATIVE_CURRENT))
</verb>
</p><sect1>
file_exists<label id="sec: file_exists" >
<p>
abstract: check if file/directory exists
</p>
<p>
param: &dollar;string file/directory to check existance of
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
result: Boolean True/False
</p>
<p>
<verb>
function file_exists (&dollar;string, &dollar;relatives = array (RELATIVE_CURRENT))
</verb>
</p><sect1>
checkperms<label id="sec: checkperms" >
<p>
abstract: Check if you have write access to create files in &dollar;dir
</p>
<p>
discussion: This isn't perfect, because vfs-&gt;touch () returns True even
</p>
<p>
if only the database entry worked. ACLs need to be
</p>
<p>
implemented for better permission checking. It's
</p>
<p>
also pretty slow, so I wouldn't recommend using it
</p>
<p>
often
</p>
<p>
param: &dollar;dir Directory to check access of
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
result: Boolean True/False
</p>
<p>
<verb>
function checkperms (&dollar;dir, &dollar;relatives = array (RELATIVE_CURRENT))
</verb>
</p><sect1>
ls<label id="sec: ls" >
<p>
abstract: get directory listing
</p>
<p>
discussion: Note: the entries are not guaranteed to be returned in any
logical order
</p>
<p>
param: &dollar;dir Directory
</p>
<p>
param: &dollar;relatives Relativity array
</p>
<p>
param: &dollar;checksubdirs Boolean, recursively list all sub directories
as well?
</p>
<p>
param: &dollar;mime_type Only return entries matching MIME-type &dollar;mime_type.
Can be &quot;Directory&quot; or &quot;&bsol;&quot; for those without MIME
types
</p>
<p>
param: &dollar;nofiles Boolean. True means you want to return just the
information about the directory &dollar;dir. If &dollar;dir is a file, &dollar;nofiles
is implied. This is the equivalent of 'ls -ld &dollar;dir'
</p>
<p>
result: array of arrays. Subarrays contain full info for each file/dir.
</p>
<p>
<verb>
function ls (&dollar;dir = False, &dollar;relatives = array (RELATIVE_CURRENT), &dollar;checksubdirs = True, &dollar;mime_type = False, &dollar;nofiles = False)
</verb>
</p><sect1>
dir<label id="sec: dir" >
<p>
abstract: shortcut to ls
</p>
<p>
<verb>
function dir (&dollar;dir = False, &dollar;relatives = array (RELATIVE_CURRENT), &dollar;checksubdirs = True, &dollar;mime_type = False, &dollar;nofiles = False)
</verb>
</article>