- fixed a few bugs

- added user_add() function - check posted images ([img]) for same domain/scipt and php files - auth_api.html updated to the coding guidelines look&feel - introduced ability to force non page-updates (cron is using it) - correctly resend coppa email git-svn-id: file:///svn/phpbb/trunk@6048 89ea8834-ac86-4346-8a33-228a782c2dd0
author: Meik Sievertsen <acydburn@phpbb.com> 2006-06-11 18:13:52 +0000
committer: Meik Sievertsen <acydburn@phpbb.com> 2006-06-11 18:13:52 +0000
commit: 01b41453812dc7b990f03b81f85dcfb9a18076fd (patch)
tree: d12e93524fa7625d1220088d34a5a957cd618624 /phpBB/docs/auth_api.html
parent: ce3b07eee7dbefc68dcd8eab3ab667e6532c8561 (diff)
download: forums-01b41453812dc7b990f03b81f85dcfb9a18076fd.tar
forums-01b41453812dc7b990f03b81f85dcfb9a18076fd.tar.gz
forums-01b41453812dc7b990f03b81f85dcfb9a18076fd.tar.bz2
forums-01b41453812dc7b990f03b81f85dcfb9a18076fd.tar.xz
forums-01b41453812dc7b990f03b81f85dcfb9a18076fd.zip
1 files changed, 316 insertions, 54 deletions
diff --git a/phpBB/docs/auth_api.html b/phpBB/docs/auth_api.html
index aa47d2c49a..edf23350ae 100644
--- a/phpBB/docs/auth_api.html
+++ b/phpBB/docs/auth_api.html
@@ -1,110 +1,372 @@
-<html>
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
-<link rel="stylesheet" href="../styles/subSilver/theme/stylesheet.css" type="text/css" />
+<title>Auth API</title>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<meta name="resource-type" content="document" />
+<meta name="description" lang="en" content="Olympus coding guidelines document" />
+<meta name="keywords" lang="en" content="" />
+<meta name="author" content="phpBB Group" />
+<meta name="copyright" content="phpBB Group" />
+<meta name="MSSmartTagsPreventParsing" content="true" />
+<link rel="shortcut icon" href="" />
+
 <style type="text/css">
 <!--
-p {font-size:125%;}
-pre {font-size:125%;line-height:150%;}
-h2 {font-size:175%;color:red;padding-top:4px;}
-h3 {font-size:150%;color:blue;padding-top:4px;}
-p {padding-top:4px;padding-bottom:4px;}
+
+/*
+	    The original "subSilver" theme for phpBB2
+	Created by subBlue design :: http://www.subBlue.com
+*/
+
+body {
+	background-color:	white;
+	font-family:		Verdana, Arial, Helvetica, sans-serif;
+	margin:				0px;
+	border:				0px;
+	padding:			0px;
+}
+
+img {
+	border: 0;
+}
+
+p {
+	font-size:	8pt;
+}
+
+hr { 
+	height: 0px; 
+	border: solid #D1D7DC 0px; 
+	border-top-width: 1px;
+}
+
+#title, h1 {
+	font: bold 18pt 'Trebuchet MS', Verdana, sans-serif;
+	text-decoration: none; 
+	line-height: 120%; 
+}
+
+h2 {
+	font: bold 12pt Arial, Helvetica, sans-serif;
+	text-decoration: none; 
+	line-height: 120%; 
+}
+
+h3 {
+	font: bold 10pt Arial, Helvetica, sans-serif;
+	text-decoration: none; 
+	line-height: 120%; 
+}
+
+.paragraph {
+	margin-left: 20px;
+}
+
+/* 
+	Structure 
+*/
+#logo {
+	background: #fff url(header_bg.jpg) repeat-x top right;
+	height: 60px;
+}
+
+#title {
+	color: #12749b;
+	float: right;
+	margin: 10px 10px 0;
+}
+
+#main {
+	margin-left: 25px;
+	margin-right: 25px;
+}
+
+.good {
+	color: green;
+}
+
+.bad {
+	color: red;
+}
+
+#footer {
+	margin-left: 75px;
+	font-size: 70%;
+	color: #006600;
+}
+
+code { 
+	color: #006600; 
+	font-weight: normal; 
+	font-family: 'Courier New', monospace; 
+	border-color: #D1D7DC; 
+	border-width: 1px; 
+	border-style: solid; 
+	background-color: #FAFAFA; 
+}
+
+.indent p {
+	padding-left: 20px;
+	font-size: 90%;
+}
+
+/*
+	Anchors
+*/
+a {
+	font-size: 70%;
+}
+
+a:link, a:active, a:visited {
+	color:	#006699;
+	text-decoration:	none;
+}
+
+a:hover {
+	color:				#DD6900;
+	text-decoration:	underline;
+}
+
+a.nav {
+	color:				#006699;
+	text-decoration:	none;
+}
+
+a.nav:hover {
+	text-decoration:	underline;
+}
+
+p a {
+	font-size: 100%;
+}
+
+.menu {
+	font-size: 80%;
+}
+
+.menu li a {
+	font-size: 100%;
+}
 //-->
 </style>
