Annotation of libwww/Library/src/HTAAUtil.html, revision 2.1
2.1 ! luotonen 1: <HEAD>
! 2: </HEAD>
! 3: <BODY>
! 4: <H1>Common Parts of Authorization Module to Both Server And Browser</H1>
! 5:
! 6:
! 7: This module is the interface to the common parts of Access
! 8: Authorization (AA) package for both server and browser.
! 9:
! 10: <B>Important</B> to know about memory allocation:<P>
! 11:
! 12: Routines in this module use dynamic allocation, but free
! 13: automatically all the memory reserved by them.
! 14: <P>
! 15: Therefore the caller never has to (and never should)
! 16: <CODE>free()</CODE> any object returned by these functions.
! 17: <P>
! 18: Therefore also all the strings returned by this package
! 19: are only valid until the next call to the same function
! 20: is made. This approach is selected, because of the nature
! 21: of access authorization: no string returned by the package
! 22: needs to be valid longer than until the next call.
! 23: <P>
! 24: This also makes it easy to plug the AA package in:
! 25: you don't have to ponder whether to <CODE>free()</CODE>
! 26: something here or is it done somewhere else (because it
! 27: is always done somewhere else).
! 28: <P>
! 29: The strings that the package needs to store are copied
! 30: so the original strings given as parameters to AA
! 31: functions may be freed or modified with no side effects.
! 32: <P>
! 33: <B>Also note:</B>
! 34: The AA package does not <CODE>free()</CODE> anything else
! 35: than what it has itself allocated.
! 36: <P>
! 37:
! 38: <PRE>
! 39: #ifndef HTAAUTIL_H
! 40: #define HTAAUTIL_H
! 41:
! 42: #include "HTUtils.h" /* BOOL, PARAMS, ARGS */
! 43: #include "HTList.h"
! 44:
! 45:
! 46: #ifdef SHORT_NAMES
! 47: #define HTAASenu HTAAScheme_enum
! 48: #define HTAASnam HTAAScheme_name
! 49: #define HTAAMenu HTAAMethod_enum
! 50: #define HTAAMnam HTAAMethod_name
! 51: #define HTAAMinL HTAAMethod_inList
! 52: #define HTAAteMa HTAA_templateMatch
! 53: #define HTAAmaPT HTAA_makeProtectionTemplate
! 54: #define HTAApALi HTAA_parseArgList
! 55: #define HTAAsuRe HTAA_setupReader
! 56: #define HTAAgUfL HTAA_getUnfoldedLine
! 57: #endif /*SHORT_NAMES*/
! 58:
! 59:
! 60: /*
! 61: ** Default filenames
! 62: */
! 63:
! 64: #ifndef PASSWD_FILE
! 65: #define PASSWD_FILE "/home2/luotonen/passwd"
! 66: #endif
! 67:
! 68: #ifndef GROUP_FILE
! 69: #define GROUP_FILE "/home2/luotonen/group"
! 70: #endif
! 71:
! 72: #define ACL_FILE_NAME ".www_acl"
! 73:
! 74:
! 75: /*
! 76: ** Numeric constants
! 77: */
! 78: #define MAX_USERNAME_LEN 16 /* @@ Longest allowed username */
! 79: #define MAX_PASSWORD_LEN 3*13 /* @@ Longest allowed password */
! 80: /* (encrypted, so really only 3*8)*/
! 81: #define MAX_METHODNAME_LEN 12 /* @@ Longest allowed method name */
! 82: #define MAX_FIELDNAME_LEN 16 /* @@ Longest field name in */
! 83: /* protection setup file */
! 84: #define MAX_PATHNAME_LEN 80 /* @@ Longest passwd/group file */
! 85: /* patname to allow */
! 86:
! 87: /*
! 88: ** External functions
! 89: */
! 90: extern int fprintf(), fclose(), ungetc(), toupper(), read(), write();
! 91: extern int pipe(), fork(), close(), wait3(), time(), fflush();
! 92:
! 93: /*
! 94: ** Helpful macros
! 95: */
! 96: #define FREE(x) if (x) {free(x); x=NULL;}
! 97:
! 98: </PRE>
! 99:
! 100:
! 101:
! 102: <H2>Datatype definitions</H2>
! 103:
! 104: <H3>HTAAScheme</H3>
! 105:
! 106: The enumeration <CODE>HTAAScheme</CODE> represents the possible
! 107: authentication schemes used by the WWW Access Authorization.
! 108: <PRE>
! 109: typedef enum {
! 110: HTAA_UNKNOWN,
! 111: HTAA_NONE,
! 112: HTAA_BASIC,
! 113: HTAA_PUBKEY,
! 114: HTAA_KERBEROS_V4,
! 115: HTAA_KERBEROS_V5,
! 116: HTAA_MAX_SCHEMES /* THIS MUST ALWAYS BE LAST! Number of schemes */
! 117: } HTAAScheme;
! 118: </PRE><P>
! 119:
! 120: <H3>Enumeration to Represent HTTP Methods</H3>
! 121: <PRE>
! 122: typedef enum {
! 123: METHOD_UNKNOWN,
! 124: METHOD_GET,
! 125: METHOD_PUT
! 126: } HTAAMethod;
! 127: </PRE><P>
! 128:
! 129:
! 130:
! 131: <H2>Authentication Schemes</H2>
! 132:
! 133: <PRE>
! 134: /* PUBLIC HTAAScheme_enum()
! 135: ** TRANSLATE SCHEME NAME TO A SCHEME ENUMERATION
! 136: ** ON ENTRY:
! 137: ** name is a string representing the scheme name.
! 138: **
! 139: ** ON EXIT:
! 140: ** returns the enumerated constant for that scheme.
! 141: */
! 142: PUBLIC HTAAScheme HTAAScheme_enum PARAMS((CONST char* name));
! 143:
! 144:
! 145: /* PUBLIC HTAAScheme_name()
! 146: ** GET THE NAME OF A GIVEN SCHEME
! 147: ** ON ENTRY:
! 148: ** scheme is one of the scheme enum values:
! 149: ** HTAA_NONE, HTAA_BASIC, HTAA_PUBKEY, ...
! 150: **
! 151: ** ON EXIT:
! 152: ** returns the name of the scheme, i.e.
! 153: ** "none", "basic", "pubkey", ...
! 154: */
! 155: PUBLIC char *HTAAScheme_name PARAMS((HTAAScheme scheme));
! 156: </PRE>
! 157:
! 158:
! 159:
! 160: <H2>Methods</H2>
! 161:
! 162: <PRE>
! 163: /* PUBLIC HTAAMethod_enum()
! 164: ** TRANSLATE METHOD NAME INTO AN ENUMERATED VALUE
! 165: ** ON ENTRY:
! 166: ** name is the method name to translate.
! 167: **
! 168: ** ON EXIT:
! 169: ** returns HTAAMethod enumerated value corresponding
! 170: ** to the given name.
! 171: */
! 172: PUBLIC HTAAMethod HTAAMethod_enum PARAMS((CONST char * name));
! 173:
! 174:
! 175: /* PUBLIC HTAAMethod_name()
! 176: ** GET THE NAME OF A GIVEN METHOD
! 177: ** ON ENTRY:
! 178: ** method is one of the method enum values:
! 179: ** METHOD_GET, METHOD_PUT, ...
! 180: **
! 181: ** ON EXIT:
! 182: ** returns the name of the scheme, i.e.
! 183: ** "GET", "PUT", ...
! 184: */
! 185: PUBLIC char *HTAAMethod_name PARAMS((HTAAMethod method));
! 186:
! 187:
! 188: /* PUBLIC HTAAMethod_inList()
! 189: ** IS A METHOD IN A LIST OF METHOD NAMES
! 190: ** ON ENTRY:
! 191: ** method is the method to look for.
! 192: ** list is a list of method names.
! 193: **
! 194: ** ON EXIT:
! 195: ** returns YES, if method was found.
! 196: ** NO, if not found.
! 197: */
! 198: PUBLIC BOOL HTAAMethod_inList PARAMS((HTAAMethod method,
! 199: HTList * list));
! 200: </PRE>
! 201:
! 202:
! 203: <H2>Match Template Against Filename</H2>
! 204:
! 205: <PRE>
! 206: /* PUBLIC HTAA_templateMatch()
! 207: ** STRING COMPARISON FUNCTION FOR FILE NAMES
! 208: ** WITH ONE WILDCARD * IN THE TEMPLATE
! 209: ** NOTE:
! 210: ** This is essentially the same code as in HTRules.c, but it
! 211: ** cannot be used because it is embedded in between other code.
! 212: ** (In fact, HTRules.c should use this routine, but then this
! 213: ** routine would have to be more sophisticated... why is life
! 214: ** sometimes so hard...)
! 215: **
! 216: ** ON ENTRY:
! 217: ** template is a template string to match the file name
! 218: ** agaist, may contain a single wildcard
! 219: ** character * which matches zero or more
! 220: ** arbitrary characters.
! 221: ** filename is the filename (or pathname) to be matched
! 222: ** agaist the template.
! 223: **
! 224: ** ON EXIT:
! 225: ** returns YES, if filename matches the template.
! 226: ** NO, otherwise.
! 227: */
! 228: PUBLIC BOOL HTAA_templateMatch PARAMS((CONST char * template,
! 229: CONST char * filename));
! 230:
! 231:
! 232: /* PUBLIC HTAA_makeProtectionTemplate()
! 233: ** CREATE A PROTECTION TEMPLATE FOR THE FILES
! 234: ** IN THE SAME DIRECTORY AS THE GIVEN FILE
! 235: ** (Used by server if there is no fancier way for
! 236: ** it to tell the client, and by browser if server
! 237: ** didn't send WWW-ProtectionTemplate: field)
! 238: ** ON ENTRY:
! 239: ** docname is the document pathname (from URL).
! 240: **
! 241: ** ON EXIT:
! 242: ** returns a template matching docname, and other files
! 243: ** files in that directory.
! 244: **
! 245: ** E.g. /foo/bar/x.html => /foo/bar/ *
! 246: ** ^
! 247: ** Space only to prevent it from
! 248: ** being a comment marker here,
! 249: ** there really isn't any space.
! 250: */
! 251: PUBLIC char *HTAA_makeProtectionTemplate PARAMS((CONST char * docname));
! 252: </PRE>
! 253:
! 254:
! 255:
! 256: <H2>MIME Argument List Parser</H2>
! 257:
! 258: <PRE>
! 259:
! 260: /* PUBLIC HTAA_parseArgList()
! 261: ** PARSE AN ARGUMENT LIST GIVEN IN A HEADER FIELD
! 262: ** ON ENTRY:
! 263: ** str is a comma-separated list:
! 264: **
! 265: ** item, item, item
! 266: ** where
! 267: ** item ::= value
! 268: ** | name=value
! 269: ** | name="value"
! 270: **
! 271: ** Leading and trailing whitespace is ignored
! 272: ** everywhere except inside quotes, so the following
! 273: ** examples are equal:
! 274: **
! 275: ** name=value,foo=bar
! 276: ** name="value",foo="bar"
! 277: ** name = value , foo = bar
! 278: ** name = "value" , foo = "bar"
! 279: **
! 280: ** ON EXIT:
! 281: ** returns a list of name-value pairs (actually HTAssocList*).
! 282: ** For items with no name, just value, the name is
! 283: ** the number of order number of that item. E.g.
! 284: ** "1" for the first, etc.
! 285: */
! 286: PUBLIC HTList *HTAA_parseArgList PARAMS((char * str));
! 287:
! 288: </PRE>
! 289:
! 290:
! 291:
! 292: <H2>Header Line Reader</H2>
! 293: <PRE>
! 294: /* PUBLIC HTAA_setupReader()
! 295: ** SET UP HEADER LINE READER, i.e. give
! 296: ** the already-read-but-not-yet-processed
! 297: ** buffer of text to be read before more
! 298: ** is read from the socket.
! 299: ** ON ENTRY:
! 300: ** start_of_headers is a pointer to a buffer containing
! 301: ** the beginning of the header lines
! 302: ** (rest will be read from a socket).
! 303: ** length is the number of valid characters in
! 304: ** 'start_of_headers' buffer.
! 305: ** soc is the socket to use when start_of_headers
! 306: ** buffer is used up.
! 307: ** ON EXIT:
! 308: ** returns nothing.
! 309: ** Subsequent calls to HTAA_getUnfoldedLine()
! 310: ** will use this buffer first and then
! 311: ** proceed to read from socket.
! 312: */
! 313: PUBLIC void HTAA_setupReader PARAMS((char * start_of_headers,
! 314: int length,
! 315: int soc));
! 316:
! 317:
! 318: /* PUBLIC HTAA_getUnfoldedLine()
! 319: ** READ AN UNFOLDED HEADER LINE FROM SOCKET
! 320: ** ON ENTRY:
! 321: ** HTAA_setupReader must absolutely be called before
! 322: ** this function to set up internal buffer.
! 323: **
! 324: ** ON EXIT:
! 325: ** returns a newly-allocated character string representing
! 326: ** the read line. The line is unfolded, i.e.
! 327: ** lines that begin with whitespace are appended
! 328: ** to current line. E.g.
! 329: **
! 330: ** Field-Name: Blaa-Blaa
! 331: ** This-Is-A-Continuation-Line
! 332: ** Here-Is_Another
! 333: **
! 334: ** is seen by the caller as:
! 335: **
! 336: ** Field-Name: Blaa-Blaa This-Is-A-Continuation-Line Here-Is_Another
! 337: **
! 338: */
! 339: PUBLIC char *HTAA_getUnfoldedLine NOPARAMS;
! 340: </PRE>
! 341:
! 342:
! 343: <PRE>
! 344: #endif /* NOT HTAAUTIL_H */
! 345: </PRE>
! 346: End of file HTAAUtil.h.
! 347: </BODY>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTAAUtil.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src