Changes

soccr/soccr.h declares three types:

soccr/soccr.h declares three types:

; <code>struct libsoccr_sk</code>

; <source lang="c" inline>struct libsoccr_sk</source>

: An abstract handler returned by ''pausing'' routine that is used as an opaque identifier by the rest of the libsoccr calls

: An abstract handler returned by ''pausing'' routine that is used as an opaque identifier by the rest of the libsoccr calls

; <code>struct libsoccr_sk_data</code>

; <source lang="c" inline>struct libsoccr_sk_data</source>

: A structure containing a set of 32-bit values that are returned by ''getter'' and that are to be passed '''as is''' to the ''setter'' call

: A structure containing a set of 32-bit values that are returned by ''getter'' and that are to be passed '''as is''' to the ''setter'' call

; <code>struct libsoccr_addr</code>

; <source lang="c" inline>struct libsoccr_addr</source>

: A structure that defines soccaddr for a socket. It's used by set/get calls described further.

: A structure that defines soccaddr for a socket. It's used by set/get calls described further.

Here are the flags that make sense:

Here are the flags that make sense:

; <code>SOCCR_FLAGS_WINDOW == 0x1</code>

; <source lang="c" inline>SOCCR_FLAGS_WINDOW == 0x1</source>

: When set, indicates that fields <code>snd_wl1</code>, <code>snd_wnd</code>, <code>max_window</code>, <code>rcv_wnd</code> and <code>rcv_wup</code> contain some valuable data (0 is a valid value for any of these)

: When set, indicates that fields <code>snd_wl1</code>, <code>snd_wnd</code>, <code>max_window</code>, <code>rcv_wnd</code> and <code>rcv_wup</code> contain some valuable data (0 is a valid value for any of these)

=== Generic ===

=== Generic ===

; <code>struct libsoccr_sk *libsoccr_pause(int sk)</code>

; <source lang="c" inline>struct libsoccr_sk *libsoccr_pause(int sk)</source>

: Pauses the socket and returns a handler for further operations. Any data flow for this socket ''must be blocked by the caller'' before this call.

: Pauses the socket and returns a handler for further operations. Any data flow for this socket ''must be blocked by the caller'' before this call.

; <code>void libsoccr_resume(struct libsoccr_sk *)</code>

; <source lang="c" inline>void libsoccr_resume(struct libsoccr_sk *)</source>

: Resumes the socket. Data flow unlock may happen before this.

: Resumes the socket. Data flow unlock may happen before this.

; <code>void libsoccr_set_log(unsigned int level, void (*fn)(unsigned int level, const char *fmt, ...))</code>

; <source lang="c" inline>void libsoccr_set_log(unsigned int level, void (*fn)(unsigned int level, const char *fmt, ...))</source>

: Sets a function that will be called when libsoccr will want to print something on the screen.

: Sets a function that will be called when libsoccr will want to print something on the screen.

=== Dump ===

=== Dump ===

; <code>int libsoccr_save(struct libsoccr_sk *sk, struct libsoccr_sk_data *data, unsigned data_size)</code>

; <source lang="c" inline>int libsoccr_save(struct libsoccr_sk *sk, struct libsoccr_sk_data *data, unsigned data_size)</source>

: Fills in the <code>data</code> structure with the info get from paused socket. The <code>data_size</code> should be the size of the structure passed. The return code is the size of the structure really filled with data.

: Fills in the <code>data</code> structure with the info get from paused socket. The <code>data_size</code> should be the size of the structure passed. The return code is the size of the structure really filled with data.

; <code>char *libsoccr_get_queue_bytes(struct libsoccr_sk *sk, int queue_id, unsigned flags)</code>

; <source lang="c" inline>char *libsoccr_get_queue_bytes(struct libsoccr_sk *sk, int queue_id, unsigned flags)</source>

: Returns a malloc()-ed array with the contents of the queue. The queue can be TCP_RECV_QUEUE or TCP_SEND_QUEUE. The amount of bytes in each is <code>data.inq_len</code> and <code>data.outq_len</code> respectively. The <code>flags</code> may have <code>SOCCR_MEM_EXCL</code> bit set (see below).

: Returns a malloc()-ed array with the contents of the queue. The queue can be TCP_RECV_QUEUE or TCP_SEND_QUEUE. The amount of bytes in each is <code>data.inq_len</code> and <code>data.outq_len</code> respectively. The <code>flags</code> may have <code>SOCCR_MEM_EXCL</code> bit set (see below).

; <code>union libsoccr_addr *libsoccr_get_addr(struct libsoccr_sk *sk, int self, unsigned flags)</code>  (currently unimplemented and returns NULL)

; <source lang="c" inline>union libsoccr_addr *libsoccr_get_addr(struct libsoccr_sk *sk, int self, unsigned flags)</source>  (currently unimplemented and returns NULL)

: Returns address (self or peer) of the socket. The <code>flags</code> may have <code>SOCCR_MEM_EXCL</code> bit set (see below)

: Returns address (self or peer) of the socket. The <code>flags</code> may have <code>SOCCR_MEM_EXCL</code> bit set (see below)

=== Restore ===

=== Restore ===

; <code>int libsoccr_restore(struct libsoccr_sk *sk, struct libsoccr_sk_data *data, unsigned data_size)</code>

; <source lang="c" inline>int libsoccr_restore(struct libsoccr_sk *sk, struct libsoccr_sk_data *data, unsigned data_size)</source>

: Restores data on a socket from the <code>data</code> structure. Should be called after the calls below, but before the "resume" one.

: Restores data on a socket from the <code>data</code> structure. Should be called after the calls below, but before the "resume" one.

; <code>int libsoccr_set_queue_bytes(struct libsoccr_sk *sk, int queue, char *buf, unsigned flags)</code>

; <source lang="c" inline>int libsoccr_set_queue_bytes(struct libsoccr_sk *sk, int queue, char *buf, unsigned flags)</source>

: Puts back the contents of the respective queue. The <code>flags</code> may contain <code>SOCCR_MEM_EXCL</code>.

: Puts back the contents of the respective queue. The <code>flags</code> may contain <code>SOCCR_MEM_EXCL</code>.

; <code>int libsoccr_set_addr(struct libsoccr_sk *sk, int self, union libsoccr_addr *, unsigned flags)</code>

; <source lang="c" inline>int libsoccr_set_addr(struct libsoccr_sk *sk, int self, union libsoccr_addr *, unsigned flags)</source>

: Sets address (self or peer) of the socket. The <code>flags</code> may contain <code>SOCCR_MEM_EXCL</code>.

: Sets address (self or peer) of the socket. The <code>flags</code> may contain <code>SOCCR_MEM_EXCL</code>.