egroupware/phpgwapi/doc/vfs/vfs_functions.lyx
2001-06-23 08:30:14 +00:00

636 lines
14 KiB
Plaintext

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