+
+<!--[if IE]>
+<style type="text/css">
+body {
+	scrollbar-face-color:		#DEE3E7;
+	scrollbar-highlight-color:	white;
+	scrollbar-shadow-color:		#DEE3E7;
+	scrollbar-3dlight-color:	#D1D7DC;
+	scrollbar-arrow-color:		#006699;
+	scrollbar-track-color:		#EFEFEF;
+	scrollbar-darkshadow-color: #98AAB1;
+}
+</style>
+<![endif]-->
+
 </head>
 
 <body>
-<a name="top"></a>
-<div id="wrapcentre">
 
-<h1>Using the <i><u>auth</u></i> class</h1>
+<div id="logo">
+	<div id="title">Auth API</div>
+	<a href="index.php"><img src="header_left.jpg" alt="phpBB Logo" /></a>
+</div>
+
+<a name="top"></a><div id="main">
+
+<p>This is an explanation of how to use the phpBB auth/acl API. This document is (c) 2006 phpBB Group, copying or redistribution is not allowed without permission.</p>
+
+<h1>Auth API</h1>
+
+<ol class="menu">
+	<li><a href="#intro">Introduction</a></li>
+	<li><a href="#methods">Methods</a>
+	<ol type="i">
+		<li><a href="#acl">acl</a></li>
+		<li><a href="#acl_get">acl_get</a></li>
+		<li><a href="#acl_gets">acl_gets</a></li>
+		<li><a href="#acl_getf">acl_getf</a></li>
+		<li><a href="#acl_getf_global">acl_getf_global</a></li>
+		<li><a href="#acl_cache">acl_cache</a></li>
+	</ol>
+	</li>
+	<li><a href="#admin_related">Admin related functions</a></li>
+</ol>
+
+<hr />
+
+<a name="intro"></a><h1>1. Introduction</h1>
+
+	<div class="paragraph">
+
+	<h3>What is it?</h3>
+
+	<p>The <code>auth</code> class contains methods related to authorisation users to access various board functions, e.g. posting, viewing, replying, logging in (and out), etc. If you need to check whether a user can carry out a task or handle user login/logouts this class is required.</p>
 
-<h2>What is it?</h2>
+	<h3>Initialisation</h3>
 
-<p>The <i><u>auth</u></i> class contains methods related to authorisation users to access various board functions, e.g. posting, viewing, replying, logging in (and out), etc. If you need to check whether a user can carry out a task or handle user login/logouts this class is required.</p>
+	<p>To use any methods contained with the <code>auth</code> class it first needs to be instantiated. This is best achieved early in the execution of the script in the following manner:</p>
 
-<h2>Initialisation</h2>
+	<blockquote><pre>
+$auth = new auth();
+	</pre></blockquote>
 
-<p>To use any methods contained with the <i><u>auth</u></i> class it first needs to be instantiated. This is best achieved early in the execution of the script in the following manner:
+	<p>Once an instance of the class has been created you are free to call the various methods it contains. Please note that should you wish to use the <code>auth_admin</code> methods you will need to instantiate this seperately but in the same way.</p>
 
-<pre>$auth = new auth();</pre>
+	</div>
+	<a href="#top">Top</a>
+	<br /><br />
 
