home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / httpfilt.h < prev    next >
Text File  |  1998-04-25  |  14KB  |  546 lines
  1. /*++
  2.  
  3. Copyright (c) 1997  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. //
  26. //  Current version of the filter spec is 4.0
  27. //
  28.  
  29. #define HTTP_FILTER_REVISION    MAKELONG( 0, 4);
  30.  
  31. #define SF_MAX_USERNAME         (256+1)
  32. #define SF_MAX_PASSWORD         (256+1)
  33. #define SF_MAX_AUTH_TYPE        (32+1)
  34.  
  35. #define SF_MAX_FILTER_DESC_LEN  (256+1)
  36.  
  37.  
  38. //
  39. //  These values can be used with the pfnSFCallback function supplied in
  40. //  the filter context structure
  41. //
  42.  
  43. enum SF_REQ_TYPE
  44. {
  45.     //
  46.     //  Sends a complete HTTP server response header including
  47.     //  the status, server version, message time and MIME version.
  48.     //
  49.     //  Server extensions should append other information at the end,
  50.     //  such as Content-type, Content-length etc followed by an extra
  51.     //  '\r\n'.
  52.     //
  53.     //  pData - Zero terminated string pointing to optional
  54.     //      status string (i.e., "401 Access Denied") or NULL for
  55.     //      the default response of "200 OK".
  56.     //
  57.     //  ul1 - Zero terminated string pointing to optional data to be
  58.     //      appended and set with the header.  If NULL, the header will
  59.     //      be terminated with an empty line.
  60.     //
  61.  
  62.     SF_REQ_SEND_RESPONSE_HEADER,
  63.  
  64.     //
  65.     //  If the server denies the HTTP request, add the specified headers
  66.     //  to the server error response.
  67.     //
  68.     //  This allows an authentication filter to advertise its services
  69.     //  w/o filtering every request.  Generally the headers will be
  70.     //  WWW-Authenticate headers with custom authentication schemes but
  71.     //  no restriction is placed on what headers may be specified.
  72.     //
  73.     //  pData - Zero terminated string pointing to one or more header lines
  74.     //      with terminating '\r\n'.
  75.     //
  76.  
  77.     SF_REQ_ADD_HEADERS_ON_DENIAL,
  78.  
  79.     //
  80.     //  Only used by raw data filters that return SF_STATUS_READ_NEXT
  81.     //
  82.     //  ul1 - size in bytes for the next read
  83.     //
  84.  
  85.     SF_REQ_SET_NEXT_READ_SIZE,
  86.  
  87.     //
  88.     //  Used to indicate this request is a proxy request
  89.     //
  90.     //  ul1 - The proxy flags to set
  91.     //      0x00000001 - This is a HTTP proxy request
  92.     //
  93.     //
  94.  
  95.     SF_REQ_SET_PROXY_INFO,
  96.  
  97.     //
  98.     //  Returns the connection ID contained in the ConnID field of an
  99.     //  ISAPI Application's Extension Control Block.  This value can be used
  100.     //  as a key to cooridinate shared data between Filters and Applications.
  101.     //
  102.     //  pData - Pointer to DWORD that receives the connection ID.
  103.     //
  104.  
  105.     SF_REQ_GET_CONNID,
  106.  
  107.     //
  108.     // Used to set a SSPI security context + impersonation token
  109.     // derived from a client certificate.
  110.     //
  111.     // pData - certificate info ( PHTTP_FILTER_CERTIFICATE_INFO )
  112.     // ul1 - CtxtHandle*
  113.     // ul2 - impersonation handle
  114.     //
  115.  
  116.     SF_REQ_SET_CERTIFICATE_INFO,
  117.  
  118.     //
  119.     // Used to get an IIS property
  120.     // as defined in SF_PROPERTY_IIS
  121.     //
  122.     // ul1 - Property ID
  123.     //
  124.  
  125.     SF_REQ_GET_PROPERTY,
  126.  
  127.     //
  128.     // Used to normalize an URL
  129.     //
  130.     // pData - URL to normalize
  131.     //
  132.  
  133.     SF_REQ_NORMALIZE_URL,
  134.  
  135.     //
  136.     // Disable Notifications
  137.     //
  138.     // ul1 - notifications to disable
  139.     //
  140.  
  141.     SF_REQ_DISABLE_NOTIFICATIONS,
  142. } ;
  143.  
  144.  
  145. enum SF_PROPERTY_IIS
  146. {
  147.     SF_PROPERTY_SSL_CTXT,
  148.     SF_PROPERTY_INSTANCE_NUM_ID
  149. } ;
  150.  
  151.  
  152. //
  153. //  These values are returned by the filter entry point when a new request is
  154. //  received indicating their interest in this particular request
  155. //
  156.  
  157. enum SF_STATUS_TYPE
  158. {
  159.     //
  160.     //  The filter has handled the HTTP request.  The server should disconnect
  161.     //  the session.
  162.     //
  163.  
  164.     SF_STATUS_REQ_FINISHED = 0x8000000,
  165.  
  166.     //
  167.     //  Same as SF_STATUS_FINISHED except the server should keep the TCP
  168.     //  session open if the option was negotiated
  169.     //
  170.  
  171.     SF_STATUS_REQ_FINISHED_KEEP_CONN,
  172.  
  173.     //
  174.     //  The next filter in the notification chain should be called
  175.     //
  176.  
  177.     SF_STATUS_REQ_NEXT_NOTIFICATION,
  178.  
  179.     //
  180.     //  This filter handled the notification.  No other handles should be
  181.     //  called for this particular notification type
  182.     //
  183.  
  184.     SF_STATUS_REQ_HANDLED_NOTIFICATION,
  185.  
  186.     //
  187.     //  An error occurred.  The server should use GetLastError() and indicate
  188.     //  the error to the client
  189.     //
  190.  
  191.     SF_STATUS_REQ_ERROR,
  192.  
  193.     //
  194.     //  The filter is an opaque stream filter and we're negotiating the
  195.     //  session parameters.  Only valid for raw read notification.
  196.     //
  197.  
  198.     SF_STATUS_REQ_READ_NEXT
  199. };
  200.  
  201. //
  202. //  pvNotification points to this structure for all request notification types
  203. //
  204.  
  205. typedef struct _HTTP_FILTER_CONTEXT
  206. {
  207.     DWORD          cbSize;
  208.  
  209.     //
  210.     //  This is the structure revision level.
  211.     //
  212.  
  213.     DWORD          Revision;
  214.  
  215.     //
  216.     //  Private context information for the server.
  217.     //
  218.  
  219.     PVOID          ServerContext;
  220.     DWORD          ulReserved;
  221.  
  222.     //
  223.     //  TRUE if this request is coming over a secure port
  224.     //
  225.  
  226.     BOOL           fIsSecurePort;
  227.  
  228.     //
  229.     //  A context that can be used by the filter
  230.     //
  231.  
  232.     PVOID          pFilterContext;
  233.  
  234.     //
  235.     //  Server callbacks
  236.     //
  237.  
  238.     BOOL (WINAPI * GetServerVariable) (
  239.         struct _HTTP_FILTER_CONTEXT * pfc,
  240.         LPSTR                         lpszVariableName,
  241.         LPVOID                        lpvBuffer,
  242.         LPDWORD                       lpdwSize
  243.         );
  244.  
  245.     BOOL (WINAPI * AddResponseHeaders) (
  246.         struct _HTTP_FILTER_CONTEXT * pfc,
  247.         LPSTR                         lpszHeaders,
  248.         DWORD                         dwReserved
  249.         );
  250.  
  251.     BOOL (WINAPI * WriteClient)  (
  252.         struct _HTTP_FILTER_CONTEXT * pfc,
  253.         LPVOID                        Buffer,
  254.         LPDWORD                       lpdwBytes,
  255.         DWORD                         dwReserved
  256.         );
  257.  
  258.     VOID * (WINAPI * AllocMem) (
  259.         struct _HTTP_FILTER_CONTEXT * pfc,
  260.         DWORD                         cbSize,
  261.         DWORD                         dwReserved
  262.         );
  263.  
  264.     BOOL (WINAPI * ServerSupportFunction) (
  265.         struct _HTTP_FILTER_CONTEXT * pfc,
  266.         enum SF_REQ_TYPE              sfReq,
  267.         PVOID                         pData,
  268.         DWORD                         ul1,
  269.         DWORD                         ul2
  270.         );
  271.  
  272. } HTTP_FILTER_CONTEXT, *PHTTP_FILTER_CONTEXT;
  273.  
  274. //
  275. //  This structure is the notification info for the read and send raw data
  276. //  notification types
  277. //
  278.  
  279. typedef struct _HTTP_FILTER_RAW_DATA
  280. {
  281.     //
  282.     //  This is a pointer to the data for the filter to process.
  283.     //
  284.  
  285.     PVOID         pvInData;
  286.     DWORD         cbInData;       // Number of valid data bytes
  287.     DWORD         cbInBuffer;     // Total size of buffer
  288.  
  289.     DWORD         dwReserved;
  290.  
  291. } HTTP_FILTER_RAW_DATA, *PHTTP_FILTER_RAW_DATA;
  292.  
  293. //
  294. //  This structure is the notification info for when the server is about to
  295. //  process the client headers
  296. //
  297.  
  298. typedef struct _HTTP_FILTER_PREPROC_HEADERS
  299. {
  300.     //
  301.     //  For SF_NOTIFY_PREPROC_HEADERS, retrieves the specified header value.
  302.     //  Header names should include the trailing ':'.  The special values
  303.     //  'method', 'url' and 'version' can be used to retrieve the individual
  304.     //  portions of the request line
  305.     //
  306.  
  307.     BOOL (WINAPI * GetHeader) (
  308.         struct _HTTP_FILTER_CONTEXT * pfc,
  309.         LPSTR                         lpszName,
  310.         LPVOID                        lpvBuffer,
  311.         LPDWORD                       lpdwSize
  312.         );
  313.  
  314.     //
  315.     //  Replaces this header value to the specified value.  To delete a header,
  316.     //  specified a value of '\0'.
  317.     //
  318.  
  319.     BOOL (WINAPI * SetHeader) (
  320.         struct _HTTP_FILTER_CONTEXT * pfc,
  321.         LPSTR                         lpszName,
  322.         LPSTR                         lpszValue
  323.         );
  324.  
  325.     //
  326.     //  Adds the specified header and value
  327.     //
  328.  
  329.     BOOL (WINAPI * AddHeader) (
  330.         struct _HTTP_FILTER_CONTEXT * pfc,
  331.         LPSTR                         lpszName,
  332.         LPSTR                         lpszValue
  333.         );
  334.  
  335.     DWORD HttpStatus;               // New in 4.0, status for SEND_RESPONSE
  336.     DWORD dwReserved;               // New in 4.0
  337.  
  338. } HTTP_FILTER_PREPROC_HEADERS, *PHTTP_FILTER_PREPROC_HEADERS;
  339.  
  340. typedef HTTP_FILTER_PREPROC_HEADERS HTTP_FILTER_SEND_RESPONSE;
  341. typedef HTTP_FILTER_PREPROC_HEADERS *PHTTP_FILTER_SEND_RESPONSE;
  342.  
  343. //
  344. //  Authentication information for this request.
  345. //
  346.  
  347. typedef struct _HTTP_FILTER_AUTHENT
  348. {
  349.     //
  350.     //  Pointer to username and password, empty strings for the anonymous user
  351.     //
  352.     //  Client's can overwrite these buffers which are guaranteed to be at
  353.     //  least SF_MAX_USERNAME and SF_MAX_PASSWORD bytes large.
  354.     //
  355.  
  356.     CHAR * pszUser;
  357.     DWORD  cbUserBuff;
  358.  
  359.     CHAR * pszPassword;
  360.     DWORD  cbPasswordBuff;
  361.  
  362. } HTTP_FILTER_AUTHENT, *PHTTP_FILTER_AUTHENT;
  363.  
  364.  
  365.  
  366. //
  367. //  Indicates the server is going to use the specific physical mapping for
  368. //  the specified URL.  Filters can modify the physical path in place.
  369. //
  370.  
  371. typedef struct _HTTP_FILTER_URL_MAP
  372. {
  373.     const CHAR * pszURL;
  374.  
  375.     CHAR *       pszPhysicalPath;
  376.     DWORD        cbPathBuff;
  377.  
  378. } HTTP_FILTER_URL_MAP, *PHTTP_FILTER_URL_MAP;
  379.  
  380.  
  381. //
  382. //  Bitfield indicating the requested resource has been denied by the server due
  383. //  to a logon failure, an ACL on a resource, an ISAPI Filter or an
  384. //  ISAPI Application/CGI Application.
  385. //
  386. //  SF_DENIED_BY_CONFIG can appear with SF_DENIED_LOGON if the server
  387. //  configuration did not allow the user to logon.
  388. //
  389.  
  390. #define SF_DENIED_LOGON             0x00000001
  391. #define SF_DENIED_RESOURCE          0x00000002
  392. #define SF_DENIED_FILTER            0x00000004
  393. #define SF_DENIED_APPLICATION       0x00000008
  394.  
  395. #define SF_DENIED_BY_CONFIG         0x00010000
  396.  
  397. typedef struct _HTTP_FILTER_ACCESS_DENIED
  398. {
  399.     const CHAR * pszURL;            // Requesting URL
  400.     const CHAR * pszPhysicalPath;   // Physical path of resource
  401.     DWORD        dwReason;          // Bitfield of SF_DENIED flags
  402.  
  403. } HTTP_FILTER_ACCESS_DENIED, *PHTTP_FILTER_ACCESS_DENIED;
  404.  
  405.  
  406. //
  407. //  The log information about to be written to the server log file.  The
  408. //  string pointers can be replaced but the memory must remain valid until
  409. //  the next notification
  410. //
  411.  
  412. typedef struct _HTTP_FILTER_LOG
  413. {
  414.     const CHAR * pszClientHostName;
  415.     const CHAR * pszClientUserName;
  416.     const CHAR * pszServerName;
  417.     const CHAR * pszOperation;
  418.     const CHAR * pszTarget;
  419.     const CHAR * pszParameters;
  420.  
  421.     DWORD  dwHttpStatus;
  422.     DWORD  dwWin32Status;
  423.  
  424.     DWORD  dwBytesSent;             // IIS 4.0 and later
  425.     DWORD  dwBytesRecvd;            // IIS 4.0 and later
  426.     DWORD  msTimeForProcessing;     // IIS 4.0 and later
  427.  
  428. } HTTP_FILTER_LOG, *PHTTP_FILTER_LOG;
  429.  
  430. //
  431. //  Notification Flags
  432. //
  433. //  SF_NOTIFY_SECURE_PORT
  434. //  SF_NOTIFY_NONSECURE_PORT
  435. //
  436. //      Indicates whether the application wants to be notified for transactions
  437. //      that are happenning on the server port(s) that support data encryption
  438. //      (such as PCT and SSL), on only the non-secure port(s) or both.
  439. //
  440. //  SF_NOTIFY_READ_RAW_DATA
  441. //
  442. //      Applications are notified after the server reads a block of memory
  443. //      from the client but before the server does any processing on the
  444. //      block.  The data block may contain HTTP headers and entity data.
  445. //
  446. //
  447. //
  448.  
  449. #define SF_NOTIFY_SECURE_PORT               0x00000001
  450. #define SF_NOTIFY_NONSECURE_PORT            0x00000002
  451.  
  452. #define SF_NOTIFY_READ_RAW_DATA             0x00008000
  453. #define SF_NOTIFY_PREPROC_HEADERS           0x00004000
  454. #define SF_NOTIFY_AUTHENTICATION            0x00002000
  455. #define SF_NOTIFY_URL_MAP                   0x00001000
  456. #define SF_NOTIFY_ACCESS_DENIED             0x00000800
  457. #define SF_NOTIFY_SEND_RESPONSE             0x00000040
  458. #define SF_NOTIFY_SEND_RAW_DATA             0x00000400
  459. #define SF_NOTIFY_LOG                       0x00000200
  460. #define SF_NOTIFY_END_OF_REQUEST            0x00000080
  461. #define SF_NOTIFY_END_OF_NET_SESSION        0x00000100
  462.  
  463.  
  464. //
  465. //  Filter ordering flags
  466. //
  467. //  Filters will tend to be notified by their specified
  468. //  ordering.  For ties, notification order is determined by load order.
  469. //
  470. //  SF_NOTIFY_ORDER_HIGH - Authentication or data transformation filters
  471. //  SF_NOTIFY_ORDER_MEDIUM
  472. //  SF_NOTIFY_ORDER_LOW  - Logging filters that want the results of any other
  473. //                      filters might specify this order.
  474. //
  475.  
  476. #define SF_NOTIFY_ORDER_HIGH               0x00080000
  477. #define SF_NOTIFY_ORDER_MEDIUM             0x00040000
  478. #define SF_NOTIFY_ORDER_LOW                0x00020000
  479. #define SF_NOTIFY_ORDER_DEFAULT            SF_NOTIFY_ORDER_LOW
  480.  
  481. #define SF_NOTIFY_ORDER_MASK               (SF_NOTIFY_ORDER_HIGH   |    \
  482.                                             SF_NOTIFY_ORDER_MEDIUM |    \
  483.                                             SF_NOTIFY_ORDER_LOW)
  484.  
  485. //
  486. //  Filter version information, passed to GetFilterVersion
  487. //
  488.  
  489. typedef struct _HTTP_FILTER_VERSION
  490. {
  491.     //
  492.     //  Version of the spec the server is using
  493.     //
  494.  
  495.     DWORD  dwServerFilterVersion;
  496.  
  497.     //
  498.     //  Fields specified by the client
  499.     //
  500.  
  501.     DWORD  dwFilterVersion;
  502.     CHAR   lpszFilterDesc[SF_MAX_FILTER_DESC_LEN];
  503.     DWORD  dwFlags;
  504.  
  505.  
  506. } HTTP_FILTER_VERSION, *PHTTP_FILTER_VERSION;
  507.  
  508.  
  509.  
  510. //
  511. //  A filter DLL's entry point looks like this.  The return code should be
  512. //  an SF_STATUS_TYPE
  513. //
  514. //  NotificationType - Type of notification
  515. //  pvNotification - Pointer to notification specific data
  516. //
  517.  
  518. DWORD
  519. WINAPI
  520. HttpFilterProc(
  521.     HTTP_FILTER_CONTEXT *      pfc,
  522.     DWORD                      NotificationType,
  523.     VOID *                     pvNotification
  524.     );
  525.  
  526. BOOL
  527. WINAPI
  528. GetFilterVersion(
  529.     HTTP_FILTER_VERSION * pVer
  530.     );
  531.  
  532. BOOL
  533. WINAPI
  534. TerminateFilter(
  535.     DWORD dwFlags
  536.     );
  537.  
  538. #ifdef __cplusplus
  539. }
  540. #endif
  541.  
  542.  
  543. #endif //_HTTPFILT_H_
  544. 
  545. 
  546.