GetServerVariable (ISAPI Extensions) (Compact 2013)

  • Article

3/26/2014

This callback function is an application-defined function. ISAPI extensions call this function to retrieve information about an HTTP connection or about the Windows Embedded Compact Web Server itself. The GetServerVariable name for this function is a placeholder for the function name defined by the header.

For ISAPI extensions, some server variables, such as Request_Method and Content_Length are embedded in the EXTENSION_CONTROL_BLOCK structure. Your extension can use this function to obtain information about the request or server that is not included in the EXTENSION_CONTROL_BLOCK structure.

Syntax

BOOL (WINAPI* GetServerVariable)(
  HCONN hConn,
  LPSTR lpszVariableName,
  LPVOID lpvBuffer,
  LPDWORD lpdwSize
);

Parameters

  • hConn
    [in] Specifier for the connection handle.

  • lpszVariableName
    [in] A null-terminated ANSI string that indicates which variable is requested. The following table lists the possible variables.

    Variable

    Description

    ALL_RAW

    All headers in raw form. The header names and values appear as they are sent by the client. Currently, this value is primarily used by proxy servers and other similar applications.

    AUTH_PASSWORD

    The value entered in the client's authentication dialog. This variable is only available if Basic authentication is used.

    AUTH_TYPE

    The type of authentication used. If the string is empty, then no authentication is used. Possible values are Basic or NTLM.

    AUTH_USER

    The value entered in the client's authentication dialog box.

    CERT_FLAGS

    If bit0 is set to 1, a client certificate is present. If bit1 is set to 1, the certification authority (CA) of the client certificate is invalid. That is, it is not on this server's list of recognized CAs.

    CERT_ISSUER

    The issuer field of the client certificate.

    CERT_KEYSIZE

    The number of bits in the Secure Sockets Layer (SSL) connection key size.

    CERT_SECRETKEYSIZE

    The number of bits in the server certificate private key.

    CERT_SERIALNUMBER

    The serial-number field of the client certificate.

    CERT_SERVER_ISSUER

    The issuer field of the server certificate.

    CERT_SERVER_SUBJECT

    The subject field of the server certificate.

    CERT_SUBJECT

    The subject field of the client certificate.

    CONTENT_LENGTH

    The number of bytes of data that the script or extension can expect to receive from the client. This total does not include headers.

    CONTENT_TYPE

    The content type of the information supplied in the body of a POST request.

    HTTP_ACCEPT

    The Accept header.

    HTTPS

    On if the request came in through secure channel (with SSL encryption), or off if the request is for an unsecure channel.

    HTTPS_KEYSIZE

    The number of bits in the SSL connection key size.

    HTTPS_SECRETKEYSIZE

    The number of bits in server certificate private key.

    HTTPS_SERVER_ISSUER

    The issuer field of the server certificate.

    HTTPS_SERVER_SUBJECT

    The subject field of the server certificate.

    PATH_INFO

    Additional path information, as given by the client. This consists of the trailing part of the URL after the script or ISAPI DLL name, but before the query string, if any.

    PATH_TRANSLATED

    The value of PATH_INFO, but with any virtual path expanded into a directory specification.

    QUERY_STRING

    The information that follows the first question mark in the URL that referenced this script.

    REMOTE_ADDR

    The IP address of the client or agent of the client (for example gateway, proxy, or firewall) that sent the request.

    REMOTE_HOST

    The host name of the client or agent of the client (for example, gateway, proxy or firewall) that sent the request if reverse DNS is enabled. Otherwise, this value is set to the IP address specified by REMOTE_ADDR.

    REMOTE_USER

    The user name supplied by the client and authenticated by the server. This comes back as an empty string when the user is anonymous.

    REQUEST_METHOD

    The HTTP request method verb.

    SCRIPT_NAME

    The name of the script program being executed.

    SERVER_NAME

    The server's host name, or IP address, as it should appear in self-referencing URLs.

    SERVER_PORT

    The TCP/IP port on which the request was received.

    SERVER_PORT_SECURE

    A string of either 0 or 1. If the request is being handled on the secure port, then this will be 1. Otherwise, it will be 0.

    SERVER_PROTOCOL

    The name and version of the information retrieval protocol relating to this request.

    SERVER_SOFTWARE

    The name and version of the Web Server under which the ISAPI extension DLL program is running.

    URL

    The base portion of the URL. Parameter values will not be included. The value is determined when the Web Server parses the URL from the header.
  • lpvBuffer
    [out] Pointer to the buffer to receive the requested information.
  • lpdwSize
    [in, out] Pointer to the size of the buffer indicated by lpvBuffer. On successful completion, the parameter contains the size of bytes transferred into the buffer, including the null-terminating byte.

Return Value

Returns TRUE if the function succeeds, and FALSE otherwise. To determine the cause of a failure, the filter should call GetLastError. The following table shows the possible error values.

Value

Description

ERROR_INVALID_PARAMETER

Bad connection handle, or invalid values, in either lpszVariableName or lpdwSize.

ERROR_INVALID_INDEX

Bad or unsupported variable identifier.

ERROR_INSUFFICIENT_BUFFER

Buffer too small. The required buffer size is specified by lpdwSize.

ERROR_NO_DATA

The data requested is not available.

Remarks

This function copies information into a buffer supplied by the caller.

If the string for the AUTH_TYPE variable is not empty, it does not mean the user was authenticated (if the authentication scheme is not Basic or NTLM-based authentication). The server allows authentication schemes it does not natively support because an ISAPI filter may be able to handle that particular scheme.

The lpszVariableName parameter can be used to retrieve a specific request (client) header by using the HTTP_headername value. For example, supplying the value HTTP_ACCEPT returns the Accept header, and HTTP_VERSION returns the Version header.

The values of the fields for the HTTP_ACCEPT variable are concatenated and separated by commas (,).

Requirements

Header

httpext.h

Library

Developer Implemented

See Also

Reference

Web Server Functions
EXTENSION_CONTROL_BLOCK