/*
 * $LynxId: HTAAUtil.h,v 1.13 2010/10/27 00:09:52 tom Exp $
 *
 *                                            Utilities for the Authorization parts of libwww
 *           COMMON PARTS OF AUTHORIZATION MODULE TO BOTH SERVER AND BROWSER
 *
 * This module is the interface to the common parts of Access Authorization (AA) package
 * for both server and browser.  Important to know about memory allocation:
 *
 * Routines in this module use dynamic allocation, but free automatically all the memory
 * reserved by them.
 *
 * Therefore the caller never has to (and never should) free() any object returned by
 * these functions.
 *
 * Therefore also all the strings returned by this package are only valid until the next
 * call to the same function is made. This approach is selected, because of the nature of
 * access authorization: no string returned by the package needs to be valid longer than
 * until the next call.
 *
 * This also makes it easy to plug the AA package in: you don't have to ponder whether to
 * free() something here or is it done somewhere else (because it is always done somewhere
 * else).
 *
 * The strings that the package needs to store are copied so the original strings given as
 * parameters to AA functions may be freed or modified with no side effects.
 *
 * Also note: The AA package does not free() anything else than what it has itself
 * allocated.
 *
 */

#ifndef HTAAUTIL_H
#define HTAAUTIL_H

#include <HTList.h>

