Callbacks¶
Callbacks are used in NEAT to signal events to the application. They are used to inform the application when a flow is readable, writable, or an error has occurred.
Most callbacks have the following syntax:
neat_error_code
on_event_name(neat_flow_operations *ops)
{
return NEAT_OK; // or some error code
}
The struct neat_flow_operations
is defined as follows:
struct neat_flow_operations
{
void *userData;
neat_error_code status;
int stream_id;
struct neat_ctx *ctx;
struct neat_flow *flow;
neat_flow_operations_fx on_connected;
neat_flow_operations_fx on_error;
neat_flow_operations_fx on_readable;
neat_flow_operations_fx on_writable;
neat_flow_operations_fx on_all_written;
neat_flow_operations_fx on_network_status_changed;
neat_flow_operations_fx on_aborted;
neat_flow_operations_fx on_timeout;
neat_flow_operations_fx on_close;
neat_cb_send_failure_t on_send_failure;
neat_cb_flow_slowdown_t on_slowdown;
neat_cb_flow_rate_hint_t on_rate_hint;
};
- userData: Applications may freely store a pointer in this field.
- status: Reports any errors associated with the flow.
- stream_id: For flows that use explicit multistreaming. Specifies which stream the event is related to, if any.
- ctx: Pointer to the context the flow belongs to.
- flow: Pointer to the flow on which the event happened.
Callbacks are set by assigning the function pointer to the struct passed to the
callback and then calling neat_set_operations
. A NULL
pointer may be used to
indicate that the callback should no longer be called.
Example callback flow¶
For most applications it will be sufficient to use the following callback flow:
+
|
|
|
+--------v---------+
| on_connected() |
+--------+---------+
|
+------------+-------------+
| |
+--------v---------+ +--------v---------+
| on_readable() | | on_writable() | <------+
+------------------+ +--------+---------+ |
| |
| |
| |
+--------v---------+ |
| on_all_written() | ------+
+------------------+
See the tutorial for more details.
Callback reference¶
on_connected¶
Called whenever an outgoing connection has been established with neat_open
,
or an incoming connection has been established with neat_accept
.
on_error¶
Called whenever an error occurs when processing the flow. Errors are considered critical.
on_readable¶
Called whenever the flow can be read from without blocking. NEAT does not permit blocking reads.
on_writable¶
Called whenever the flow can be written to without blocking. NEAT does not permit blocking writes.
on_all_written¶
Called when all previous data sent with neat_write
has been completely
written. Does not signal that the flow is writable. Applications may use this
callback to re-enable the on_writable
callback.
on_network_status_changed¶
Inform application that something has happened in the network. This also
includes flow endpoints going up, which will subsequently trigger
on_connected
if that callback is set.
Only available when using SCTP.
on_aborted¶
Called when the remote end aborts the flow. Available for flows using TCP or SCTP.
on_timeout¶
Called if sent data is not acknowledged within the time specified with
neat_change_timeout
.
Currently only available for TCP on Linux.
on_close¶
Called when the graceful connection shutdown has completed.
Only available when using SCTP or TCP. Note that when using TCP, this callback
is called when the close()
system call is made, as TCP implementations currently
does not provide any more accurate way of signalling this.
on_send_failure¶
Defined as:
void
on_send_failure(struct neat_flow_operations *flowops, int context, const unsigned char *unsent)
{
}
Called to inform the application that the returned message unsent
could not be
transmitted. The failure reason as reported by the transport protocol is
returned in the standard status code, as an abstracted NEAT error code. If the
message was tagged with a context number, it is returned in context.
Only available for SCTP. Flows using TCP may use timeouts instead.
on_slowdown¶
Not currently implemented.
Defined as:
void
on_slowdown(struct neat_flow_operations *ops, int ecn, uint32_t rate)
{
}
Inform the application that the flow has experienced congestion and that the
sending rate should be lowered. If rate
is non-zero, it is an estimate of the
new maximum sending rate. ecn
is a boolean indicating whether this
notification was triggered by an ECN mark.
on_rate_hint¶
Not currently implemented.
Defined as:
void
on_rate_hint(struct neat_flow_operations *ops, uint32_t new_rate)
{
}
Called to inform the application that it may increase its sending rate. If
new_rate
is non-zero, it is an estimate of the maximum sending rate.