aboutsummaryrefslogtreecommitdiffstats
path: root/lualdap/doc
diff options
context:
space:
mode:
authorTomas Guisasola <tomas@luaforge.net>2004-05-31 11:00:13 +0000
committerTomas Guisasola <tomas@luaforge.net>2004-05-31 11:00:13 +0000
commitd2baf844908d8d657d9bd3e1e5847343d7f91d38 (patch)
tree142ef16b310fa4bab3ebae34bd9d378f09d1b5d2 /lualdap/doc
parentErro de digitacao. (diff)
downloadlualdap-d2baf844908d8d657d9bd3e1e5847343d7f91d38.tar.xz
lualdap-d2baf844908d8d657d9bd3e1e5847343d7f91d38.zip
Correcao de bug no retorno de entradas que sao referencias.
Melhoria no ingles da documentacao.
Diffstat (limited to 'lualdap/doc')
-rwxr-xr-xlualdap/doc/us/index.html35
-rwxr-xr-xlualdap/doc/us/manual.html107
2 files changed, 72 insertions, 70 deletions
diff --git a/lualdap/doc/us/index.html b/lualdap/doc/us/index.html
index 8930946..6548b04 100755
--- a/lualdap/doc/us/index.html
+++ b/lualdap/doc/us/index.html
@@ -32,8 +32,8 @@ interface to the OpenLDAP library
<a href=#installation>installation</a> &middot;
<a href="manual.html">manual</a> &middot;
<a href="license.html">license</a> &middot;
-<a href="#hist">history</a> &middot;
-<a href="#contact">contact</a>
+<a href="#credits">credits</a> &middot;
+<a href="#contact">contact us</a>
</small></center>
<p>
@@ -57,7 +57,8 @@ interface to the OpenLDAP library
<li> <a href="manual.html#examples">Examples</a>
</ul>
<li> <a href="license.html">Copyright & License</a>
- <li> <a href=#hist>History</a>
+ <li> <a href="#credits">Credits</a>
+ <li> <a href="#contact">Contact us</a>
</ul>
</p>
@@ -66,7 +67,7 @@ interface to the OpenLDAP library
<h2>Overview</h2>
<p>
LuaLDAP is a simple interface from Lua to an LDAP client
-(in fact it's a bind to <a href="http://www.openldap.org">OpenLDAP</a> client).
+(in fact it is a bind to <a href="http://www.openldap.org">OpenLDAP</a>).
It enables a Lua program to:
<ul>
<li> Connect to an LDAP server;
@@ -116,20 +117,21 @@ LuaLDAP can be downloaded in source code from the following links: <p>
<p>
LuaLDAP is a bind to the <a href="http://www.openldap.org">OpenLDAP</a>
-library so it depends on it.
-You can download the library from the
+library,
+therefore it depends on a previous installation of this library.
+You can download OpenLDAP from the
<a href="http://www.openldap.org/software/download">OpenLDAP download page</a>.
</p>
-<a name=hist>
-<h2>History</h2>
+<a name="credits">
+<h2>Credits</h2>
<p>
LuaLDAP was designed by Roberto Ierusalimschy, Andr&eacute; Carregal
-and Tom&aacute;s Guisasola for
+and Tom&aacute;s Guisasola as part of
<a href="http://www.keplerproject.org">The Kepler Project</a>
-that keeps its copyright.
+which holds its copyright.
It was implemented by Tom&aacute;s Guisasola.
</p>
<p>
@@ -140,12 +142,11 @@ and FINEP.
<a name="contact"></a>
-<h2>Contact</h2>
+<h2>Contact us</h2>
<p>
-For more information please
-<a href="mailto:tomas-NO-SPAM-THANKS@keplerproject.org">contact</a>
-us.
+For further information please
+<a href="mailto:tomas-NO-SPAM-THANKS@keplerproject.org">contact us</a>.
Comments are welcome!
</p>
@@ -158,14 +159,14 @@ Comments are welcome!
<a href=#installation>installation</a> &middot;
<a href="manual.html">manual</a> &middot;
<a href="license.html">license</a> &middot;
-<a href="#hist">history</a> &middot;
-<a href="#contact">contact</a>
+<a href="#credits">credits</a> &middot;
+<a href="#contact">contact us</a>
</small></center>
<p>
<hr>
<small>
-$Id: index.html,v 1.14 2004-01-12 10:44:06 tomas Exp $
+$Id: index.html,v 1.15 2004-05-31 11:00:13 tomas Exp $
</small>
</body>
diff --git a/lualdap/doc/us/manual.html b/lualdap/doc/us/manual.html
index 71f2387..fab0506 100755
--- a/lualdap/doc/us/manual.html
+++ b/lualdap/doc/us/manual.html
@@ -41,28 +41,26 @@ interface to the OpenLDAP library
<h2>Introduction</h2>
<p>
LuaLDAP is a simple interface from Lua to an LDAP client
-(in fact it's a bind to
+(in fact it is a bind to
<a href="http://www.openldap.org">OpenLDAP</a>
client).
</p>
<p>
-LuaLDAP defines one single global variable, a table called
-<tt>lualdap</tt>
-which holds the function that creates a connection object.
-To initiate an LDAP session is required a hostname and a user
-identification.
-If desired Transport Layer Security (TLS) can be used throughout
-the connection.
+LuaLDAP defines one single global variable:
+a table called <tt>lualdap</tt>.
+This table holds the functions used to create an LDAP connection object.
</p>
<p>
-With a connection object any operation can be performed on the
-directory such as value comparation, addition of new entries,
-modification of attributes on existing entries, remotion and
-the most common of all: searches.
-Entries are represented as Lua tables; attributes are it's
-fields.
-Attribute's values can be strings or tables of strings when
-they have multiple values on the directory.
+A connection object offers methods to perform any operation on the directory
+such as
+comparing values,
+adding new entries,
+modifying attributes on existing entries,
+removing entries,
+and the most common of all: searching.
+Entries are represented as Lua tables; attributes are its fields.
+The attribute values can be strings or tables of strings
+(used to represent multiple values).
</p>
<p>
LuaLDAP is free software and uses the same
@@ -74,14 +72,12 @@ as Lua 5.0.
<a name="attributes">
<h2>Representing attributes</h2>
-
<p>
Many LDAP operations manage sets of attributes and values.
-So LuaLDAP provides a uniform way of representing them: using Lua tables.
+LuaLDAP provides a uniform way of representing them: using Lua tables.
A table of attributes is indexed by the name of the attribute and its
-value can be a string (it can be a "binary string", so be careful),
-when there is only one value for that attribute or a list/table of values
-indexed by numbers from 1 to <em>n</em>.
+value can be a string (be careful: it can also be a "binary string")
+or a list/table of values indexed by numbers from 1 to <em>n</em>.
Some operations have different approaches that will be explained
when necessary.
<p>
@@ -95,7 +91,7 @@ Follows a small example:
},
}
</pre>
-Attribute's names cannot contain zeroes (<tt>'\0'</tt>)
+Attribute names cannot contain zeroes (<tt>'\0'</tt>)
<a name="dn"></a>
@@ -104,30 +100,33 @@ Attribute's names cannot contain zeroes (<tt>'\0'</tt>)
<p>
The distinguished name (DN) is the term used to identify an entry on the
directory information tree.
-It is formed by the concatenation of the relative distinguished name (RDN)
-of the entry with the distinguished name of its parent.
+It is formed by the relative distinguished name (RDN) of the entry
+and the distinguished name of its parent.
LuaLDAP will always use a string to represent the DN of any entry.
<p>
A more precise definition can be found on the LDAP documentation.
-You can find a list of some of these files in section
+A list of some of these files can be found in section
<a href="#related_docs">Related documentation</a>.
<a name="initialization_functions"></a>
<h2>Initialization functions</h2>
<p>
-LDAP provides some way to connect to a server and so did LuaLDAP:
+LuaLDAP provides a single way to connect to an LDAP server:
<ul>
+<a name="open_simple"></a>
<li> <b><tt>lualdap.open_simple (hostname, who, password, usetls)</tt></b> <br>
Initializes a session with an LDAP server.
-Quoting the C LDAP API definition <em>"hostname contains a space-separated
+This function requires a hostname,
+accordingly to <a href="#related_docs">the C LDAP API</a> definition
+(<em>"hostname contains a space-separated
list of hostnames or dotted strings representing the IP address of hosts
running an LDAP server to connect to. Each hostname in the list MAY include
a port number which is separated from the host itself with a colon (:)
-character."</em>
+character."</em>).
The argument <tt>who</tt> should be the <a href="#dn">distinguished name</a>
of the entry that has the password to be checked against the third argument,
<tt>password</tt>.
-The optional argument <tt>usetls</tt> is a boolean flag indicating if
+The optional argument <tt>usetls</tt> is a Boolean flag indicating if
Transport Layer Security (TLS) should be used.
</ul>
@@ -137,17 +136,18 @@ Transport Layer Security (TLS) should be used.
<h2>Connection objects</h2>
<p>
-A connection object offers methods that implement the LDAP operations.
+A connection object offers methods which implement LDAP operations.
Almost all of them need a <a href="#dn">distinguished name</a> to
identify the entry on which the operation will be executed.
<p>
These methods execute asynchronous operations and return a function
-that should be called to get the result(s).
+that should be called to obtain the result(s).
These functions will return <tt>true</tt> indicating success of the operation;
-the only exception is <a href="#conn_compare">compare</a> that can return
-<tt>false</tt> (the result of the comparison) on a success operation.
+the only exception is the function <tt><a href="#conn_compare">compare</a></tt>
+which can return either <tt>true</tt> or <tt>false</tt> (which is the result
+of the comparison) on a successful operation.
<p>
-There are two kinds of errors:
+There are two types of errors:
<em>API errors</em>, such as wrong parameters, absent connection etc.; and
<em>LDAP errors</em>, such as mal-formed DN, unknown attribute etc.
API errors will raise a Lua error,
@@ -155,15 +155,15 @@ while LDAP errors will be reported by the function/method
returning <tt>nil</tt> followed by the error message provided by
the OpenLDAP client.
<p>
-A connection object can be created by calling one of the
-<a href="#initialization_functions">Initialization functions</a>.
+A connection object can be created by calling the
+<a href="#initialization_functions">Initialization function</a>.
<h4>Methods</h4>
<ul>
<a name="conn_add"></a>
<li> <b><tt>conn:add (distinguished_name, table_of_attributes)</tt></b> <br>
-Add a new entry to the directory with the given attributes and values.
+Adds a new entry to the directory with the given attributes and values.
<a name="conn_close"></a>
<li> <b><tt>conn:close()</tt></b> <br>
@@ -171,15 +171,15 @@ Closes the connection <tt>conn</tt>.
<a name="conn_compare"></a>
<li> <b><tt>conn:compare (distinguished_name, attribute, value)</tt></b> <br>
-Compare a value against an entry.
+Compares a value against an entry.
<a name="conn_delete"></a>
<li> <b><tt>conn:delete (distinguished_name)</tt></b> <br>
-Delete an entry from the directory.
+Deletes an entry from the directory.
<a name="conn_modify"></a>
<li> <b><tt>conn:modify (distinguished_name, table_of_operations*)</tt></b> <br>
-Modify values of attributes on the given entry.
+Changes values of attributes in the given entry.
The tables of operations are <a href="#attributes">table of attributes</a>
but with the value on index <tt>1</tt> indicating the operation to be
performed.
@@ -189,29 +189,29 @@ The valid operations are:
<li> <b><tt>'-'</tt></b> to delete the values of the attributes
<li> <b><tt>'='</tt></b> to replace the values of the attributes
</ul>
-All tables of operations passed as arguments will be joined together to
-perform just one LDAP modify operation.
+All tables of operations given as arguments will be joined together to
+perform a single LDAP modify operation.
<a name="conn_rename"></a>
<li> <b><tt>conn:rename (distinguished_name, new_relative_dn, new_parent)</tt></b> <br>
-Modify the name of the entry
+Changes entry names
(<i>i.e. change its <a href="#dn">distinguished name</a></i>).
<a name="conn_search"></a>
<li> <b><tt>conn:search (table_of_search_parameters)</tt></b> <br>
-Execute a search on directory using the given parameters.
+Performs a search operation on the directory.
The parameters are described below:
<ul>
- <li> <b><tt>attrs</tt></b> a string or a list of attributes names to be retrieved (default is to retrieve all attributes).
- <li> <b><tt>attrsonly</tt></b> a boolean value that must be <i>false</i> (default) if both attribute names and values are to be retrieved or <i>true</i> if only names are wanted.
- <li> <b><tt>base</tt></b> The <a href="#dn">distinguished name</a> of the entry at which to start the search.
- <li> <b><tt>filter</tt></b> A string representing the search filter as described in <a href="http://www.ietf.org/rfc/rfc2254.txt">The String Representation of LDAP Search Filters (RFC 2254)</a>.
- <li> <b><tt>scope</tt></b> A string indicating the scope of the search. The valid strings are: "base", "onelevel" and "subtree". In fact, just the initial letter is tested, so any string beginning with the same lower case letters will be accepted. The empty string ("") and <tt>nil</tt> will be treated as the default scope.
- <li> <b><tt>sizelimit</tt></b> The maximum number of entries to return (the default is no limit).
- <li> <b><tt>timeout</tt></b> The timeout in seconds (default is no timeout). The precision is microseconds.
+ <li> <b><tt>attrs</tt></b>: a string or a list of attribute names to be retrieved (default is to retrieve all attributes).
+ <li> <b><tt>attrsonly</tt></b>: a Boolean value that must be either <i>false</i> (default) if both attribute names and values are to be retrieved, or <i>true</i> if only names are wanted.
+ <li> <b><tt>base</tt></b>: The <a href="#dn">distinguished name</a> of the entry at which to start the search.
+ <li> <b><tt>filter</tt></b>: A string representing the search filter as described in <a href="http://www.ietf.org/rfc/rfc2254.txt">The String Representation of LDAP Search Filters (RFC 2254)</a>.
+ <li> <b><tt>scope</tt></b>: A string indicating the scope of the search. The valid strings are: "base", "onelevel" and "subtree". The empty string ("") and <tt>nil</tt> will be treated as the default scope.
+ <li> <b><tt>sizelimit</tt></b>: The maximum number of entries to return (default is no limit).
+ <li> <b><tt>timeout</tt></b>: The timeout in seconds (default is no timeout). The precision is microseconds.
</ul>
The search method will return a <i>search iterator</i> which is a function
-that should be called with no arguments.
+that requires no arguments.
The search iterator is used to get the search result and will return
a string representing the <a href="#dn">distinguished name</a> and
a <a href="#attributes">table of attributes</a> as returned by the
@@ -280,6 +280,7 @@ Access Protocol (v3)</a>
Specification</a>
<li> <a href="http://www.ietf.org/rfc/rfc2254.txt">The String Representation
of LDAP Search Filters (RFC 2254)</a>
+ <li> <a href="http://www.ietf.org/proceedings/01aug/I-D/draft-ietf-ldapext-ldap-c-api-05.txt">The C LDAP Application Program Interface</a>
</ul>
@@ -321,7 +322,7 @@ of LDAP Search Filters (RFC 2254)</a>
<hr>
<small>
-$Id: manual.html,v 1.14 2004-04-28 14:43:54 tomas Exp $
+$Id: manual.html,v 1.15 2004-05-31 11:00:13 tomas Exp $
</small>
</body>