home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / Tools / lynx-2.4 / WWW / Library / Implementation / HTAABrow.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-06-28  |  5.4 KB  |  138 lines
  1. /*                          BROWSER SIDE ACCESS AUTHORIZATION MODULE
  2.                                              
  3.    This module is the browser side interface to Access Authorization (AA) package.  It
  4.    contains code only for browser.
  5.    
  6.    Important to know about memory allocation:
  7.    
  8.    Routines in this module use dynamic allocation, but free automatically all the memory
  9.    reserved by them.
  10.    
  11.    Therefore the caller never has to (and never should) free() any object returned by
  12.    these functions.
  13.    
  14.    Therefore also all the strings returned by this package are only valid until the next
  15.    call to the same function is made. This approach is selected, because of the nature of
  16.    access authorization: no string returned by the package needs to be valid longer than
  17.    until the next call.
  18.    
  19.    This also makes it easy to plug the AA package in: you don't have to ponder whether to
  20.    free()something here or is it done somewhere else (because it is always done somewhere
  21.    else).
  22.    
  23.    The strings that the package needs to store are copied so the original strings given as
  24.    parameters to AA functions may be freed or modified with no side effects.
  25.    
  26.    Also note:The AA package does not free() anything else than what it has itself
  27.    allocated.
  28.    
  29.  */
  30.  
  31. #ifndef HTAABROW_H
  32. #define HTAABROW_H
  33.  
  34. #ifndef HTUTILS_H
  35. #include "HTUtils.h"            /* BOOL, PARAMS, ARGS */
  36. #endif /* HTUTILS_H */
  37. #include "HTAAUtil.h"           /* Common parts of AA */
  38.  
  39.  
  40. #ifdef SHORT_NAMES
  41. #define HTAAcoAu        HTAA_composeAuth
  42. #define HTAAsRWA        HTAA_shouldRetryWithAuth
  43. #endif /*SHORT_NAMES*/
  44.  
  45. /*
  46.  
  47. Routines for Browser Side Recording of AA Info
  48.  
  49.    Most of the browser-side AA is done by the following two functions (which are called
  50.    from file HTTP.c so the browsers using libwww only need to be linked with the new
  51.    library and not be changed at all):
  52.    
  53.       HTAA_composeAuth() composes the Authorization: line contents, if the AA package
  54.       thinks that the given document is protected. Otherwise this function returns NULL.
  55.       This function also calls the functions HTPrompt(),HTPromptPassword() and HTConfirm()
  56.       to get the username, password and some confirmation from the user.
  57.       
  58.       HTAA_shouldRetryWithAuth() determines whether to retry the request with AA or with a
  59.       new AA (in case username or password was misspelled).
  60.       
  61.  */
  62.  
  63. /* PUBLIC                                               HTAA_composeAuth()
  64. **
  65. **      COMPOSE THE ENTIRE AUTHORIZATION HEADER LINE IF WE
  66. **      ALREADY KNOW, THAT THE HOST MIGHT REQUIRE AUTHORIZATION
  67. **
  68. ** ON ENTRY:
  69. **      hostname        is the hostname of the server.
  70. **      portnumber      is the portnumber in which the server runs.
  71. **      docname         is the pathname of the document (as in URL)
  72. **
  73. ** ON EXIT:
  74. **      returns NULL, if no authorization seems to be needed, or
  75. **              if it is the entire Authorization: line, e.g.
  76. **
  77. **                 "Authorization: basic username:password"
  78. **
  79. **              As usual, this string is automatically freed.
  80. */
  81. PUBLIC char *HTAA_composeAuth PARAMS((CONST char * hostname,
  82.                                       CONST int   portnumber,
  83.                                       CONST char * docname));
  84.  
  85.  
  86. /* BROWSER PUBLIC                               HTAA_shouldRetryWithAuth()
  87. **
  88. **              DETERMINES IF WE SHOULD RETRY THE SERVER
  89. **              WITH AUTHORIZATION
  90. **              (OR IF ALREADY RETRIED, WITH A DIFFERENT
  91. **              USERNAME AND/OR PASSWORD (IF MISSPELLED))
  92. ** ON ENTRY:
  93. **      start_of_headers is the first block already read from socket,
  94. **                      but status line skipped; i.e. points to the
  95. **                      start of the header section.
  96. **      length          is the remaining length of the first block.
  97. **      soc             is the socket to read the rest of server reply.
  98. **
  99. **                      This function should only be called when
  100. **                      server has replied with a 401 (Unauthorized)
  101. **                      status code.
  102. ** ON EXIT:
  103. **      returns         YES, if connection should be retried.
  104. **                           The node containing all the necessary
  105. **                           information is
  106. **                              * either constructed if it does not exist
  107. **                              * or password is reset to NULL to indicate
  108. **                                that username and password should be
  109. **                                reprompted when composing Authorization:
  110. **                                field (in function HTAA_composeAuth()).
  111. **                      NO, otherwise.
  112. */
  113. PUBLIC BOOL HTAA_shouldRetryWithAuth PARAMS((char *     start_of_headers,
  114.                                              int        length,
  115.                                              int        soc));
  116. /*
  117.  
  118. Enabling Gateway httpds to Forward Authorization
  119.  
  120.    These functions should only be called from daemon code, and HTAAForwardAuth_reset()
  121.    must be called before the next request is handled to make sure that authorization
  122.    string isn't cached in daemon so that other people can access private files using
  123.    somebody elses previous authorization information.
  124.    
  125.  */
  126.  
  127. PUBLIC void HTAAForwardAuth_set PARAMS((CONST char * scheme_name,
  128.                                         CONST char * scheme_specifics));
  129. PUBLIC void HTAAForwardAuth_reset NOPARAMS;
  130. /*
  131.  
  132.  */
  133.  
  134. #endif  /* NOT HTAABROW_H */
  135. /*
  136.  
  137.    End of file HTAABrow.h.  */
  138.