<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>Session Handling</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.3-rc2 -->
<center>
<a class="qindex" href="main.html">Main Page</a> <a class="qindex" href="modules.html">Modules</a> <a class="qindex" href="pages.html">Related Pages</a> </center>
<hr><h1>Session Handling</h1><hr><a name="_details"></a><h2>Detailed Description</h2>
One of the most diferencials of LibCGI is its support to sessions, a mechanism that permits the application to keep variables trough the user's session, when he is visiting your website.
<p>
<table width='90%' align='center' border='0' bgcolor='#cccccc'>
<tr>
<td>
Session functions are easy to use and understand, and probably you'll want to take a closer
look at <i>cgi_session_save_path()</i> and <i>cgi_session_cookie_name()</i> functions. These functions,
let the programmer to set the directory where session files will
be saved in the hard disk and the cookie name to the session, respectively.
<br><br>
As the CGI is running on the webserver which a common user, it have full access to its respective session
file. But the most big problem is that you may
have full access to all other session files as well, even from other sites. Yes, that's a big problem, and still
other large used scripting languages like PHP does have this kind of problem (using the default installation).
So, LibCGI is trying to
make a bit harder to a potential attacker to stole session data or even destroy it.
Now is possible to store session files in different locations, specified
by the programmer ( using <i>cgi_session_save_path()</i> function ), as described in this doc ). <br>
And yes, I ( me, LibCGI's author ) knows that there are problems yet, so your opinion is very important.
You will find some useful examples under "examples/sessions" directory.
</td>
</tr>
</table>
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td></td></tr>
<tr><td colspan=2><br><h2>Functions</h2></td></tr>
<tr><td nowrap align=right valign=top>int </td><td valign=bottom><a class="el" href="group__libcgi__session.html#a15">cgi_session_destroy</a> ()</td></tr>
<tr><td> </td><td><font size=-1><em>Destroys the session.</em> <a href="#a15"></a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>char * </td><td valign=bottom><a class="el" href="group__libcgi__session.html#a17">cgi_session_var</a> (const char *var_name)</td></tr>
<tr><td> </td><td><font size=-1><em>Gets session variable's value.</em> <a href="#a17"></a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>void </td><td valign=bottom><a class="el" href="group__libcgi__session.html#a18">cgi_session_cookie_name</a> (const char *cookie_name)</td></tr>
<tr><td> </td><td><font size=-1><em>Defines the name of the cookie that LibCGI will use to store session's ID.</em> <a href="#a18"></a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>void </td><td valign=bottom><a class="el" href="group__libcgi__session.html#a19">cgi_session_save_path</a> (const char *path)</td></tr>
<tr><td> </td><td><font size=-1><em>Defines where session control files will be saved.</em> <a href="#a19"></a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>int </td><td valign=bottom><a class="el" href="group__libcgi__session.html#a20">cgi_session_register_var</a> (const char *name, const char *value)</td></tr>
<tr><td> </td><td><font size=-1><em>Register a variable in the current opened session.</em> <a href="#a20"></a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>int </td><td valign=bottom><a class="el" href="group__libcgi__session.html#a21">cgi_session_alter_var</a> (const char *name, const char *new_value)</td></tr>
<tr><td> </td><td><font size=-1><em>Alter session variable value.</em> <a href="#a21"></a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>int </td><td valign=bottom><a class="el" href="group__libcgi__session.html#a22">cgi_session_var_exists</a> (const char *name)</td></tr>
<tr><td> </td><td><font size=-1><em>Searches for determined session variable.</em> <a href="#a22"></a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>int </td><td valign=bottom><a class="el" href="group__libcgi__session.html#a23">cgi_session_unregister_var</a> (char *name)</td></tr>
<tr><td> </td><td><font size=-1><em>Unregister some session variable.</em> <a href="#a23"></a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>int </td><td valign=bottom><a class="el" href="group__libcgi__session.html#a24">cgi_session_start</a> ()</td></tr>
<tr><td> </td><td><font size=-1><em>Starts a new session.</em> <a href="#a24"></a><em></em></font><br><br></td></tr>
</table>
<hr><h2>Function Documentation</h2>
<a name="a21" doxytag="session.c::cgi_session_alter_var"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> int cgi_session_alter_var </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top">const char * </td>
<td class="mdname" nowrap> <em>name</em>, </td>
</tr>
<tr>
<td></td>
<td></td>
<td class="md" nowrap>const char * </td>
<td class="mdname" nowrap> <em>new_value</em></td>
</tr>
<tr>
<td></td>
<td class="md">) </td>
<td class="md" colspan="2"></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Alter session variable value.
<p>
Change session variable 'name' value to data pointer by 'new_value' <dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign=top><em>name</em> </td><td>Session variable name to change </td></tr>
<tr><td valign=top><em>new_value</em> </td><td>New session variable value </td></tr>
</table>
</dl>
<dl compact><dt><b>See also:</b></dt><dd><a class="el" href="group__libcgi__session.html#a20">cgi_session_register_var()</a>, <a class="el" href="group__libcgi__session.html#a23">cgi_session_unregister_var()</a> </dd></dl>
</td>
</tr>
</table>
<a name="a18" doxytag="session.c::cgi_session_cookie_name"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> void cgi_session_cookie_name </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top">const char * </td>
<td class="mdname1" valign="top" nowrap> <em>cookie_name</em> </td>
<td class="md" valign="top">) </td>
<td class="md" nowrap></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Defines the name of the cookie that LibCGI will use to store session's ID.
<p>
This function works like <a class="el" href="group__libcgi__session.html#a19">cgi_session_save_path()</a>. This functionality let you to use different names for each site, but remember, you cannot use multiple session for the same application yet.
<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign=top><em>cookie_name</em> </td><td>Name of the cookie to create </td></tr>
</table>
</dl>
<dl compact><dt><b>See also:</b></dt><dd><a class="el" href="group__libcgi__session.html#a19">cgi_session_save_path()</a> </dd></dl>
<dl compact><dt><b>Note:</b></dt><dd>This function must be called before <a class="el" href="group__libcgi__session.html#a24">cgi_session_start()</a> </dd></dl>
</td>
</tr>
</table>
<a name="a15" doxytag="session.c::cgi_session_destroy"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> int cgi_session_destroy </td>
<td class="md" valign="top">( </td>
<td class="mdname1" valign="top" nowrap> </td>
<td class="md" valign="top">) </td>
<td class="md" nowrap></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Destroys the session.
<p>
Destroys the current opened session, including all data. After session_destroy() was called, is not more possible to use session functions before an another call to session_start() <dl compact><dt><b>Returns:</b></dt><dd>1 if no errors, 0 if. </dd></dl>
<dl compact><dt><b>See also:</b></dt><dd><a class="el" href="group__libcgi__session.html#a24">cgi_session_start</a>
<p>
cgi_session_error_message </dd></dl>
</td>
</tr>
</table>
<a name="a20" doxytag="session.c::cgi_session_register_var"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> int cgi_session_register_var </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top">const char * </td>
<td class="mdname" nowrap> <em>name</em>, </td>
</tr>
<tr>
<td></td>
<td></td>
<td class="md" nowrap>const char * </td>
<td class="mdname" nowrap> <em>value</em></td>
</tr>
<tr>
<td></td>
<td class="md">) </td>
<td class="md" colspan="2"></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Register a variable in the current opened session.
<p>
Note that we are opening and closing the session file every time this function is called... ( I/O ^ 1000000 :-/ ) <dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign=top><em>name</em> </td><td>Variable name </td></tr>
<tr><td valign=top><em>value</em> </td><td>Variable value </td></tr>
</table>
</dl>
<dl compact><dt><b>See also:</b></dt><dd><a class="el" href="group__libcgi__session.html#a21">cgi_session_alter_var()</a>, <a class="el" href="group__libcgi__session.html#a23">cgi_session_unregister_var()</a> </dd></dl>
</td>
</tr>
</table>
<a name="a19" doxytag="session.c::cgi_session_save_path"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> void cgi_session_save_path </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top">const char * </td>
<td class="mdname1" valign="top" nowrap> <em>path</em> </td>
<td class="md" valign="top">) </td>
<td class="md" nowrap></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Defines where session control files will be saved.
<p>
If in the your CGI you don't make a call to <a class="el" href="group__libcgi__session.html#a19">cgi_session_save_path()</a>, LibCGI will use the default value, which is "/tmp/". To see how to modify the value, see the following example. <br>
Just note you need to add '/' at the end of the directory name <div class="fragment"><pre>
<span class="comment">// your_cgi.c</span>
<span class="comment">// Set "session_files" directory under your CGI directory as the path </span>
<span class="comment">// which LibCGI will use to store session files.</span>
<a class="code" href="group__libcgi__session.html#a19">cgi_session_save_path</a>(<span class="stringliteral">"session_files/"</span>);
</pre></div>
<p>
Note that using this form, LibCGI will search for "session_files" directory using relative path to your cgi application. For example, if your CGI script is located at /usr/local/httpd/web/your_name/cgi-bin/ directory, and you use the above declaration, the files for the session will be stored at /usr/local/httpd/web/your_name/cgi-bin/session_files directory. Resuming, the path is relative to where your application resides. <br>
<br>
And remember, LibCGI <b>does</b> <b>not</b> create the directory for you.
<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign=top><em>path</em> </td><td>Path, relative or absolute </td></tr>
</table>
</dl>
<dl compact><dt><b>See also:</b></dt><dd><a class="el" href="group__libcgi__session.html#a18">cgi_session_cookie_name</a> </dd></dl>
<dl compact><dt><b>Note:</b></dt><dd>This function must be called before <a class="el" href="group__libcgi__session.html#a24">cgi_session_start()</a> </dd></dl>
</td>
</tr>
</table>
<a name="a24" doxytag="session.c::cgi_session_start"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> int cgi_session_start </td>
<td class="md" valign="top">( </td>
<td class="mdname1" valign="top" nowrap> </td>
<td class="md" valign="top">) </td>
<td class="md" nowrap></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Starts a new session.
<p>
This function is responsible for starting and creating a new session. It must be called before any other session function, and every time before any HTML header has sent. <dl compact><dt><b>See also:</b></dt><dd>session_destroy() </dd></dl>
</td>
</tr>
</table>
<a name="a23" doxytag="session.c::cgi_session_unregister_var"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> int cgi_session_unregister_var </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top">char * </td>
<td class="mdname1" valign="top" nowrap> <em>name</em> </td>
<td class="md" valign="top">) </td>
<td class="md" nowrap></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Unregister some session variable.
<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign=top><em>name</em> </td><td>Session variable name to unregister </td></tr>
</table>
</dl>
<dl compact><dt><b>See also:</b></dt><dd><a class="el" href="group__libcgi__session.html#a22">cgi_session_var_exists()</a>, <a class="el" href="group__libcgi__session.html#a20">cgi_session_register_var()</a> </dd></dl>
</td>
</tr>
</table>
<a name="a17" doxytag="session.c::cgi_session_var"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> char* cgi_session_var </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top">const char * </td>
<td class="mdname1" valign="top" nowrap> <em>var_name</em> </td>
<td class="md" valign="top">) </td>
<td class="md" nowrap></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Gets session variable's value.
<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign=top><em>name</em> </td><td>Session variable name to get the value </td></tr>
</table>
</dl>
<dl compact><dt><b>Returns:</b></dt><dd>Variable contents if found, NULL if not. </dd></dl>
<dl compact><dt><b>See also:</b></dt><dd><a class="el" href="group__libcgi__session.html#a22">cgi_session_var_exists()</a> </dd></dl>
</td>
</tr>
</table>
<a name="a22" doxytag="session.c::cgi_session_var_exists"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> int cgi_session_var_exists </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top">const char * </td>
<td class="mdname1" valign="top" nowrap> <em>name</em> </td>
<td class="md" valign="top">) </td>
<td class="md" nowrap></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Searches for determined session variable.
<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign=top><em>name</em> </td><td>Session variable name to search </td></tr>
</table>
</dl>
<dl compact><dt><b>Returns:</b></dt><dd>1 if variable is registered, 0 if not </dd></dl>
<dl compact><dt><b>See also:</b></dt><dd><a class="el" href="group__libcgi__session.html#a17">cgi_session_var()</a> </dd></dl>
</td>
</tr>
</table>
<hr><address style="align: right;"><small>Generated on Thu Mar 13 10:13:11 2003 for LibCGI by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border=0
width=110 height=53></a>1.3-rc2 </small></address>
</body>
</html>
