SIM_INTERFACE(external_connection_ctl) {
void (*accept)(conf_object_t *NOTNULL obj,
uint64 id, ext_con_cookie_t *cookie,
bool blocking);
ssize_t (*read)(conf_object_t *NOTNULL obj,
ext_con_cookie_t *NOTNULL cookie,
buffer_t buffer);
ssize_t (*write)(conf_object_t *NOTNULL obj,
ext_con_cookie_t *NOTNULL cookie,
bytes_t bytes);
void (*write_async)(conf_object_t *NOTNULL obj,
ext_con_cookie_t *NOTNULL cookie,
bytes_t bytes);
bool (*has_error)(conf_object_t *NOTNULL obj,
ext_con_cookie_t *NOTNULL cookie);
void (*notify)(conf_object_t *NOTNULL obj,
ext_con_cookie_t *NOTNULL cookie,
notify_mode_t notify_mode, exec_mode_t exec_mode,
bool active);
void (*close)(conf_object_t *NOTNULL obj,
ext_con_cookie_t *NOTNULL cookie);
};
#define EXTERNAL_CONNECTION_CTL_INTERFACE "external_connection_ctl"
The accept method must be called on every incoming connection,
generally in the on_accept method of the
external_connection_event, to indicate to the server whether
a connection is accepted. The value of id must be the value given
to the on_accept method. The value of the cookie
argument will be used in all other methods of
external_connection_ctl and
external_connection_event to identify the connection. Its
value is defined by the caller and opaque to the server. Use the value
NULL to specify that the connection is not accepted. If the
blocking argument is set to true, then the
read and write methods will have blocking semantics
for this connection.
The read method reads bytes from the connection identified by
cookie into the caller-allocated buffer, whose size
defines an upper bound on the number of bytes read. The method returns the
number of bytes read (which may be less than the size of buffer),
or -1 on error. If blocking semantics was turned on for the
connection, in the accept method call, then the read
method call will block until there is some data to return. Otherwise it will
return -2 immediately in that case.
The write method writes bytes to the connection identified by
cookie from the buffer bytes. If blocking semantics
was turned on for the connection, in the accept method call, then
the write method call will block until some data has been
written. Otherwise it will return -2 immediately in that case.
The write_async method queues up the data in bytes and sends it as soon as possible on the connection identified by cookie. The method makes a copy of the data and returns immediately.
The has_error method returns true if and only if there has been an error on the connection identified by cookie.
The notify method activates or deactivates read or write
notifications on the connection identified by cookie. The
active argument specifies if the call is an activation or a
deactivation and the notify_mode argument specifies if read
(Sim_NM_Read) or write (Sim_NM_Write) notifications should
be affected. Activating read notifications means that the
on_input method in the external_connection_event
interface may be called on this connection at any time after the call to
notify. Activating write notifications means that the
can_write method in the external_connection_event
interface may be called on this connection at any time after the call to
notify. If exec_mode is set to Sim_EM_Global,
the call to on_input or can_write will be done in
GLobal Context and if exec_mode is set to Sim_EM_Thread,
the call will be in done in Threaded Context.
The close method closes the connection identified by cookie. After this call, it is is illegal to call any other method using this value of cookie.