TWIG 2.0 Code Specifications
March 13, 2000

FUTURE
======
    By structuring TWIG as an information framework, PHP can be extended to
    allow rapid application development and deployment that will be able to
    work within a highly integrated, mutli-user environment.

STRUCTURE
=========
    TWIG is designed to be highly and easily extended.  It does this by
    providing an application framework which allows "feature modules" to be
    plugged in and take full advantage of the overall API, authentication,
    session variable management, and virtualhosting configurability.

    The framework is provided by the main index.php file, which reads in the
    configuration files, function libraries, and feature modules.  The output
    is generally wrapped in a custom header and footer that the admin can
    define.

General File Conventions
========================

    Some general guidelines for file naming are as follows:

	- All files that php will parse must end in .php3 or .php
	- Files which are not top level php files but instead
	  are included for functions should end in .inc.php3 or .inc.php

    Where applicable all include file should use if( !$included[filename] ) 
    to  ensure that the same include file is not included more than once.

FILES AND DIRECTORIES
=====================

    index.php
	- Includes core library
	- Includes and parses config files
	- Initializes essential variables to defaults if not already set
	- Includes features/$feature/$feature.inc.php3
	- Authenticates user if necessary
	- Outputs HTML headers if necessary
	- Displays menu if necessary
	- Includes features/$feature/$feature.feature
	- Outputs HTML footers if necessary

    config/
	announcments.inc.php3
		- Site specific file displayed on the default page if it
		exists
	config.inc.php3
		- Basic configuration options
	dbconfig.inc.php3
		- Database configuration options
	defaults.inc.php3
		- Define the default preferences for the site
	footer.inc.php3
	header.inc.php3 
		- Site specific header and footer placed on every page
	images.inc.php3
		- Define IMG tags or text for images
	login.form.php3
		- Customizable template for form used in forms based login
		(to allow sites to easily create customized login screens)
	login.footer.inc.php3
		- footer for login.form
	login.header.inc.php3
		- header for login.form
	mailfooter.inc.php
		- Text to append to the footer of each mail message sent
		  from TWIG, this file does not have to exist
	mainmenu.inc.php3
		- defines the options that appear in the main menu
	newusergroups.inc.php3
		- acl groups to add new users to

	(header.inc.php3, footer.inc.php3, announcements.inc.php3, and 
	 login.form.php3 can all include HTML and PHP tags)

    docs/
	- Contains all documentation except the README file.
	
    docs/AdminManual
	- Contains an html administrative manual

    features/
	- Contains $feature/ for each major feature in TWIG (mail,
	schedule, contacts, etc.)
	- Contains files needed by every page, such as twig.header.inc.php3,
	twig.footer.inc.php3, and goto.inc.php3

    features/$feature/
	- Contains *.inc.php3 for $feature

	features/$feature/*.feature.php3
		- Defines functions used by all parts of that feature
		- Parses $action
		- Includes appropriate features/$feature/????.inc.php3 file

	features/$feature/$feature.inc.php3
		- Defines commonly used constants and functions for that feature
		to be included by index.php before anything else loads

	features/$feature/strings/$config[language].strings.php3
		- Defines $TWIGphrase[] array common to files in $feature.
		- Loaded directly from index.php before the feature is
		  included

	features/$feature/help/$config[language]/$topic.$subtopic.help.php3
		- Helpful information goes here

    features/shared/
	- Contains code shared by multiple features (such as listing and
	editing routines)

    features/prefs/modules
	- contains the prefs files for each feature

    images/
	- Images directory, overridable in config.inc.php3

    lib/
	- Contains files to be included by much of TWIG
	
    lib/auth
	- Contains the authentication systems that TWIG supports

    lib/db/
	- Contains the database specific include files
	$dbconfig["sqltype"].inc.php3

    lib/db/sqltxt
	- Contains files for the sqldbase support code

    lib/groups
	- Contains the group providers

    lib/ldap
	- Contains the ldap providers

    lib/login
	- Contains files for the various login storage systems

    lib/mail
	- Contains files for the mail providers

    lib/prevnext
 	- Contains the prev/next style code

    lib/security
	- Contains files for the various security providers

    lib/session
	- Contains files for the various sessions/context storage
	  systems

    lib/strings/$config[language].strings.php3
	- Defines $TWIGphrase[] array for phrases used by all of TWIG
	- $TWIGphrase[] phrases used in only one feature go into
	  features/$feature/strings/$config[language].strings.php3

    setup/
	- Contains twig.table.<sqltype> files and any setup scripts

    setup/Strings
	- contains three scripts:
		1. generate.strings.php3
		2. populate.strings.pl
		3. strings.layout.php3

	  1 is used to convert the files in setup/Strings/SourceFiles
	  in to the individual feature string files, which are outputed
	  to setup/Strings/Output.  See docs/languages.txt for more 
	  details on how to use this script.

	  2 is used to move the files from setup/Strings/Output to the
	  appropriate directories.

	  3 supports 1, by defining what strings are required for each
	  of the features.

    setup/Strings/Output
	- Where the output from generate.strings.php3 is stored, this
	  directory must be writable by the user the web server is 
	  running as.

    setup/Strings/SourceFiles
	- The string definitions for each language

    setup/upgrade/
	- Contains scripts to upgrade from the last major version
	  of TWIG

    setup/upgrade/Pre-1.0
	- Contains scripts to upgrade between previous versions of TWIG

    setup/upgrade/x.y.0
	- Contains scripts to upgrade between previous version of TWIG

GLOBAL VARIABLES
================
    $context[] 	= any information specific to the current page
    			$context["feature"] = which major TWIG feature is 
    					      being used
    			$context["action"]  = what command is being passed 
    					      to $feature.feature

    $config[] 	= array of configuration variables
    			$config["debug"] = specific element of $config[] 
    					   array which controls the
    					   level of debugging information 
    					   that is shown.  Setting
    					   $config["debug"] to 10 will show 
    					   all debugging info but break any
    					   Header() or SetCookie() calls, 
    					   which are required for
    					   authentication.  A setting of 9 
    					   will bypass debug messages which
    					   keep authentication from happening.  
    					   The default debuglevel for
    					   the debug function is 10.

			$config["defaults"][$feature][$item]
					   These items define the defaults used
					   throughout TWIG.

    $vhosts[] 	= array of configuration variables for virtual hosts

    $dbconfig[] = array of database configuration variables

    $disabled[] = array of disabled features, this has been replaced by the use
		  of the security functions except in a few specific areas.

    $login[] 	= array storing current username and password of user after 
		  they have been authenticated

    $session[] 	= array to store state.  There is also a session() function for
    		  creating the session string to use both GET and POST type 
		  forms.

    		  Current mailbox, current group, current sorting order, and 
		  current page in the mailbox view are some of the items for 
		  which $session[] is often used.

    $included[] = array of included files.  This should be used to make
    		  sure files are not included twice.

    $pagetitle	= title of the current page, set in $feature.inc.php3
    
FUNCTIONS
=========
    Here are a few functions that will be present that might be useful.

    TWIGPrintError( $string )
	- Outputs a string in the standard error format.

    TWIGDebugLevel( $level = 10 )
	- Returns TRUE if user or system debug level is >= $level and
	  FALSE otherwise.

    TWIGDebug( $string, $level = 10 )
	- Outputs $string if user or system debug level >= $level.
	- The debug function should be called madly.

    TWIGCheckAdmin( $username )
	- Checks to see if $username is an administrator of the current
	  TWIG installation.
    
    TWIGLink( $text, $feature, $action, $params, $linkparams, $sother, $cother )
	- Creates a hyperlink $text to the given $feature and $action with
	$params parameters.  It also adds the session information to the
	link after checking that none of that information is specified by
	$params.

	$linkparams can be used to add additional parameters to the link,
	for example you can add " target=_blank" to have a new window
	opened for the page.

	$sother and $cother pass through to TWIGSession() and TWIGContext(), as
	the $other parameter.

    TWIGMailto( $address, $fullname = $address )
	- Checks to see if you have rights to send an email in TWIG. If so,
	  returns a TWIGLink( ) to Compose Mail. If not, returns a link
	  to "mailto:$address".
	- $fullname is always used as the link text, unless it is not set, in
	  which case $address is used instead.

    TWIGImage( $image="", $alt="", $tip="", $border="0", $height="", $width="", $align="", $valign="" ) 
	- Creates an <IMG> html tag.
	- Does some sanity checking to make sure that the HTML output is valid.
	- Generates tooltips that are compatible with older HTML 3 browsers as
	  well as newer browsers that follow HTML 4 fairly strictly.
	- $tip will default to $alt unless you specifically want an HTML 4
	  style tooltip that's too long for an ordinary 'alt' property.
	- Arguments with the same name as properties of the IMG tag go right into
	  the HTML stream as the values for those properties, respectively.

    TWIGSession( $type="get", $other )
	- Outputs current session array in form appropriate for GET or
	POST style forms.
	- $other is a 2 dimensional array where:
		$other[0]["item"] is an entry in $session.
		$other[0]["value"] is the value for the above.
	  This allows for custom session types.

    TWIGContext( $type="get", $feature, $action, $other )
	- Outputs current context array in form appropriate for GET or
	POST style forms.
	- if $feature/$action are specified, outputs those instead of
	current context array.
	- $other is a 2 dimensional array where:
		$other[0]["item"] is an entry in $context.
		$other[0]["value"] is the value for the above.
	  This allows for custom context types.

    TWIGPrevNext( $currentlow, $total, $pagesize, $context, $linkoption, $displaytype="arrows" )
	- Displays previous/next buttons, arrows, menus, etc.

    GetPref( $prefname, $preftable, $default ) 
    PutPref( $prefname, $value, $preftable )
    	- Retrieves or stores a preference in a database
	- $prefname is the name of the preference
	- $preftable is the db table to retrieve from (should be one of 
	  $dbconfig[tablename])

    TWIGGenerateMenu( $contents, $menutype, $imagepage = "primary" )
	- takes a 2 dim. array ($contents) and generates a command bar
	  in a style
		- the first dim. of $contents is a number from 0 > x
		- the second dim contains the following items:
			"command"
			"desc"
			"action"
			"options"
			"target"
			"image"
	- $menutype allows for the menu to be generated in a given style:
		0 - traditional TWIG text
		1 - Drop Down List
		2 - Button Bar
		3 - traditional TWIG secondary bar
		4 - vertical bulleted list
		5 - tab list
		6 - Simple list
		7 - Button Bar without text
		8 - Button Bar #2
		9 - Button Bar without text #2
		10- TWIG primary with bullets
		11- TWIG secondary with bullets

	- $imagepath defines what set of images to load

    TWIGGenerateTable( $headers, $contents, $columns, $width = "100%", $align = "" )
	- takes an array $headers to display in the first line, this
	  can also be a 2 dim. array as follows:
		$header[]["header"] =  cell contents
		$header[]["bgcolor"] = background color of cell
		$header[]["colspan"] = number of columns to span
		$header[]["align"] = cell alignment
		$header[]["valign"] = vertical cell alignment
		$header[]["nowrap"] = don't wrap the cell
	- takes a 2 dim. array ($contents) and generates a table as follows:
		$contents[row][column] = cell contents
	  or this may be a 3 dim. array as follows:
		$contents[][]["contents"] = cell contents
		$contents[][]["bgcolor"] = background color of cell
		$contents[][]["colspan"] = number of columns to span
		$contents[][]["align"] = cell alignment
		$contents[][]["valign"] = vertical cell alignment
		$contents[][]["nowrap"] = don't wrap the cell
	- $columns is the total number of columns found in the table, this
	  is sometimes necessary if colspan is used in headers, if not it
	  can be left blank.
	- $width is the width of the table. The value may be a percentage or a
	  number of pixels, though pixels are *highly* discouraged.
	- $align is the alignment of the table. The value may be "left",
	  "right", or "center". It is recommended to be used only for
	  centering, however.

    TWIGGenerateTabs( $contents, $selected = -1 )
	- takes an array $contents and returns an html segment that
	  displays $contents in a "tab" format.
	- if $selected is specified and is >= 0 then that tab will be
	  displayed as selected.

    TWIGGenerateLeftRightOptions( &$left, &$right, $name, $lefthead, $righthead, $size = 5 )
    	- $name is the prefix to use for the following variables:
	    $name_left
	    $name_right
	    $name_orig_left
	    $name_orig_right
	- $lefthead is the title text for the left box
	- $righthead is the title text for the right box
	- $size is the vertical size of the boxes

    TWIGProcessLeftRightOptions( $name )
        - This function processes the form data from a LeftRightOptions
	  to update the variables based on how the user has rearranged
	  the form's contents
    	- $name is the prefix for the following variables:
	    $name_left
	    $name_right
	    $name_orig_left
	    $name_orig_right
	- the variables $name_left/right should not be operated upon, but
	  should simply be passed back into the GenerateLeftRightOptions for
	  the next page show
	- the variables $name_orig_left/right may be munged as desired. they
	  contain the current items on the left and on the right as updated by
	  this function

    TWIGLoadLanguageFile( $filepath, $filename, $lang )
	- loads a language file, if the desired language is not found
	  then an english version is loaded.
	- $filepath needs to have a trailing / on it

    TWIGdate( $format, $timestamp )
	- a replacement for PHP's date() function that translates day
	  and month names into the current language

    TWIGFindHTML( $string )
	- scans through string and finds any http:/ftp:/mailto: links (or
	  text that looks like one) and adds in the appropriate <a>'s.

    TWIGProcessGPCString( $string )
	- takes a $string that has been passed in to TWIG through a 
	  GET, POST or COOKIE and strips the added slashes if required

    TWIGProcessGPCtoSQL( $string )
	- takes a $string that has been passed in to TWIG through a 
	  GET, POST or COOKIE and converts it for use in a SQL statement

    TWIGBytesToText( $size = 0 )
	- Takes a $size and returns a string representing the number in 
	  bytes, k, mb, etc.

    TWIGExecuteServerCommands( $opencon, $CmdArray )

	Once a connection has been opened to a server on the desired port, this
	function will take a series of commands and execute them.

	$opencon is the connection handle to use.

	$CmdArray is a multi-dimensional array of the following format:
	
		$CmdArray[$i][0] = Command to write, empty command are not 
				   written but a response can be expected.
		$CmdArray[$i][1] = The response to expect back, empty 
				   responses are acceptable.  Partial
				   responses are matched against the first
				   part of the response and then returned.

	On success the function will TRUE, otherwise it will return the last 
	response from the server.

    TWIGPhrase( $phrase, $args = array() )
	
	This is the TWIG translation code, it takes a $phrase with various 
	argument (as %1...%7...) embedded and then translates the phrase,
	substitues the arguments and then returns the result.

	Example:

		TWIGPhrase( "This is %1 cool!", "totally" )

	Would return:

		In English: This is totally cool!
		In Spanish: I have no idea :) but it would still be cool ;)

	If no translation exists then the substitiution is done and the passed
	values are returned.

    TWIGSessionSet( $key, $val, $def=NULL, $nullok=FALSE )

	Sets a session key to a value:

		$key	- The key in $session[] to set
		$val	- The value to set $session[$key] to
		$def	- The default value to set to if $val is empty
		$nullok - Allow $val to be set to null, effectivly overriding 
			  the default value set

	This will return the value that $session[$key] was set to.

    TWIGDateSelector( $prefix, $year, $month, $day )

	This function generates an <option> list for a standard M/D/Y selector 
	group and use $year, $month and $day as the currently selected Y/M/D
	to display.

	$prefix is used to prefix the selectors name in the <select> tag, so
	if $prefix = "Main" then the <select> tag will look like:

	<select name="MainHour>

    TWIGTimeSelector( $prefix, $hour, $minute )

	This function generates an <option> list for a standard time selector
	using $hour and $minute as the currently selected time.

	$prefix is used to prefix the selectors name in the <select> tag, so
	if $prefix = "Main" then the <select> tag will look like:

	<select name="MainHour>




Security Functions
==================

    TWIG Version 2.0 introduced the concept of security providers.  These
    providers allowed more granularity in the access a user had to various
    parts of TWIG.

    At this time there are two security providers available for TWIG:

	- basic
	- advanced

    Basic emulates the functionality of TWIG 1 by using $disabled to define
    on a global scale what features are available.  Basic is the default
    security provider.

    Advanced introduces the concept of Access Control Lists (ACL's) to TWIG
    which allows for an admin to define either individuals or groups various
    access levels to the items in TWIG.  Unlike basic, advanced uses db tables
    to hold this information and additional steps are required to configure 
    it.

    One additional note should be made, there is a fundamental difference
    between the two providers; basic assumes everything is accessible unless 
    specifically disabled, advanced assumes nothing is accessible unless
    specifically enabled.

    TWIG's security system uses several security 'levels', they include; none,
    read, write, delete, sidadmin, owner, admin.  These levels are 'human' 
    readable however all of the security functions require the internal 
    representation of these items.  It is therefore required to call
    TWIGConvertAccess() on these.

    For example, to check to see if a user has read access on a sid, use the
    following function call:

	TWIGCheckACL( $login["username"], 2001, TWIGConvertAccess( "read" ) );

    As you have just seen the security systems share a common set of functions 
    that are used through out TWIG, these functions allow for TWIG to support
    multiple security providers without rewriting the code for each one.

    TWIGGenerateSID( $owner )
		
	Creates a unique SID for use in assigning security to an item and 
	assigns $owner as the owner of the SID.  If $owner is not defined
	then $login["username"] is used as the owner.

    TWIGCheckACL( $login["username"]/$group, $sid, $access )

	Check to see if $login['username"] or $group has $access to the 
	given $sid object.

    TWIGGetACL( $login["username"]/$group, $sid )

	Retrieve the access level for $login["username"]/$group for the given 
	$sid object.

    TWIGModifyACL( $login["username"]/$group, $sid )

	Build an HTML section for modifying  $sid as $login["username"]/$group.

    TWIGDisplayACL( $login["username"]/$group, $sid )

	Build an HTML section for displaying $sid as $login["username"]/$group.

    TWIGIsMemberOfACLGroup( $name, $groupname )

	Checks to see if $name is a member of $groupname.

    TWIGConvertAccess( $access )

	Converts an access type (name or number) in to the opposite.

    TWIGCreateACLGroup( $name, $groupname )

	Creates an ACL group ($groupname) with $name as the owner.

    TWIGDeleteACLGroup( $name, $groupname )

	Deletes an ACL group ($groupname), it checks to see if $name has 
	permissions before it is deleted.

	This function will delete the group and associated acl list entries.

    TWIGGetSID( $name )

	Retrieve a SID for the user/group $name.

    TWIGAddACLEntry( $user, $addname, $sid, $access )

	Add $addname to the $sid object with $access it checks to see if 
	$name has permissions to change	the acl before it is added.

    TWIGGetACLUsers()

	Get a list of current valid users in the system	and returns them as an
	array.

    TWIGGetACLGroups()

	Get a list of current valid groups in the system and returns them as 
	an array.

    TWIGGetACLGroupMembers( $group )

	Get a list of current members of a group and returns them as an array.
		
    TWIGAddACLGroupMember( $username, $usernametoadd, $groupname )

	Adds $usernametoadd to group $groupname as user $username.

    TWIGRemoveACLGroupMember( $username, $usernametoremove, $groupname )

	Removes $usernametoremove from group $groupname as user	$username.

    TWIGProcessACLModify()
	
	Processes information submitted by the form generated by TWIGModifyACL().  
	This should be called at the beginning of a page that uses TWIGModifyACL().

Group Functions
===============

    TWIG 2.0.3 removed the direct access to the groups functions from the code
    base and abstracted them to allow for new types of group functionality to be
    created.  To this end the groups abstraction layer consists of the following
    functions:

    TWIGGroupsCreateSQLGroupQuery( $username, $grouplist, $table="", $perms=0 )

	This function returns a sql query string (at least the WHERE portion 
	of it) that will select $username's items that are in the groups
	listed in $grouplist to which the user has at least $perms access
	(if the groups system supports access levels).  The optional $table
	parameter causes the query to be formatted as '$table.groupid' and
	'$table.username' rather than simply 'groupid' and 'username'.

    TWIGGroupsGetName( $gid ) 
	
	Given $gid this function will return the name of the group.

    TWIGGroupsMemberOf( $gid, $perms=0 ) 
	
	Given $gid this function will return true/false if $login["username"] is
	a member of $gid with at least $perms access (where permissions
	are supported).
	
    TWIGGroupsMembers( $gid, $perms=0 ) 
	
	Returns an array of all members of group $gid with $perms level
	access (where permissions are supported).

    TWIGGroupsMembership( $user, $perms=0 ) 
	
	Returns an array of all of which groups $user is a member with at
	least $perms access (where permissions are supported).
	
    TWIGGroupsSelect( $username = "", $gid = "" , $is_listoption = "", $perms=0) 
		
	Returns a string which contains a series of <option> tags that represent
	all groups $username belongs to.  $gid will select that group as the 
	currently selected group in the list.  

	If $is_listopiton is empty then the ALL group will be included in the
	list.

	If $perms are defined then only those groups to which the user has
	$perms access will be included.

    TWIGGroupsSelector( $Username = "", $GID = "", $IsListOption = "", $OptionName = "data_thisGroup", $GoName = "TWIGChangeGroup", $perms=0 )
	
	Returns a string that has a complete <form> section in it representing
	the current list of groups the user has access to.

	See TWIGGroupSelect() for the first three options.

	$OptionName can be passed in to define a nonstandard name for the 
	select tag.

	$GoName can be passed in to define a nonstandard name for the go
	input tag.

	$perms can be passed to restrict the list of groups to those to which
	the user has at least $perms access.

    $groupquery = "username='" . $login["username"] . "'";
	
	While not actually a function, this needs to be defined so that various
	select statements will function correctly.  Use of this variable
	has been depreciated, and it will likely be removed in future
	versions.

Database Functions
==================

    TWIG uses it's own database abstraction layer which allows it to be quickly
    ported to new db servers.  This layer provides basic functionality for 
    querying a SQL server and then manipulating the results.

    TWIGProcessSQLString( $string )

	This function takes a string returned from a SQL query and strips
	slashes (or anything else) as required.

    SQLString( $string ) 

	This function take a string and prepares it for use in a SQL query.

    createSqlDate( $year, $month, $day ) 

	This function returns a string used to store dates in the db.

    createSqlDateTime( $year, $month, $day, $hour, $min, $sec ) 

	This function returns a string used to store dates in the db.
 
    convertSQLTimetoUTime( $sqldate ) 

	This function converts the db's time/date structure in to a Unix time
	stamp.

    MakeInsertString( $data ) 

	This function takes an array $data and creates a partial insert query.

    MakeUpdateString( $data )

	This function takes an array $data and creates a partial update query.

    dbQuery( $statement ) 

	This function executes $statement on the sql server and returns the 
  	results.

    dbResult( $result, $i, $field ) 

	This function takes a $result returned by dbQuery and returns the value
	of $field on row $i.  

	NOTE: This function should not be used if you want to retrieve values
	      for more than on field on a row.  Instead use dbResultArray().

    dbNumRows( $result ) 
	
	This function returns the number of rows in $result.

    dbResultArray( $result, $i ) 

	This function returns an array of all fields in row $i of $result.

Authentication Functions
========================

    TWIG uses two 'levels' of auth providers:

	- front end
	- back end

    The front end provider is what the user sees, either a form or a standard
    http auth message.

    The back end providers actually do the work at authenticating what the 
    front end gets from the user.

    Front End Providers
    -------------------

	include( "lib/auth/" . $config["auth_provider"] . ".authpro.inc.php3" );

		The first thing that the front end providers need to do is to 
		include the back end providers, otherwise they will not be
		able to properly authenticate the user.

	TWIGLogout( $realm )

		This function will logout the user from the system, clearing 
		any stored information.

		This function should call exit and never return.

	TWIGAuth( $realm = "TWIG", $logout = "" ) 
		
		This function will pass the user/pass to the backend system
		and then store the credentials as required.

		This function should return FALSE when successful, otherwise
		it should call exit and end the script.

    Back End Providers
    ------------------

	TWIGCheckAuth( $mbox, $logout = "" )

		This function will check to see if $login["username"] has
		access to the system, passing in $logout will undo any
		access that was setup while logging in.

		$mbox is mostly passed in for historical reasons, it should
		not be used in any new auth providers.

		This function should return an array with two elements, the 
		first should be true/false based upon if the user has been
		auth'd or not.  The second should always be false (again for
		historical reasons).

Login Provider Functions
========================

    TWIG's login providers allow the admin to select where persistent
    login information is stored.  The login providers use the following
    functions:

    TWIGGetLogin() 

	This function will retrieve the login information from storage.

	This function should not return an array containing the username 
	and password elements.

    TWIGStoreLogin( $username, $password, $expire, $delete = 0 )

	This function will store the login information in to storage.

	$expire is the number of seconds after storage until the login 
	information should be considered invalid and deleted.

	If $delete is set then the login information should be deleted from
	storage and the user not allowed to login.

	This function should not return any value.

Session Provider Functions
==========================

    Like Login Providers, TWIG supports session providers to all the admin
    of the server to decide how they would like to store the session/context
    array's between page loads.  To accomplish this the following functions
    are defined:

    TWIGGetContext() 

	This function retrieves $context from storage.

	This function should return an array that contains all the elements
	from $context.

    TWIGGetSession() 

	This function retrieves $session from storage.

	This function should return an array that contains all the elements
	from $session.

    TWIGSession( $type = "get", $other = "" ) 

	This function modifies a copy of $session based upon entries in 
	$other and then	stores it.

	$type is defined as either "get" or "put" depending on the type of
	output required.

	$other is a multi-dimensional array as follows:

		$other[$i]["item"]	= session value to replace
		$other[$i]["value"]	= value to replace it with

    TWIGContext( $type = "get", $feature = "", $action = "", $other = "" )

	This function modifies a copy of $context based upon entries in 
	$other, $feature and $action and then stores it.

	$type is defined as either "get" or "put" depending on the type of
	output required.

	$feature is the feature that should be stored in $context.
	
	$action is the action that should be stored in $context.

	$other is a multi-dimensional array as follows:

		$other[$i]["item"]	= context value to replace/add
		$other[$i]["value"]	= value to replace/add


    TWIGCleanSession()

	This function cleans up any left over $session data that may be left
	in storage once the page has been completed.

    TWIGCleanContext()

	This function cleans up any left over $context data that may be left
	in storage once the page has been completed.
		
New List Functions
==================

    TWIG 2.1.0 introduced a major change in how the 'list' code functionality 
    worked.  Many of the various features of TWIG uses the list code (contacts,
    bookmarks, etc.) and the changes were designed to make the code more
    flexible.

    At this time all new features created should use the new list functions
    instead of the old list includes which will be phased out over the next
    several versions of TWIG.  Once all existing features have been migrated
    over the old list code will be removed.

    The new list functions are as follows:

    TWIGListHeader( $menu )

	This function builds the standard header found in all list based 
	functions, $menu is passed in to TWIGGenerateMenu() so that custom
	menu items can be created.

    TWIGListGenerateTable( $tableheaders, $tablecontents, $start = 1, $titems, $pagesize )

	This function is similar to TWIGGenerateTable() (see it's docs for the 
	description of the first two parameters).  

	$start defines what item to start the display with.

	$titems defines the total number of items in the list.

	$pagesize defines how many items to display on this page.

    TWIGListGetItem( $ItemID, $db="", $fields = "*", $GroupQuery="" )

	This function retrieves the columns $fields from table $db where the
	item's ID is $ItemID.

	$ItemID is the item to retrieve.

	$db is the table.  If none is passed $db defaults to
	$dbconfig["<feature>_table"].

	$fields is a comma separated string defining the columns to grap for
	the item.  This defaults to "*" or all columns.

	$GroupQuery is a SQL statement fragment defining a set of groups from
	which to pull the item.  This is generally not needed since the item's
	ID should be unique, but it has been preserved as an optional
	parameter to ensure compatibility with previous implementations.

    TWIGListItemHeader( $data, $viewtype="view", $menu="" )

	This function displays the standard header for viewing or editting an
	item.

	$data is an array of the gathered information for the item.

	$viewtype may be either "view" or "edit".  It defines whether the item
	is being viewed or editted.  If omitted, this defaults to "view".

	$menu is an array to be passed to TWIGGenerateMenu().  If omitted,
	the function will generate its own generic menu.

    TWIGListItemFooter( $data, $viewtype="view", $buttons="")

	This function displays the standard footer for viewing or editting an
	item.

	$data is an array of the gathered information for the item.

	$viewtype may be either "view" or "edit".  It defines whether the item
	is being viewed or editted.  If omitted, this defaults to "view".

	$buttons is a string defining the buttons to be placed at the bottom
	of the form when $viewtype="edit".  If omitted a default set of
	buttons is inserted (usually "Update" and "Delete" depending on
	permissions).

    TWIGListItemEditFormHeader( $edittype = "new", $menu, $ListDB, $ItemID, $GroupQuery )

	This legacy function displays the standard header when editing an item.
	However, it has now simply a wrapper for the TWIGListGetItem() and
	TWIGListItemHeader() functions.  It has been preserved for compatibility
	with previous applications, but will likely be removed in the future.

	$edittype is included for consistency with the footer call but is 
	not actually used.

	$menu is an array that is passed to TWIGGenerateMenu().

	$ListDB is the table name to use in queries.

	$ItemID is the item to edit.

	$GroupQuery is the current $groupquery string.

    TWIGListItemEditFormFooter( $edittype = "new", $menu, $ListDB, $ItemID, $GroupQuery )

	This legacy function displays the standard footer when editing an item.
	However, it has now simply a wrapper for the TWIGListGetItem() and
	TWIGListItemFooter() functions.  It has been preserved for compatibility
	with previous applications, but will likely be removed in the future.

	$edittype is used to determine if an add button or update/delete buttons
	are displayed.

	$menu is included for consistency with the header call but is 
	not actually used.

	$ListDB is the table name to use in queries.

	$ItemID is the item to edit.

	$GroupQuery is the current $groupquery string.
	

    TWIGListItemEditProcess( $action, $ListDB, $GroupQuery, $data, $destination = "" )

	This function processes any changes that are required after the
	edit form has been submitted, it should be included at the top 
	of the page that will process the edit form.

	$action can be any of the following:
		
		$TWIGphrase["Update"]
		$TWIGphrase["Delete"]
		$TWIGphrase["Add"]
		$TWIGphrase["Delete Selected"]
		$TWIGphrase["Move"]
		$TWIGphrase["Copy"]

	$ListDB is the table name to use in queries.

	$GroupQuery is the current $groupquery string.

	$data is an array, either submitted by the edit form or retrieved
	from a dbQuery() call.

	$destination is the group to move the items to if performing a move.

Mail Functions
==============

    The mail relay function are a little more low level to the system, but some
    programmers may find them useful.

    TWIG's mail functions changed between 2.2.3 and 2.3, 
    TWIGExecuteServerCommands() has been moved to the common.inc.php3, and
    TWIGMailRelay() has been replaced with a mail sending system provider 
    structure that loads an include that defines TWIGMailSendMessage()

    Additionally, all of the php defined mail functions (the imap_?() functions)
    have been wrapped with php functions to allow for the mail system to be 
    abstracted.

    Currently there are two providers available, the traditional imap provider
    and a pop3 provider.

    TWIGMailSendMessage( $server = "localhost", $port = "25", $to, $from, $domain, $header, $body ) 

	This function sends a message through the mail system.

	$server - defines what mail server to use during sending.
	$port   - defines the port to connect to.
	$to 	- is a list of users to send the message to.
	$from 	- is the e-mail address of the sender.
	$domain - is the default domain to append to $to addresses that are 
                  missing one.
	$header - the message headers.
	$body   - the message body.
	
	Currently only two providers are supported, the built in php mail() 
	function and the mail relay style code from previous version of TWIG.

    TWIGOpenMB( $mailbox, $oldmbox = FALSE) 

	This function opens a connection the the mail server, this function
	returns a handle to be used in the other mail functions.

	$mailbox - the mailbox to open.
	$oldmbox - a pointer to an open mailbox if one exists.

    TWIGCloseMB( $mbox )

	This function closes an open connection as opened by TWIGOpenMB().

    TWIGCheckNewMail( $mbox )

	This function checks to see if there is any new mail in the opened
	mailbox.

    TWIGGetMessageCount( $mbox )

	This function returns the number of messages in an open mailbox.

    MailboxEncode( $mb )

	This function encodes a text representation of a mailbox so that it
	is safe to pass it through a url.

    MailboxDecode( $mb, $strip = "" )

	This function decodes a string encoded by MailboxEncode().

    CheckMBType( $str )

	This function returns the type of mailbox represented by a string.

    TWIGMailFetchStructure()

	See imap_fetchstructure() in the php manual for details.

    TWIGMailFetchBody( $mailbox, $message, $section )

	See imap_fetchbody() in the php manual for details.
	
    TWIGMailBoxCheck( $mailbox )

	See imap_check() in the php manual for details.

    TWIGMailCopy( $mailbox, $message, $destination )

	See imap_mail_copy() in the php manual for details.

    TWIGMailMove( $mailbox, $message, $destination )

	See imap_mail_move() in the php manual for details.
		
    TWIGMailDelete( $mailbox, $item )

	See imap_delete() in the php manual for details.

    TWIGMailSubscribedFolders( $mailbox, $path, $filter )

	See imap_listsubscribed() in the php manual for details.

    TWIGMailEmptyTrash( $mailbox )

	See imap_expunge() in the php manual for details.

    TWIGMailGetSortedList( $mailbox, $sortedby, $sorteddirection )

	See imap_sort() in the php manual for details.

    TWIGMailCreateFolder( $mailbox, $folder )

   	See imap_createmailbox() in the php manual for details.

    TWIGMailSubscribeFolder( $mailbox, $folder )

	  See imap_subscribe() in the php manual for details.
	
    TWIGMailUnSubscribeFolder( $mailbox, $folder )

    	See imap_unsubscribe() in the php manual for details.

    TWIGMailDeleteFolder( $mailbox, $folder )

    	See imap_deletemailbox() in the php manual for details.

    TWIGMailRenameFolder( $mailbox, $folder, $newname )

	See imap_renamemailbox() in the php manual for details.

    TWIGMailFolderList( $mailbox, $startingfolder, $filter )

	See imap_listmailbox() in the php manual for details.

    TWIGMailFolderInfo( $mailbox )

	See imap_mailboxmsginfo() in the php manual for details.

    TWIGMailHeader( $mailbox, $message, $fromlength, $subjectlength, $defaultdomain )

	See imap_header() in the php manual for details.

    TWIGMailSetMessageFlag( $mailbox, $message, $flag )

	See imap_setflag_full() in the php manual for details.

    TWIGMailUnSetMessageFlag( $mailbox, $message, $flag )

	See imap_clearflag_full() in the php manual for details.

    TWIGMailAppendMessage( $mailbox, $folder, $message, $flags )

	See imap_append() in the php manual for details.

    TWIGMailUndelete( $mailbox, $message )

	See imap_undelete() in the php manual for details.

    TWIGMailFetchHeader( $mailbox, $message )

	See imap_fetchheader() in the php manual for details.

    TWIGMailParseAddresssList( $list, $defaultdomain )

	See imap_rfc822_parse_adrlist() in the php manual for details.

    TWIGMailDecodeBase64( $text )

	See imap_base64() in the php manual for details.

    TWIGMailGetFolderString( $server, $port, $type, $folder, $user = "", $pass = "" )

	Creates a folder string that represents a folder to be opened.

	$server - the server to connect to
	$port	- the port to connect to on the $server
	$type	- the folder type
	$folder - the folder name
	$user	- the user to open the folder as
	$pass	- the password to open the folder with

    TWIGMailParseFolderString( $FolderString )

	Parses a folder string created by TWIGMailGetFolderString() and returns
	an array of:

	array( $server, $port, $type, $folder, $user, $pass )

    TWIGMailGetDisplayName( $Folder )
	
	Parses a folder string and returns a text string to display to the user
	for use in lists etc.