The net_flush function flushes any buffered data. If you require that data be sent immediately, call net_flush after calling the network output functions such as net_write or net_sendfile.
int net_flush(SYS_NETFD sd);
0 on success, or a negative value if an error occurs.
SYS_NETFD sd is the socket to flush.
net_write(sn->csd, "Please wait... ", 15); net_flush(sn->csd); /* Perform some time-intensive operation */ ... net_write(sn->csd, "Thank you.\n", 11);
The net_ip2host function transforms a textual IP address into a fully-qualified domain name and returns it.
This function works only if the DNS directive is enabled in the magnus.conf file.
char *net_ip2host(char *ip, int verify);
A new string containing the fully-qualified domain name if the transformation is accomplished, or NULL if the transformation is not accomplished.
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 the access control.
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.
int net_read (SYS_NETFD sd, char *buf, int sz, int timeout);
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.
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.
The net_sendfile function sends the contents of a specified file to a specified a socket. Either the whole file or a fraction might be sent, and the contents of the file might 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.
int net_sendfile(SYS_NETFD sd, const sendfiledata *sfd);
A positive number indicating the number of bytes successfully written, including the headers, file contents, and trailers. A negative value indicating an error.
SYS_NETFD sd is the socket to write to.
const sendfiledata *sfd identifies the data to send.
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; }
The net_write function writes a specified number of bytes to a specified socket from a specified buffer.
int net_write(SYS_NETFD sd, char *buf, int sz);
The number of bytes written, which may be less than the requested size if an error occurs.
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.
if (net_write(sn->csd, FIRSTMSG, strlen(FIRSTMSG)) == IO_ERROR) return REQ_EXIT;
The netbuf_buf2sd function sends a buffer to a socket. You can use this function to send data from IPC pipes to the client.
int netbuf_buf2sd(netbuf *buf, SYS_NETFD sd, int len);
The number of bytes transferred to the socket, if successful, or the constant IO_ERROR if unsuccessful.
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.
netbuf_close, netbuf_getc, netbuf_getbytes, netbuf_grab, netbuf_open
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.
void netbuf_close(netbuf *buf);
void
netbuf *buf is the buffer to close.
netbuf_buf2sd, netbuf_getc, netbuf_getbytes, netbuf_grab, netbuf_open
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.
int netbuf_getbytes(netbuf *buf, char *buffer, int sz);
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.
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.
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; }
netbuf_buf2sd, netbuf_close, netbuf_getc, netbuf_grab, netbuf_open
The netbuf_getc function retrieves a character from the cursor position of the network buffer specified by b.
Because the constant IO_EOF has a value of 0, netbuf_getc cannot be used to read data that may contain a null character. To read binary data, use netbuf_getbytes or netbuf_grab.
netbuf_getc(netbuf b);
The integer representing the character if a character is retrieved, or the constant IO_EOF or IO_ERROR for end of file or error.
netbuf b is the buffer from which to retrieve one character.
netbuf_buf2sd, netbuf_close, netbuf_getbytes, netbuf_grab, netbuf_open
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.
int netbuf_grab(netbuf *buf, int sz);
The number of bytes actually read (between 1 and sz) if the operation is successful, or the constant IO_EOF or IO_ERROR for end of file or error.
netbuf *buf is the buffer to read into.
int sz is the number of bytes to read.
netbuf_buf2sd, netbuf_close, netbuf_getbytes, netbuf_getc, 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.
netbuf* netbuf_open(SYS_NETFD sd, int sz);
A pointer to a new netbuf structure (network buffer).
SYS_NETFD sd is the platform-independent identifier of the socket.
int sz is the number of characters to allocate for the network buffer.
netbuf_buf2sd, netbuf_close, netbuf_getc, netbuf_getbytes, netbuf_grab
Define the 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 is 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.
int nsapi_module_init(pblock *pb, Session *sn, Request *rq);
REQ_PROCEED on success, or REQ_ABORTED on error.
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.
filter_create, func_insert, vs_register_cb
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, Sun ONE Web Server 6.1 and Sun Java System Web Server 7.0. 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.
You must not attempt to set the value of the NSAPI_RUNTIME_VERSION macro directly. Instead, see the USE_NSAPI_VERSION macro.
int NSAPI_RUNTIME_VERSION
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; }
filter_create, func_insert, vs_register_cb
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 or 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.
You must not attempt to set the value of the NSAPI_VERSION macro directly. Instead, see the USE_NSAPI_VERSION macro.
int NSAPI_VERSION
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; }