N
net_flush() Function
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.
Syntax
int net_flush(SYS_NETFD sd);
Return Values
0 on success, or a negative value if an error occurs.
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() Function, net_sendfile() Function
net_ip2host() Function
The net_ip2host function transforms a textual IP address into a fully qualified domain name and returns the name.
Note –
This function works only if the DNS directive is enabled in the magnus.conf file.
Syntax
char *net_ip2host(char *ip, int verify);
Return Values
A new string containing the fully qualified domain name if the transformation is accomplished, or NULL if the transformation is 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 verification requires an extra query, you should use it when checking the access control.
net_read() Function
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);
Return Values
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 to limit the amount of time devoted to waiting until some data arrives.
See Also
net_sendfile() Function
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 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);
Return Values
A positive number indicating 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_write() Function
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);
Return Values
The number of bytes written, which might be less than the requested size if an error occurs.
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
netbuf_buf2sd() Function
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);
Return Values
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() Function, netbuf_getc() Function, netbuf_getbytes() Function, netbuf_grab() Function, netbuf_open() Function
netbuf_close() Function
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.
Never close the netbuf parameter in a session structure.
Syntax
void netbuf_close(netbuf *buf);
Return Values
void
Parameters
netbuf *buf is the buffer to close.
See Also
netbuf_buf2sd() Function, netbuf_getc() Function, netbuf_getbytes() Function, netbuf_grab() Function, netbuf_open() Function
netbuf_getbytes() Function
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);
Return Values
The number of bytes placed into the 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() Function, netbuf_close() Function, netbuf_getc() Function, netbuf_grab() Function, netbuf_open() Function
netbuf_getc() Function
The netbuf_getc function retrieves a character from the cursor position of the network buffer specified by b.
Note –
Because the constant IO_EOF has a value of 0, netbuf_getc cannot be used to read data that might contain a null character. To read binary data, use netbuf_getbytes() Function or netbuf_grab() Function.
Syntax
netbuf_getc(netbuf b);
Return Values
The integer representing the character if a character is retrieved, or the constant IO_EOF or IO_ERROR for end of file or an error.
Parameters
netbuf b is the buffer from which to retrieve one character.
See Also
netbuf_buf2sd() Function, netbuf_close() Function, netbuf_getbytes() Function, netbuf_grab() Function, netbuf_open() Function
netbuf_grab() Function
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);
Return Values
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 an error.
Parameters
netbuf *buf is the buffer to read into.
int sz is the number of bytes to read.
See Also
netbuf_buf2sd() Function, netbuf_close() Function, netbuf_getbytes() Function, netbuf_getc() Function, netbuf_open() Function
netbuf_open() Function
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);
Return Values
A pointer to a new netbuf network buffer structure.
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() Function, netbuf_close() Function, netbuf_getc() Function, netbuf_getbytes() Function, netbuf_grab() Function
nsapi_module_init() Function
Defines 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.
Use the nsapi_module_init function 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);
Return Values
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.
See Also
filter_create() Function, func_insert() Function, vs_register_cb() Function
NSAPI_RUNTIME_VERSION() Macro
The NSAPI_RUNTIME_VERSION macro defines the NSAPI version available at runtime. This version 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 Update 2. 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.
Do not attempt to set the value of the NSAPI_RUNTIME_VERSION macro directly. Instead, use 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
filter_create() Function, func_insert() Function, vs_register_cb() Function
NSAPI_VERSION() Macro
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.
Do not attempt to set the value of the NSAPI_VERSION macro directly. Instead, use 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
- © 2010, Oracle Corporation and/or its affiliates