Index: doc/API
===================================================================
--- doc/API	(revision 5d06689e2b01138202c40932797284b0fcdf7603)
+++ doc/API	(revision 669b4810acfbeee6bdec4a2443a99b2994efedc8)
@@ -29,5 +29,5 @@
      constructor that takes a constraining role
        [role:?R[{role-constraint}]
-     (c:abac_constraint_from_role)
+     (C:abac_constraint_from_role)
 
    Constraint(Oset &)
@@ -35,5 +35,5 @@
        [oset:?O[{oset-constraint}]
        [urn:?F[keyid:$alpha_keyid].oset:documents([string:?P])]
-     (c:abac_constraint_from_oset)
+     (C:abac_constraint_from_oset)
 
    Constraint(char *)
@@ -48,56 +48,65 @@
      it should be followed with one or many of following utility
      calls.
-     (C:abac_condition_create)
+     (C:abac_constraint_create)
 
    void constraint_add_integer_max(int)
-     (c:abac_constraint_add_integer_max)
+     (C:abac_constraint_add_integer_max)
    void constraint_add_integer_min(int)
      utility routines to setup a integer range constraint 
        [integer:?I[10 .. 20]]
-     (c:abac_constraint_add_integer_min)
+     (C:abac_constraint_add_integer_min)
 
    void constraint_add_integer_target(int)
      utility routine to setup a integer list constraint 
        [integer:?I[10,20]]
-     (c:abac_constraint_add_integer_target)
+     (C:abac_constraint_add_integer_target)
 
    void constraint_add_float_max(float)
+     (C:abac_constraint_add_float_max)
    void constraint_add_float_min(float)
      utility routines to setup a float range constraint 
        [float:?F[1.0 .. 2.5]]
+     (C:abac_constraint_add_float_min)
 
    void constraint_add_float_target(float)
      utility routine to setup a float list constraint 
        [float:?F[0.5, 2.5]]
+     (C:abac_constraint_add_float_target)
 
    void constraint_add_time_max(char*)
+     (C:abac_constraint_add_time_max)
    void constraint_add_time_min(char*)
      utility routines to setup a time range constraint, 
      takes quoted string values, beyond T is optional 
        [time:?F["20120228T" .. "20120228T090000"]]
+     (C:abac_constraint_add_time_min)
 
    void constraint_add_time_target(char*)
      utility routine to setup a time list constraint 
        [time:?M["20201101T182930","20201101T"]] 
+     (C:abac_constraint_add_time_target)
 
    void constraint_add_urn_target(char*)
      utility routine to setup a an urn list constraint
        [urn:?U["fileA","http://fileB"]] 
+     (C:abac_constraint_add_urn_target)
 
    void constraint_add_string_target(char*)
      utility routine to setup a a string list constraint
        [string:?S["abc",'efg',"hij"]]
+     (C:abac_constraint_add_string_target)
 
    void constraint_add_boolean_target(char*)
      utility routine to setup a a boolean list constraint
        [boolean:?B['true']]
+     (C:abac_constraint_add_boolean_target)
 
    char *string() const
      returns literal string of the constraint
-     (c:abac_condition_string)
+     (C:abac_constraint_string)
 
    char *typed_string() const
      returns typed literal string of the constraint
-     (c:abac_condition_typed_string)
+     (C:abac_constraint_typed_string)
 
 ABAC::DataTerm
@@ -105,7 +114,14 @@
    maybe be instantiated, or uninstantiated but being constrained,
    or as a principal oset term (standalone right handside of an oset
-   policy rule).  It holds a pointer to a abac_term_t structure and 
-   an optional constraint that may be imposed on this data term if it
-   is indeed an unistantiated variable.
+   policy rule).  It holds a pointer to a abac_term_t structure.
+   Types of data terms are:
+     "integer"
+     "urn"
+     "float"
+     "boolean"
+     "string"
+     "time"
+     "principal"
+     "anonymous"
 
    DataTerm()
@@ -122,4 +138,8 @@
      (C: abac_term_named_create)
 
+   DataTerm(const ID&)
+     constructor to make named principal data term for parameter term
+     (C: abac_term_id_create)
+
    DataTerm(char*, char*, Constraint*)
      constructor for making a variable data term 
@@ -132,24 +152,31 @@
    char *string() const
      returns literal string of the data term
-     (c:abac_term_string)
+     (C:abac_term_string)
 
    char *typed_string() const
      returns typed literal string of the data term
-     (c:abac_term_typed_string)
+     (C:abac_term_typed_string)
 
    bool term_is_time() const
+     (C:abac_term_is_time)
    bool term_is_string() const
+     (C:abac_term_is_string)
    bool term_is_urn() const
+     (C:abac_term_is_urn)
    bool term_is_integer() const 
+     (C:abac_term_is_integer)
      returns true if data term is of certain type
 
    int term_add_constraint(Contraint&)
      utiltiy routine to add a constraint to this data term
+     (C:abac_term_add_constraint)
 
    int term_type() const
      returns subtype of the data term
+     (C:abac_term_type) 
 
    char *term_name() const
      returns the name of the data term 
+     (C:abac_term_name) 
 
 ABAC::Role
@@ -167,10 +194,15 @@
    Role(char*) 
      constructor that builds a bare bone role with just principal's name
-     (c:abac_role_principal_create)
+     (C:abac_role_principal_create)
 
    Role(char*, char*) 
      constructor that builds a bare bone role with just principal's name
      and a role name
-     (c:abac_role_create)
+     (C:abac_role_create)
+
+   Role(char*, char*, char*) 
+     constructor that builds a bare bone role with just principal's name
+     and a linking role name and a role name
+     (C:abac_role_linked_create)
 
    bool role_is_principal() const
@@ -178,4 +210,5 @@
      a data term), the right hand side of, 
        [keyid:A].role:r <- [keyid:B]
+     (C:abac_role_is_principal)
 
    bool role_is_linking() const
@@ -183,16 +216,18 @@
      the right hand side of,
        [keyid:A].role:r1 <- [keyid:B].role:r2.role:r3
+     (C:abac_role_is_linking)
 
    char *string() const
      returns literal string of the role
-     (c:abac_aspect_string)
+     (C:abac_role_string)
 
    char *typed_string() const
      returns typed literal string of the role
-     (c:abac_aspect_typed_string)
+     (C:abac_role_typed_string)
 
    char *role_linked_role() const 
      returns linked part of a linking role, for
        [keyid:A].role:r1.role:r2, it returns r1
+     (C:abac_role_linked_role)
 
    char *role_name() const 
@@ -200,20 +235,26 @@
        [keyid:A].role.r1.role:r2, it returns r2
        [keyid:A].role.r1, it returns r1
+     (C:abac_role_name)
 
    char *role_principal() const
      returns the principal of role (the part before the first dot)
        [keyid:A].role.r1, it returns A 
+     (C:abac_role_principal)
 
    void role_add_data_term(DataTerm&)
      add a data term to the role
+     (C:abac_role_add_data_term)
 
    std::vector<DataTerm> get_data_terms(bool &)
      return the data terms bound to this role.
+     (C:abac_role_get_data_terms)
 
    void role_add_linked_data_term(DataTerm&)
      add a data term to the linking role
+     (C:abac_role_add_linked_data_term)
 
    std::vector<DataTerm> get_linked_data_terms(bool &)
      return the data terms bound to this role's linking role.
+     (C:abac_role_get_linked_data_terms)
 
 ABAC::Oset
@@ -231,15 +272,21 @@
    Oset(char *)
      constructor that makes a principal oset, ie [keyid:B]
-     (c:abac_role_principal_create)
+     (C:abac_role_principal_create)
 
    Oset(char *, char *)
      constructor that makes a regular oset, ie. [keyid:B].oset:o
-     (c:abac_role_create)
+     (C:abac_role_create)
+
+   Oset(char *, char*, char *)
+     constructor that makes a linked oset, ie. [keyid:B].role:r.oset:o
+     (C:abac_oset_linked_create)
 
    Oset(DataTerm&)
      constructor that makes an object oset, ie. [urn:'file/fileA']
+     (C:abac_oset_object_create)
 
    bool oset_is_object(), ie <- [integer:10]
      return ture if this oset is an object oset
+     (C:abac_oset_is_object)
 
    bool oset_is_principal() const
@@ -247,4 +294,5 @@
      a data term), the right hand side of, 
        [keyid:A].oset:o <- [keyid:B]
+     (C:abac_oset_is_principal)
 
    bool oset_is_linking() const
@@ -252,16 +300,18 @@
      the right hand side of,
        [keyid:A].oset:o1 <- [keyid:B].role:r1.oset:o2
+     (C:abac_oset_is_linking)
 
    char *string() const
      returns literal string of the oset
-     (c:abac_aspect_string)
+     (C:abac_oset_string)
 
    char *typed_string() const
      returns typed literal string of the oset
-     (c:abac_aspect_typed_string)
+     (C:abac_oset_typed_string)
 
    char *oset_linked_role() const 
      returns linked part of a linking oset, for
        [keyid:A].role:r1.oset:o1, it returns r1
+     (C:abac_oset_linked_role)
 
    char *oset_name() const 
@@ -269,24 +319,31 @@
        [keyid:A].role:r1.oset:o1, it returns o1
        [keyid:A].oset:o1, it returns o1
+     (C:abac_oset_name)
 
    char *oset_principal() const 
      returns principal name,
        [keyid:A].role:r1.oset:o1, it returns A 
+     (C:abac_oset_principal)
 
    char *oset_object() const 
      returns object's name when the oset is a principal object
        [keyid:A].oset:values <- [integer:10], it returns 10
+     (C:abac_oset_object)
 
    void add_data_term(DataTerm&)
      add a data term to this oset's parameter set
+     (C:abac_oset_add_data_term)
 
    std::vector<DataTerm> get_data_terms(bool &)
      returns the data terms bound to this oset.  
+     (C:abac_oset_get_data_terms)
 
    void oset_add_linked_data_term(DataTerm&)
      add a data term to this oset's linking role's parameter set.
+     (C:abac_oset_add_linked_data_term)
 
    std::vector<DataTerm> get_linked_data_terms(bool &)
      returns the data terms bound to this oset's linking role.  
+     (C:abac_oset_get_linked_data_terms)
 
 ABAC::ID
@@ -307,5 +364,5 @@
      load an ID cert from a file, will throw an exception 
      if the cert cannot be loaded 
-     (c:abac_id_from_file)
+     (C:abac_id_from_file)
 
    ID(char *,int)
@@ -314,34 +371,41 @@
      - validity must be at least one second
      will throw an exception if either of the above is violated 
-     (c:abac_id_generate)
+     (C:abac_id_generate)
 
    void id_load_privkey_file(char *)
      loads the private key associated with the ID credential
      will throw an exception if the key cannot be loaded 
+     (C:abac_id_load_privkey_file)
 
    char *id_keyid()
      returns the SHA1 keyid of the id cert
+     (C:abac_id_keyid)
 
    char *id_name()
      returns the CN (the parameter passed to the constructor or the
      CN of the cert).
-     (c:abac_id_cn)
+     (C:abac_id_cn)
 
    bool id_has_privkey()
      returns true if the ID has an associated private key
+     (C:abac_id_has_privkey)
 
    void id_write_cert(FILE *)
      writes a PEM-encoded cert to the file handle 
+     (C:abac_id_write_cert)
 
    void id_write_cert(char *)
      writes a PEM-encoded cert to a file named out 
+     (C:abac_id_write_cert_fname)
 
    void id_write_privkey(FILE *)
      writes a PEM-encoded private key to the file handle
      throws an exception if no private key is loaded 
+     (C:abac_id_write_privkey)
 
    void id_write_privkey(char *)
       writes a PEM-encoded private key a file named out
       throws an exception if no private key is loaded 
+     (C:abac_id_write_privkey_fname)
 
    abac_chunk_t id_cert_chunk()
@@ -349,8 +413,9 @@
      associated with this ID.
      can be passed to libabac's Context::load_id_chunk() 
+     (C:abac_id_cert_chunk)
 
    char *string()
      returns literal string of the id credential
-     (c:abac_id_string)
+     (C:abac_id_string)
 
 ABAC::Attribute
@@ -380,5 +445,5 @@
        - the Head role is invalid
        - the validity period is invalid (must be >= 1 second) 
-     (c:abac_attribute_create)
+     (C:abac_attribute_create)
 
    Attribute(Oset&, int)
@@ -389,31 +454,37 @@
        - the Head oset is invalid
        - the validity period is invalid (must be >= 1 second) 
-     (c:abac_attribute_create)
+     (C:abac_attribute_create)
 
    bool attribute_add_tail(Role&)
-      Add a role tail.  Call multiple times for intersections
+      Add a role tail.  Call multiple times for intersection
+     (C:abac_attribute_add_tail)
 
    bool attribute_add_tail(Oset&)
-      Add an oset tail.  Call multiple times for intersections
+      Add an oset tail.  Call multiple times for intersection
+     (C:abac_attribute_add_tail)
 
    char *head_string()
      returns literal string of head of the attribute
+     (C:abac_head_string)
 
    char *tail_string()
      returns literal string of tail of the attribute
+     (C:abac_tail_string)
 
    char *head_typed_string()
      returns typed literal string of head of the attribute
+     (C:abac_head_typed_string)
 
    char *tail_typed_string()
      returns typed literal string of tail of the attribute
+     (C:abac_tail_typed_string)
 
    char *string()
      returns literal string of the attribute
-     (c:abac_attribute_string)
+     (C:abac_attribute_string)
 
    char *typed_string()
      returns typed literal string of the attribute
-     (c:abac_attribute_typed_string)
+     (C:abac_attribute_typed_string)
 
    const Role &role_head()
@@ -425,7 +496,9 @@
    std::vector<Role> role_tails(bool &)
      retrieve tail role which maybe more than 1 if intersecting
+     (C:abac_attribute_role_tails)
 
    std::vector<Oset> oset_tails(bool &)
      retrieve tail oset which maybe more than 1 if intersecting
+     (C:abac_attribute_oset_tails)
 
    bool attribute_bake()
@@ -433,15 +506,19 @@
      This returns false if there are no subjects
      This will throw an exception if the cert's already been baked.
+     (C:abac_attribute_bake)
 
    bool attribute_baked()
      returns true iff the cert has been baked.
+     (C:abac_attribute_baked)
 
    void attribute_write_cert(FILE *)
      write the DER-encoded X.509 attribute cert to the open file handle
      Throws an exception if the cert isn't baked 
+     (C:abac_attribute_write_cert)
 
    void attribute_write_cert(char *)
      write the DER-encoded X.509 attribute cert to a file named out
      Throws an exception if the cert isn't baked 
+     (C:abac_attribute_write_cert_fname)
 
    abac_chunk_t cert_chunk()
@@ -450,4 +527,5 @@
      Throws an exception if the cert isn't baked
      the chunk can be passed to libabac's Context::load_attribute_chunk() 
+     (C:abac_attribute_cert_chunk)
 
 ABAC::Context
@@ -465,22 +543,22 @@
    void dump_yap_db()
      dump the complete yap prolog database
-     (c:show_yap_db)
+     (C:show_yap_db)
 
    int load_id(ABAC::ID&)
      load id cert from ID 
-     (c:abac_context_load_id)
+     (C:abac_context_load_id)
 
    int load_id_file(char *)
      load id cert from an idkey combo file. key retrieval will be attempt
      but won't fail if not found
-     (c:abac_context_load_id_file)
+     (C:abac_context_load_id_file)
 
    int load_id_files(char *, char *) 
      load id cert from an id file and a key file
-     (c:abac_context_load_id_files)
+     (C:abac_context_load_id_files)
 
    int load_id_chunk(abac_chunk_t) 
      load id cert from a chunk structure
-     (c:abac_context_load_id_chunk)
+     (C:abac_context_load_id_chunk)
      returns:
        ABAC_CERT_SUCCESS   successfully loaded
@@ -490,13 +568,13 @@
    int load_attribute(ABAC::Attribute&)
      load attribute credential from attribute structure
-     (c:abac_context_load_attribute)
+     (C:abac_context_load_attribute)
 
    int load_attribute_file(char *)
      load attribute credential from a file
-     (c:abac_context_load_attribute_file)
+     (C:abac_context_load_attribute_file)
 
    int load_attribute_chunk(abac_chunk_t)
      load attribute credential from a chunk
-     (c:abac_context_load_attribute_chunk)
+     (C:abac_context_load_attribute_chunk)
 
      returns the same values as above, additionally
@@ -512,14 +590,15 @@
         then: ${path}/*_IDKEY.{der,pem} as id/key combo certificate
         last: ${path}/*_attr.der as attribute certificates 
+      (C:abac_context_load_directory)
 
    std::vector<Attribute> query(char *, char *, bool &)
      the string version is for query that is composed by hand with SHA or
      in non ABAC_CN mode  
-     (c:abac_context_query)
+     (C:abac_context_query)
 
    std::vector<Attribute> query(Role &, Role &, bool &)
-     (c:abac_context_query_with_structure)
+     (C:abac_context_query_with_structure)
    std::vector<Attribute> query(Oset &, Oset &, bool &)
-     (c:abac_context_query_with_structure)
+     (C:abac_context_query_with_structure)
      runs the query:
        role <-?- principal
@@ -532,8 +611,10 @@
      returns a vector of all the credentials loaded in the context
      extracted from the internal data structure
+     (C:abac_context_credentials)
 
    std::vector<Attribute> context_principals(bool &)
      returns a vector of all the principals loaded in the context
      extracted from the internal data structure
+     (C:abac_context_principals)
 
    char *version()
@@ -543,20 +624,32 @@
 The C API is nearly identical to the C++ API. Due to lack of namespaces,
 all function names are preceeded by abac_. Furthermore, the parameter
-representing the object must be passed explicitly.
-
-Example:
-
-    C++:    ctx.load_attribute_file("test_attr.der");
-    C:      abac_context_load_attribute_file(ctx, "test_attr.der");
-
-Instead of copy constructors, the C API uses _dup. Therefore, to copy a
-role use abac_role_dup(role_t *), to copy a context use
-abac_context_dup(context_t *), and to copy a credential use
-abac_credential_dup(abac_credential_t *).
-
-abac_context_query() and abac_context_credentials() return
-NULL-terminated arrays of Credential objects (abac_credential_t * in C).
+representing the object must be passed explicitly. Each of the C++ calls
+are appended with a matching C routine call. The C function declaration 
+can be found in abac.h
+
+Examples:
+
+    C++:    head.role_name()
+    C:      abac_role_name(head)
+    or 
+    C++:    ctxt.load_attribute_file("test_attr.der")
+    C:      abac_context_load_attribute_file(ctx, "test_attr.der")
+
+Instead of copy constructors, the C API uses _dup.  Therefore,
+to copy a role use abac_aspect_dup(m_role), 
+to copy a oset use abac_aspect_dup(m_oset),
+to copy a context use abac_context_dup(m_ctx),
+to copy a constraint use abac_condition_dup(m_constraint),
+to copy a data term use abac_term_dup(m_term),
+to copy a ID use abac_id_dup(m_id) 
+and to copy an attribute use abac_attribute_dup(m_attr)
+
+Various flavors of abac_context_query() and abac_context_credentials() 
+return NULL-terminated arrays of Attribute objects (abac_credential_t * in C).
+abac_context_principals() returns NULL-terminated array of ID objects
+(abac_id_credential_t * in C)
+
 When you are done with them, you must free the whole array at once using
-abac_context_credentials_free().
+abac_context_credentials_free() and abac_context_principals_free() respectively.
 
 PERL AND PYTHON API
