libssh  0.7.3
Functions
The SSH poll functions.

Add a generic way to handle sockets asynchronously. More...

Collaboration diagram for The SSH poll functions.:

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. More...
 
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. More...
 
int ssh_event_dopoll (ssh_event event, int timeout)
 Poll all the sockets and sessions associated through an event object. More...
 
void ssh_event_free (ssh_event event)
 Free an event context. More...
 
ssh_event ssh_event_new (void)
 Create a new event context. More...
 
int ssh_event_remove_fd (ssh_event event, socket_t fd)
 Remove a socket fd from an event context. More...
 
int ssh_event_remove_session (ssh_event event, ssh_session session)
 Remove a session object from an event context. More...
 
void ssh_poll_add_events (ssh_poll_handle p, short events)
 Add extra events to a poll object. More...
 
int ssh_poll_ctx_add (ssh_poll_ctx ctx, ssh_poll_handle p)
 Add a poll object to a poll context. More...
 
int ssh_poll_ctx_add_socket (ssh_poll_ctx ctx, ssh_socket s)
 Add a socket object to a poll context. More...
 
int ssh_poll_ctx_dopoll (ssh_poll_ctx ctx, int timeout)
 Poll all the sockets associated through a poll object with a poll context. More...
 
void ssh_poll_ctx_free (ssh_poll_ctx ctx)
 Free a poll context. More...
 
ssh_poll_ctx ssh_poll_ctx_new (size_t chunk_size)
 Create a new poll context. More...
 
void ssh_poll_ctx_remove (ssh_poll_ctx ctx, ssh_poll_handle p)
 Remove a poll object from a poll context. More...
 
void ssh_poll_free (ssh_poll_handle p)
 Free a poll object. More...
 
ssh_poll_ctx ssh_poll_get_ctx (ssh_poll_handle p)
 Get the poll context of a poll object. More...
 
short ssh_poll_get_events (ssh_poll_handle p)
 Get the events of a poll object. More...
 
socket_t ssh_poll_get_fd (ssh_poll_handle p)
 Get the raw socket of a poll object. More...
 
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. More...
 
void ssh_poll_remove_events (ssh_poll_handle p, short events)
 Remove events from a poll object. More...
 
void ssh_poll_set_callback (ssh_poll_handle p, ssh_poll_callback cb, void *userdata)
 Set the callback of a poll object. More...
 
void ssh_poll_set_events (ssh_poll_handle p, short events)
 Set the events of a poll object. More...
 
void ssh_poll_set_fd (ssh_poll_handle p, socket_t fd)
 Set the file descriptor of a poll object. More...
 

Detailed Description

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.

Function Documentation

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
eventThe ssh_event
fdSocket that will be polled.
eventsPoll events that will be monitored for the socket. i.e. POLLIN, POLLPRI, POLLOUT
cbFunction 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);
userdataUserdata to be passed to the callback function. NULL if not needed.
Returns
SSH_OK on success SSH_ERROR on failure

References ssh_poll_ctx_add(), ssh_poll_free(), and ssh_poll_new().

Referenced by ssh_select().

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
eventThe ssh_event object
sessionThe session to add to the event.
Returns
SSH_OK on success SSH_ERROR on failure

References ssh_poll_ctx_add(), and ssh_poll_ctx_remove().

Referenced by ssh_channel_select(), and ssh_select().

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
eventThe ssh_event object to poll.
timeoutAn 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.

References ssh_poll_ctx_dopoll().

Referenced by ssh_channel_select(), and ssh_select().

void ssh_event_free ( ssh_event  event)

Free an event context.

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

References ssh_poll_ctx_add(), ssh_poll_ctx_free(), and ssh_poll_ctx_remove().

Referenced by ssh_channel_select(), and ssh_select().

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.

References ssh_poll_ctx_free(), and ssh_poll_ctx_new().

Referenced by ssh_channel_select(), and ssh_select().

int ssh_event_remove_fd ( ssh_event  event,
socket_t  fd 
)

Remove a socket fd from an event context.

Parameters
eventThe ssh_event object.
fdThe fd to remove.
Returns
SSH_OK on success SSH_ERROR on failure

