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