Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Chapter 10 - C API Reference Guide, Part I / Processing Requests
Sending Data to the Client

Content handlers are responsible for sending the HTTP headers to the client followed by the contents of the document itself (if any). The functions listed in this section provide the interface for sending data to the client. In addition to handling the details of writing the information to the outgoing TCP connection, Apache keeps track of the number of bytes sent, updating the bytes_sent field of the request record each time one of these calls is made. In general, the calls return the number of bytes successfully sent to the client or EOF (-1) if the client unexpectedly closed the connection.

Because it's possible for the client to hang while accepting data from the server, you should bracket your writes with calls to ap_hard_timeout() or ap_soft_timeout() to time out broken connections or extraordinarily slow connections. See "The Timeout API" later in this chapter for more details.

The declarations for these functions can all be found in the include file http_protocol.h. They all begin with the prefix ap_r, where the "r" stands for "request_rec," a required argument for each call.

void ap_send_http_header (request_rec *r)

This function sends the status line and all HTTP headers, building them up from the contents of the request record's headers_out and err_headers_out tables, along with various fields including content_type and content_encoding. Certain headers are generated by ap_send_http_header() that are not related to the request record, such as Server and Date.

int ap_rwrite (const void *buf, int nbyte, request_rec *r)

This function will send nbyte bytes of the contents of the data buffer buf to the client. The function result is the number of bytes actually sent or -1 if an error occurred before any bytes could be sent.

   if ((sent = ap_rwrite(buffer, len, r)) < 0) {
       ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_WARNING,
                   r->server, "error during ap_rwrite()");
  }

int ap_rputs (const char *str, request_rec *r)

This function will send a string of arbitrary length to the client, returning the number of bytes actually sent.

ap_rputs(html_tag, r);

int ap_rvputs (request_rec *r,...)

The ap_rvputs() function works just like ap_rputs(), but it accepts a variable list of string arguments, which must be NULL-terminated.

ap_rvputs(r, "<", html_tag, ">", NULL);

int ap_rputc (int c, request_rec *r)

This function is used to send a single character to the client, similar to the standard I/O library function putc(). The function returns the character on success, EOF (-1) on failure.

ap_rputc('<', r);
ap_rputs(html_tag, r);
ap_rputc('>', r);

int ap_rprintf (request_rec *r, const char *fmt,...)

This function works like the standard printf() function, but the formatted string is sent to the client. In this example, the username used for authentication is incorporated into the document sent down the wire. The function returns the number of characters sent.

ap_rprintf(r, "Hello %s", r->connection->user);

void ap_send_size (size_t size, request_rec *r)

This function converts the file size given in size into a formatted string and sends the string to the client. The size given in the string will be in units of bytes, kilobytes, or megabytes, depending on the size of the file. This function is used in mod_autoindex to display the size of files in automatic directory listings, and by mod_include to implement the fsize directive.

ap_rputs("File size: ");
ap_send_size(r->finfo.st_size, r);

int ap_rflush (request_rec *r)

This call causes Apache to flush the outgoing socket connection, sending any buffered data down the wire to the client. You can use this function to display a partial page or, in a server push application, to display a new page of a multipart document. Don't use it more often than you need to, however, or overall performance will degrade.