References ssh_poll_free().

Referenced by ssh_select().

int ssh_event_remove_session ( ssh_event  event,
ssh_session  session 
)

Remove a session object from an event context.

Parameters
eventThe ssh_event object.
sessionThe session to remove.
Returns
SSH_OK on success SSH_ERROR on failure

References ssh_poll_ctx_add(), and ssh_poll_ctx_remove().

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
pPointer to an already allocated poll object.
eventsPoll events.

References ssh_poll_get_events(), and ssh_poll_set_events().

Referenced by ssh_set_fd_except().

int ssh_poll_ctx_add ( ssh_poll_ctx  ctx,
ssh_poll_handle  p 
)

Add a poll object to a poll context.

Parameters
ctxPointer to an already allocated poll context.
pPointer to an already allocated poll object.
Returns
0 on success, < 0 on error

Referenced by ssh_event_add_fd(), ssh_event_add_session(), ssh_event_free(), ssh_event_remove_session(), ssh_poll_ctx_add_socket(), and ssh_set_fd_except().

int ssh_poll_ctx_add_socket ( ssh_poll_ctx  ctx,
ssh_socket  s 
)

Add a socket object to a poll context.

Parameters
ctxPointer to an already allocated poll context.
sA SSH socket handle
Returns
0 on success, < 0 on error

References ssh_poll_ctx_add().

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
ctxPointer to an already allocated poll context.
timeoutAn 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

References ssh_poll_ctx_new(), and ssh_timeout_update().

Referenced by ssh_event_dopoll(), and ssh_set_fd_except().

void ssh_poll_ctx_free ( ssh_poll_ctx  ctx)

Free a poll context.

Parameters
ctxPointer to an already allocated poll context.

References ssh_poll_free().

Referenced by ssh_event_free(), ssh_event_new(), and ssh_free().

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_sizeThe 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.

Referenced by ssh_event_new(), and ssh_poll_ctx_dopoll().

void ssh_poll_ctx_remove ( ssh_poll_ctx  ctx,
ssh_poll_handle  p 
)

Remove a poll object from a poll context.

Parameters
ctxPointer to an already allocated poll context.
pPointer to an already allocated poll object.

Referenced by ssh_event_add_session(), ssh_event_free(), ssh_event_remove_session(), and ssh_poll_free().

void ssh_poll_free ( ssh_poll_handle  p)

Free a poll object.

Parameters
pPointer to an already allocated poll object.

References ssh_poll_ctx_remove().

Referenced by ssh_event_add_fd(), ssh_event_remove_fd(), and ssh_poll_ctx_free().

ssh_poll_ctx ssh_poll_get_ctx ( ssh_poll_handle  p)

Get the poll context of a poll object.

Parameters
pPointer to an already allocated poll object.
Returns
Poll context or NULL if the poll object isn't attached.

Referenced by ssh_set_fd_except().

short ssh_poll_get_events ( ssh_poll_handle  p)

Get the events of a poll object.

Parameters
pPointer to an already allocated poll object.
Returns
Poll events.

Referenced by ssh_poll_add_events(), and ssh_poll_remove_events().

socket_t ssh_poll_get_fd ( ssh_poll_handle  p)

Get the raw socket of a poll object.

Parameters
pPointer 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
fdSocket that will be polled.
eventsPoll events that will be monitored for the socket. i.e. POLLIN, POLLPRI, POLLOUT
cbFunction 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);
userdataUserdata to be passed to the callback function. NULL if not needed.
Returns
A new poll object, NULL on error

Referenced by ssh_bind_set_callbacks(), and ssh_event_add_fd().

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
pPointer to an already allocated poll object.
eventsPoll events.

References ssh_poll_get_events(), and ssh_poll_set_events().

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

Set the callback of a poll object.

Parameters
pPointer to an already allocated poll object.
cbFunction to be called if any of the events are set.
userdataUserdata 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
pPointer to an already allocated poll object.
eventsPoll events.

Referenced by ssh_poll_add_events(), and ssh_poll_remove_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
pPointer to an already allocated poll object.
fdNew file descriptor.