molib documentation

Languages Available: français español

CLASS

moCGI

NAME

Constructor -- initialize an moCGI object
Destructor -- free all the resources used by the moCGI

VERSION

Version: 1.2.0

SYNOPSIS

moCGI(void);
virtual ~moCGI();

DESCRIPTION

The constructor initializes an moCGI object so you can use it to read the query information with one of the Read() functions.

The destructor ensures that the object released all the memory it used to read and hold the data.

SEE ALSO

ReadQuery, ReadPost, ReadMultiparts

BUGS

The destructor deletes th files received in a multipart message. This could be a problem if you wanted to 1st create a list of the files, then get rid of the moCGI object.

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moCGI

NAME

Empty -- clean up the resources currently used

VERSION

Version: 1.2.0

SYNOPSIS

virtual void Empty(void);

DESCRIPTION

You can reuse the same moCGI object to read multiple input source one after another. Each time you call one of the Read() function, this Empty() function is called to get rid of the information of the previous input.

If you are done an won't use the data held by the moCGI object anymore, you can also clean up by calling this function to release the data.

NOTES

After you called this function, the temporary files created with the data read from the message sent by the browser will have been deleted.

SEE ALSO

ReadQuery, ReadPost, ReadMultiparts

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moCGI

NAME

FixVars -- fix the variables after they were loaded
FixChars -- replace +'s and %##'s

VERSION

Version: 1.2.0

SYNOPSIS

void FixVars(const moWCString& encoding);
void FixChars(moWCString& string);

PARAMETERS

string - the value to fix

DESCRIPTION

When a query, post or multi-part message is sent via an HTTP connection the spaces are replaced by + characters and the special characters (such as the +, %, space, etc.) are replaced with a %## entry. Unicode characters are also replaced with U+####.

These functions fix these characters to the normal internal form. This is automatically called from the ReadQuery(), ReadPost() and ReadMultiparts() functions as required.

The FixChars() fixes one string and the FixVars() calls FixChars() with each one of the variables defined in this moCGI script.

RETURN VALUE

The FixChars() function modifies its input. It doesn't return anything.

SEE ALSO

ReadQuery, ReadPost, ReadMultiparts

BUGS

If you can the FixVars() more than once, you are likely to get invalid results.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moCGI

NAME

ReadQuery -- reads a standard HTML query
ReadPost -- reads a standard HTML post
ReadMultiparts -- reads a standard HTML multi-part message

VERSION

Version: 1.2.0

SYNOPSIS

bool ReadQuery(const moWCString& encoding);
bool ReadPost(const moWCString& encoding);
bool ReadMultiparts(const moWCString& encoding);

private:
bool ReadHeader(moCGIInput& in);
void ReadContentDisposition(moCGIInput& in, const mowc::wc_t *str);
void ReadFilename(moCGIInput& in);
void ReadData(moCGIInput& in);

PARAMETERS

