home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1996 May / PCW596.iso / wtest / microsft / sdk / httpfilt.h < prev    next >
Text File  |  1996-01-03  |  11KB  |  427 lines
  1. /*++
  2.  
  3. Copyright (c) 1995  Microsoft Corporation
  4.  
  5. Module Name:
  6.  
  7.     httpfilt.h
  8.  
  9. Abstract:
  10.  
  11.     This module contains the Microsoft HTTP filter extension info
  12.  
  13. Revision History:
  14.  
  15. --*/
  16.  
  17. #ifndef _HTTPFILT_H_
  18. #define _HTTPFILT_H_
  19.  
  20. #ifdef __cplusplus
  21. extern "C" {
  22. #endif
  23.  
  24. //
  25. //  Current version of the filter spec is 1.0
  26. //
  27.  
  28. #define HTTP_FILTER_REVISION    MAKELONG( 0, 1);
  29.  
  30. #define SF_MAX_USERNAME         (256+1)
  31. #define SF_MAX_PASSWORD         (256+1)
  32.  
  33. #define SF_MAX_FILTER_DESC_LEN  (256+1)
  34.  
  35. //
  36. //  These values can be used with the pfnSFCallback function supplied in
  37. //  the filter context structure
  38. //
  39.  
  40. enum SF_REQ_TYPE
  41. {
  42.     //
  43.     //  Sends a complete HTTP server response header including
  44.     //  the status, server version, message time and MIME version.
  45.     //
  46.     //  Server extensions should append other information at the end,
  47.     //  such as Content-type, Content-length etc followed by an extra
  48.     //  '\r\n'.
  49.     //
  50.     //  pData - Zero terminated string pointing to optional
  51.     //      status string (i.e., "401 Access Denied") or NULL for
  52.     //      the default response of "200 OK".
  53.     //
  54.     //  ul1 - Zero terminated string pointing to optional data to be
  55.     //      appended and set with the header.  If NULL, the header will
  56.     //      be terminated with an empty line.
  57.     //
  58.  
  59.     SF_REQ_SEND_RESPONSE_HEADER,
  60.  
  61.     //
  62.     //  If the server denies the HTTP request, add the specified headers
  63.     //  to the server error response.
  64.     //
  65.     //  This allows an authentication filter to advertise its services
  66.     //  w/o filtering every request.  Generally the headers will be
  67.     //  WWW-Authenticate headers with custom authentication schemes but
  68.     //  no restriction is placed on what headers may be specified.
  69.     //
  70.     //  pData - Zero terminated string pointing to one or more header lines
  71.     //      with terminating '\r\n'.
  72.     //
  73.  
  74.     SF_REQ_ADD_HEADERS_ON_DENIAL,
  75.  
  76.     //
  77.     //  Only used by raw data filters that return SF_STATUS_READ_NEXT
  78.     //
  79.     //  ul1 - size in bytes for the next read
  80.     //
  81.  
  82.     SF_REQ_SET_NEXT_READ_SIZE
  83. };
  84.  
  85.  
  86. //
  87. //  These values are returned by the filter entry point when a new request is
  88. //  received indicating their interest in this particular request
  89. //
  90.  
  91. enum SF_STATUS_TYPE
  92. {
  93.     //
  94.     //  The filter has handled the HTTP request.  The server should disconnect
  95.     //  the session.
  96.     //
  97.  
  98.     SF_STATUS_REQ_FINISHED = 0x8000000,
  99.  
  100.     //
  101.     //  Same as SF_STATUS_FINISHED except the server should keep the TCP
  102.     //  session open if the option was negotiated
  103.     //
  104.  
  105.     SF_STATUS_REQ_FINISHED_KEEP_CONN,
  106.  
  107.     //
  108.     //  The next filter in the notification chain should be called
  109.     //
  110.  
  111.     SF_STATUS_REQ_NEXT_NOTIFICATION,
  112.  
  113.     //
  114.     //  This filter handled the notification.  No other handles should be
  115.     //  called for this particular notification type
  116.     //
  117.  
  118.     SF_STATUS_REQ_HANDLED_NOTIFICATION,
  119.  
  120.     //
  121.     //  An error occurred.  The server should use GetLastError() and indicate
  122.     //  the error to the client
  123.     //
  124.  
  125.     SF_STATUS_REQ_ERROR,
  126.  
  127.     //
  128.     //  The filter is an opaque stream filter and we're negotiating the
  129.     //  session parameters.  Only valid for raw read notification.
  130.     //
  131.  
  132.     SF_STATUS_REQ_READ_NEXT
  133. };
  134.  
  135. //
  136. //  pvNotification points to this structure for all request notification types
  137. //
  138.  
  139. typedef struct _HTTP_FILTER_CONTEXT
  140. {
  141.     DWORD          cbSize;
  142.  
  143.     //
  144.     //  This is the structure revision level.
  145.     //
  146.  
  147.     DWORD          Revision;
  148.  
  149.     //
  150.     //  Private context information for the server.
  151.     //
  152.  
  153.     PVOID          ServerContext;
  154.     DWORD          ulReserved;
  155.  
  156.     //
  157.     //  TRUE if this request is coming over a secure port
  158.     //
  159.  
  160.     BOOL           fIsSecurePort;
  161.  
  162.     //
  163.     //  A context that can be used by the filter
  164.     //
  165.  
  166.     PVOID          pFilterContext;
  167.  
  168.     //
  169.     //  Server callbacks
  170.     //
  171.  
  172.     BOOL (WINAPI * GetServerVariable) (
  173.         struct _HTTP_FILTER_CONTEXT * pfc,
  174.         LPSTR                         lpszVariableName,
  175.         LPVOID                        lpvBuffer,
  176.         LPDWORD                       lpdwSize
  177.         );
  178.  
  179.     BOOL (WINAPI * AddResponseHeaders) (
  180.         struct _HTTP_FILTER_CONTEXT * pfc,
  181.         LPSTR                         lpszHeaders,
  182.         DWORD                         dwReserved
  183.         );
  184.  
  185.     BOOL (WINAPI * WriteClient)  (
  186.         struct _HTTP_FILTER_CONTEXT * pfc,
  187.         LPVOID                        Buffer,
  188.         LPDWORD                       lpdwBytes,
  189.         DWORD                         dwReserved
  190.         );
  191.  
  192.     VOID * (WINAPI * AllocMem) (
  193.         struct _HTTP_FILTER_CONTEXT * pfc,
  194.         DWORD                         cbSize,
  195.         DWORD                         dwReserved
  196.         );
  197.  
  198.     BOOL (WINAPI * ServerSupportFunction) (
  199.         struct _HTTP_FILTER_CONTEXT * pfc,
  200.         enum SF_REQ_TYPE              sfReq,
  201.         PVOID                         pData,
  202.         DWORD                         ul1,
  203.         DWORD                         ul2
  204.         );
  205.  
  206. } HTTP_FILTER_CONTEXT, *PHTTP_FILTER_CONTEXT;
  207.  
  208. //
  209. //  This structure is the notification info for the read and send raw data
  210. //  notification types
  211. //
  212.  
  213. typedef struct _HTTP_FILTER_RAW_DATA
  214. {
  215.     //
  216.     //  This is a pointer to the data for the filter to process.
  217.     //
  218.  
  219.     PVOID         pvInData;
  220.     DWORD         cbInData;       // Number of valid data bytes
  221.     DWORD         cbInBuffer;     // Total size of buffer
  222.  
  223.     DWORD         dwReserved;
  224.  
  225. } HTTP_FILTER_RAW_DATA, *PHTTP_FILTER_RAW_DATA;
  226.  
  227. //
  228. //  This structure is the notification info for when the server is about to
  229. //  process the client headers
  230. //
  231.  
  232. typedef struct _HTTP_FILTER_PREPROC_HEADERS
  233. {
  234.     //
  235.     //  Retrieves the specified header value.  Header names should include
  236.     //  the trailing ':'.  The special values 'method', 'url' and 'version'
  237.     //  can be used to retrieve the individual portions of the request line
  238.     //
  239.  
  240.     BOOL (WINAPI * GetHeader) (
  241.         struct _HTTP_FILTER_CONTEXT * pfc,
  242.         LPSTR                         lpszName,
  243.         LPVOID                        lpvBuffer,
  244.         LPDWORD                       lpdwSize
  245.         );
  246.  
  247.     //
  248.     //  Replaces this header value to the specified value.  To delete a header,
  249.     //  specified a value of '\0'.
  250.     //
  251.  
  252.     BOOL (WINAPI * SetHeader) (
  253.         struct _HTTP_FILTER_CONTEXT * pfc,
  254.         LPSTR                         lpszName,
  255.         LPSTR                         lpszValue
  256.         );
  257.  
  258.     //
  259.     //  Adds the specified header and value
  260.     //
  261.  
  262.     BOOL (WINAPI * AddHeader) (
  263.         struct _HTTP_FILTER_CONTEXT * pfc,
  264.         LPSTR                         lpszName,
  265.         LPSTR                         lpszValue
  266.         );
  267.  
  268.     DWORD dwReserved;
  269. } HTTP_FILTER_PREPROC_HEADERS, *PHTTP_FILTER_PREPROC_HEADERS;
  270.  
  271. //
  272. //  Authentication information for this request.
  273. //
  274.  
  275. typedef struct _HTTP_FILTER_AUTHENT
  276. {
  277.     //
  278.     //  Pointer to username and password, empty strings for the anonymous user
  279.     //
  280.     //  Client's can overwrite these buffers which are guaranteed to be at
  281.     //  least SF_MAX_USERNAME and SF_MAX_PASSWORD bytes large.
  282.     //
  283.  
  284.     CHAR * pszUser;
  285.     DWORD  cbUserBuff;
  286.  
  287.     CHAR * pszPassword;
  288.     DWORD  cbPasswordBuff;
  289.  
  290. } HTTP_FILTER_AUTHENT, *PHTTP_FILTER_AUTHENT;
  291.  
  292. //
  293. //  Indicates the server is going to use the specific physical mapping for
  294. //  the specified URL.  Filters can modify the physical path in place.
  295. //
  296.  
  297. typedef struct _HTTP_FILTER_URL_MAP
  298. {
  299.     const CHAR * pszURL;
  300.  
  301.     CHAR *       pszPhysicalPath;
  302.     DWORD        cbPathBuff;
  303.  
  304. } HTTP_FILTER_URL_MAP, *PHTTP_FILTER_URL_MAP;
  305.  
  306. //
  307. //  The log information about to be written to the server log file.  The
  308. //  string pointers can be replaced but the memory must remain valid until
  309. //  the next notification
  310. //
  311.  
  312. typedef struct _HTTP_FILTER_LOG
  313. {
  314.     const CHAR * pszClientHostName;
  315.     const CHAR * pszClientUserName;
  316.     const CHAR * pszServerName;
  317.     const CHAR * pszOperation;
  318.     const CHAR * pszTarget;
  319.     const CHAR * pszParameters;
  320.  
  321.     DWORD  dwHttpStatus;
  322.     DWORD  dwWin32Status;
  323.  
  324. } HTTP_FILTER_LOG, *PHTTP_FILTER_LOG;
  325.  
  326. //
  327. //  Notification Flags
  328. //
  329. //  SF_NOTIFY_SECURE_PORT
  330. //  SF_NOTIFY_NONSECURE_PORT
  331. //
  332. //      Indicates whether the application wants to be notified for transactions
  333. //      that are happenning on the server port(s) that support data encryption
  334. //      (such as PCT and SSL), on only the non-secure port(s) or both.
  335. //
  336. //  SF_NOTIFY_READ_RAW_DATA
  337. //
  338. //      Applications are notified after the server reads a block of memory
  339. //      from the client but before the server does any processing on the
  340. //      block.  The data block may contain HTTP headers and entity data.
  341. //
  342. //
  343. //
  344.  
  345. #define SF_NOTIFY_SECURE_PORT               0x00000001
  346. #define SF_NOTIFY_NONSECURE_PORT            0x00000002
  347.  
  348. #define SF_NOTIFY_READ_RAW_DATA             0x00008000
  349. #define SF_NOTIFY_PREPROC_HEADERS           0x00004000
  350. #define SF_NOTIFY_AUTHENTICATION            0x00002000
  351. #define SF_NOTIFY_URL_MAP                   0x00001000
  352. #define SF_NOTIFY_SEND_RAW_DATA             0x00000400
  353. #define SF_NOTIFY_LOG                       0x00000200
  354. #define SF_NOTIFY_END_OF_NET_SESSION        0x00000100
  355.  
  356. //
  357. //  Filter ordering flags
  358. //
  359. //  Filters will tend to be notified by their specified
  360. //  ordering.  For ties, notification order is determined by load order.
  361. //
  362. //  SF_NOTIFY_ORDER_HIGH - Authentication or data transformation filters
  363. //  SF_NOTIFY_ORDER_MEDIUM
  364. //  SF_NOTIFY_ORDER_LOW  - Logging filters that want the results of any other
  365. //                      filters might specify this order.
  366. //
  367.  
  368. #define SF_NOTIFY_ORDER_HIGH               0x00080000
  369. #define SF_NOTIFY_ORDER_MEDIUM             0x00040000
  370. #define SF_NOTIFY_ORDER_LOW                0x00020000
  371. #define SF_NOTIFY_ORDER_DEFAULT            SF_NOTIFY_ORDER_LOW
  372.  
  373. #define SF_NOTIFY_ORDER_MASK               (SF_NOTIFY_ORDER_HIGH   |    \
  374.                                             SF_NOTIFY_ORDER_MEDIUM |    \
  375.                                             SF_NOTIFY_ORDER_LOW)
  376.  
  377. //
  378. //  Filter version information, passed to GetFilterVersion
  379. //
  380.  
  381. typedef struct _HTTP_FILTER_VERSION
  382. {
  383.     //
  384.     //  Version of the spec the server is using
  385.     //
  386.  
  387.     DWORD  dwServerFilterVersion;
  388.  
  389.     //
  390.     //  Fields specified by the client
  391.     //
  392.  
  393.     DWORD  dwFilterVersion;
  394.     CHAR   lpszFilterDesc[SF_MAX_FILTER_DESC_LEN];
  395.     DWORD  dwFlags;
  396.  
  397.  
  398. } HTTP_FILTER_VERSION, *PHTTP_FILTER_VERSION;
  399.  
  400. //
  401. //  A filter DLL's entry point looks like this.  The return code should be
  402. //  an SF_STATUS_TYPE
  403. //
  404. //  NotificationType - Type of notification
  405. //  pvNotification - Pointer to notification specific data
  406. //
  407.  
  408. DWORD
  409. WINAPI
  410. HttpFilterProc(
  411.     HTTP_FILTER_CONTEXT *      pfc,
  412.     DWORD                      NotificationType,
  413.     VOID *                     pvNotification
  414.     );
  415.  
  416. BOOL
  417. WINAPI
  418. GetFilterVersion(
  419.     HTTP_FILTER_VERSION * pVer
  420.     );
  421.  
  422. #ifdef __cplusplus
  423. }
  424. #endif
  425.  
  426. #endif //_HTTPFILT_H_
  427.