#ifdef __cplusplus
extern "C" {
#endif
/*
 * Numeric constants
 */
#define MAX_USERNAME_LEN        16	/* @@ Longest allowed username    */
#define MAX_PASSWORD_LEN        3*13	/* @@ Longest allowed password    */
    /* (encrypted, so really only 3*8) */
#define MAX_METHODNAME_LEN      12	/* @@ Longest allowed method name */
#define MAX_FIELDNAME_LEN       16	/* @@ Longest field name in       */
    /* protection setup file          */
#define MAX_PATHNAME_LEN        80	/* @@ Longest passwd/group file   */
/* pathname to allow               */
/*

   Datatype definitions

   HTAASCHEME

   The enumeration HTAAScheme represents the possible authentication schemes used by the
   WWW Access Authorization.

 */ typedef enum {
	HTAA_UNKNOWN,
	HTAA_NONE,
	HTAA_BASIC,
	HTAA_PUBKEY,
	HTAA_KERBEROS_V4,
	HTAA_KERBEROS_V5,
	HTAA_MAX_SCHEMES	/* THIS MUST ALWAYS BE LAST! Number of schemes */
    } HTAAScheme;

/*

  ENUMERATION TO REPRESENT HTTP METHODS

 */

    typedef enum {
	METHOD_UNKNOWN,
	METHOD_GET,
	METHOD_PUT
    } HTAAMethod;

/*

Authentication Schemes

 */

/* PUBLIC                                               HTAAScheme_enum()
 *              TRANSLATE SCHEME NAME TO A SCHEME ENUMERATION
 * ON ENTRY:
 *      name            is a string representing the scheme name.
 *
 * ON EXIT:
 *      returns         the enumerated constant for that scheme.
 */
    extern HTAAScheme HTAAScheme_enum(const char *name);

/* PUBLIC                                               HTAAScheme_name()
 *                      GET THE NAME OF A GIVEN SCHEME
 * ON ENTRY:
 *      scheme          is one of the scheme enum values:
 *                      HTAA_NONE, HTAA_BASIC, HTAA_PUBKEY, ...
 *
 * ON EXIT:
 *      returns         the name of the scheme, i.e.
 *                      "none", "basic", "pubkey", ...
 */
    extern const char *HTAAScheme_name(HTAAScheme scheme);

/*

Methods

 */

/* PUBLIC                                                   HTAAMethod_enum()
 *              TRANSLATE METHOD NAME INTO AN ENUMERATED VALUE
 * ON ENTRY:
 *      name            is the method name to translate.
 *
 * ON EXIT:
 *      returns         HTAAMethod enumerated value corresponding
 *                      to the given name.
 */
    extern HTAAMethod HTAAMethod_enum(const char *name);

/* PUBLIC                                               HTAAMethod_name()
 *                      GET THE NAME OF A GIVEN METHOD
 * ON ENTRY:
 *      method          is one of the method enum values:
 *                      METHOD_GET, METHOD_PUT, ...
 *
 * ON EXIT:
 *      returns         the name of the scheme, i.e.
 *                      "GET", "PUT", ...
 */
    extern const char *HTAAMethod_name(HTAAMethod method);

/* PUBLIC                                               HTAAMethod_inList()
 *              IS A METHOD IN A LIST OF METHOD NAMES
 * ON ENTRY:
 *      method          is the method to look for.
 *      list            is a list of method names.
 *
 * ON EXIT:
 *      returns         YES, if method was found.
 *                      NO, if not found.
 */
    extern BOOL HTAAMethod_inList(HTAAMethod method, HTList *list);

/*

Match Template Against Filename

 */

/* PUBLIC                                               HTAA_templateMatch()
 *              STRING COMPARISON FUNCTION FOR FILE NAMES
 *                 WITH ONE WILDCARD * IN THE TEMPLATE
 * NOTE:
 *      This is essentially the same code as in HTRules.c, but it
 *      cannot be used because it is embedded in between other code.
 *      (In fact, HTRules.c should use this routine, but then this
 *       routine would have to be more sophisticated... why is life
 *       sometimes so hard...)
 *
 * ON ENTRY:
 *      ctemplate       is a template string to match the file name
 *                      against, may contain a single wildcard
 *                      character * which matches zero or more
 *                      arbitrary characters.
 *      filename        is the filename (or pathname) to be matched
 *                      against the template.
 *
 * ON EXIT:
 *      returns         YES, if filename matches the template.
 *                      NO, otherwise.
 */
    extern BOOL HTAA_templateMatch(const char *ctemplate,
				   const char *filename);

/* PUBLIC                                               HTAA_templateCaseMatch()
 *              STRING COMPARISON FUNCTION FOR FILE NAMES
 *                 WITH ONE WILDCARD * IN THE TEMPLATE (Case Insensitive)
 * NOTE:
 *      This is essentially the same code as in HTAA_templateMatch, but
 *      it compares case insensitive (for VMS). Reason for this routine
 *      is that HTAA_templateMatch gets called from several places, also
 *      there where a case sensitive match is needed, so one cannot just
 *      change the HTAA_templateMatch routine for VMS.
 *
 * ON ENTRY:
 *      ctemplate       is a template string to match the file name
 *                      against, may contain a single wildcard
 *                      character * which matches zero or more
 *                      arbitrary characters.
 *      filename        is the filename (or pathname) to be matched
 *                      against the template.
 *
 * ON EXIT:
 *      returns         YES, if filename matches the template.
 *                      NO, otherwise.
 */
    extern BOOL HTAA_templateCaseMatch(const char *ctemplate,
				       const char *filename);

/* PUBLIC                                       HTAA_makeProtectionTemplate()
 *              CREATE A PROTECTION TEMPLATE FOR THE FILES
 *              IN THE SAME DIRECTORY AS THE GIVEN FILE
 *              (Used by server if there is no fancier way for
 *              it to tell the client, and by browser if server
 *              didn't send WWW-ProtectionTemplate: field)
 * ON ENTRY:
 *      docname is the document pathname (from URL).
 *
 * ON EXIT:
 *      returns a template matching docname, and other files
 *              files in that directory.
 *
 *              E.g.  /foo/bar/x.html  =>  /foo/bar/ *
 *                                                  ^
 *                              Space only to prevent it from
 *                              being a comment marker here,
 *                              there really isn't any space.
 */
    extern char *HTAA_makeProtectionTemplate(const char *docname);

/*

MIME Argument List Parser

 */

/* PUBLIC                                               HTAA_parseArgList()
 *              PARSE AN ARGUMENT LIST GIVEN IN A HEADER FIELD
 * ON ENTRY:
 *      str     is a comma-separated list:
 *
 *                      item, item, item
 *              where
 *                      item ::= value
 *                             | name=value
 *                             | name="value"
 *
 *              Leading and trailing whitespace is ignored
 *              everywhere except inside quotes, so the following
 *              examples are equal:
 *
 *                      name=value,foo=bar
 *                       name="value",foo="bar"
 *                        name = value ,  foo = bar
 *                         name = "value" ,  foo = "bar"
 *
 * ON EXIT:
 *      returns a list of name-value pairs (actually HTAssocList*).
 *              For items with no name, just value, the name is
 *              the number of order number of that item. E.g.
 *              "1" for the first, etc.
 */
    extern HTList *HTAA_parseArgList(char *str);

/*

Header Line Reader

 */

/* PUBLIC                                               HTAA_setupReader()
 *              SET UP HEADER LINE READER, i.e., give
 *              the already-read-but-not-yet-processed
 *              buffer of text to be read before more
 *              is read from the socket.
 * ON ENTRY:
 *      start_of_headers is a pointer to a buffer containing
 *                      the beginning of the header lines
 *                      (rest will be read from a socket).
 *      length          is the number of valid characters in
 *                      'start_of_headers' buffer.
 *      soc             is the socket to use when start_of_headers
 *                      buffer is used up.
 * ON EXIT:
 *      returns         nothing.
 *                      Subsequent calls to HTAA_getUnfoldedLine()
 *                      will use this buffer first and then
 *                      proceed to read from socket.
 */
    extern void HTAA_setupReader(char *start_of_headers,
				 size_t length,
				 int soc);

/* PUBLIC                                               HTAA_getUnfoldedLine()
 *              READ AN UNFOLDED HEADER LINE FROM SOCKET
 * ON ENTRY:
 *      HTAA_setupReader must absolutely be called before
 *      this function to set up internal buffer.
 *
 * ON EXIT:
 *      returns a newly-allocated character string representing
 *              the read line.  The line is unfolded, i.e.
 *              lines that begin with whitespace are appended
 *              to current line.  E.g.
 *
 *                      Field-Name: Blaa-Blaa
 *                       This-Is-A-Continuation-Line
 *                       Here-Is_Another
 *
 *              is seen by the caller as:
 *
 *      Field-Name: Blaa-Blaa This-Is-A-Continuation-Line Here-Is_Another
 *
 */
    extern char *HTAA_getUnfoldedLine(void);

#ifdef __cplusplus
}
#endif
#endif				/* NOT HTAAUTIL_H */