The SSH poll functions.

Overview

Add a generic way to handle sockets asynchronously. More…

// typedefs

typedef int (*poll_fn)(
    ssh_pollfd_t *,
    nfds_t,
    int
    );

// structs

struct ssh_event_fd_wrapper;
struct ssh_event_struct;
struct ssh_poll_ctx_struct;
struct ssh_poll_handle_struct;

// global variables

static poll_fn ssh_poll_emu;

// global functions

int
ssh_event_add_fd(
    ssh_event event,
    socket_t fd,
    short events,
    ssh_event_callback cb,
    void* userdata
);

int
ssh_event_add_session(
    ssh_event event,
    ssh_session session
);

int
ssh_event_dopoll(
    ssh_event event,
    int timeout
);

void
ssh_event_free(ssh_event event);

ssh_event
ssh_event_new(void);

int
ssh_event_remove_fd(
    ssh_event event,
    socket_t fd
);

int
ssh_event_remove_session(
    ssh_event event,
    ssh_session session
);

void
ssh_poll_add_events(
    ssh_poll_handle p,
    short events
);

int
ssh_poll_ctx_add(
    ssh_poll_ctx ctx,
    ssh_poll_handle p
);

int
ssh_poll_ctx_dopoll(
    ssh_poll_ctx ctx,
    int timeout
);

void
ssh_poll_ctx_free(ssh_poll_ctx ctx);

ssh_poll_ctx
ssh_poll_ctx_new(size_t chunk_size);

void
ssh_poll_ctx_remove(
    ssh_poll_ctx ctx,
    ssh_poll_handle p
);

void
ssh_poll_free(ssh_poll_handle p);

ssh_poll_ctx
ssh_poll_get_ctx(ssh_poll_handle p);

short
ssh_poll_get_events(ssh_poll_handle p);

socket_t
ssh_poll_get_fd(ssh_poll_handle p);

ssh_poll_handle
ssh_poll_new(
    socket_t fd,
    short events,
    ssh_poll_callback cb,
    void* userdata
);

void
ssh_poll_remove_events(
    ssh_poll_handle p,
    short events
);

void
ssh_poll_set_callback(
    ssh_poll_handle p,
    ssh_poll_callback cb,
    void* userdata
);

void
ssh_poll_set_events(
    ssh_poll_handle p,
    short events
);

void
ssh_poll_set_fd(
    ssh_poll_handle p,
    socket_t fd
);

static
int
bsd_poll(
    ssh_pollfd_t* fds,
    nfds_t nfds,
    int timeout
);

static
int
ssh_event_fd_wrapper_callback(
    ssh_poll_handle p,
    socket_t fd,
    int revents,
    void* userdata
);

int
ssh_poll(
    ssh_pollfd_t* fds,
    nfds_t nfds,
    int timeout
);

void
ssh_poll_cleanup(void);

int
ssh_poll_ctx_add_socket(
    ssh_poll_ctx ctx,
    ssh_socket s
);

static
int
ssh_poll_ctx_resize(
    ssh_poll_ctx ctx,
    size_t new_size
);

ssh_poll_ctx
ssh_poll_get_default_ctx(ssh_session session);

void
ssh_poll_init(void);

Detailed Documentation

Add a generic way to handle sockets asynchronously.

It’s based on poll objects, each of which store a socket, its events and a callback, which gets called whenever an event is set. The poll objects are attached to a poll context, which should be allocated on per thread basis.

Polling the poll context will poll all the attached poll objects and call their callbacks (handlers) if any of the socket events are set. This should be done within the main loop of an application.

Global Functions

int
ssh_event_add_fd(
    ssh_event event,
    socket_t fd,
    short events,
    ssh_event_callback cb,
    void* userdata
)

Add a fd to the event and assign it a callback, when used in blocking mode.

Parameters:

event	The ssh_event
fd	Socket that will be polled.
events	Poll events that will be monitored for the socket. i.e. POLLIN, POLLPRI, POLLOUT
cb	Function to be called if any of the events are set. The prototype of cb is: int (*ssh_event_callback)(socket_t fd, int revents, void *userdata);
userdata	Userdata to be passed to the callback function. NULL if not needed.

Returns:

SSH_OK on success SSH_ERROR on failure

int
ssh_event_add_session(
    ssh_event event,
    ssh_session session
)

remove the poll handle from session and assign them to a event, when used in blocking mode.

Parameters:

event	The ssh_event object
session	The session to add to the event.

Returns:

SSH_OK on success SSH_ERROR on failure

int
ssh_event_dopoll(
    ssh_event event,
    int timeout
)

Poll all the sockets and sessions associated through an event object.

If any of the events are set after the poll, the call back functions of the sessions or sockets will be called. This function should be called once within the programs main loop.

Parameters:

event	The ssh_event object to poll.
timeout	An upper limit on the time for which the poll will block, in milliseconds. Specifying a negative value means an infinite timeout. This parameter is passed to the poll() function.

Returns:

SSH_OK No error. SSH_ERROR Error happened during the poll.

void
ssh_event_free(ssh_event event)

Free an event context.

Parameters:

event

The ssh_event object to free. Note: you have to manually remove sessions and socket fds before freeing the event object.

ssh_event
ssh_event_new(void)

Create a new event context.

It could be associated with many ssh_session objects and socket fd which are going to be polled at the same time as the event context. You would need a single event context per thread.

