egroupware/phpgwapi/doc/vfs/vfs_functions.sgml

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