|
htmlServer
Server interface base class | [Previous] [Main] [Next] |
| htmlServer provides a common interface for managing interaction between a variety of web servers and the html++ application, making it easy to pass data such as form fields, and even entire files, to and from web browsers.
| |
|
| |
| htmlServer contains functionality to perform automatic encryption of name/value pairs in hidden form fields and URL-encoded data before final output, as well as for similar decryption. In addition, htmlServer also provides capabilities for automatic replacement of name/value pairs in form input fields, making it easy to create pages that pre-populate fields based on content from other sources or pages.
| |
|
| |
| htmlServer is derived from CNVList, which is the library's name/value list management class. To access or modify name/value pairs, simply use the Value() methods inherited from that class.
| |
|
| |
| It is rare for an application to instantiate htmlServer directly. Instead, most applications with use the htmlCgi or htmlISAPI subclasses.
| |
|
| |
| The htmlServer constructor accepts any C++ istream-compatible input (such as cin for regular CGI), though it is typically overriden by subclasses to accept the communication mechanism appropriate to the environment (such as an extension control block pointer in ISAPI). If the browser data is passed using the POST method, the input stream will be used to obtain the data. Alternatively, if the GET method is used, the browser data will be obtained from the server environment and the input stream will be ignored.
| |
|
| |
| htmlServer automatically adapts to both the GET and POST methods, decoding and parsing data using either method into a name/value list for easy management.
| |
|
| |
| If the request method or mime type is not recognized, the input will be ignored and the following name/value pair will be created to indicate the error:
| |
| Name Value
| |
| "ERROR" "html++ Error: Unknown encoding type"
| |
|
| |
| If such an error occurs, the Content_Type and/or Request_Method member variables can be checked to determine the type of mime encoding causing the problem. By default, the following mime types are recognized:
| |
| application/x-www-form-urlencoded
| |
| multipart/form-data
| |
|
| |
| htmlServer also contain an embedded htmlCookie object. The Cookie() method provides access to the cookie object for the browser session, which is used to receive and send HTTP cookies (user-defined values) to and from a web browser. Cookie objects are sent to the server using the << insertion operator or by assigning a new cookie object using the Cookie() method.
| |
|
| |
| When receiving uploaded files from forms, file contents are automatically captured and saved in a temporary file. In such cases, the name of the form field will not appear in the resulting name/value list. Instead, two name/value pairs for each file element received are generated. The names of these values are based on the form field name from which they originated, with the addition of a dot followed the word "local" or "remote". They are accessible via the Value() method.
| |
|
| |
| For example, if the field name representing the file upload button on the form were named "file", the following two name/value pairs would be generated:
| |
| file.local
| |
| file.remote
| |
|
| |
| The value associated with the ".local" suffix represents the name of the local temporary file used to store the received file contents. The value associated with the ".remote" suffix represents the remote (on the browser) name of the file that the user selected on their system.
| |
|
| |
| It is the responsibility of the developer to use or delete temporary files once received.
| |
|
| |
| #include <dcmicro/htmlpp/htmlsrvr.h>
| |
|
| |
|
| |
|
| |
| htmlCgi, htmlISAPI, CNVList, htmlForm, htmlInputHidden, htmlCookie
| |
|
| |
| None.
| |
|
| |
| htmlServer()
| |
| Constructs an empty, uninitialized cgi object, loading environment variables into the member variables. This constructor is rarely used, and must be followed by a manual call to the Initialize() method.
| |
|
| |
| htmlServer( istream& is )
| |
| Constructs the object from the is input stream, loading environment variables into the member variables. Implicitly executes the Initialize() method, passing along is as the argument. Typically, the standard C++ cin input stream object is used unless overriden by a derived class.
| |
|
| |
| virtual ~htmlServer()
| |
| Destroys the object.
| |
|
| |
| << | htmlServer& operator<< ( htmlObject& element )
| |
| Writes element to the server output, returning a reference to the server.
| |
|
| ||
| << | htmlServer& operator<< ( const String& text )
| |
| Converts text to an htmlText object, writes it to the server output, then returns a reference to the server.
| |
|
| ||
| << | htmlServer& operator<< ( const htmlCookie& cookie )
| |
| Replaces the cookie object for the browser session with cookie, and returns a reference to the server.
| |
|
| |
| Cookie | htmlCookie& Cookie()
| |
| Returns a reference to the cookie object (which may be empty) for the browser session.
| |
|
| ||
| Crypt | void Crypt( Coder * coder_ptr )
| |
| Sets the encryption/decryption algorithm used for hidden fields and URL-encoded data. By default, htmlServer will use NullCoder, effectively turning off encryption.
| |
|
| ||
| Crypt | Coder * Crypt() const
| |
| Returns a pointer to the encryption object for the server. If no encryption object has been specified, a pointer to an internal static copy of NullCoder is returned.
| |
|
| ||
| Decode | void Decode( String& string ) const
| |
| Performs in-place decoding of string from a URL. Once decoded, the contents can be parsed into name/value pairs using the String::GetNextToken() method. Note that htmlServer automatically decodes and parses data -- this method is provided for convenience.
| |
|
| |
| Encode | void Encode( String& string ) const
| |
| Performs in-place encoding of string, making it suitable for use in a URL. Spaces are translated to +'s, and non-alphanumeric characters are translated to hexadecimal codes. This method is useful for assembling URL's containing data for another CGI application, such as for maintaining state information between pages without using forms or hidden fields.
| |
|
| |
| NOTE: In order to use Encode()'d strings as part of a URL, you must insert a "?" character between the action and the encoded string.
| |
|
| |
| AsURL | String AsURL() const
| |
| Encodes all name/value pairs in the object as a single string suitable for inclusion as a URL in a form action or as a hyperlink. The resulting string should be prefixed with a CGI script or exectuable name and a "?" character before use.
| |
|
| |
| AsHidden | void AsHidden( htmlForm& form ) const
| |
| Encodes all name/value pairs in the object and inserts them as individual hidden fields in the specified form.
| |
|
| |
| CreateTemp | virtual String CreateTemp()
| |
| Returns a string representing a unique temporary filename (not the actual file) for use by the htmlServer class when receiving uploaded files from web browsers that support the feature (see htmlInputFile). The default implementation uses the tmpnam() system routine. This method is declared as virtual so that derived classes can implement their own temporary filename generation routine if necessary.
| |
|
| |
| GetEnv | virtual String GetEnv( const String& name )
| |
| Retrieves the value for name from the environment as a string. This method provides a uniform interface across multiple platforms for accessing data from the web server. The default implementation uses the C-lanugage getenv() function internally, and derived classes typically override it to retrieve data from server-provided structures.
| |
|
| |
| LoadEnvironment | virtual void LoadEnvironment()
| |
| Populates the public member varaibles using the GetEnv() virtual function. Called implicitly by the Initialize() method. Only member variables that are emtpy strings or zero value will be overwritten, thus allowing the user to safely pre-populate any member variables as needed.
| |
|
| |
| Initialize | int Initialize()
| |
| Initializes the object, decoding content passed from the browser to the server. If successful, the number of name/value pairs received from the system is returned, zero if no data was received or if there was an error. This method is used in conjunction with the empty htmlServer() constructor to obtain content data from an alternative source, such as a native web server API routine or structure.
| |
|
| |
| For content data sent using the GET method, one should first set Request_Method to "GET", then set Query_String to the content (e.g., "name1=value1&name2=value2").
| |
|
| |
| Initialize | int Initialize( istream& is )
| |
| Initializes the object, decoding content (such as name/value pairs from a form) passed from the browser to the server through is. If successful, the number of name/value pairs received from the system is returned, zero if no data was received or if there was an error. This method is used in conjunction with the empty htmlServer() constructor to obtain content data from an alternative source, such as a native web server API routine or structure.
| |
|
| |
| For content data sent using the POST method, one should first set Request_Method to "POST", Content_Type to "application/x-www-form-urlencoded", then pass the content data (e.g., "name1=value1&name2=value2") though an istream-compatible object such as strstream to the Initialize() method.
| |
|
| |
| The following variables, unless noted otherwise, are all String variables. They are commonly defined by most web servers as CGI environment variables, though your particular server may or may not include all of them. html++ applications can use the information contained in these variables to customize behavior or to implement advanced features, such as tailoring document contents based upon the client IP address.
| |
|
| |
| Server_Software
| |
| The name and version number of the server software (e.g., Stronghold/2.0b3).
| |
|
| |
| Server_Name
| |
| The host being addressed in this request, which may be the main host or a virtual host, either as a fully-qualified domain name or an IP address.
| |
|
| |
| Gateway_Interface
| |
| The name and version number of the CGI gateway (e.g., CGI/1.1).
| |
|
| |
| Server_Protocol
| |
| The protocol and version number used to send the request, which the server may also use in its response in order to ensure compatibility with the client (e.g., protocol/version).
| |
|
| |
| Server_Port
| |
| The port number to which the request was sent.
| |
|
| |
| Request_Method
| |
| The method used in the request, such as GET or POST.
| |
|
| |
| Http_Accept
| |
| One or more MIME types that the client can accept (e.g., MIME-type[, MIME-type, MIME-type . . .]).
| |
|
| |
| Path_Info
| |
| Extra path information submitted in the request URL and used as input to a CGI program.
| |
|
| |
| Path_Translated
| |
| The absolute path of the requested file, if the value of Path_Info can be translated to a file.
| |
|
| |
| Script_Name
| |
| The URL of the requested script.
| |
|
| |
| Query_String
| |
| The query-string for this transaction, embedded in the requested URL.
| |
|
| |
| Remote_Host
| |
| The hostname or IP number of the client host or proxy server that originated the request.
| |
|
| |
| Remote_Addr
| |
| The IP number of the client host.
| |
|
| |
| Auth_Type
| |
| The authentication method used in this request, if any.
| |
|
| |
| Remote_User
| |
| The remote username, if the script is subject to basic authentication.
| |
|
| |
| Remote_Ident
| |
| The remote username, if available.
| |
|
| |
| Content_Type
| |
| The MIME type of any data attached to the request header.
| |
|
| |
| Content_Length
| |
| The size, in bytes as an integer, of any data attached to the request header.
| |
|
| |
| Content
| |
| Data attached to the request header.
| |
| Refer to the example for htmlCgi
| |
|
| |
|
| |