-<p>Once an instance of the class has been created you are free to call the various methods it contains. Please note that should you wish to use the <i><u>auth_admin</u></i> methods you will need to instantiate this seperately but in the same way.</p>
+<hr />
 
-<h3><i>acl</i></h3>
+<a name="methods"></a><h1>2. Methods</h1>
 
-<p>The <i>acl</i> method is the initialisation routine for all the acl functions. If you intend calling any acl method you must first call this. The method takes as its one and only required parameter an associative array containing user information as stored in the database. This array must contain at least the following information; user_id, user_permissions and user_type. It is called in the following way:
+	<p>Following are the methods you are able to use.</p>
 
-<pre>$auth->acl(<i>userdata</i>);</pre>
+	<a name="acl"></a><b>2.i. acl</b>
+	<br /><br />
+	<div class="paragraph">
+	
+	<p>The <code>acl</code> method is the initialisation routine for all the acl functions. If you intend calling any acl method you must first call this. The method takes as its one and only required parameter an associative array containing user information as stored in the database. This array must contain at least the following information; user_id, user_permissions and user_type. It is called in the following way:</p>
 
-<p>Where userdata is the array containing the aforementioned data.</p>
+	<blockquote><pre>
+$auth->acl(<code>userdata</code>);
+	</pre></blockquote>
 
-<h3><i>acl_get</i></h3>
+	<p>Where userdata is the array containing the aforementioned data.</p>
 
-<p>This method is the primary way of determining what a user can and cannot do for a given option globally or in a given forum. The method should be called in the following way:</p>
+	</div>
+	<a href="#top">Top</a>
+	<br /><br />
 
-<pre>$result = $auth->acl_get(<i>option</i>[, <i>forum</i>]);</pre>
 
-<p>Where option is a string representing the required option, e.g. 'f_list', 'm_edit', 'a_adduser', etc. By adding a ! in front of the option, e.g. '!f_list' the result of this method will be negated. The optional forum term is the integer forum_id.</p>
+	<a name="acl_get"></a><b>2.ii. acl_get</b>
+	<br /><br />
+	<div class="paragraph">
 
-<p>The method returns a positive integer when the user is allowed to carry out the option and a zero if denied or the other way around if the option is prefixed with an exclamation mark.</p>
+	<p>This method is the primary way of determining what a user can and cannot do for a given option globally or in a given forum. The method should be called in the following way:</p>
 
-<p>If you specify a forum and there is also a global setting for the specified option then this method will return a positive integer if one of them evaluates to a positive integer. An example would be the m_approve option which can be set per forum but also globally. If a user has the global option he will automatically have m_approve in every forum.</p>
+	<blockquote><pre>
+$result = $auth->acl_get(<code>option</code>[, <code>forum</code>]);
+	</pre></blockquote>
 
-<p>There are some special options or <i>flags</i> which are used as prefixes for other options, e.g. 'f_' or 'm_'. These flags will automatically be set to a positive integer if the user has one or more permissions with the given prefix. A local setting will result in the flag being set only locally (so it will require a forum id to retrieve). If a user has one or more global permissions with the prefix acl_get will return a positive integer regardless of the forum id.</p>
+	<p>Where option is a string representing the required option, e.g. 'f_list', 'm_edit', 'a_adduser', etc. By adding a ! in front of the option, e.g. '!f_list' the result of this method will be negated. The optional forum term is the integer forum_id.</p>
 
-<h3><i>acl_gets</i></h3>
+	<p>The method returns a positive integer when the user is allowed to carry out the option and a zero if denied or the other way around if the option is prefixed with an exclamation mark.</p>
 
-<p>This method is funtionally similar to <i>acl_get</i> in that it returns information on whether a user can or cannot carry out a given task. The difference here is the ability to test several different options in one go. This may be useful for testing whether a user is a moderator or an admin in one call. Rather than having to call and check <i>acl_get</i> twice.</p>
+	<p>If you specify a forum and there is also a global setting for the specified option then this method will return a positive integer if one of them evaluates to a positive integer. An example would be the m_approve option which can be set per forum but also globally. If a user has the global option he will automatically have m_approve in every forum.</p>
 
