
                      Socket Communication Library

                             version 0.1.0

                             Documentation

--- Index ---

0.0.0 Preface

1.0.0 Socket API

  1.1.0 Socket and session management

    1.1.1  sock_open
    1.1.2  sock_close
    1.1.3  sock_listen
    1.1.4  sock_connect
    1.1.5  sock_reconnect
    1.1.6  sock_disconnect
    1.1.7  sock_set_timeout
    1.1.8  sock_get_remote_name
    1.1.9  sock_get_remote_ip

  1.2.0 Cryptography control

    1.2.1  sock_set_encryption_in
    1.2.2  sock_set_encryption_out

  1.3.0 Stream control/transfer

    1.3.1  sock_flush
    1.3.2  sock_write
    1.3.3  sock_putc
    1.3.4  sock_puts
    1.3.5  sock_printf
    1.3.6  sock_read
    1.3.7  sock_dread
    1.3.8  sock_getc
    1.3.9  sock_gets
    1.3.10 sock_dgets
    1.3.11 sock_scanf

2.0.0 Communications API (high-level)

---

0.0.0 Preface

  The API facilitates easy access to simple and complex socket operations,
including socket creation, listening, connecting, and data transfer, with
name/ip translation, protection against host address spoofing and optional
cryptography support.

  Two major interfaces comprise the API: the socket level calls and the
communication level calls.

  In general, socket calls can be used in any application, as their use won't
render your application incompatible in any way. Except for cryptography, they
don't add any protocol to the usual socket interface.

  The communication level calls, on the other hand, comprise an encapsulating
top-level protocol for asynchronously exchanging notifications, requests and
data. They assume both ends using this interface, and are thus only beneficial
in new server/client development.

1.0.0 Socket API

  All calls herein demand that you #include <comm/sock.h> and link with
libcomm.

1.1.0 Socket and session management

  These are calls for opening, closing, connecting, polling, listening etc. on
sockets.

1.1.1 sock_open

  SOCK *sock_open(int port_local);

  DESCRIPTION: Creates and binds a local socket, but does not connect it to a
remote host.

  port_local is the local port you want the socket to bind to, and you can pass
NULL if you want the port assigned automatically.

  RETURNS: A pointer to a SOCK structure if successful, or NULL if an error
(like inability to bind to the desired port) occurred.

1.1.2 sock_close

  SOCK *sock_close(SOCK *s, int immediate);

  DESCRIPTION: Closes the socket whose structure is pointed to by s, and frees
the structure. Also disconnects the socket if it's currently connected.

  immediate is a flag specifying if you want the socket to be disconnected
immediately, even if there is undelivered data. Pass FALSE if you will try to
deliver this data, TRUE otherwise.

  RETURNS: Nothing. Always succeeds.

1.1.3 sock_listen

  SOCK *sock_listen(int timeout_secs, SOCK *s_parent, ...);

  DESCRIPTION: Waits for incoming connections on one or more specified sockets.

  timeout_secs specifies the number of seconds to wait before giving up and
returning even if there were no incoming calls. This can be used to poll rather
than wait indefinitely, possibly never returning. If you pass NULL here,
sock_listen will not return until there is either a connection or a (serious)
error.

  RETURNS: Socket structure of spawned connection. This is a separate connection
from the one you were listening on, so you can safely close the parent if you
don't need it anymore (for instance, in a concurrent child process). NULL if
there were no connection attempts within the specified amount of time, or there
was an error.
  
1.1.4 sock_connect

  int sock_connect(SOCK *s, char *desthost_str, int destport);

  DESCRIPTION: Tries to connect the already opened socket to a destination
endpoint (remote host).

  desthost_str can be a name (primary or alias) or IP of the host to connect to,
represented by an ASCII string ("fix.no" or "194.52.240.179"). This is required.

  destport is the port number you'd like to connect to. This is 23 for telnet,
119 for nntp, etc. This is also required.

  RETURNS: TRUE on success, FALSE on failure. The socket's status is set
accordingly:

  SOCK_STAT_OK: Everything fine.
  SOCK_STAT_PARADOX: The application requested an impossible action, like
connecting an already connected socket.
  SOCK_STAT_NONAME: desthost_str was not a valid hostname or IP number.
  SOCK_STAT_CONNREFUSED: The remote host did not accept your connection to the
desired port.

1.1.5 sock_reconnect

  int sock_reconnect(SOCK *s);

  DESCRIPTION: Tries to re-establish a closed/broken connection to a destination
endpoint (remote host). The socket must have been connected earlier, and the
last known connection is used. If the socket is currently connected, it is
disconnected first (the connection is flashed off, then on).

  RETURNS: TRUE on success, FALSE on failure. The socket's status is set
accordingly:

  SOCK_STAT_OK: Everything fine.
  SOCK_STAT_PARADOX: The socket has never been connected.
  SOCK_STAT_CONNREFUSED: The remote host did not accept your connection.

1.1.6 sock_disconnect

  int sock_disconnect(SOCK *s, int immediate);

  DESCRIPTION: Breaks an established connection. Does not free the socket
structure, which can be used again (through sock_connect or sock_reconnect).

  immediate is a flag specifying if you want the socket to be disconnected
immediately, even if there is undelivered data. Pass FALSE if you will try to
deliver this data, TRUE otherwise.

  RETURNS: 1 on success, 0 if the socket was already unconnected, -1 if there
was an error. -1 also means the socket structure used has been freed, so you
must do a successful sock_open to re-aquire such a struct.

1.1.7 sock_poll

  int sock_poll(SOCK *s);

  DESCRIPTION: Does a non-blocking read to see if there is any incoming data
pending on the socket. Always returns immediately, indicating whether there
is data to be read.

  RETURNS: The number of bytes pending (NULL if there are none).

1.1.8 sock_set_timeout

  void sock_set_timeout(SOCK *s, int timeout_secs);

  DESCRIPTION: Sets the data transmission/reception timeout for the socket.

  RETURNS: Nothing.

1.1.9 sock_get_remote_name

  char *sock_get_remote_name(SOCK *s);

  DESCRIPTION: Returns the primary nameserver address of the remote host.
Note: The host is only looked up the first time you use this call. The name
is cached for successive calls. The socket must be connected for this to
work.

  RETURNS: Pointer to a statically allocated string, or NULL if the name
couldn't be resolved, or the socket wasn't connected.

1.1.10 sock_get_remote_ip

  char *sock_get_remote_ip(SOCK *s);

  DESCRIPTION: Returns an ASCII string representing the remote host's
network address. This call can only fail if the local socket isn't
connected.

  RETURNS: Pointer to a statically allocated string, or NULL if the
socket wasn't connected.

1.1.11 sock_get_remote_name_or_ip

  char *sock_get_remote_name_or_ip(SOCK *s);

  DESCRIPTION: Convenience call



