rubbos/app/httpd-2.0.64/modules/arch/win32/mod_isapi.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file mod_isapi.h
  19  * @brief ISAPI module extension to Apache
  20  *
  21  * @defgroup MOD_ISAPI mod_isapi
  22  * @ingroup  APACHE_MODS
  23  * @{
  24  */
  25
  26 #ifndef MOD_ISAPI_H
  27 #define MOD_ISAPI_H
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /* The Version Information storage passed to a module on startup
  34  * via the GetExtensionVersion() entry point.
  35  */
  36 typedef struct HSE_VERSION_INFO {
  37     apr_uint32_t dwExtensionVersion;
  38     char         lpszExtensionDesc[256];
  39 } HSE_VERSION_INFO;
  40
  41 /* The startup entry point that must be exported by every ISAPI handler
  42  */
  43 int APR_THREAD_FUNC GetExtensionVersion(HSE_VERSION_INFO *ver_info);
  44 typedef int (APR_THREAD_FUNC *PFN_GETEXTENSIONVERSION)(HSE_VERSION_INFO *ver_info);
  45
  46 /* Our internal 'HCONN' representation, always opaque to the user.
  47  */
  48 typedef struct isapi_cid isapi_cid;
  49 typedef struct isapi_cid *HCONN;
  50
  51 /* Prototypes of the essential functions exposed by mod_isapi
  52  * for the module to communicate with Apache.
  53  */
  54 typedef int (APR_THREAD_FUNC
  55                 *PFN_GETSERVERVARIABLE)(HCONN         cid,
  56                                         char         *variable_name,
  57                                         void         *buf_data,
  58                                         apr_uint32_t *buf_size);
  59 typedef int (APR_THREAD_FUNC
  60                 *PFN_WRITECLIENT)(HCONN         cid,
  61                                   void         *buf_data,
  62                                   apr_uint32_t *buf_size,
  63                                   apr_uint32_t  flags);
  64 typedef int (APR_THREAD_FUNC
  65                 *PFN_READCLIENT)(HCONN         cid,
  66                                  void         *buf_data,
  67                                  apr_uint32_t *buf_size);
  68 typedef int (APR_THREAD_FUNC
  69                 *PFN_SERVERSUPPORTFUNCTION)(HCONN         cid,
  70                                             apr_uint32_t  HSE_code,
  71                                             void         *buf_data,
  72                                             apr_uint32_t *buf_size,
  73                                             apr_uint32_t *flags);
  74
  75 /* The ecb structure is passed on each invocation of the module
  76  */
  77 typedef struct EXTENSION_CONTROL_BLOCK {
  78     apr_uint32_t   cbSize;
  79     apr_uint32_t   dwVersion;
  80     HCONN          ConnID;
  81     apr_uint32_t   dwHttpStatusCode;
  82     char           lpszLogData[80];
  83     char          *lpszMethod;
  84     char          *lpszQueryString;
  85     char          *lpszPathInfo;
  86     char          *lpszPathTranslated;
  87     apr_uint32_t   cbTotalBytes;
  88     apr_uint32_t   cbAvailable;
  89     unsigned char *lpbData;
  90     char          *lpszContentType;
  91
  92     PFN_GETSERVERVARIABLE     GetServerVariable;
  93     PFN_WRITECLIENT           WriteClient;
  94     PFN_READCLIENT            ReadClient;
  95     PFN_SERVERSUPPORTFUNCTION ServerSupportFunction;
  96 } EXTENSION_CONTROL_BLOCK;
  97
  98 /* Status/Headers structure to pass to HSE_SEND_HEADER_EX,
  99  * an MS extension to ServerSupportFunction
 100  */
 101 typedef struct HSE_SEND_HEADER_EX_INFO {
 102     const char * pszStatus; /* HTTP status text, such as "200 OK" */
 103     const char * pszHeader; /* HTTP header lines text, such as
 104                              *   "Content-type: text/plain\r\n"
 105                              *   "Content-Language: en\r\n"
 106                              * Note that (in spite of cchFoo lengths below)
 107                              * NULL characters will interfere in headers.
 108                              */
 109     apr_uint32_t cchStatus; /* length of pszStatus text */
 110     apr_uint32_t cchHeader; /* length of pszHeader text */
 111     int          fKeepConn; /* Ignored: used to set keep-alive status,
 112                              * but Apache follows the client's negotiated
 113                              * HTTP contract to decide.
 114                              */
 115 } HSE_SEND_HEADER_EX_INFO;
 116
 117 /* Our only 'supported' MS extended flag bit for TransmitFile,
 118  * HSE_IO_SEND_HEADERS indicates that Status+Headers are present
 119  * in the pszStatusCode member of the HSE_TF_INFO structure.
 120  */
 121 #define HSE_IO_SEND_HEADERS 8
 122
 123 /* The remaining flags are MS extended flag bits that bear little
 124  * relation to Apache; the rules that the Apache server obeys follow
 125  * its own design and HTTP protocol filter rules.
 126  *
 127  * We do not support async, however, we fake it.  If HSE_IO_SYNC is
 128  * not passed, and a completion context was defined, we will invoke the
 129  * completion function immediately following the transfer, and then
 130  * return to the caller.  If HSE_IO_SYNC is passed, there is no call
 131  * neccessary to the completion context.
 132  */
 133 #define HSE_IO_SYNC  1
 134 #define HSE_IO_ASYNC 2
 135 #define HSE_IO_DISCONNECT_AFTER_SEND 4
 136 #define HSE_IO_NODELAY 4096
 137
 138 /* The Completion function prototype.  This callback may be fixed with
 139  * the HSE_REQ_IO_COMPLETION ServerSupportFunction call, or overriden
 140  * for the HSE_REQ_TRANSMIT_FILE call.
 141  */
 142 typedef void (APR_THREAD_FUNC *PFN_HSE_IO_COMPLETION)
 143                                   (EXTENSION_CONTROL_BLOCK *ecb,
 144                                    void                    *ctxt,
 145                                    apr_uint32_t             cbIO,
 146                                    apr_uint32_t             dwError);
 147
 148 /* TransmitFile structure to pass to HSE_REQ_TRANSMIT_FILE, an MS extension
 149  */
 150 typedef struct HSE_TF_INFO {
 151     PFN_HSE_IO_COMPLETION pfnHseIO;      /* Overrides the default setting of
 152                                           * HSE_REQ_IO_COMPLETION if not NULL
 153                                           */
 154     void                 *pContext;
 155     apr_os_file_t         hFile;         /* HANDLE/fd to transmit */
 156     const char           *pszStatusCode; /* Ignored if HSE_IO_SEND_HEADERS is
 157                                           * not set.  Includes HTTP status text
 158                                           * plus header text lines, such as
 159                                           *   "200 OK\r\n"
 160                                           *   "Content-type: text/plain\r\n"
 161                                           */
 162     apr_uint32_t          BytesToWrite;  /* 0 is write-all */
 163     apr_uint32_t          Offset;        /* File Offset */
 164     void                 *pHead;         /* Prefix with *pHead body text */
 165     apr_uint32_t          HeadLength;    /* Length of *pHead body text */
 166     void                 *pTail;         /* Prefix with *pTail body text */
 167     apr_uint32_t          TailLength;    /* Length of *pTail body text */
 168     apr_uint32_t          dwFlags;       /* bit flags described above */
 169 } HSE_TF_INFO;
 170
 171 typedef struct HSE_URL_MAPEX_INFO {
 172     char         lpszPath[260];
 173     apr_uint32_t dwFlags;
 174     apr_uint32_t cchMatchingPath;
 175     apr_uint32_t cchMatchingURL;
 176     apr_uint32_t dwReserved1;
 177     apr_uint32_t dwReserved2;
 178 } HSE_URL_MAPEX_INFO;
 179
 180 /* Original ISAPI ServerSupportFunction() HSE_code methods */
 181 #define HSE_REQ_SEND_URL_REDIRECT_RESP   1
 182 #define HSE_REQ_SEND_URL                 2
 183 #define HSE_REQ_SEND_RESPONSE_HEADER     3
 184 #define HSE_REQ_DONE_WITH_SESSION        4
 185
 186 /* MS Extented methods to ISAPI ServerSupportFunction() HSE_code */
 187 #define HSE_REQ_MAP_URL_TO_PATH          1001 /* Emulated */
 188 #define HSE_REQ_GET_SSPI_INFO            1002 /* Not Supported */
 189 #define HSE_APPEND_LOG_PARAMETER         1003 /* Supported */
 190 #define HSE_REQ_IO_COMPLETION            1005 /* Emulated */
 191 #define HSE_REQ_TRANSMIT_FILE            1006 /* Async Emulated */
 192 #define HSE_REQ_REFRESH_ISAPI_ACL        1007 /* Not Supported */
 193 #define HSE_REQ_IS_KEEP_CONN             1008 /* Supported */
 194 #define HSE_REQ_ASYNC_READ_CLIENT        1010 /* Emulated */
 195 /*   Added with ISAPI 4.0 */
 196 #define HSE_REQ_GET_IMPERSONATION_TOKEN  1011 /* Not Supported */
 197 #define HSE_REQ_MAP_URL_TO_PATH_EX       1012 /* Emulated */
 198 #define HSE_REQ_ABORTIVE_CLOSE           1014 /* Ignored */
 199 /*   Added after ISAPI 4.0 in IIS 5.0 */
 200 #define HSE_REQ_GET_CERT_INFO_EX         1015 /* Not Supported */
 201 #define HSE_REQ_SEND_RESPONSE_HEADER_EX  1016 /* Supported (no nulls!) */
 202 #define HSE_REQ_CLOSE_CONNECTION         1017 /* Ignored */
 203 #define HSE_REQ_IS_CONNECTED             1018 /* Supported */
 204 #define HSE_REQ_EXTENSION_TRIGGER        1020 /* Not Supported */
 205
 206 /* The request entry point that must be exported by every ISAPI handler
 207  */
 208 apr_uint32_t APR_THREAD_FUNC HttpExtensionProc(EXTENSION_CONTROL_BLOCK *ecb);
 209 typedef apr_uint32_t (APR_THREAD_FUNC
 210                         *PFN_HTTPEXTENSIONPROC)(EXTENSION_CONTROL_BLOCK *ecb);
 211
 212 /* Allowable return values from HttpExtensionProc (apparently 0 is also
 213  * accepted by MS IIS, and we will respect it as Success.)
 214  * If the HttpExtensionProc returns HSE_STATUS_PENDING, we will create
 215  * a wait mutex and lock on it, until HSE_REQ_DONE_WITH_SESSION is called.
 216  */
 217 #define HSE_STATUS_SUCCESS                1
 218 #define HSE_STATUS_SUCCESS_AND_KEEP_CONN  2 /* 1 vs 2 Ignored, we choose */
 219 #define HSE_STATUS_PENDING                3 /* Emulated (thread lock) */
 220 #define HSE_STATUS_ERROR                  4
 221
 222 /* Anticipated error code for common faults within mod_isapi itself
 223  */
 224 #ifndef ERROR_INSUFFICIENT_BUFFER
 225 #define ERROR_INSUFFICIENT_BUFFER ENOBUFS
 226 #endif
 227 #ifndef ERROR_INVALID_INDEX
 228 #define ERROR_INVALID_INDEX EINVAL
 229 #endif
 230 #ifndef ERROR_INVALID_PARAMETER
 231 #define ERROR_INVALID_PARAMETER EINVAL
 232 #endif
 233 #ifndef ERROR_READ_FAULT
 234 #define ERROR_READ_FAULT EIO
 235 #endif
 236 #ifndef ERROR_WRITE_FAULT
 237 #define ERROR_WRITE_FAULT EIO
 238 #endif
 239 #ifndef ERROR_SUCCESS
 240 #define ERROR_SUCCESS 0
 241 #endif
 242
 243 /* Valid flags passed with TerminateExtension()
 244  */
 245 #define HSE_TERM_MUST_UNLOAD      1
 246 #define HSE_TERM_ADVISORY_UNLOAD  2
 247
 248 /* The shutdown entry point óptionally exported by an ISAPI handler, passed
 249  * HSE_TERM_MUST_UNLOAD or HSE_TERM_ADVISORY_UNLOAD.  The module may return
 250  * if passed HSE_TERM_ADVISORY_UNLOAD, and the module will remain loaded.
 251  * If the module returns 1 to HSE_TERM_ADVISORY_UNLOAD it is immediately
 252  * unloaded.  If the module is passed HSE_TERM_MUST_UNLOAD, its return value
 253  * is ignored.
 254  */
 255 int APR_THREAD_FUNC TerminateExtension(apr_uint32_t flags);
 256 typedef int (APR_THREAD_FUNC *PFN_TERMINATEEXTENSION)(apr_uint32_t flags);
 257
 258 /* Module may return 0 if passed HSE_TERM_ADVISORY_UNLOAD, and the module
 259  * will remain loaded, or 1 if it consents to being unloaded. If the module
 260  * is passed HSE_TERM_MUST_UNLOAD, it's return value is ignored.
 261  */
 262 #define HSE_TERM_MUST_UNLOAD      1
 263 #define HSE_TERM_ADVISORY_UNLOAD  2
 264
 265 #ifdef __cplusplus
 266 }
 267 #endif
 268
 269 #endif  /* !MOD_ISAPI_H */
 270 /** @} */
 271