NAME

cat_installiohandler - install a session I/O handler

SYNOPSIS

#include <cat.h>

int cat_installiohandler(cat_session *session, const cat_iohandler *h, void *handle);

DESCRIPTION

The cat_iohandler struct is defined as:

 typedef struct cat_iohandler {
    int (*init)(cat_session *sess, void **handle);
    int (*free)(cat_session *sess, void *handle);
    int (*read)(cat_session *sess, void *handle, int fd_id);
    int (*write)(cat_session *sess, void *handle, int fd_id);
    int (*setlen)(cat_session *sess, void *handle, int readlen);
    int (*poll)(cat_session *sess, void *handle, int fd_ids, int mseconds);
    int (*close)(cat_session *sess, void *handle, int fd_id);
 } cat_iohandler;

This function installs I/O handler h in session and calls the init() function. The value of the handle is stored in the (cat_session) struct and can also be modified by the init() function. The same value is passed as the handle to all I/O handler functions for the session.

I/O Handlers can be installed only once for each session. The free() function is called when the session is closed by cat_close(). The setlen() function sets the desired read length to be used, and should return the previous length. setlen() should support the CAT_DEFAULT_SIZE (-1) constant to use a built-in default. The poll() function is used by cat_poll(), and should use the same semantics as that function.

The read() function should provide data to the session via catbuf_put() and return the number of bytes read. If no data is available, CAT_EAGAIN should be returned. When data has been exhausted, the function should return CAT_EOF.

The write() function should extract the current buffer with catbuf_get(), consume its data, for example by sending it over a network, and free the buffer with catbuf_free(). The function should return the number of bytes consumed, which should be the entire contents of the data buffer. Partial writes are not allowed. The function may block.

All functions should, with the exceptions specified above, return zero if successful and a negative code on error. Errors will be propagated upwards and cause the calling function to fail.

The default implementation of the TCP/IP IO handler can be obtained by calling catnet_iohandler().

RETURN VALUES

The function returns CAT_OK if successful, or a negative error code otherwise. If init() fails, cat_installiohandler() will propagate its error code.

SEE ALSO

cat

catnet_iohandler