File: conn.html

package info (click to toggle)
aolserver4 4.5.1-18.1
links: PTS, VCS
area: main
in suites: stretch
size: 12,008 kB
sloc: ansic: 45,126; tcl: 5,533; sh: 1,037; makefile: 380; pascal: 219; php: 13
file content (3475 lines) | stat: -rw-r--r-- 52,000 bytes
parent folder | download | duplicates (8)
<html>
<head>
<title>AOLserver</title>
</head>
<body>

<h1>Connection and Socket C Library Functions</h1>

<p>
$Header: /cvsroot/aolserver/aolserver.com/docs/devel/c/index.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
<p>





<h2><a name= href=./>Ns_BindSock</a></h2>

Bind socket as root

<h3>Syntax</h3>

<pre>    
    int Ns_BindSock (
    struct sockaddr_in* saPtr
    );
</pre>

<h3>Description</h3>

Bind a socket as root. This function can only be called before server
startup.

<p>

<hr>

<br>


<h2><a name= href=./>Ns_ConnAuthPasswd</a></h2>

Return password

<h3>Syntax</h3>

<pre>    
    char *Ns_ConnAuthPasswd(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnAuthPasswd function returns the decoded password from the
   header information associated with the connection.

<h3>Examples</h3>

<pre>
    /* PassTrace - A server trace to log users and passwords. */
    void
    PassTrace(void *ctx, Ns_Conn *conn)
    {
        char *user;
        char *pass;

        user = Ns_ConnAuthUser(conn);
        pass = Ns_ConnAuthPasswd(conn);
        if (user != NULL && pass != NULL) {
                Ns_Log(Notice, "User: %s Password: %s", user, pass);
        }
    }

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnAuthUser</a></h2>

Return user name

<h3>Syntax</h3>

<pre>    
    char *Ns_ConnAuthUser(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnAuthUser function returns the decoded user name from the
   header information associated with the connection.

<h3>Examples</h3>

<pre>
   See the example for Ns_ConnAuthPasswd.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnClose</a></h2>

Close a connection

<h3>Syntax</h3>

<pre>    
    int Ns_ConnClose(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnClose function closes a connection. The semantics of this
   call are specific to the driver associated with the connection. In the
   case of a socket driver (the nssock module), this function will cause
   the socket associated with the connection to be closed. Ns_ConnClose
   returns a status of NS_OK or NS_ERROR.

<p>

This function is called by AOLserver before running any registered
   traces. You do not normally need to call it.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnCondSetHeaders</a></h2>

Set the value for a header field conditionally

<h3>Syntax</h3>

<pre>    
    void Ns_ConnCondSetHeaders(
    Ns_Conn *conn,
    char *field,
    char *value
    );
</pre>

<h3>Description</h3>

The Ns_ConnCondSetHeaders function sets the value of a field if and
   only if the field/value pair does not already exist. The search for an
   existing field is not case sensitive.

<h3>Examples</h3>

<pre>
        /* Set a Cookie header if not already set. */
        Ns_ConnCondSetHeaders(conn, "Cookie", "randomStuff");

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnConstructHeaders</a></h2>

Put HTTP header into DString

<h3>Syntax</h3>

<pre>    
    void Ns_ConnConstructHeaders(
    Ns_Conn *conn,
    Ns_DString *dsPtr
    );
</pre>

<h3>Description</h3>

Put the header of an HTTP response into the DString. Content-Length
   and Connection-Keepalive headers will be added if possible.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnContentLength</a></h2>

Return content length

<h3>Syntax</h3>

<pre>    
    int Ns_ConnContentLength(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnContentLength function returns the number of bytes in the
   content associated with the connection.

<h3>Examples</h3>

<pre>
        /* Copy the content from the browser to a DString. */
        Ns_DString ds;
        int len;

        Ns_DStringInit(&ds);
        len = Ns_ConnContentLength(conn);
        Ns_ConnCopyToDString(conn, len, &ds);

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnContentSent</a></h2>

Check if browser sent content

<h3>Syntax</h3>

<pre>    
    int Ns_ConnContentSent (
    Ns_Conn* conn
    );
</pre>

<h3>Description</h3>

Returns TRUE if the browser sent any content, such as in a PUT
   request. Returns FALSE otherwise.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnCopyToChannel</a></h2>

Copy content to Tcl channel

<h3>Syntax</h3>

<pre>    
    int Ns_ConnCopyToChannel (
    Ns_Conn* conn,
    size_t iToCopy,
    Tcl_Channel chan
    );
</pre>

<h3>Description</h3>

Copy content, such as in a PUT request, from the connection into an
   open Tcl channel. iToCopy bytes will be copied.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnCopyToDString</a></h2>

Copy data from connection to dynamic string

<h3>Syntax</h3>

<pre>    
    int Ns_ConnCopyToDString(
    Ns_Conn *conn,
    size_t iToCopy,
    Ns_DString *pds
    );
</pre>

<h3>Description</h3>

The Ns_ConnCopyToDString function copies iToCopy bytes of data from
   the connection to the Ns_DString pointed to by pds.
   Ns_ConnCopyToDString returns a status of NS_OK or NS_ERROR.

<h3>Examples</h3>

<pre>
   See the example for Ns_ConnContentLength.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnCopyToFd</a></h2>

Copy content to file descriptor

<h3>Syntax</h3>

<pre>    
    int Ns_ConnCopyToFd (
    Ns_Conn* conn,
    size_t iToCopy,
    int fd
    );
</pre>

<h3>Description</h3>

Copy content, such as in a PUT request, from the connection into an
   open file descriptor. iToCopy bytes will be copied.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnCopyToFile</a></h2>

Copy data from connection to a file

<h3>Syntax</h3>

<pre>    
    int Ns_ConnCopyToFile(
    Ns_Conn *conn,
    size_t iToCopy,
    FILE *fp
    );
</pre>

<h3>Description</h3>

The Ns_ConnCopyToFile function copies iToCopy bytes of data from the
   connection to the file pointed to by fp. Ns_ConnCopyToFile returns a
   status of NS_OK or NS_ERROR.

<h3>Examples</h3>

<pre>
        /* Copy the content from the browser to a file. */
        FILE *fp;
        int len;

        fp = fopen("content.out", "w");
        len = Ns_ConnContentLength(conn);
        Ns_ConnCopyToFile(conn, len, fp);
        fclose(fp);

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnDriverContext</a></h2>

Return driver context

<h3>Syntax</h3>

<pre>    
    void *Ns_ConnDriverContext(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnDriverContext function returns a pointer to the
   communications driver context associated with the connection. This
   context is set in the Ns_QueueConn function. This function exists
   primarily for AOLserver communications driver developers.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnDriverName</a></h2>

Return driver name

<h3>Syntax</h3>

<pre>    
    char *Ns_ConnDriverName(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnDriverName function returns the communications driver name
   associated with the connection.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnFlushContent</a></h2>

Flush remaining content

<h3>Syntax</h3>

<pre>    
    int Ns_ConnFlushContent (
    Ns_Conn* conn
    );
</pre>

<h3>Description</h3>

Read all remaining content sent by the browser, for example in a PUT
   request, and throw it away.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnFlushHeaders</a></h2>

Mark the end of the headers

<h3>Syntax</h3>

<pre>    
    int Ns_ConnFlushHeaders(
    Ns_Conn *conn,
    int status
    );
</pre>

<h3>Description</h3>

The Ns_ConnFlushHeaders functions returns a single blank line that
   signifies the end of the headers. It also sets the state of the
   connection from header buffering mode to immediate sending of data to
   the client. Before this function is called, any headers are not
   actually sent to the client but instead are buffered in the Ns_Conn
   structure to avoid the cost of sending the headers in individual
   network packets.

<p>

The status is a standard error code such as 403 for access denied or
   200 for OK. Returns NS_OK or NS_ERROR.

<p>

This function is normally required just before sending content to the
   client.

<h3>Examples</h3>

<pre>
    /* A simple Hello request function. */
    int
    MyHello(Ns_Conn *conn, void *ctx)
    {
        char hello[] = "hello";
        int len;

        len = strlen(hello);
        Ns_ConnSetRequiredHeaders(conn, "text/plain", len);
        Ns_ConnFlushHeaders(conn, 200);
        return Ns_ConnWrite(conn, hello, len);
    }

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnGetQuery</a></h2>

Construct Ns_Set representing query data

<h3>Syntax</h3>

<pre>    
    Ns_Set *Ns_ConnGetQuery(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnGetQuery function constructs and returns an Ns_Set
   structure representing the query data associated with the connection.
   It reads the POST content or the query string. The POST content takes
   precedence over the query string.

<p>

Note that you must not call Ns_SetFree on the result of this function.

<h3>Examples</h3>

<pre>
        /* Get the value from an <INPUT NAME="mydata"> form tag. */
        Ns_Set *set;
        char *value;

        set = Ns_ConnGetQuery(conn);
        if (set != NULL) {
                value = Ns_SetGetValue(set, "mydata");
        }

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnGets</a></h2>

Read content into a buffer

<h3>Syntax</h3>

<pre>    
    char *Ns_ConnGets(
    char *buf,
    size_t sz,
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnGets function reads sz bytes of a single line (until
   newline/cr) from the connection into the buffer specified by buf.
   Ns_ConnGets returns buf or, in the case of a read error, NULL.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnHeaders</a></h2>

Return headers

<h3>Syntax</h3>

<pre>    
    Ns_Set *Ns_ConnHeaders(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnHeaders function returns, as an Ns_Set, the headers
   associated with the connection.

<h3>Examples</h3>

<pre>
        /* Log the Referer header. */
        Ns_Set *headers;
        char *refer;

        headers = Ns_ConnHeaders(conn);
        if (headers != NULL) {
                refer = Ns_SetGet(headers, "Referer");
                if (refer != NULL) {
                        Ns_Log(Notice, "Referer: %s", refer);
                }
        }

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnHost</a></h2>

Return host

<h3>Syntax</h3>

<pre>    
    char *Ns_ConnHost(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnHost function returns the server hostname associated with
   the connection.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnInit</a></h2>

Run socket init procedure

<h3>Syntax</h3>

<pre>    
    int Ns_ConnInit (
    Ns_Conn* connPtr
    );
</pre>

<h3>Description</h3>

Run a socket driver's init procedure. This function is usually only
   called internally.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnLocation</a></h2>

Return location

<h3>Syntax</h3>

<pre>    
    char *Ns_ConnLocation(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnLocation function returns the HTTP location associated with
   the connection. For example: http://www.avalon.com:81.

<p>

Multiple communications drivers can be loaded into a single server.
   This means a server may have more than one location. For example, if
   the nsssl module is loaded and bound to port 8000 and the nssock
   module is loaded and bound to port 9000, the server would have the
   following two locations:

        http://www.avalon.com:9000
        https://www.avalon.com:8000

   For this reason it is important to use the Ns_ConnLocation function to
   determine the driver location at run time.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnModifiedSince</a></h2>

Determine if content modified since a specified date

<h3>Syntax</h3>

<pre>    
    int Ns_ConnModifiedSince(
    Ns_Conn *conn,
    time_t mtime
    );
</pre>

<h3>Description</h3>

The Ns_ConnModifiedSince function returns 1 if the content associated
   with the connection has been modified since mtime. It uses the HTTP
   header variable "If-Modified-Since".
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnOutputHeaders</a></h2>

Get Ns_Set of headers to send to client

<h3>Syntax</h3>

<pre>    
    Ns_Set * Ns_ConnOutputHeaders(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

Get a writeable Ns_Set containing headers to send back to the client.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnPeer</a></h2>

Return name of peer

<h3>Syntax</h3>

<pre>    
    char *Ns_ConnPeer(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnPeer function returns the name of the peer associated with
   the connection.

<p>

The peer address is determined by the communications driver in use by
   the connection. Typically it is a dotted IP address, for example,
   199.221.53.205, but this is not guaranteed.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnPeerPort</a></h2>

Return peer port

<h3>Syntax</h3>

<pre>    
    int Ns_ConnPeerPort (
    Ns_Conn* conn
    );
</pre>

<h3>Description</h3>

Returns the port from which the peer is connected.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnPort</a></h2>

Return port

<h3>Syntax</h3>

<pre>    
    int Ns_ConnPort(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnPort function returns the server port number associated
   with the connection.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnPrintfHeader</a></h2>

Return a formatted header

<h3>Syntax</h3>

<pre>    
    int Ns_ConnPrintfHeader(
    Ns_Conn *conn,
    char *fmt,
    ...
    );
</pre>

<h3>Description</h3>

The Ns_ConnPrintfHeader function constructs a formatted string using
   the given format specification and any optional arguments. It then
   appends the necessary line feed and carriage return characters and
   sends the header to the client.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnPuts</a></h2>

Send a string to a client

<h3>Syntax</h3>

<pre>    
    int Ns_ConnPuts(
    Ns_Conn *conn,
    char *string
    );
</pre>

<h3>Description</h3>

The Ns_ConnPuts function sends the given string to the client. It
   returns NS_OK on success and NS_ERROR on failure.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnRead</a></h2>

Read content into buffer

<h3>Syntax</h3>

<pre>    
    int Ns_ConnRead(
    Ns_Conn *conn,
    void *pvBuf,
    int iToRead
    );
</pre>

<h3>Description</h3>

The Ns_ConnRead function reads iToRead bytes from the connection into
   pvBuf. Ns_ConnRead returns the status NS_ERROR or the number of bytes
   read from the connection.

<h3>Examples</h3>

<pre>
    /* Read content from the browser into buf. */
    char buf[1024];

    Ns_ConnRead(conn, buf, sizeof(buf));

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReadHeaders</a></h2>

Read headers into Ns_Set

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReadHeaders (
    Ns_Conn* conn,
    Ns_Set* psetHeaders,
    int* iRead
    );
</pre>

<h3>Description</h3>

Read headers from the conn and put them into the passed-in set.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReadLine</a></h2>

Read a line from a connection

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReadLine(
    Ns_Conn *conn,
    Ns_DString *pdsLine,
    int* *iRead
    );
</pre>

<h3>Description</h3>

The Ns_ConnReadLine function reads an \n or \r terminated line from
   the connection into the Ns_DString pointed to by pdsLine. The iRead
   argument will contain the number of bytes read. Ns_ConnReadLine
   returns a status of NS_OK or NS_ERROR.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnRedirect</a></h2>

Perform internal redirect

<h3>Syntax</h3>

<pre>    
    int Ns_ConnRedirect (
    Ns_Conn* conn,
    char* url
    );
</pre>

<h3>Description</h3>

Perform an internal redirect, i.e., make it appear that the user
   requested a different URL and then run that request. This doesn't
   require an additional thread.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReplaceHeaders</a></h2>

Replace output headers for connection

<h3>Syntax</h3>

<pre>    
    void Ns_ConnReplaceHeaders(
    Ns_Conn *conn,
    Ns_Set *newheaders
    );
</pre>

<h3>Description</h3>

The Ns_ConnReplaceHeaders function sets the current output headers for
   the connection to the newheaders set. It copies the newheaders set and
   frees memory associated with the old output headers in the connection.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnResponseLength</a></h2>

Return response length

<h3>Syntax</h3>

<pre>    
    int Ns_ConnResponseLength(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnResponseStatus function returns the response length
   associated with the connection. This value is only meaningful after a
   response has been returned to the client. This function will normally
   be used in trace functions. See Ns_RegisterTrace for more information
   about traces.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnResponseStatus</a></h2>

Return response status

<h3>Syntax</h3>

<pre>    
    int Ns_ConnResponseStatus(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnResponseStatus function returns the response status
   associated with the connection. This value is only meaningful after a
   response has been returned to the client. This function will normally
   be used in trace functions. See Ns_RegisterTrace for more information
   about traces.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnAdminNotice</a></h2>

Return a short notice to a client to contact system administrator

<h3>Syntax</h3>

<pre>    
    void Ns_ConnReturnAdminNotice(
    Ns_Conn *conn,
    int status,
    char *notice,
    char *html
    );
</pre>

<h3>Description</h3>

The Ns_ConnReturnAdminNotice function returns to a client a simple
   HTML page with the given notice as the title of the page. It also
   appends a message directing users to contact the system administrator
   or web master if specified in the configuration file. The page
   includes the /NS/Asset/notice.gif image at the top of the page. If the
   html parameter is not NULL, it is added to the page after the notice.
   The HTML source can be arbitrarily long and should not contain the
   <HTML> or <BODY> begin or end tags; these tags will be added by
   Ns_ConnReturnAdminNotice. Ns_ConnReturnAdminNotice returns a status of
   NS_OK or NS_ERROR.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnBadRequest</a></h2>

Return an "invalid request" HTTP status line.

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnBadRequest(
    Ns_Conn *conn,
    char *reason
    );
</pre>

<h3>Description</h3>

Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of
   400 to indicate that the request was invalid.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnData</a></h2>

Return an HTML string to a client

<h3>Syntax</h3>

<pre>    
    EXTERN int Ns_ConnReturnData(
    Ns_Conn *conn,
    int status,
    char *html,
    int len,
    char *type
    );
</pre>

<h3>Description</h3>

The Ns_ConnReturnData function calls the Ns_ConnSetRequiredHeaders
   function with the given status followed by the given HTML string. The
   length is used to generate the Content-Length header. If the length is
   -1, the function calculates the Content-Length from the string. The
   type is used to generate the Content-Type header. Ns_ConnReturnData
   returns a status of NS_OK or NS_ERROR.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnFile</a></h2>

Return a file to a client

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnFile(
    Ns_Conn *conn,
    int status,
    char *type,
    char *file
    );
</pre>

<h3>Description</h3>

The Ns_ConnReturnFile function returns the entire contents of the
   given file to the client. In addition to setting the HTTP status
   response line and Content-Type headers from the given parameters,
   Ns_ConnReturnFile also uses the stat system call to generate the
   appropriate Last-Modified and Content-Length headers.
   Ns_ConnReturnFile returns a status of NS_OK or NS_ERROR.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnForbidden</a></h2>

Return a "request forbidden" HTTP status line.

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnForbidden(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of
   403 to indicate that the request is forbidden. There is no
   Authorization header that will authorize access from this IP address.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnHtml</a></h2>

Return an HTML string to a client

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnHtml(
    Ns_Conn *conn,
    int status,
    char *html,
    int len
    );
</pre>

<h3>Description</h3>

The Ns_ConnReturnHtml function calls the Ns_ConnSetRequiredHeaders
   function with the given status followed by the given HTML string. The
   length is used to generate the Content-Length header. If the length is
   -1, the function calculates the Content-Length from the string.
   Ns_ConnReturnHtml returns a status of NS_OK or NS_ERROR.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnInternalError</a></h2>

Return an "internal error" HTTP status line.

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnInternalError(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of
   500 to indicate that an internal error occurred.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnNoResponse</a></h2>

Return a "no response" HTTP status line.

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnNoResponse(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of
   204 to indicate that the request requires no response.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnNotFound</a></h2>

Return a "not found" HTTP status line.

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnNotFound(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of
   404 to indicate that the requested URL was not found on the server.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnNotice</a></h2>

Return a short notice to a client

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnNotice(
    Ns_Conn *conn,
    int status,
    char *notice,
    char *html
    );
</pre>

<h3>Description</h3>

The Ns_ConnReturnNotice function returns to a client a simple HTML
   page with the given notice as the title of the page. The page includes
   the /NS/Asset/notice.gif image at the top of the page. If the html
   parameter is not NULL, it is added to the page after the notice. The
   HTML source can be arbitrarily long and should not contain the <HTML>
   or <BODY> begin or end tags; these tags will be added by
   Ns_ConnReturnNotice. AOLserver uses Ns_ConnReturnNotice extensively,
   to achieve a consistent look on the pages it automatically generates.
   Ns_ConnReturnNotice returns a status of NS_OK or NS_ERROR.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnNotImplemented</a></h2>

Return a "not implemented" HTTP status line.

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnNotImplemented(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of
   500 to indicate that the request has not been implemented by the
   server.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnNotModified</a></h2>

Return a "not modified" HTTP status line.

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnNotModified(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of
   304 to indicate that the requested data have not been modified since
   the time specified by the If-Modified-Since header sent by the client.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnOk</a></h2>

Return an "OK" HTTP status line.

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnOk(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of
   200 to indicate that the request was successful.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnOpenChannel</a></h2>

Write channel content to conn

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnOpenChannel (
    Ns_Conn* conn,
    int status,
    char* type,
    Tcl_Channel chan,
    int len
    );
</pre>

<h3>Description</h3>

Write len bytes of an open Tcl channel out to the conn. Return HTTP
   status in status and Content-type in type.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnOpenFd</a></h2>

Return a file to a client

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnOpenFile(
    Ns_Conn *conn,
    int status,
    char *type,
    int fd,
    int len
    );
</pre>

<h3>Description</h3>

The Ns_ConnReturnOpenFd function is the same as Ns_ConnReturnFile
   except that it takes an fd argument instead of a file name, and it
   requires an additional length argument. It returns the entire contents
   of the given file to the client. Ns_ConnReturnOpenFd returns a status
   of NS_OK or NS_ERROR.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnOpenFile</a></h2>

Return a file to a client

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnOpenFile(
    Ns_Conn *conn,
    int status,
    char *type,
    FILE *fp,
    int len
    );
</pre>

<h3>Description</h3>

The Ns_ConnReturnOpenFile function is the same as Ns_ConnReturnFile
   except that it takes a FILE *fp argument instead of a file name, and
   it requires an additional length argument. It returns the entire
   contents of the given file to the client. Ns_ConnReturnOpenFile
   returns a status of NS_OK or NS_ERROR.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnRedirect</a></h2>

Return an HTTP redirect response to a client

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnRedirect(
    Ns_Conn *conn,
    char *location
    );
</pre>

<h3>Description</h3>

The Ns_ConnReturnRedirect function returns a properly formatted HTTP
   redirect message for the given location. This causes the browser to
   seamlessly open the new location on behalf of the user.
   Ns_ConnReturnRedirect returns NS_OK or NS_ERROR.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnStatus</a></h2>

Return a status message to a client

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnStatus(
    Ns_Conn *conn,
    int status
    );
</pre>

<h3>Description</h3>

The Ns_ConnReturnStatus function calls Ns_ConnSetRequiredHeaders with
   the given status and reason and then immediately calls
   Ns_ConnFlushHeaders. It can be used when only the status of the
   request must be returned to the client.

<p>

The status is a standard error code such as 403 for access denied or
   200 for OK. Returns NS_OK or NS_ERROR.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnReturnUnauthorized</a></h2>

Return an "unauthorized" HTTP status line.

<h3>Syntax</h3>

<pre>    
    int Ns_ConnReturnUnauthorized(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of
   401 to indicate that the request did not include a valid Authorization
   header or the header did not specify an authorized user. The user will
   usually be prompted for a username/password after this status is
   returned.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnRunRequest</a></h2>

Execute procedure for method and URL pattern

<h3>Syntax</h3>

<pre>    
    int Ns_ConnRunRequest(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

Locate and execute the procedure for the given method and URL pattern
   (in the conn->request). Returns a standard request procedure result,
   normally NS_OK.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnSendChannel</a></h2>

Send Tcl channel content to conn

<h3>Syntax</h3>

<pre>    
    int Ns_ConnSendChannel (
    Ns_Conn* conn,
    Tcl_Channel chan,
    int len
    );
</pre>

<h3>Description</h3>

Read len bytes from an open Tcl channel and write it out to the conn
   until EOF.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnSendDString</a></h2>

Write a DString to the conn

<h3>Syntax</h3>

<pre>    
    int Ns_ConnSendDString(
    Ns_Conn *conn,
    Ns_DString *dsPtr
    );
</pre>

<h3>Description</h3>

Write out a DString to the conn.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnSendFd</a></h2>

Write file to connection content

<h3>Syntax</h3>

<pre>    
    int Ns_ConnSendFd(
    Ns_Conn *conn,
    int fd,
    int len
    );
</pre>

<h3>Description</h3>

The Ns_ConnSendFd function writes len bytes from the file pointed to
   by fd to the connection. Ns_ConnSendFd returns the status NS_ERROR or
   NS_OK.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnSendFp</a></h2>

Write file to connection content

<h3>Syntax</h3>

<pre>    
    int Ns_ConnSendFp(
    Ns_Conn *conn,
    FILE *fp,
    int len
    );
</pre>

<h3>Description</h3>

The Ns_ConnSendFp function writes len bytes from the file pointed to
   by fp to the connection. Ns_ConnSendFp returns the status NS_ERROR or
   NS_OK.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnServer</a></h2>

Return name of server

<h3>Syntax</h3>

<pre>    
    char *Ns_ConnServer(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

The Ns_ConnServer function returns the name of the server associated
   with the connection.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnSetExpiresHeader</a></h2>

Return an "expires" header for the given time

<h3>Syntax</h3>

<pre>    
    void Ns_ConnSetExpiresHeader(
    Ns_Conn *conn,
    char *httptime
    );
</pre>

<h3>Description</h3>

The Ns_ConnSetExpiresHeader formats and sends a header that will
   expire, using the time specified by the httptime string. You can use
   the Ns_HttpTime function to generate the time specification string.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnSetHeaders</a></h2>

Set the value for a header field

<h3>Syntax</h3>

<pre>    
    void Ns_ConnSetHeaders(
    Ns_Conn *conn,
    char *field,
    char *value
    );
</pre>

<h3>Description</h3>

The Ns_ConnSetHeaders function sets the value of a field in the output
   headers, replacing an existing field/value pair.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnSetLastModifiedHeader</a></h2>

Return a last modified header using the given time

<h3>Syntax</h3>

<pre>    
    void Ns_ConnSetLastModifiedHeader(
    Ns_Conn *conn,
    time_t *when
    );
</pre>

<h3>Description</h3>

The Ns_ConnSetLastModifiedHeader function formats and sends a
   Last-Modified header based on the given time. The time parameter is
   most often generated with the stat system call on an existing file.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnSetLengthHeader</a></h2>

Return a Content-Length header

<h3>Syntax</h3>

<pre>    
    void Ns_ConnSetLengthHeader(
    Ns_Conn *conn,
    int len
    );
</pre>

<h3>Description</h3>

The Ns_ConnSetLengthHeader function formats and sends a Content-Length
   header for the given length.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnSetRequiredHeaders</a></h2>

Return the required HTTP headers

<h3>Syntax</h3>

<pre>    
    void Ns_ConnSetRequiredHeaders(
    Ns_Conn *conn,
    char *contentType,
    int contentLength
    );
</pre>

<h3>Description</h3>

The Ns_ConnSetRequiredHeaders function writes the required headers of
   the HTTP response. If contentType is NULL, it defaults to 'text/html'.
   If contentLength is 0, no contentLength header will be written out.

<p>

The Ns_ConnReturnStatus function can be used to return a status-only
   response to the client.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnSetTypeHeader</a></h2>

Return a Content-Type header

<h3>Syntax</h3>

<pre>    
    void Ns_ConnSetTypeHeader(
    Ns_Conn *conn,
    char *type
    );
</pre>

<h3>Description</h3>

The Ns_ConnSetTypeHeader function formats and sends a Content-Type
   header for the given type. You can use the Ns_GuessMimeType() function
   to look up a Content-Type string for filename.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConnWrite</a></h2>

Send data to a client

<h3>Syntax</h3>

<pre>    
    int Ns_ConnWrite(
    Ns_Conn *conn,
    void *buf,
    int len
    );
</pre>

<h3>Description</h3>

The Ns_ConnWrite function attempts to write out the specified length
   of data from the given buffer to the client. It returns the number of
   bytes sent or -1 if there is an error. This function may write fewer
   than len bytes.

<h3>Examples</h3>

<pre>

    /* Write towrite bytes from buf. */

    while (towrite > 0) {
        int nwrote;

        nwrote = Ns_ConnWrite(conn, buf, towrite);
        if (nwrote == -1) {
                /* ... handle error ... */
        }
        buf += nwrote;
        towrite -= nwrote;
    }

   
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_DriverEnableKeepalive</a></h2>

Enable HTTP keepalive on driver

<h3>Syntax</h3>

<pre>    
    void Ns_DriverEnableKeepalive (
    Ns_Driver driver
    );
</pre>

<h3>Description</h3>

This function is used by socket drivers; it enables HTTP keepalive on
   the specified driver.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_GetDriver</a></h2>

Get socket driver

<h3>Syntax</h3>

<pre>    
    Ns_Driver Ns_GetDriver (
    char* hServer,
    char* hDriver
    );
</pre>

<h3>Description</h3>

Find the socket driver of the current server and the specified driver
   name. (The hserver argument is ignored; it is only there for backwards
   compatibility.)
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_GetDriverContext</a></h2>

Get socket driver context

<h3>Syntax</h3>

<pre>    
    void* Ns_GetDriverContext (
    Ns_Driver drv
    );
</pre>

<h3>Description</h3>

Return a socket driver's context pointer, which is set when the driver
   is registered with Ns_RegisterDriver.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_GetDriverLabel</a></h2>

Get socket driver label

<h3>Syntax</h3>

<pre>    
    char* Ns_GetDriverLabel (
    Ns_Driver driver
    );
</pre>

<h3>Description</h3>

Get the name of the socket driver as it appears in the configuration
   file. For example, the following configuration file entries would
   result in this function returning "mysocket":
    ns_section ns/server/server1/modules
    ns_param mysocket nsssl

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_GetDriverName</a></h2>

Get socket driver name

<h3>Syntax</h3>

<pre>    
    char* Ns_GetDriverName (
    Ns_Driver driver
    );
</pre>

<h3>Description</h3>

Get the name (for eample, `nsssl' or `nssock') of a socket driver.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_GetDriverProc</a></h2>

Get a communications driver procedure

<h3>Syntax</h3>

<pre>    
    int Ns_GetDriverProc(
    Ns_Driver driver,
    Ns_DrvId id,
    void **pprocPtrPtr
    );
</pre>

<h3>Description</h3>

Get a communications driver procedure for the specified ID. Valid ID
   values are listed in the left column of the table below.

<p>

The procPtrPtr will be filled in with the address of a registerd
   driver function. NS_ERROR will be returned if no registered function
   could be found. The resulting function is of the type shown in the
   right column below

<p>

ID Value

<p>

Resulting Function Type

<p>

Ns_DrvIdName

<p>

typedef char *(Ns_ConnDriverNameProc) (void *pConnCtx);

<p>

Ns_DrvIdStart

<p>

typedef int (Ns_DriverStartProc) (char *hServer, char *hDriver, void
   **ppDriverCtx);

<p>

Ns_DrvIdAccept

<p>

typedef int (Ns_DriverAcceptProc) (void *pDriverCtx, void
   **ppConnCtx);

<p>

Ns_DrvIdStop

<p>

typedef void (Ns_DriverStopProc) (void *pDriverCtx);

<p>

Ns_DrvIdInit

<p>

typedef int (Ns_ConnInitProc) (void *pConnCtx);

<p>

Ns_DrvIdRead

<p>

typedef int (Ns_ConnReadProc) (void *pConnCtx, void *pvBuf, int
   iToRead);

<p>

Ns_DrvIdWrite

<p>

typedef int (Ns_ConnWriteProc) (void *pConnCtx, void *pvBuf, int
   iToWrite);

<p>

Ns_DrvIdClose

<p>

typedef int (Ns_ConnCloseProc) (void *pConnCtx);

<p>

Ns_DrvIdFree

<p>

typedef void (Ns_ConnFreeProc) (void *pConnCtx);

<p>

Ns_DrvIdPeer

<p>

typedef char *(Ns_ConnPeerProc) (void *pConnCtx);

<p>

Ns_DrvIdLocation

<p>

typedef char *(Ns_ConnLocationProc) (void *pConnCtx);

<p>

Ns_DrvIdHost

<p>

typedef char *(Ns_ConnHostProc) (void *pConnCtx);

<p>

Ns_DrvIdPort

<p>

typedef int (Ns_ConnPortProc) (void *pConnCtx);

<p>

Ns_DrvIdSendFd

<p>

typedef int (Ns_ConnSendFdProc) (void *pConnCtx, int fd, int nsend);

<p>

Ns_DrvIdSendFile

<p>

typedef int (Ns_ConnSendFileProc) (void *pConnCtx, char *file);

<p>

Ns_DrvIdDetach

<p>

typedef void *(Ns_ConnDetachProc) (void *pConnCtx);

<p>

Ns_DrvIdConnectionFd

<p>

typedef int (Ns_ConnConnectionFdProc) (void *pConnCtx);

<p>

Ns_DrvIdMoveContext

<p>

(unsupported)

<p>

Ns_DrvIdPeerPort

<p>

typedef int (Ns_ConnPeerPortProc) (void *pConnCtx);

<p>

Ns_DrvIdSetSSLAuth

<p>

typedef int (Ns_SetSSLAuthProc) (void *pCtx, Ns_SSLAuthProc *, void
   *ctx, Ns_FreeAuthCtxProc *);

<p>

Ns_DrvIdSSLHandshake

<p>

typedef void *(Ns_SSLHandshakeProc) (void *aCtx, int socket, char *DN,
   Ns_SSLAuthProc *auth, void *authctx, Ns_FreeAuthCtxProc *pFree);

<p>

:
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_GetFirstDriver</a></h2>

Get pointer to first socket driver

<h3>Syntax</h3>

<pre>    
    void* Ns_GetFirstDriver (
    char* ignored
    );
</pre>

<h3>Description</h3>

Returns a pointer to the first socket driver. Use this function with
   Ns_GetNextDriver.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_GetHostByAddr</a></h2>

Convert an IP address to a hostname

<h3>Syntax</h3>

<pre>    
    int Ns_GetHostByAddr(
    Ns_DString *pds,
    char *addrStr
    );
</pre>

<h3>Description</h3>

The Ns_GetHostByAddr function converts a numeric IP address into a
   host name. If no name can be found, the function returns NS_FALSE;
   otherwise, it returns NS_TRUE. Because the response time of the Domain
   Name Service can be slow, this function may significantly delay the
   response to a client. The hostname string is appended to the specified
   Ns_DString (pds).
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_GetNextDriver</a></h2>

Get pointer to next socket driver

<h3>Syntax</h3>

<pre>    
    void* Ns_GetNextDriver (
    Ns_Driver driver
    );
</pre>

<h3>Description</h3>

Returns a pointer to the next socket driver. Use this function with
   Ns_GetFirstDriver.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_GetSockAddr</a></h2>

Get socket driver address

<h3>Syntax</h3>

<pre>    
    int Ns_GetSockAddr (
    struct sockaddr_in* saPtr,
    char* host,
    int port
    );
</pre>

<h3>Description</h3>

Specify host and port in saPtr. Specify an IP address or a hostname
   for host. A NULL host means INADDR_ANY.
</pre>


<p>

<hr>

<br>





<h2><a name= href=./>Ns_QueueConn</a></h2>

Make and queue a new conn

<h3>Syntax</h3>

<pre>    
    int Ns_QueueConn (
    Ns_Driver driver,
    void* ctx
    );
</pre>

<h3>Description</h3>

Make a new conn and put it on the list of conns to be served. This
   function is called by socket drivers.
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_RegisterDriver</a></h2>

Register a socket driver

<h3>Syntax</h3>

<pre>    
    Ns_Driver Ns_RegisterDriver (
    char* hServer,
    char* hDriver,
    Ns_DrvProc* procs,
    void* ctx
    );
</pre>

<h3>Description</h3>

Register a socket driver.
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_RegisterLocation</a></h2>

Register location for socket driver

<h3>Syntax</h3>

<pre>    
    int Ns_RegisterLocation (
    char* name,
    char* location,
    char* address,
    int port
    );
</pre>

<h3>Description</h3>

Register the built-in socket driver with the name of the socket driver
   and a location, host, and port. For example:
    Ns_RegisterLocation("nssock", "http://host:port/",
    "hostname.com", 80)

   After this call, the server will immediately begin serving pages from
   that location, host, and port.
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_SockAsyncConnect</a></h2>

Create a remote socket and return immediately

<h3>Syntax</h3>

<pre>    
    SOCKET Ns_SockAsyncConnect (
    char *host,
    int port
    );
</pre>

<h3>Description</h3>

Ns_SockAsyncConnect creates a socket connected to a remote host and
   port, returning immediately with the connection in progress. A select
   call can later be used to determine when the connection has been
   established.

<h3>Examples</h3>

<pre>
    SOCKET sock;
    fd_set set;
    struct timeval tv;
    sock = Ns_SockAsyncConnect("mailhost", 25);
    ... perform some other work while connection is in progress...

    ... check for connection ...
    tv.tv_sec = 2; /* allow 2 more seconds */
    tv.tv_usec = 0;
    FD_ZERO(&set);
    FD_SET(sock, &set);
    if (select(sock+1, NULL, &set, NULL, &tv) != 1) {
      ... timeout - close socket and return error...
      Ns_CloseLater(sock);
    } else {
      ... use socket ...
    }

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_SockCallback</a></h2>

Register a socket callback function

<h3>Syntax</h3>

<pre>    
    int Ns_SockCallback (
    SOCKET sock,
    Ns_SockProc *proc,
    void *ctx,
    int when
    );
</pre>

<h3>Description</h3>

Ns_SockCallback registers a user-defined socket callback function and
   should be called by your module at startup time. You must create a
   listening TCP socket (named sock). The ctx argument is your context
   which will be passed back as the second argument of your callback
   function.

<p>

The when argument is a bitmask with one or more of the following
   options specified:

<p>

NS_SOCK_READ:

<p>

the socket is readable

<p>

NS_SOCK_WRITE:

<p>

the socket is writeable

<p>

NS_SOCK_EXCEPTION:

<p>

the socket has an exceptional condition

<p>

NS_SOCK_EXIT:

<p>

the server is shutting down

<p>

The proc is your socket callback function in the following format:
    typedef int (Ns_SockProc) (int sock, void *arg, int why);

   The sock will be a readable, writable socket. The arg is the ctx you
   passed to Ns_SockCallback. The why argument is the when you passed to
   Ns_SockCallback.

<p>

At startup time, AOLserver creates a single socket service thread
   dedicated to handling socket callbacks. Since several sockets are
   needed to listen for connection requests, and because connection
   requests are handled so quickly, all the socket drivers share a single
   thread for that purpose.

<h3>Examples</h3>

<pre>
    1. Create a C callback function to handle a request. The callback
       function must execute without blocking so that other sockets can
       get serviced. Typically, the callback function just performs an
       accept() call and queues the request. The prototype is:
    typedef int (Ns_SockProc) (SOCKET sock, void *context, int
why);
       
        The parameters are:
                
   sock
             the registered socket
   context
             your context passed to Ns_SockCallback()
   why
             the reason the function was called, which is one of the following:
   NS_SOCK_READ: the socket is readable
   NS_SOCK_WRITE: the socket is writeable
   NS_SOCK_EXCEPTION: the socket has an exceptional condition
   NS_SOCK_EXIT: the server is shutting down

<p>

     The callback function must return either NS_TRUE to tell the
                socket thread to keep watching the socket or NS_FALSE to
                tell the socket thread to stop watching the socket.
                
        For example:
                
    int
    MySock(SOCKET sock, void *context, int why)
    {
          if (why == NS_SOCK_READ) {
                  .. handle read ..
                if (error) {
                            return NS_FALSE;
                } else {
                        return NS_TRUE;
                  }
          } else if (why == NS_SOCK_EXIT) {
                  .. free(context) ..
                  return NS_FALSE;
          }
    }
    2. At server startup time, your module must register your callback
       function with the server using the Ns_SockCallback() function.
       
        This example specifies that MySock will be called when the socket
                is readable or when the server is shutting down:
                
    Ns_SockCallback(sock, MySock, myCtx,
        NS_SOCK_READ | NS_SOCK_EXIT);
       
        Remember that there is only one socket service thread, so your
                callback function must return immediately without
                blocking!
             </pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_SockCancelCallback</a></h2>

Remove a socket callback

<h3>Syntax</h3>

<pre>    
    void Ns_SockCancelCallback(
    int sock
    );
</pre>

<h3>Description</h3>

Remove a callback registered on a socket.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_SockConnect</a></h2>

Create a socket to a remote host and port

<h3>Syntax</h3>

<pre>    
    SOCKET Ns_SockConnect (
    char *host,
    int port
    );
</pre>

<h3>Description</h3>

Ns_SockConnect creates a socket connected to a remote host and port.
   Ns_SockConnect waits for the connection to be established before
   returning.

<h3>Examples</h3>

<pre>
    sock = Ns_SockConnect("mailhost", 25);
    if (sock != INVALID_SOCKET) {
     ... talk SMTP over sock ...
    }

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_SockListen</a></h2>

Create a socket on a specified address and port

<h3>Syntax</h3>

<pre>    
    SOCKET Ns_SockListen (
    char *host,
    int port
    );
</pre>

<h3>Description</h3>

Ns_SockListen creates a socket listening for connections on the
   specified address and port.

<h3>Examples</h3>

<pre>
    sock = Ns_SockListen("localhost", 25);
    while (1) {
       new = accept(sock, NULL, 0);
       ... communicate with client on new ...
    }

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_SockListenCallback</a></h2>

Register a socket callback function and create socket

<h3>Syntax</h3>

<pre>    
    int Ns_SockListenCallback (
    char* address,
    int port,
    Ns_SockProc* proc,
    void* ctx
    );
</pre>

<h3>Description</h3>

Ns_SockListenCallback registers a user-defined socket callback
   function and should be called by your module at startup time. It also
   creates, binds, and listens on the socket (with the specified address
   and port) for you.

<p>

The proc is your socket callback function. The ctx argument is your
   context which will be passed back as the second argument of your
   callback function.

<p>

The when argument is a bitmask with one or more of the following
   options specified:

<p>

NS_SOCK_READ:

<p>

the socket is readable

<p>

NS_SOCK_EXIT:

<p>

the server is shutting down
   

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_SockPipe</a></h2>

Return a pair of connected sockets

<h3>Syntax</h3>

<pre>    
    int Ns_SockPipe (
    SOCKET socks[2]
    );
</pre>

<h3>Description</h3>

Ns_SockPipe returns a pair of connected sockets. On Unix, Ns_SockPipe
   uses socketpair(). A socket pipe can be used for IPC between threads
   or as a way to wakeup a thread waiting in a select call as in the
   example below.

<h3>Examples</h3>

<pre>
    SOCKET sockPipe[2];
    /* Init - called at startup to create the pipe. */
    void Init(void)
    {
        Ns_SockPipe(sockPipe);
    }
    /* Wakeup - called by another thread to stop InteruptableIO in
       another thread. */

    void Wakeup(void)
    {
      send(sockPipe[1], "w", 1, 0);
    }
    /* InterruptableIO - called by a thread dedicated to reading from
       a remote host.  Reading will continue until another thread
       calls Wakeup, causing sockPipe to be readable. */

    void InteruptableIO(void)
    {
          SOCKET sock, max;
          fd_set set;
          char sig;
          sock = Ns_SockConnect("slowmachine", 6767);
          FD_ZERO(&set);
          FD_SET(sock, &set);
          FD_SET(sockPipe[0], &set);
          max = sockPipe;
          if (sock > max) {
             max = sock;
          }
          while (1) {
              select(max+1, &set, NULL, NULL, NULL);
              if (FD_ISSET(sockPipe[0], &set)) {
                      /* Another thread called Wakeup().
                       * Read the signal and return. */
                      recv(sockPipe[0], &sig, 1, 0);
                      closesocket(sock);
                      return;
              } else if (FD_ISSET(sock, &set)) {
                      recv(sock, buf, sizeof(buf), 0);
                      ... process buf ...
              }
          }
    }

   Note: Interruptable I/O typically makes use of the alarm() system call
   on Unix. The method above, used throughout AOLserver, works on all
   platforms and avoids the alarm system call which is inappropriate for
   a multithreaded application.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_SockPortBound</a></h2>

Determine if port is bound

<h3>Syntax</h3>

<pre>    
    int Ns_SockPortBound (
    int port
    );
</pre>

<h3>Description</h3>

This function returns a boolean value specifying whether the specified
   port is already bound. The port is a TCP port, and INADDR_ANY is
   assumed.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_SockSetBlocking</a></h2>

Set a socket in blocking mode

<h3>Syntax</h3>

<pre>    
    Ns_SockSetBlocking (
    SOCKET sock
    );
</pre>

<h3>Description</h3>

Ns_SockSetBlocking sets a socket in blocking I/O mode.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_SockSetNonBlocking</a></h2>

Set a socket in nonblocking mode

<h3>Syntax</h3>

<pre>    
    Ns_SockSetNonBlocking (
    SOCKET sock
    );
</pre>

<h3>Description</h3>

Ns_SockSetNonBlocking sets a socket in nonblocking I/O mode.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_SockTimedConnect</a></h2>

Create a remote socket within a specified time

<h3>Syntax</h3>

<pre>    
    SOCKET Ns_SockTimedConnect (
    char *host,
    int port,
    int timeout
    );
</pre>

<h3>Description</h3>

Ns_SockTimedConnect creates a socket connected to a remote host and
   port, ensuring that the connection is established within the number of
   seconds specified by the timeout argument.

<h3>Examples</h3>

<pre>
    sock = Ns_SockTimedConnect("mailhost", 25);
    if (sock == INVALID_SOCKET) {
       ... timeout or error connecting ...
    } else {
       ... use socket ...
    }

   
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_TclGetConn</a></h2>

Get connection

<h3>Syntax</h3>

<pre>    
    Ns_Conn* Ns_TclGetConn (
    Tcl_Interp* interp
    );
</pre>

<h3>Description</h3>

Return the conn associated with this thread. The interp parameter is
   ignored and should be NULL.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_WriteConn</a></h2>

Send a specified length of data to the client

<h3>Syntax</h3>

<pre>    
    int Ns_WriteConn(
    Ns_Conn *conn,
    char *buf,
    int len
    );
</pre>

<h3>Description</h3>

The Ns_WriteConn function performs the same function as Ns_ConnWrite,
   except that Ns_WriteConn guarantees to write as many bytes as are
   specified in len. It writes the specified length of data from the
   buffer to the client.
</pre>


<p>

<hr>

<br>



</body>
</html>