NetIO API Structures
At the core of it, the NetIO API uses and manipulates a few structures.
The structure called a pr_netio_t holds the pointers to the
callback functions to be used. The remaining structures,
pr_netio_stream_t and pr_netio_buffer_t, define the
internal structure of the network I/O streams. The module developer may
need to know these structures in order to devise the proper callbacks.
The code definining these structures is in include/netio.h, but is excerpted here for your reading pleasure:
/* Network I/O objects */
typedef struct {
/* Pointer to the buffer memory. */
char *buf;
/* Total length of the buffer. */
unsigned long buflen;
/* Pointer to the current byte in the buffer. */
char *current;
/* Number of bytes left in the buffer. */
int remaining;
} pr_netio_buffer_t;
typedef struct {
/* Memory pool for this object. */
pool *strm_pool;
/* Stream type */
int strm_type;
/* File descriptor for this I/O stream. */
int strm_fd;
/* I/O mode: PR_NETIO_IO_RD or PR_NETIO_IO_WR. Patterned after
* open(2).
*/
int strm_mode;
/* Poll interval for this stream. */
unsigned int strm_interval;
/* Internal use. */
volatile unsigned long strm_flags;
/* Buffer. */
pr_netio_buffer_t *strm_nbuf;
/* Arbitrary data for outside use. */
void *strm_data;
/* errno, if applicable. */
int strm_errno;
} pr_netio_stream_t;
The strm_data field is where NetIO modules can store and pass
around data specific to that module, e.g. transformation objects,
custom structures, etc etc.
typedef struct {
/* Memory pool for this object. */
pool *pool;
/* NetIO callback pointers. */
void (*abort)(pr_netio_stream_t *);
int (*close)(pr_netio_stream_t *);
pr_netio_stream_t *(*open)(pr_netio_stream_t *, int, int);
int (*poll)(pr_netio_stream_t *);
int (*postopen)(pr_netio_stream_t *);
int (*read)(pr_netio_stream_t *, char *, size_t);
pr_netio_stream_t *(*reopen)(pr_netio_stream_t *, int, int);
int (*shutdown)(pr_netio_stream_t *, int);
int (*write)(pr_netio_stream_t *, char *, size_t);
} pr_netio_t;
Also note that, when instantiated, a subpol is allocated from the given
parent pool, and it is from this subpool (stored as
pr_netio_t->pool) that the object is actually allocated.
Therefore, to destroy a pr_netio_t, one needs merely to call
destroy_pool()
on the pr_netio_t's pool.