-<p>The method should be called thus:</p>
+	<p>There are some special options or <em>flags</em> which are used as prefixes for other options, e.g. 'f_' or 'm_'. These flags will automatically be set to a positive integer if the user has one or more permissions with the given prefix. A local setting will result in the flag being set only locally (so it will require a forum id to retrieve). If a user has one or more global permissions with the prefix acl_get will return a positive integer regardless of the forum id.</p>
 
-<pre>$result = $auth->acl_gets(<i>option1</i>[, <i>option2</i>, ..., <i>optionN</i>, <i>forum</i>]);</pre>
+	</div>
+	<a href="#top">Top</a>
+	<br /><br />
 
-<p>As with the <i>acl_get</i> method the options are strings representing the required permissions to check. The forum again is an integer representing a given forum_id.</p>
 
-<p>The method will return a positive integer if acl_get for one of the options evaluates to a positive integer (combines permissions with OR).</p>
+	<a name="acl_gets"></a><b>2.iii. acl_gets</b>
+	<br /><br />
+	<div class="paragraph">
 
-<h3><i>acl_getf</i></h3>
+	<p>This method is funtionally similar to <code>acl_get</code> in that it returns information on whether a user can or cannot carry out a given task. The difference here is the ability to test several different options in one go. This may be useful for testing whether a user is a moderator or an admin in one call. Rather than having to call and check <code>acl_get</code> twice.</p>
 
-<p>This method is used to find out in which forums a user is allowed to carry out an operation or to find out in which forums he is not allowed to carry out an operation. The method should be called in the following way:</p>
+	<p>The method should be called thus:</p>
 
-<pre>$result = $auth->acl_getf(<i>option</i>[, <i>clean</i>])</pre>
+	<blockquote><pre>
+$result = $auth->acl_gets(<code>option1</code>[, <code>option2</code>, ..., <code>optionN</code>, <code>forum</code>]);
+	</pre></blockquote>
 
-<p>Just like in the <i>acl_get</i> method the option is a string specifying the permission which has to be checked (negation using ! is allowed). The second parameter is a boolean. If it is set to false this method returns all forums with either zero or a positive integer. If it is set to true only those forums with a positive integer as the result will be returned.</p>
+	<p>As with the <code>acl_get</code> method the options are strings representing the required permissions to check. The forum again is an integer representing a given forum_id.</p>
 
-<p>The method returns an associative array of the form:</p>
+	<p>The method will return a positive integer if <code>acl_get</code> for one of the options evaluates to a positive integer (combines permissions with OR).</p>
 
-<pre>array(<i>forum_id1</i> => array(<i>option</i> => <i>integer</i>), <i>forum_id2</i> => ...)</pre>
+	</div>
+	<a href="#top">Top</a>
+	<br /><br />
 
-<p>Where option is the option passed to the method and integer is either zero or a positive integer and the same <i>acl_get(option, forum_id)</i> would return.</p>
 
-<h3><i>acl_getf_global</i></h3>
+	<a name="acl_getf"></a><b>2.iv. acl_getf</b>
+	<br /><br />
+	<div class="paragraph">
 
-<p>This method is used to find out whether a user has a permission in at least one forum or globally. This method is similar to checking whether <i>acl_getf(option, true)</i> returned one or more forums but it's faster. It should be called in the following way:</p>
+	<p>This method is used to find out in which forums a user is allowed to carry out an operation or to find out in which forums he is not allowed to carry out an operation. The method should be called in the following way:</p>
 
-<pre>$result = acl_getf_global(<i>option</i>)</pre>
+	<blockquote><pre>
+$result = $auth->acl_getf(<code>option</code>[, <code>clean</code>]);
+	</pre></blockquote>
 
-<p>As with the previous methods option is a string specifying the permission which has to be checked.</p>
+	<p>Just like in the <code>acl_get</code> method the option is a string specifying the permission which has to be checked (negation using ! is allowed). The second parameter is a boolean. If it is set to false this method returns all forums with either zero or a positive integer. If it is set to true only those forums with a positive integer as the result will be returned.</p>
 
-<p>This method returns either zero or a positive integer.</p>
+	<p>The method returns an associative array of the form:</p>
 
-<h3><i>acl_cache</i></h3>
+	<blockquote><pre>
+array(<em>forum_id1</em> => array(<em>option</em> => <em>integer</em>), <em>forum_id2</em> => ...)
+	</pre></blockquote>
 