Returns:

The ssh_event object on success, NULL on failure.

int
ssh_event_remove_fd(
    ssh_event event,
    socket_t fd
)

Remove a socket fd from an event context.

Parameters:

event	The ssh_event object.
fd	The fd to remove.

Returns:

SSH_OK on success SSH_ERROR on failure

int
ssh_event_remove_session(
    ssh_event event,
    ssh_session session
)

Remove a session object from an event context.

Parameters:

event	The ssh_event object.
session	The session to remove.

Returns:

SSH_OK on success SSH_ERROR on failure

void
ssh_poll_add_events(
    ssh_poll_handle p,
    short events
)

Add extra events to a poll object.

Duplicates are ignored. The events will also be propagated to an associated poll context.

Parameters:

p	Pointer to an already allocated poll object.
events	Poll events.

int
ssh_poll_ctx_add(
    ssh_poll_ctx ctx,
    ssh_poll_handle p
)

Add a poll object to a poll context.

Parameters:

ctx	Pointer to an already allocated poll context.
p	Pointer to an already allocated poll object.

Returns:

0 on success, < 0 on error

int
ssh_poll_ctx_dopoll(
    ssh_poll_ctx ctx,
    int timeout
)

Poll all the sockets associated through a poll object with a poll context.

If any of the events are set after the poll, the call back function of the socket will be called. This function should be called once within the programs main loop.

Parameters:

ctx	Pointer to an already allocated poll context.
timeout	An upper limit on the time for which ssh_poll_ctx() will block, in milliseconds. Specifying a negative value means an infinite timeout. This parameter is passed to the poll() function.

Returns:

SSH_OK No error. SSH_ERROR Error happened during the poll. SSH_AGAIN Timeout occured

void
ssh_poll_ctx_free(ssh_poll_ctx ctx)

Free a poll context.

Parameters:

ctx	Pointer to an already allocated poll context.

ssh_poll_ctx
ssh_poll_ctx_new(size_t chunk_size)

Create a new poll context.

It could be associated with many poll object which are going to be polled at the same time as the poll context. You would need a single poll context per thread.

Parameters:

chunk_size

The size of the memory chunk that will be allocated, when more memory is needed. This is for efficiency reasons, i.e. don’t allocate memory for each new poll object, but for the next 5. Set it to 0 if you want to use the library’s default value.

void
ssh_poll_ctx_remove(
    ssh_poll_ctx ctx,
    ssh_poll_handle p
)

Remove a poll object from a poll context.

Parameters:

ctx	Pointer to an already allocated poll context.
p	Pointer to an already allocated poll object.

void
ssh_poll_free(ssh_poll_handle p)

Free a poll object.

Parameters:

p	Pointer to an already allocated poll object.

ssh_poll_ctx
ssh_poll_get_ctx(ssh_poll_handle p)

Get the poll context of a poll object.

Parameters:

p	Pointer to an already allocated poll object.

Returns:

Poll context or NULL if the poll object isn’t attached.

short
ssh_poll_get_events(ssh_poll_handle p)

Get the events of a poll object.

Parameters:

p	Pointer to an already allocated poll object.

Returns:

Poll events.

socket_t
ssh_poll_get_fd(ssh_poll_handle p)

Get the raw socket of a poll object.

Parameters:

p	Pointer to an already allocated poll object.

Returns:

Raw socket.

ssh_poll_handle
ssh_poll_new(
    socket_t fd,
    short events,
    ssh_poll_callback cb,
    void* userdata
)

Allocate a new poll object, which could be used within a poll context.

Parameters:

fd	Socket that will be polled.
events	Poll events that will be monitored for the socket. i.e. POLLIN, POLLPRI, POLLOUT
cb	Function to be called if any of the events are set. The prototype of cb is: int (*ssh_poll_callback)(ssh_poll_handle p, socket_t fd, int revents, void *userdata);
userdata	Userdata to be passed to the callback function. NULL if not needed.

Returns:

A new poll object, NULL on error

void
ssh_poll_remove_events(
    ssh_poll_handle p,
    short events
)

Remove events from a poll object.

Non-existent are ignored. The events will also be propagated to an associated poll context.

Parameters:

p	Pointer to an already allocated poll object.
events	Poll events.

void
ssh_poll_set_callback(
    ssh_poll_handle p,
    ssh_poll_callback cb,
    void* userdata
)

Set the callback of a poll object.

Parameters:

p	Pointer to an already allocated poll object.
cb	Function to be called if any of the events are set.
userdata	Userdata to be passed to the callback function. NULL if not needed.

void
ssh_poll_set_events(
    ssh_poll_handle p,
    short events
)

Set the events of a poll object.

The events will also be propagated to an associated poll context.

Parameters:

p	Pointer to an already allocated poll object.
events	Poll events.

void
ssh_poll_set_fd(
    ssh_poll_handle p,
    socket_t fd
)

Set the file descriptor of a poll object.

The FD will also be propagated to an associated poll context.

Parameters:

p	Pointer to an already allocated poll object.
fd	New file descriptor.

int
ssh_poll_ctx_add_socket(
    ssh_poll_ctx ctx,
    ssh_socket s
)

Add a socket object to a poll context.

Parameters:

ctx	Pointer to an already allocated poll context.
s	A SSH socket handle

Returns:

0 on success, < 0 on error