[prev in list] [next in list] [prev in thread] [next in thread]
List: midgard-dev
Subject: [midgard-cvs] cvs: midgard /proposals/storage20/namespace/api Makefile nsapifuncs.sgml nsapistruct.s
From: jpbrunon <cvslog () midgard-project ! org>
Date: 2000-10-31 18:26:11
[Download RAW message or body]
jpbrunon Tue Oct 31 19:26:11 2000 EDT
Modified files:
/midgard/proposals/storage20/namespace/api Makefile nsapifuncs.sgml
nsapistruct.sgml
Log:
begin defining some functions
Index: midgard/proposals/storage20/namespace/api/Makefile
diff -u midgard/proposals/storage20/namespace/api/Makefile:1.3 \
midgard/proposals/storage20/namespace/api/Makefile:1.4
--- midgard/proposals/storage20/namespace/api/Makefile:1.3 Mon Oct 30 19:14:33 2000
+++ midgard/proposals/storage20/namespace/api/Makefile Tue Oct 31 19:26:11 2000
@@ -10,13 +10,10 @@
# rtf does not work with images now.
all: img txt html ps pdf
-toto:
- echo $(SGML_SOURCES)
-
# Documents to build in each format
# ! images -> documents dependencies omitted to have simple implicit rules
txt: $(TXT_DIR)/ns-api.txt
-html: img_jpg $(HTML_DIR)/ns-api toto
+html: img_jpg $(HTML_DIR)/ns-api
ps: img_eps $(PS_DIR)/ns-api.ps
pdf: img_eps $(PDF_DIR)/ns-api.pdf
rtf: img_eps $(RTF_DIR)/ns-api.rtf
Index: midgard/proposals/storage20/namespace/api/nsapifuncs.sgml
diff -u midgard/proposals/storage20/namespace/api/nsapifuncs.sgml:1.1 \
midgard/proposals/storage20/namespace/api/nsapifuncs.sgml:1.2
--- midgard/proposals/storage20/namespace/api/nsapifuncs.sgml:1.1 Sat Oct 28 11:39:18 \
2000
+++ midgard/proposals/storage20/namespace/api/nsapifuncs.sgml Tue Oct 31 19:26:11 \
2000 @@ -1,7 +1,347 @@
<chapter id="nsapifuncs">
- <title>List of Functions (beta)</title>
+ <title>List of Functions (alpha)</title>
<para>
</para>
+
+ <section id="nsapicommon">
+ <title>Common Functions</title>
+ <para>
+ </para>
+ <section>
+ <title>Options</title>
+ <para>
+ Some parameters are common to several functions, so it's more convenient to have \
common utility functions to handle such values. + </para>
+ <table>
+ <title>GetOption function parameters</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="1.00in">
+ <colspec colnum="2" colwidth="1.25in">
+ <colspec colnum="3" colwidth="0.60in">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Mode</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>-</entry>
+ <entry>INTEGER</entry>
+ <entry>RET-VAL</entry>
+ <entry>Error code</entry>
+ </row>
+ <row>
+ <entry>option</entry>
+ <entry>INTEGER</entry>
+ <entry>IN</entry>
+ <entry>Type of option</entry>
+ </row>
+ <row>
+ <entry>value</entry>
+ <entry>VOID</entry>
+ <entry>OUT</entry>
+ <entry>Value of option (type depends on option's type)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table>
+ <title>SetOption function parameters</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="1.00in">
+ <colspec colnum="2" colwidth="1.25in">
+ <colspec colnum="3" colwidth="0.60in">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Mode</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>-</entry>
+ <entry>INTEGER</entry>
+ <entry>RET-VAL</entry>
+ <entry>Error code</entry>
+ </row>
+ <row>
+ <entry>option</entry>
+ <entry>INTEGER</entry>
+ <entry>IN</entry>
+ <entry>Type of option</entry>
+ </row>
+ <row>
+ <entry>value</entry>
+ <entry>VOID</entry>
+ <entry>IN</entry>
+ <entry>Value of option (type depends on option's type)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table>
+ <title>List of options (TO COMPLETE)</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="1.00in">
+ <colspec colnum="2" colwidth="1.25in">
+ <colspec colnum="3" colwidth="0.30in">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Set</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>sizeLimit (option?)</entry>
+ <entry>INTEGER</entry>
+ <entry>Y</entry>
+ <entry>Maximum number of returned entries (records)</entry>
+ </row>
+ <row>
+ <entry>TimeLimit</entry>
+ <entry>INTEGER</entry>
+ <entry>Y</entry>
+ <entry>Maximum number of seconds to wait for a result</entry>
+ </row>
+ <row>
+ <entry>UseLinks</entry>
+ <entry>BOOLEAN</entry>
+ <entry>Y</entry>
+ <entry>Use or don't use entry links</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ </section>
+
+ <section id="nsapiread">
+ <title>Read</title>
+ <para>
+ </para>
+ <table>
+ <title>Read function parameters</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="1.00in">
+ <colspec colnum="2" colwidth="1.25in">
+ <colspec colnum="3" colwidth="0.60in">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Mode</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>-</entry>
+ <entry>INTEGER</entry>
+ <entry>RET-VAL</entry>
+ <entry>Error code</entry>
+ </row>
+ <row>
+ <entry>conId</entry>
+ <entry>INTEGER</entry>
+ <entry>IN</entry>
+ <entry>Connection identifier</entry>
+ </row>
+ <row>
+ <entry>base</entry>
+ <entry>{DistinguishedName}</entry>
+ <entry>IN</entry>
+ <entry>GUID (DN) of the entry where to start searching</entry>
+ </row>
+ <row>
+ <entry>attributeTypeList</entry>
+ <entry>{ObjectIdentifier}*</entry>
+ <entry>IN</entry>
+ <entry>List of attributes to be returned</entry>
+ </row>
+ <row>
+ <entry>typesOnly</entry>
+ <entry>BOOLEAN</entry>
+ <entry>IN</entry>
+ <entry>
+ True if values not included in results.
+ Useful to know which attributes have at least one value.
+ </entry>
+ </row>
+ <row>
+ <entry>result</entry>
+ <entry>Entry</entry>
+ <entry>OUT</entry>
+ <entry>Entry (record) returned</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section id="nsapilist">
+ <title>List</title>
+ <para>
+ </para>
+ <table>
+ <title>List function parameters</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="1.00in">
+ <colspec colnum="2" colwidth="1.25in">
+ <colspec colnum="3" colwidth="0.60in">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Mode</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>-</entry>
+ <entry>INTEGER</entry>
+ <entry>RET-VAL</entry>
+ <entry>Error code</entry>
+ </row>
+ <row>
+ <entry>conId</entry>
+ <entry>INTEGER</entry>
+ <entry>IN</entry>
+ <entry>Connection identifier</entry>
+ </row>
+ <row>
+ <entry>base</entry>
+ <entry>{DistinguishedName}</entry>
+ <entry>IN</entry>
+ <entry>GUID (DN) of the entry where to start searching</entry>
+ </row>
+ <row>
+ <entry>sortList</entry>
+ <entry>{SortList}</entry>
+ <entry>IN</entry>
+ <entry>Sort list to use (order by clause)</entry>
+ </row>
+ <row>
+ <entry>attributeTypeList</entry>
+ <entry>{ObjectIdentifier}*</entry>
+ <entry>IN</entry>
+ <entry>List of attributes to be returned</entry>
+ </row>
+ <row>
+ <entry>typesOnly</entry>
+ <entry>BOOLEAN</entry>
+ <entry>IN</entry>
+ <entry>
+ True if values not included in results.
+ Useful to know which attributes have at least one value.
+ </entry>
+ </row>
+ <row>
+ <entry>result</entry>
+ <entry>(Entry)*</entry>
+ <entry>OUT</entry>
+ <entry>List of entries (records) returned</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section id="nsapisearch">
+ <title>Search</title>
+ <para>
+ </para>
+ <table>
+ <title>Search function parameters</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="1.00in">
+ <colspec colnum="2" colwidth="1.25in">
+ <colspec colnum="3" colwidth="0.60in">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Mode</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>-</entry>
+ <entry>INTEGER</entry>
+ <entry>RET-VAL</entry>
+ <entry>Error code</entry>
+ </row>
+ <row>
+ <entry>conId</entry>
+ <entry>INTEGER</entry>
+ <entry>IN</entry>
+ <entry>Connection identifier</entry>
+ </row>
+ <row>
+ <entry>base</entry>
+ <entry>{DistinguishedName}</entry>
+ <entry>IN</entry>
+ <entry>GUID (DN) of the entry where to start searching</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>INTEGER</entry>
+ <entry>IN</entry>
+ <entry>Depth of search (self, children, or whole subtree)</entry>
+ </row>
+ <row>
+ <entry>filter</entry>
+ <entry>{Filter}</entry>
+ <entry>IN</entry>
+ <entry>Filter to use (where clause)</entry>
+ </row>
+ <row>
+ <entry>sortList</entry>
+ <entry>{SortList}</entry>
+ <entry>IN</entry>
+ <entry>Sort list to use (order by clause)</entry>
+ </row>
+ <row>
+ <entry>attributeTypeList</entry>
+ <entry>{ObjectIdentifier}*</entry>
+ <entry>IN</entry>
+ <entry>List of attributes to be returned</entry>
+ </row>
+ <row>
+ <entry>typesOnly</entry>
+ <entry>BOOLEAN</entry>
+ <entry>IN</entry>
+ <entry>
+ True if values not included in results.
+ Useful to know which attributes have at least one value.
+ </entry>
+ </row>
+ <row>
+ <entry>result</entry>
+ <entry>(Entry)*</entry>
+ <entry>OUT</entry>
+ <entry>List of entries (records) returned</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section id="nsapierrcode">
+ <title>Error codes</title>
+ <para>
+ This list of error codes will be completed as new errors will appear during \
development. + </para>
+ </section>
</chapter>
Index: midgard/proposals/storage20/namespace/api/nsapistruct.sgml
diff -u midgard/proposals/storage20/namespace/api/nsapistruct.sgml:1.2 \
midgard/proposals/storage20/namespace/api/nsapistruct.sgml:1.3
--- midgard/proposals/storage20/namespace/api/nsapistruct.sgml:1.2 Mon Oct 30 \
19:14:33 2000
+++ midgard/proposals/storage20/namespace/api/nsapistruct.sgml Tue Oct 31 19:26:11 \
2000 @@ -1,12 +1,12 @@
<chapter id="nsapistruct">
- <title>Data Structures (alpha)</title>
+ <title>Data Structures (beta)</title>
<para>
- Most fields are strings.
- See the proposed C language header file ...
+ Most fields are just strings.
+ See the proposed C language header (***LINK***) file.
</para>
<para>
- All attribute values are STRING, syntax is about string format.
+ In particular, all attribute values are strings, syntax is about the format of \
this string. </para>
<section id="nsapiconv">
@@ -27,11 +27,11 @@
<entry>optional item</entry>
</row>
<row>
- <entry>[item]+</entry>
+ <entry>(item)+</entry>
<entry>List of items, with at least 1 item</entry>
</row>
<row>
- <entry>[item]*</entry>
+ <entry>(item)*</entry>
<entry>List of items, can be empty</entry>
</row>
<row>
@@ -70,20 +70,31 @@
</entry>
<entry>
The string format of the DN is defined in LDAP <emphasis>RFC 1779</emphasis>.
- A {DistinguishedName} string may be parsed and exploded into components (RDN) \
using utility functions. + A {DistinguishedName} string may be built or parsed \
and exploded into components (RDN) using utility functions.
The "<emphasis><link linkend="nsapidn">DistinguishedName</link></emphasis>" \
structure will then be used. </entry>
</row>
<row>
<entry>{ObjectIdentifier}</entry>
<entry>
- The <emphasis>Object Identifier</emphasis> is the unique identifier of any \
kind of structure: entry (record) or attribute type (field). + The \
<emphasis>Object Identifier</emphasis> is the unique identifier of any kind of \
structure: entry (record) or attribute type (field of record). </entry>
<entry>
The Object Identifier string can be either a "classic" identifier or a list \
of numbers separated by a dot. </entry>
</row>
<row>
+ <entry>{SearchFilter}</entry>
+ <entry>
+ The <emphasis>Search Filter</emphasis> (or where clause) is used to define \
search criterias when searching for entries (records). + </entry>
+ <entry>
+ The string format of the search filter is defined in LDAP <emphasis>RFC \
2254</emphasis>. + A {SearchFilter} string may be built or parsed and exploded \
into components (filter items) using utility functions. + The "<emphasis><link \
linkend="nsapifilter">Filter</link></emphasis>" structure will then be used. + \
</entry> + </row>
+ <row>
<entry>{GeneralizedTime}</entry>
<entry>
<emphasis>Generalized Time</emphasis> is Greewhich Mean Time (GMT) with a \
precision of one second. @@ -105,6 +116,7 @@
<entry>{LanguageOption}</entry>
<entry>
Attribute (field) option for language.
+ It extends an attribute type.
</entry>
<entry>
Format is "lang-ll-CC" where "ll" is the language code (ISO 639), and "CC" is \
the country code (ISO 3166). @@ -116,7 +128,7 @@
</section>
<section id="nsapientry">
- <title>Generic Record (entry) (alpha)</title>
+ <title>Generic Record (entry) (beta)</title>
<table>
<title>Entry structure (record)</title>
<tgroup cols="3">
@@ -137,14 +149,35 @@
</row>
<row>
<entry>attributeList</entry>
- <entry>[Attribute]*</entry>
+ <entry>AttributeList</entry>
<entry>List of attributes (fields) of the entry</entry>
</row>
</tbody>
</tgroup>
</table>
+ <table>
+ <title>EntryList structure</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="1.00in">
+ <colspec colnum="2" colwidth="1.75in">
+ <thead>
+ <row>
+ <entry>Field</entry>
+ <entry>Datatype</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>entryList</entry>
+ <entry>(Entry)*</entry>
+ <entry>List of entries (records)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<section>
- <title id ="nsapidn">DistinguishedName (GUID) (alpha)</title>
+ <title id ="nsapidn">DistinguishedName (GUID) (beta)</title>
<table>
<title>DistinguishedName structure (GUID)</title>
<tgroup cols="3">
@@ -160,7 +193,7 @@
<tbody>
<row>
<entry>rdnList</entry>
- <entry>[AttributeTypeAndValue]+</entry>
+ <entry>(AttributeTypeAndValue)+</entry>
<entry>List of components (RDNs) of the DN</entry>
</row>
</tbody>
@@ -168,9 +201,12 @@
</table>
</section>
<section>
- <title>Attribute structures (alpha)</title>
+ <title>Attribute structures (beta)</title>
+ <para>
+ <emphasis>Attribute structures</emphasis> are all the data structures which are \
used to define attribute types and attribute values. + </para>
<table>
- <title>Attribute structure (field)</title>
+ <title>Attribute structure (field of record)</title>
<tgroup cols="3">
<colspec colnum="1" colwidth="1.00in">
<colspec colnum="2" colwidth="1.75in">
@@ -188,14 +224,35 @@
<entry>Type of the attribute</entry>
</row>
<row>
- <entry>ValueList</entry>
- <entry>[STRING]*</entry>
+ <entry>valueList</entry>
+ <entry>(STRING)*</entry>
<entry>List of values of the attribute</entry>
</row>
</tbody>
</tgroup>
</table>
<table>
+ <title>AttributeList structure</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="1.00in">
+ <colspec colnum="2" colwidth="1.75in">
+ <thead>
+ <row>
+ <entry>Field</entry>
+ <entry>Datatype</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>attributeList</entry>
+ <entry>(Attribute)*</entry>
+ <entry>List of attributes (fields)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table>
<title>AttributeTypeAndValue structure</title>
<tgroup cols="3">
<colspec colnum="1" colwidth="1.00in">
@@ -222,7 +279,7 @@
</tgroup>
</table>
<para>
- The exact format of string for values depends on the syntax of the attribute type.
+ The exact format of STRING for values depends on the syntax of the attribute type.
</para>
<para>
The type can be extended by setting an option.
@@ -232,7 +289,7 @@
Its format is {LanguageOption}.
</para>
<para>
- Subtyping ...
+ If the storage backend supports <emphasis>subtyping</emphasis> of attribute types, \
then a subtype also has the type of its supertype. </para>
<table>
<title>Predefined types of attributes</title>
@@ -284,6 +341,63 @@
<entry>1.3.6.1.4.1.6994.?</entry>
<entry>{MidgardVersion}</entry>
<entry>Version of the entry (record)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ <section>
+ <title id="nsapifilter">SearchFilter structures (beta)</title>
+ <para>
+ <emphasis>Search filter structures</emphasis> are all the data structures which are \
used to define the filter (where clauses) as well as the order by (sort) clauses. + \
</para> + <para>
+ Search filter structures are derived from LDAPv3.
+ Sorting is derived from RFC 2891: LDAP Control Extension for Server Side Sorting, \
but may have to be implemented in the name space storage library depending on the \
storage backend sorting facilities. + </para>
+ <table>
+ <title>SearchFilter structure</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="1.00in">
+ <colspec colnum="2" colwidth="1.75in">
+ <thead>
+ <row>
+ <entry>Field</entry>
+ <entry>Datatype</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>filter</entry>
+ <entry>{SearchFilter}</entry>
+ <entry>Search filter string</entry>
+ </row>
+ <row>
+ <entry>sortKeyList</entry>
+ <entry>(SortKey)+</entry>
+ <entry>List of keys used to sort search results</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table>
+ <title>Filter structure</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="1.00in">
+ <colspec colnum="2" colwidth="1.75in">
+ <thead>
+ <row>
+ <entry>Field</entry>
+ <entry>Datatype</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>filterItemList</entry>
+ <entry>(FilterItem)*</entry>
+ <entry>List of items in filter</entry>
</row>
</tbody>
</tgroup>
---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@midgard-project.org
For additional commands, e-mail: cvs-help@midgard-project.org
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic