#ifndef AK_CAP_H
#define AK_CAP_H

/**
  * A minimal C interface to a capabilty certificate. It consists
  * of C-style opaque pointers to a number of C++ classes and C 
  * functions to manipulate these pointers.                     <BR>
  *
  * List of C++ objects that are wrapped:                       <BR>
  *                                                             <PRE> 
  *       CapabilityCertificate
  *       AkentiPrincipal 
  *       AttributeInfo 
  *       UtcTime
  *       PublicKey
  *       ConditionalActions
  *
  * Usage:                                                       
  *
  *    // CALL BACK FUNCTION.
  *
  *    int doEvaluate(ExprToken op, const AttrInfo info) {
  *        const char* attribute = getAttribute(info);
  *        const char* value = getAttribute(info);
  *
  *        if (...) {
  *          return 1;    // SUCCESS
  *        } else {
  *          return 0;    // FAILURE
  *        }
  *    }
  *
  *    void someFunction() {
  *        CapCert cert = NULL;
  *        AKPrincipal subject;
  *        char* resource;
  *        int version;
  *
  *        if (initFromFile("PEM", "cap", &cert)) {
  *          printf("initFromFile Failed\n");
  *          freeCapCert(cert);
  *          return;
  *        }
  *       
  *        version = getVersionNumber(cert);
  *        resource = (char*) getResource(cert);
  *        subject = (AKPrincipal) getSubject(cert);
  *
  *        ...
  *
  *        if (hasGrantedActions(cert)) {
  *          int size = numOfGrantedActions(cert);
  *
  *          for (int i = 0; i < size; ++i) {
  *             const char* action = grantedActionAt(cert, i); 
  *             ...
  *          }
  *        }
  *
  *        if (hasCondActions(cert)) {
  *          int size = numOfCondActions(cert);
  *          int i;
  *
  *          for (i = 0; i < size; ++i) {
  *             const CondActions condActions = condActionsAt(cert, i);
  *             
  *             if (evaluate(condActions, doEvaluate, NULL)) {
  *               int j;
  *
  *               for (j = 0; j < numOfActions(condActions); ++j) {
  *                  const char* action = actionAt(condActions, j);  //allow this action
  *               }
  *             } else if (isCritical(condActions)) {
  *               // DENY ACCESS 
  *             } 
  *          }
  *        }
  *
  *        freeCapCert(cert);
  *    }
  *
  *                                                             </PRE> 
  */
#ifdef __cplusplus
#include "CapabilityCertificate.hpp"
#include "AkentiMessage.hpp"
#include "TokenType.hpp"
typedef Akenti::CapabilityCertificate* CapCert;
typedef Akenti::AkentiMessage* AKMessage ;
typedef Akenti::AkentiPrincipal* AKPrincipal;
typedef Akenti::PublicKey* PubKey;
typedef Akenti::UtcTime* UTCTime;
typedef Akenti::ConditionalActions* CondActions;
typedef Akenti::AttributeInfo* AttrInfo;
typedef Akenti::AttributeInfo::Type AttrType;
typedef Akenti::TokenType ExprToken;
extern "C" {
#else 
typedef struct AkentiMessage* AKMessage;
typedef struct CapabilityCertificate* CapCert;
typedef struct AkentiPrincipal* AKPrincipal;
typedef struct PublicKey* PubKey;
typedef struct UtcTime* UTCTime;
typedef struct ConditionalActions* CondActions;
typedef struct AttributeInfo* AttrInfo;
typedef enum { AK_SYSTEM, AK_X509, AK_AKENTI, AK_EXT_AUTH } AttrType;
typedef enum { AK_CONST, AK_AND, AK_OR, AK_NOT,AK_LPAREN,AK_RPAREN, 
               AK_GR, AK_GRE, AK_LT, AK_LTE, AK_EQ, AK_NEQ,AK_INVALID } ExprToken;
#endif

/**
  * Initializes a <i>CapCert</i> from a string.
  *
  * @param encType PEM or XML.
  * @param certString a string containing an encoded capability certificate.
  * @param cert the capablity certificate.
  * @return 0 if successful.
  *
  * @see CapCert_free(CapCert)
  */
int CapCert_initFromString(const char* encType, 
                           const char* certString, 
                           CapCert* cert); 

/**
  * Initializes a <i>CapCert</i> from a <i>PEM</i> file.
  *
  * @param encType PEM or XML.
  * @param filename name of a file containing an encoded capability certificate.
  * @param cert the capablity certificate.
  * @return 0 if successful.
  *
  * @see CapCert_free(CapCert)
  */
int CapCert_initFromFile(const char* encType,
                         const char* fileName,
                         CapCert* cert); 
/**
  * Writes cert to buffer.
  *
  * @param encType PEM or XML.
  * @param cert the capablity certificate. 
  * @param buffer used to hold the encoded capablity certificate. 
  * @return numOfBytes in the string representation of the certificate if successful
  */
int CapCert_writeToBuffer(const char* encType, 
                          const CapCert cert,
                          char* buffer);
/**
  * Writes cert to file.
  *
  * @param encType PEM or XML.
  * @param cert the capablity certificate .
  * @param filename name of a file to store the capablity certificate.
  * @return 0 if successful.
  *
  */
int CapCert_writeToFile(const char* encType, 
                        const CapCert cert,
                        const char* fileName);
/**
  * Writes pretty text to buffer.
  *
  * @param cert the capablity certificate. 
  * @param buffer used to hold the pretty text. 
  * @return numOfBytes in the string representation of the certificate if successful
  */
int CapCert_toText(const CapCert cert, char* buffer); 

/**
  * Destroys a <i>CapCert</i>.
  *
  * @param cert a pointer to a capability certificate.
  */
void CapCert_free(CapCert cert);

/**
  * Returns the version number of the capability certificate.
  *
  * @param cert a pointer to a capability certificate
  */
int CapCert_getVersionNumber(const CapCert cert);

/**
  * Returns the subject of the capability certificate.
  *
  * @param cert a pointer to a capability certificate,
  *
  * @return an AkPrincipal pointer that contains the DN and CA
  *        of the subject of this certificate.
  *
  * @see CapCert_getName(const AKPrincipal)
  * @see CapCert_getGuarantor(const AKPrincipal)
  */
const AKPrincipal CapCert_getSubject(const CapCert cert);

/**
  * Returns the subject's public key from the capability certificate.
  *
  * @param cert a pointer to a capability certificate
  *
  * @return a PEM encoded public key
  */
const PubKey CapCert_getSubjectPublicKey(const CapCert cert);

/**
  * Returns the name of the resource that the capability certificate 
  *           applies to.
  *
  * @param cert a pointer to a capability certificate
  *
  * @return a string containing the name of resource to which the
  *       capability applies
  */
const char* CapCert_getResource(const CapCert cert);

/**
  * Returns the issuer of the capability certificate.
  *
  * @param cert a pointer to a capability certificate
  *
  * @return an AkPrincipal pointer that contains the DN and CA
  *        of the issuer of this certificate.
  *
  * @see CapCert_getName(const AKPrincipal)
  * @see CapCert_getGuarantor(const AKPrincipal)
  */
const AKPrincipal CapCert_getIssuer(const CapCert cert);

/**
  * Returns the time before which the capability certificate is not valid. 
  *
  * @param cert a pointer to a capability certificate
  *
  * @return a UCTTime pointer before which this certificate is not valid
  * @see UTCT_toUtcSting(const UTCTime)
  */
const UTCTime CapCert_getNotBefore(const CapCert cert);

/**
  * Returns the time after which the capability certificate is no longer valid.
  *
  * @param cert a pointer to a capability certificate
  *
  * @return a UCTTime pointer after which this certificate is not valid
  * @see UTCT_toUtcSting(const UTCTime)
  */
const UTCTime CapCert_getNotAfter(const CapCert cert);

/**
  * Checks the validity time of the capability certificate.
  *
  * @param cert a pointer to a capability certificate
  *
  * @return 1 if notBefore<= now <= notAfter,
  *         0 otherwise
  *
  * @see CapCert_getNotBefore(const CapCert)
  * @see CapCert_getNotAfter(const CapCert)
  */
int CapCert_checkValidity(const CapCert cert);

/**
  * Checks if there are granted unconditional actions in a <i>CapCert</i>.
  *
  * @param cert a pointer to a capability certificate
  *
  * @return 1 if there is at least one action,
  *         0 otherwise 
  */
int CapCert_hasGrantedActions(const CapCert cert);

/**
  * Returns the number of granted actions in a <i>CapCert</i>.  
  *
  * @param cert a pointer to a capability certificate
  *
  * @return 1 if there is at least one action,
  *         0 otherwise 
  * @see CapCert_grantedActionAt
  */
int CapCert_numOfGrantedActions(const CapCert cert);

/**
  * Returns the action at index <i>idx</i>.
  *
  * @param cert a pointer to a capability certificate
  *
  * @see CapCert_numOfGrantedActions(const CapCert)
  */
const char* CapCert_grantedActionAt(const CapCert cert, int idx);

/**
  * Checks if there are <i>CondActions</i> in a <i>CapCert</i>.
  *
  * @param cert a pointer to a capability certificate
  *
  * @return 1 if there is at least one CondActions,
  *         0 otherwise 
  */
int CapCert_hasCondActions(const CapCert cert);

/**
  * Returns the number of <i>CondActions<i> in a <i>CapabilityCertificate</i>.
  *
  * @param cert a pointer to a capability certificate
  * @return the number of conditional actions
  *
  * @see CapCert_condActionsAt
  */
int CapCert_numOfCondActions(const CapCert cert);

/**
  * Returns the <i>CondActions</i> at index <i>idx</i>.
  *
  * @param cert a pointer to a capability certificate
  *
  * @see CapCert_numOfCondActions(const CapCert)
  */
const CondActions CapCert_condActionsAt(const CapCert cert, int idx);

/**
  * Copies the <i>AKPrincipal</i>'s distinguished name 
  * into <i>buff</i>. This function should be called first with
  * buff equal to NULL to get the length of the distinguished name.
  * Then a buffer should be allocated by the caller of that length
  * and this method called again to fill in the buffer
  *
  * @param ap a pointer to an AkPrincipal
  * @param buff if NULL only the length of the DN will be returned
  *        if non-NULL a pointer to a buffer into which the DN will be coppied
  *
  * @return the length of the dn.
  */
int AKPrin_getName(const AKPrincipal ap, char* buff);

/**
  * Copies the <i>AKPrincipal</i>'s CA's distinguished name 
  * into <i>buff</i>.This function should be called first with
  * buff equal to NULL to get the length of the distinguished name.
  * Then a buffer should be allocated by the caller of that length
  * and this method called again to fill in the buffer
  *
  * @param ap a pointer to an AkPrincipal
  * @param buff if NULL only the length of the DN will be returned
  *        if non-NULL a pointer to a buffer into which the CA's DN 
  *        will be coppied
  * 
  * @return the length of the ca's dn.
  */
int AKPrin_getGuarantor(const AKPrincipal, char* buff);

/**
  * Copies the <i>UTCTime</i>'s string representation.
  * This function should be first called with buff equal to NULL
  * to get the length of the string representation.  
  * Then a buffer should be allocated by the caller of that length
  * and this method called again to fill in the buffer
  *
  * @param utc pointer to a time in UTC format
  * @param buff f NULL only the length of the time string will be returned
  *        if non-NULL a pointer to a buffer into which the string 
  *        representaion of the time will be coppied 
  * @return the length of the string represenation.
  */
int UTCT_toUtcString(const UTCTime utc, char* buff);

/**
  * Returns the constraint string from a CondActions pointer.
  *
  * @param condActions a pointer to a conditional action structure/class
  *
  * @return a string representation of the constraint.
  *
  * @see CapCert_numOfCondActions
  * @see CapCert_condActionsAt
  */
const char* CondAct_getConstraint(const CondActions condActions);

/**
  * Return whether the constraint must be satisfied. If any critical
  *        contraint is not satisified the user should get no rights 
  *        (including any unconditional rights) to the resource.
  *
  * @param condActions a pointer to a conditional action structure/class
  *
  * @return  1 if the condition is critical
  *          0 if it is not critical
  *
  * @see  CapCert_numOfCondActions
  * @see  CapCert_condActionsAt
  */
int CondAct_isCritical(const CondActions condActions);

/**
  * Returns the number of actions in CondActions.
  *
  * @param condActions a pointer to a conditional action structure/class
  *
  * @return number of actions
  *
  * @see CondAct_actionAt
  */
int CondAct_numOfActions(const CondActions condActions);

/**
  * Returns the action at index <i>idx</i>. Once numOfActions has been
  * called, this method can be used to find each of the actions.
  *
  * @param condActions a pointer to a conditional action structure/class
  * @param idx the index of the action.
  *
  * @return a string containing a single action
  *
  * @see CondAct_numOfActions
  */
const char* CondAct_actionAt(const CondActions, int idx);

/**
  * Returns the number of <i>AttrInfo</i>s in CondActions.
  *
  * @param condActions a pointer to a conditional action structure/class
  *
  * @return the number of AttrInfo for this conditional action.
  * 
  * @see CondAct_attrInfoAt
  */
int CondAct_numOfAttrInfos(const CondActions condActions);

/**
  * Returns the <i>AttrInfo</i> at index <i>idx</i>. Once numOfAttrInfos
  * has been called, this method is used to extract each AttrInfo.
  *
  * @param condActions a pointer to a conditional action structure/class
  * @param idx the index of the attrInfo.
  *
  * @return a AttrInfo pointer to a structure or class
  *
  * @see CondAct_numOfAttrInfos
  * @see Attr_getType, Attr_getAttributeName, Attr_ getValue
  */
const AttrInfo CondAct_AttrInfoAt(const CondActions condActions, int idx);
  
/**
  * Returns the type of an Attibute. Type will be "SYSTEM" or "EXT_AUTH"
  *
  * @param info a pointer to a AttributeInfo class object
  *
  * @return the type of the Attribute. It should be SYSTEM or EXT_AUTH
  *       since X509 and AKENTI attributes are already evaluated
  *       
  * @see Attr_getAttributeName, Attr_getValue
  * @see AttributeInfo 
  */
AttrType Attr_getType(const AttrInfo info);

/**
  * Returns the name of an attribute.
  *
  * @param info a pointer to a AttributeInfo class object
  *
  * @return a string containing the name of the attribute
  *
  * @see getAttribute, getValue
  * @see AttributeInfo 
  */
const char* Attr_getAttributeName(const AttrInfo info);

/**
  * Returns the value of the attribute.It is assumed that the caller
  * of the getAttribute and getValue methods can evaluate whether the
  * contraint is met. See the evaluate method for an alternative way
  * to evaluate all the CondActions.
  *
  * @param info a pointer to a AttributeInfo class object
  *
  * @return a string containing the value  of the attribute
  *
  * @see Attr_getAttributName, CondAct_evaluate
  * @see AttributeInfo 
  */
const char* Attr_getValue(const AttrInfo info);

/**
  * Returns the status code rom an AKMessage
  *
  * @param mesg pointer to an AkentiMessage class
  *
  * @return the numeric value of the error.
  *
  * @see AKMsg_getDescription, AKMsg_free
  * @see AkentiMessage  
  */
int AKMsg_getCode(AKMessage mesg);

/**
  * Returns the description of an AKMessage
  *
  * @param mesg pointer to an AkentiMessage class
  *
  * @return the description of the message
  *
  * @see AKMsg_getCode, AKMsg_free
  * @see AkentiMessage  
  */
const char* AKMsg_getDescription(AKMessage mesg);

/**
  * Frees an AKMessage.  The checkAccess methods allocate AKMessages
  * in which they return the error status. 
  * When you are no longer using an AKMessage, it should be freed.
  *
  * @param mesg pointer to an AkentiMessage class
  *
  * @see getMessage,
  */
void AKMsg_free(AKMessage mesg);

#ifdef __cplusplus
}
#endif

#endif /* AK_CAP_H */