network.h

   1 /*
   2  * Networking abstraction in PuTTY.
   3  *
   4  * The way this works is: a back end can choose to open any number
   5  * of sockets - including zero, which might be necessary in some.
   6  * It can register a function to be called when data comes in on
   7  * any given one, and it can call the networking abstraction to
   8  * send data without having to worry about blocking. The stuff
   9  * behind the abstraction takes care of selects and nonblocking
  10  * writes and all that sort of painful gubbins.
  11  */
  12
  13 #ifndef PUTTY_NETWORK_H
  14 #define PUTTY_NETWORK_H
  15
  16 typedef struct Socket_tag *Socket;
  17 typedef struct SockAddr_tag *SockAddr;
  18
  19 /*
  20  * This is the function a client must register with each socket, to
  21  * receive data coming in on that socket. The parameter `urgent'
  22  * decides the meaning of `data' and `len':
  23  *
  24  *  - urgent==0. `data' points to `len' bytes of perfectly ordinary
  25  *    data.
  26  *
  27  *  - urgent==1. `data' points to `len' bytes of data, which were
  28  *    read from before an Urgent pointer.
  29  *
  30  *  - urgent==2. `data' points to `len' bytes of data, the first of
  31  *    which was the one at the Urgent mark.
  32  *
  33  *  - urgent==3. An error has occurred on the socket. `data' points
  34  *    to an error string, and `len' points to an error code.
  35  */
  36 typedef int (*sk_receiver_t)(Socket s, int urgent, char *data, int len);
  37
  38 void sk_init(void);                    /* called once at program startup */
  39
  40 SockAddr sk_namelookup(char *host, char **canonicalname);
  41 void sk_addr_free(SockAddr addr);
  42
  43 Socket sk_new(SockAddr addr, int port, int privport, sk_receiver_t receiver);
  44 void sk_close(Socket s);
  45 void sk_write(Socket s, char *buf, int len);
  46 void sk_write_oob(Socket s, char *buf, int len);
  47
  48 /*
  49  * Each socket abstraction contains a `void *' private field in
  50  * which the client can keep state.
  51  */
  52 void sk_set_private_ptr(Socket s, void *ptr);
  53 void *sk_get_private_ptr(Socket s);
  54
  55 /*
  56  * Special error values are returned from sk_namelookup and sk_new
  57  * if there's a problem. These functions extract an error message,
  58  * or return NULL if there's no problem.
  59  */
  60 char *sk_addr_error(SockAddr addr);
  61 char *sk_socket_error(Socket addr);
  62
  63 #endif