-<p>This should be considered a private method and not be called externally. It handles the generation of the user_permissions data from the basic user and group authorisation data. When necessary this method is called automatically by <i>acl</i>.</p>
+	<p>Where option is the option passed to the method and integer is either zero or a positive integer and the same <code>acl_get(option, forum_id)</code> would return.</p>
 
-<p></p>
+	</div>
+	<a href="#top">Top</a>
+	<br /><br />
 
-<h2>Admin related functions</h2>
 
-<p>A number of additional methods are available related to <i><u>auth</u></i>. These handle more basic functions such as adding user and group permissions, new options and clearing the user cache. These methods are contained within a seperate class, <i><u>auth_admin</u></i>. This can be found in includes/acp/auth.php.</p>
+	<a name="acl_getf_global"></a><b>2.v. acl_getf_global</b>
+	<br /><br />
+	<div class="paragraph">
 
-<p>To use any methods this class contains it first needs to be instantiated seperately from <i><u>auth</u></i>. This is achieved in the same way as <i><u>auth</u></i>:</p>
+	<p>This method is used to find out whether a user has a permission in at least one forum or globally. This method is similar to checking whether <code>acl_getf(option, true)</code> returned one or more forums but it's faster. It should be called in the following way:</p>
 
-<pre>$authadmin = new auth_admin();</pre>
+	<blockquote><pre>
+$result = acl_getf_global(<code>option</code>)
+	</pre></blockquote>
 
-<p>This instance gives you access to both the methods of this specific class and that of <i><u>auth</u></i>.</p>
+	<p>As with the previous methods option is a string specifying the permission which has to be checked.</p>
+
+	<p>This method returns either zero or a positive integer.</p>
+
+	</div>
+	<a href="#top">Top</a>
+	<br /><br />
+
+
+	<a name="acl_cache"></a><b>2.vi. acl_cache</b>
+	<br /><br />
+	<div class="paragraph">
+
+	<p>This should be considered a private method and not be called externally. It handles the generation of the user_permissions data from the basic user and group authorisation data. When necessary this method is called automatically by <code>acl</code>.</p>
+
+	</div>
+	<a href="#top">Top</a>
+	<br /><br />
+
+<hr />
+
+<a name="admin_related"></a><h1>3. Admin related functions</h1>
+
+	<div class="paragraph">
+
+	<p>A number of additional methods are available related to <code>auth</code>. These handle more basic functions such as adding user and group permissions, new options and clearing the user cache. These methods are contained within a seperate class, <code>auth_admin</code>. This can be found in <code>includes/acp/auth.php</code>.</p>
+
+	<p>To use any methods this class contains it first needs to be instantiated seperately from <code>auth</code>. This is achieved in the same way as <code>auth</code>:</p>
+
+	<blockquote><pre>
+$auth_admin = new auth_admin();
+	</pre></blockquote>
+
+	<p>This instance gives you access to both the methods of this specific class and that of <code>auth</code>.</p>
+
+	</div>
+	<a href="#top">Top</a>
+
+</div>
 
+<div id="footer"> $Id$ 
+<br /><br />
 </div>
 
 </body>
-</html>
-\ No newline at end of file
+</html>
author	Meik Sievertsen <acydburn@phpbb.com>	2006-06-11 18:13:52 +0000
committer	Meik Sievertsen <acydburn@phpbb.com>	2006-06-11 18:13:52 +0000
commit	01b41453812dc7b990f03b81f85dcfb9a18076fd (patch)
tree	d12e93524fa7625d1220088d34a5a957cd618624 /phpBB/docs/auth_api.html
parent	ce3b07eee7dbefc68dcd8eab3ab667e6532c8561 (diff)
download	forums-01b41453812dc7b990f03b81f85dcfb9a18076fd.tar forums-01b41453812dc7b990f03b81f85dcfb9a18076fd.tar.gz forums-01b41453812dc7b990f03b81f85dcfb9a18076fd.tar.bz2 forums-01b41453812dc7b990f03b81f85dcfb9a18076fd.tar.xz forums-01b41453812dc7b990f03b81f85dcfb9a18076fd.zip