encoding - the name of the encoding used in your HTML page
(note that the CGI can't infer that name)

DESCRIPTION

The ReadQuery() function gets the URL query information; in other words, what in the URL comes after the question mark (?). The variables are automatically broken up in a list of variables.

This call uses the environment variable QUERY_STRING.

The ReadPost() function reads one line from stdin and uses that as the list of variables to be broken up in this list of variables.

This call uses stdin and thus it can lock the application if the input never arrives.

The ReadMultiparts() function reads a seperator and then a list of parts which each are saved in a temporary file. The class will automatically delete these files once the moCGI is destroyed.

This call uses stdin and thus it can lock the application if the input never arrives. Also, because it will need to read many lines, it will be slow.

RETURN VALUE

These functions return true if some variables have been
defined in the moCGI object.

SEE ALSO

FixChars, SetTempDir, GetCount, GetFilename

BUGS

The conversion from the specified encoding only happens on the variable contents. Note the variable name nor the multi-part files.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moCGI

NAME

SetTempDir -- set the temporary directory

VERSION

Version: 1.2.0

SYNOPSIS

void SetTempDir(const moWCString& dir);

DESCRIPTION

Define a directory where the CGI object will create temporary files. This is especially useful whenever you expect to receive multi-part messages in which case the data will be saved in files in that directory.

EXAMPLES

SetTempDir("/var/tmp");

SEE ALSO

GetCount, GetFilename

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moCGI

NAME

GetCount -- get the number of multi-path filenames
GetFilename -- get one of the multi-path filename

VERSION

Version: 1.2.0

SYNOPSIS

unsigned long GetCount(void) const;
const moWCString& GetFilename(int idx) const;

DESCRIPTION

When a multi-part message is read (see ReadMultiparts), it saves the transfered files in temporary files. These files will automatically be deleted when the moCGI script is emptied, reused or released.

For you to be able to access these files, you need to have their filenames. This is done using the GetCount() function to know how many files were received and the GetFilename() to get the name of each file. Note that these names are not the user filenames. This is important because the user may be sending multiple files with the same name from different directories (and we can't know that these are from different directories on the clients machine). Thus, we need to save them in temporary file names.

If you don't want these files to be public, you certainly want to call SetTempDir() once with a private directory. By default, the system will use "/tmp".

EXAMPLES

moCGI cgi;
int idx, max;

cgi.SetTempDir("../tmp");
cgi.ReadMultiparts();
max = cgi.GetCount();
for(idx = 0; idx < max; ++idx) {
// NOTE:
// if you rename the file (we expect they are on
// the same drive...) it is fine because the CGI
// script doesn't generate an error if it can't
// delete one of the file
RenameFile(cgi.GetFilename(idx), ...);
}

NOTES

Changing the temporary directory after calling the ReadMultiparts() function will have no effect to the current filenames.

RETURN VALUE

GetCount() returns the number of files which were saved in
the last ReadMultiparts() call. This can be zero.

GetFilename() returns the specified filename. The index
needs to be between 0 and GetCount() - 1 inclusive.
The name will be fully qualified (include the path).

SEE ALSO

SetTempDir

BUGS

Since the Empty() function deletes all the files. Getting the filenames, calling Empty() and then trying to load the files won't work.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moCGI

NAME

VERSION

Version: 1.2.0

SYNOPSIS

void SetEtcDir(const moWCString& path, bool large = false);
bool Login(void);
void Logout(void);
bool CheckUserID(int time_out = 60 * 60);

PARAMETERS

time_out - seconds before the check fails

DESCRIPTION

The SetEtcDir() specifies where the password file will be found. Because the moPasswd object isn't very fast, there is a special option named 'large' to tell the system to make a sub-directory with the first two letters of the usernames. This will improve the search for users whenever your site is expected to have many users.

The password file read in that directory is 'passwd'. The format of the password file is as follow:

The <user id> is a unique identifier. It has nothing to do with the file created when the Login() function is created. Also, this id doesn't need to correspond to the real identifier of the Unix system if that same user has an account on that system.

The <user ips> is a list of ip/mask. If the user can connect from any computer, use: 0.0.0.0/32. If the user can connect only from one specific address, then specify that IP address and no mask (i.e. the default mask is 255.255.255.255). A port can be specified, but it will be ignored.

The <user groups> and <rights> are currently ignored.

The Login() function uses several variables to try to log a user in. This means looking up for a password and creating an identity file which is later used to know that such and such user is logged in.

The variables used by the Login() function are:

username The login name of the user trying to login; this represents the key used to search the password file

password The password for this user; since this feature should only be used with SSL connections, this password will be encrypted on the transitional connection and thus it is safe unless the user computer is being watched

The Login() function generates a unique filename each time a user logs in successfully. This filename is saved in a variable named 'id' (which stands for identity). The name doesn't represent the user nor the password. It is very much random. The function also creates that file and saves the username and his IP address in the file. Thus, when the user tries to go to another page (or loads images, etc.) the CGI scripts can check for the identity of the user to make sure that user is properly logged in. The file is created in the temporary directory as specified to the moCGI script by the SetTempDir().

The Logout() function deletes the file of the specified user. The function looks for the variable named 'id'. By deleting the file, the user will be considered non-logged in. All the pages which run after the login need to have a POST (avoid using the GET with secure protocols since the URL may not always be encrypted).

id filename of the user to logout

The CheckUserID() function search the user file (it expects a variable named 'id' like the Logout() file). If it finds the file, it reads it and compares the IP address saved in that file with the current IP address of the user. If they match, then the function returns true and you are considered logged in. If the IP addresses don't match or no user file of that name was found, then the check fails and the function returns false.

The check will also fail if the time_out parameter is set to a value other than 0 and the number of seconds since the user logged in is larger than this time_out value.

Note that when the CheckUserID() function fails, it deletes the identification file when present. This prevents the user from trying to use CGI scripts which require the user ID to be valid.

RETURN VALUE

SEE ALSO

ReadMultiparts, ReadFilename

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

private:
moCGI::moCGIInput

NAME

Constructor -- initializes a CGI input object
Destructor -- cleans up the CGI input object

VERSION

Version: 1.2.0

SYNOPSIS

moCGIInput(void);
~moCGIInput();

DESCRIPTION

Initializes and cleans up an moCGIInput object. Note that these objects are private to the moCGI implementation.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

private:
moCGI::moCGIInput

NAME

GetC -- read one character
NextLine -- read one line of text

VERSION

Version: 1.2.0

SYNOPSIS

long GetC(void);
bool NextLine(moWCString *& str);

DESCRIPTION

The GetC() function reads one character from the input.

The NextLine() function reads the next line of text. This is very similar to the NextLine() of the moTextStream except it makes sure that the very first character isn't 0x0FEFF.

It also forces the standard input reading in ISO-8859-1 which means that the input won't be modified, even when it is binary data.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

private:
moCGI::moCGIInput

NAME

SetHasFilename -- set whether there is a filename
GetHasFilename -- check whether a filename was specified
SetVariableName -- set the name of a variable
GetVariableName -- get the variable name
SetDelimiter -- defines the delimiter
GetDelimiter -- retrieve the delimiter
GetBuffer -- get the current buffer
GetLength -- get the length

VERSION

Version: 1.2.0

SYNOPSIS

void SetHasFilename(bool status = true);
bool GetHasFilename(void) const;
void SetVariableName(const moWCString& name);
const moWCString& GetVariableName(void) const;
void SetDelimiter(const moWCString& delimiter);
const char *GetDelimiter(void) const;
char *GetBuffer(void);
unsigned long GetLength(void) const;

DESCRIPTION

While reading a multi-part message, we can find a header which includes a filename. If that is the case, the filename flag will be turned on using the SetHasFilename() function.

Similarly, it is frequent that there will be a name. That name is used as a variable name and it will be saved in the CGI input as such.

The very first line you read from a multi-part message of a web server is a delimiter which seperate each input and ends the list of data.

That delimiter needs to be saved in the moCGIInput object and the system takes care of allocating a buffer which will later be used to check whether the delimiter was found. That is, the caller can get the pointer to the buffer, add bytes to it and compare it to the delimiter.

The length of the delimiter is found with GetLength().

The current delimiter can be retrieved with GetDelimiter().

RETURN VALUE

GetHasFilename returns true if we found a filename
GetVariableName returns the name of a variable
GetDelimiter returns the delimiter
GetBuffer returns a pointer to the internal buffer
GetLength returns the length of the internal buffer

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

private:
moCGI::moCGIInput

NAME

GetCount -- get the next unique number for this input file

VERSION

Version: 1.2.0

SYNOPSIS

unsigned int GetCount(void);

DESCRIPTION

In a multi-part message you can have many files one after another. This function returns a unique number for the next file found in such a multi-part message.

It is used to generate a unique filename such as

.../upload-<count>.tmp

At this time, the counter starts at 1 and increases by one on each call.

RETURN VALUE

the next unique number starting at 1

SEE ALSO

ReadMultiparts, ReadFilename

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox