Sun Java System Web Server 6.1 SP7 NSAPI Programmer's Guide

N

net_flush

The net_flush function flushes any buffered data. If you require that data be sent immediately, call net_flush after calling network output functions such as net_write or net_sendfile.

Syntax

int net_flush(SYS_NETFD sd);

Returns

0 on success, or a negative value if an error occurred.

Parameters

SYS_NETFD sd is the socket to flush.

Example

net_write(sn->csd, "Please wait... ", 15);
net_flush(sn->csd);
/* Perform some time-intensive operation */
...
net_write(sn->csd, "Thank you.\n", 11);

See Also

net_write, net_sendfile

net_ip2host

The net_ip2host function transforms a textual IP address into a fully-qualified domain name and returns it.


Note –

This function works only if the DNS directive is enabled in the magnus.conf file. For more information, see Chapter 2, SAFs in the magnus.conf File.


Syntax

char *net_ip2host(char *ip, int verify);

Returns

A new string containing the fully-qualified domain name if the transformation was accomplished, or NULL if the transformation was not accomplished.

Parameters

char *ip is the IP address as a character string in dotted-decimal notation: nnn.nnn.nnn.nnn

int verify, if nonzero, specifies that the function should verify the fully-qualified domain name. Though this requires an extra query, you should use it when checking access control.

net_read

The net_read function reads bytes from a specified socket into a specified buffer. The function waits to receive data from the socket until either at least one byte is available in the socket or the specified time has elapsed.

Syntax

int net_read (SYS_NETFD sd, char *buf, int sz, int timeout);

Returns

The number of bytes read, which will not exceed the maximum size, sz. A negative value is returned if an error has occurred, in which case errno is set to the constant ETIMEDOUT if the operation did not complete before timeout seconds elapsed.

Parameters

SYS_NETFD sd is the platform-independent socket descriptor.

char *buf is the buffer to receive the bytes.

int sz is the maximum number of bytes to read.

int timeout is the number of seconds to allow for the read operation before returning. The purpose of timeout is not to return because not enough bytes were read in the given time, but to limit the amount of time devoted to waiting until some data arrives.

See Also

net_write

net_sendfile

The net_sendfile function sends the contents of a specified file to a specified socket. Either the whole file or a fraction may be sent, and the contents of the file may optionally be preceded and/or followed by caller-specified data.

Parameters are passed to net_sendfile in the sendfiledata structure. Before invoking net_sendfile, the caller must initialize every sendfiledata structure member.

Syntax

int net_sendfile(SYS_NETFD sd, const sendfiledata *sfd);

Returns

A positive number indicates the number of bytes successfully written, including the headers, file contents, and trailers. A negative value indicates an error.

Parameters

SYS_NETFD sd is the socket to write to.

const sendfiledata *sfd identifies the data to send.

Example

The following Service SAF sends a file bracketed by the strings "begin" and "end."

#include <string.h>
#include "nsapi.h"

NSAPI_PUBLIC int service_net_sendfile(pblock *pb, Session *sn, Request *rq)
{
    char *path;
    SYS_FILE fd;
    struct sendfiledata sfd;
    int rv;

    path = pblock_findval("path", rq->vars);
    fd = system_fopenRO(path);
    if (!fd) {
        log_error(LOG_MISCONFIG, "service-net-sendfile", sn, rq,
                  "Error opening %s (%s)", path, system_errmsg());
        return REQ_ABORTED;
    }

    sfd.fd = fd;                         /* file to send */
    sfd.offset = 0;                       /* start sending from the beginning */
    sfd.len = 0;                         /* send the whole file */
    sfd.header = "begin";               /* header data to send before the file */
    sfd.hlen = strlen(sfd.header);        /* length of header data */
    sfd.trailer = "end";                /* trailer data to send after the file */
    sfd.tlen = strlen(sfd.trailer);       /* length of trailer data */

    /* send the headers, file, and trailers to the client */
    rv = net_sendfile(sn->csd, &sfd);

    system_fclose(fd);

    if (rv < 0) {
        log_error(LOG_INFORM, "service-net-sendfile", sn, rq,"Error sending %s 
(%s)", path, system_errmsg());
        return REQ_ABORTED;
    }

    return REQ_PROCEED;
}

See Also

net_flush

net_write

The net_write function writes a specified number of bytes to a specified socket from a specified buffer.

Syntax

int net_write(SYS_NETFD sd, char *buf, int sz);

Returns

The number of bytes written, which may be less than the requested size if an error occurred.

Parameters

SYS_NETFD sd is the platform-independent socket descriptor.

char *buf is the buffer containing the bytes.

int sz is the number of bytes to write.

Example

if (net_write(sn->csd, FIRSTMSG, strlen(FIRSTMSG)) == IO_ERROR)    return REQ_EXIT;

See Also

net_read

netbuf_buf2sd

The netbuf_buf2sd function sends a buffer to a socket. You can use this function to send data from IPC pipes to the client.

Syntax

int netbuf_buf2sd(netbuf *buf, SYS_NETFD sd, int len);

Returns

The number of bytes transferred to the socket, if successful, or the constant IO_ERROR if unsuccessful.

Parameters

netbuf *buf is the buffer to send.

SYS_NETFD sd is the platform-independent identifier of the socket.

int len is the length of the buffer.

See Also

netbuf_close, netbuf_getc, netbuf_grab, netbuf_open, netbuf_getbytes

netbuf_close

The netbuf_close function deallocates a network buffer and closes its associated files. Use this function when you need to deallocate the network buffer and close the socket.

You should never close the netbuf parameter in a session structure.

Syntax

void netbuf_close(netbuf *buf);

Returns

void

Parameters

netbuf *buf is the buffer to close.

See Also

netbuf_buf2sd, netbuf_getc, netbuf_grab, netbuf_open, netbuf_getbytes

netbuf_getbytes

The netbuf_getbytes function reads bytes from a network buffer into a caller-supplied buffer. If the network buffer is empty, the function waits to receive data from the network buffer's socket until either at least one byte is available from the socket or the network buffer's timeout has elapsed.

Syntax

int netbuf_getbytes(netbuf *buf, char *buffer, int sz);

Returns

The number of bytes placed into buffer (between 1 and sz) if the operation is successful, the constant NETBUF_EOF on end of file, or the constant NETBUF_ERROR if an error occurred.

Parameters

netbuf *buf is the buffer from which to retrieve bytes.

char *buffer is the caller-supplied buffer that receives the bytes.

int sz is the maximum number of bytes to read.

Example

int cl = 0;

* Read the entire request body */
for (;;) {
     char mybuf[1024];
     int rv;

     rv = netbuf_getbytes(sn->inbuf, mybuf, sizeof(mybuf));
     if (rv == NETBUF_EOF) {
         log_error(LOG_INFORM, "mysaf", sn, rq,
                   "Received %d byte(s)",
                   cl);
         break;
     }
     if (rv == NETBUF_ERROR) {
         log_error(LOG_FAILURE, "mysaf", sn, rq,
                   "Error reading request body (%s)",
                   cl, system_errmsg());
         break;     }

     cl += rv;
} 

See Also

netbuf_buf2sd, netbuf_close, netbuf_getc, netbuf_grab, netbuf_open

netbuf_getc

The netbuf_getc function retrieves a character from the cursor position of the network buffer specified by b.

Syntax

netbuf_getc(netbuf b);

Returns

The integer representing the character if one was retrieved, or the constant IO_EOF or IO_ERROR for end of file or error.

Parameters

netbuf b is the buffer from which to retrieve one character.

See Also

netbuf_buf2sd, netbuf_close, netbuf_grab, netbuf_open, netbuf_getbytes

netbuf_grab

The netbuf_grab function reads sz number of bytes from the network buffer’s (buf) socket into the network buffer. If the buffer is not large enough it is resized. The data can be retrieved from buf->inbuf on success.

This function is used by the function netbuf_buf2sd.

Syntax

int netbuf_grab(netbuf *buf, int sz);

Returns

The number of bytes actually read (between 1 and sz) if the operation was successful, or the constant IO_EOF or IO_ERROR for end of file or error.

Parameters

netbuf *buf is the buffer to read into.

int sz is the number of bytes to read.

See Also

netbuf_buf2sd, netbuf_close, netbuf_grab, netbuf_open, netbuf_getbytes

netbuf_open

The netbuf_open function opens a new network buffer and returns it. You can use netbuf_open to create a netbuf structure and start using buffered I/O on a socket.

Syntax

netbuf* netbuf_open(SYS_NETFD sd, int sz);

Returns

A pointer to a new netbuf structure (network buffer).

Parameters

SYS_NETFD sd is the platform-independent identifier of the socket.

int sz is the number of characters to allocate for the network buffer.

See Also

netbuf_buf2sd, netbuf_close, netbuf_getc, netbuf_grab, netbuf_getbytes

nsapi_module_init

Plugin developers may define an nsapi_module_init function, which is a module initialization entry point that enables a plug-in to create filters when it is loaded. When an NSAPI module contains an nsapi_module_init function, the server will call that function immediately after loading the module. The nsapi_module_init presents the same interface as an Init SAF, and it must follow the same rules.

The nsapi_module_init function may be used to register SAFs with func_insert, create filters with filter_create, register virtual server initialization/destruction callbacks with vs_register_cb, and perform other initialization tasks.

Syntax

int nsapi_module_init(pblock *pb, Session *sn, Request *rq);

Returns

REQ_PROCEED on success, or REQ_ABORTED on error.

Parameters

pblock *pb is a set of parameters specified by the fn="load-modules" directive.

Session *sn (the Session) is NULL.

Request *rq (the Request) is NULL.

NSAPI_RUNTIME_VERSION

The NSAPI_RUNTIME_VERSION macro defines the NSAPI version available at runtime. This is the same as the highest NSAPI version supported by the server the plug-in is running in. The NSAPI version is encoded as in USE_NSAPI_VERSION.

The value returned by the NSAPI_RUNTIME_VERSION macro is valid only in iPlanet™ Web Server 6.0, Netscape Enterprise Server 6.0, and Sun Java System Web Server 6.1. That is, the server must support NSAPI 3.1 for this macro to return a valid value. Additionally, to use NSAPI_RUNTIME_VERSION, you must compile against an nsapi.h header file that supports NSAPI 3.2 or higher.

Plugin developers should not attempt to set the value of the NSAPI_RUNTIME_VERSION macro directly. Instead, see the USE_NSAPI_VERSION macro.

Syntax

int NSAPI_RUNTIME_VERSION

Example

NSAPI_PUBLIC int log_nsapi_runtime_version(pblock *pb, Session *sn, Request *rq) {
    log_error(LOG_INFORM, "log-nsapi-runtime-version", sn, rq,
                "Server supports NSAPI version %d.%d\n",
                NSAPI_RUNTIME_VERSION / 100,
                NSAPI_RUNTIME_VERSION % 100);
return REQ_PROCEED;
}

See Also

NSAPI_VERSION,USE_NSAPI_VERSION

NSAPI_VERSION

The NSAPI_VERSION macro defines the NSAPI version used at compile time. This value is determined by the value of the USE_NSAPI_VERSION macro. If the plug-in developer did not define USE_NSAPI_VERSION, by the highest NSAPI version supported by the nsapi.h header the plug-in was compiled against. The NSAPI version is encoded as in USE_NSAPI_VERSION.

Plugin developers should not attempt to set the value of the NSAPI_VERSION macro directly. Instead, see the USE_NSAPI_VERSION macro.

Syntax

int NSAPI_VERSION

Example

NSAPI_PUBLIC int log_nsapi_compile_time_version(pblock *pb, Session *sn, Request *rq) {
    log_error(LOG_INFORM, "log-nsapi-compile-time-version", sn, rq,
            "Plugin compiled against NSAPI version %d.%d\n",
            NSAPI_VERSION / 100,
            NSAPI_VERSION % 100);
return REQ_PROCEED;
}

See Also

NSAPI_RUNTIME_VERSION, USE_NSAPI_VERSION