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.
int net_flush(SYS_NETFD sd);
0 on success, or a negative value if an error occurred.
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 that name.
This function works only if the DNS directive is enabled in the obj.conf file. For more information, see Sun Java System Web Proxy Server 4.0.6 Configuration File Reference.
char *net_ip2host(char *ip, int verify);
A new string containing the fully qualified domain name if the transformation was accomplished, or NULL if the transformation was 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. This parameter requires an extra query but you should use it when checking 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. Do not use timeout to return because not enough bytes were read in the given time instead, use this parameter 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 socket. Either the whole file or a fraction of a file may be sent. The contents of the file may optionally be preceded 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 indicates the number of bytes successfully written, including the headers, file contents, and trailers. A negative value indicates 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 occurred.
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_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_grab, netbuf_open
The netbuf_getc function retrieves a character from the cursor position of the network buffer specified by b.
netbuf_getc(netbuf b);
The integer representing the character if one was 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_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 was 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_grab, 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_grab
plug-in 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, and create filters with filter_create .
int nsapi_module_init(pblock *pb, Session *sn, Request *rq);
Returns 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.
The NSAPI_RUNTIME_VERSION macro defines the NSAPI version available at runtime. This value 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 Java System Web Server 6.1, and Sun Java System Web Proxy Server 4.0 and higher. 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.
plug-in developers should 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; }
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, 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.
plug-in developers should 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; }