lib/silcutil/silcsockconn.h

   1 /*
   2
   3   silcsockconn.h
   4
   5   COPYRIGHT
   6
   7   Author: Pekka Riikonen <priikone@silnet.org>
   8
   9   Copyright (C) 1997 - 2001 Pekka Riikonen
  10
  11   This program is free software; you can redistribute it and/or modify
  12   it under the terms of the GNU General Public License as published by
  13   the Free Software Foundation; either version 2 of the License, or
  14   (at your option) any later version.
  15
  16   This program is distributed in the hope that it will be useful,
  17   but WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19   GNU General Public License for more details.
  20
  21 */
  22
  23 /****h* silcutil/silcsockconn.h
  24  *
  25  * DESCRIPTION
  26  *
  27  * Implementation of the Socket Connection object. The SilcSocketConnection
  28  * is used by all applications to represent a socket based connection
  29  * to the network. The Socket Connection object handles inbound and outbound
  30  * data buffers, can perform keepalive actions for the connection and
  31  * supports connection based protocols as well.
  32  *
  33  ***/
  34
  35 #ifndef SILCSOCKCONN_H
  36 #define SILCSOCKCONN_H
  37
  38 /****s* silcutil/SilcSocketConnectionAPI/SilcSocketConnection
  39  *
  40  * NAME
  41  *
  42  *    typedef struct SilcSocketConnectionStruct *SilcSocketConnection;
  43  *
  44  * DESCRIPTION
  45  *
  46  *    This context is forward declaration for the SilcSocketConnectionStruct.
  47  *    This is allocated by the silc_socket_alloc and freed by the
  48  *    silc_socket_free function. The silc_socket_dup can be used to
  49  *    increase the reference counter of the context. The data is freed
  50  *    by the silc_socket_free function only after the reference counter
  51  *    hits zero.
  52  *
  53  ***/
  54 typedef struct SilcSocketConnectionStruct *SilcSocketConnection;
  55
  56 /****s* silcutil/SilcSocketConnectionAPI/SilcSocketConnectionHB
  57  *
  58  * NAME
  59  *
  60  *    typedef struct SilcSocketConnectionHB *SilcSocketConnectionHB;
  61  *
  62  * DESCRIPTION
  63  *
  64  *    This context is the heartbeat context for the SilcSockeConnection.
  65  *    It is meant to hold the keepalive information for the connection.
  66  *    This is allocated internally and freed internally by the
  67  *    interface routines.
  68  *
  69  ***/
  70 typedef struct SilcSocketConnectionHBStruct *SilcSocketConnectionHB;
  71
  72 /****d* silcutil/SilcSocketConnectionAPI/SilcSocketType
  73  *
  74  * NAME
  75  *
  76  *    typedef enum { ... } SilcSocketType;
  77  *
  78  * DESCRIPTION
  79  *
  80  *    Socket types. These identifies the socket connection. There
  81  *    are four different types; unknown, client, server and router.
  82  *    Unknown connections are connections that hasn't advanced long
  83  *    enough so that we might know which type of connection it is.
  84  *    It is the applications responsibility to update the type
  85  *    information when it becomes available.
  86  *
  87  * SOURCE
  88  */
  89 typedef enum {
  90   SILC_SOCKET_TYPE_UNKNOWN = 0,
  91   SILC_SOCKET_TYPE_CLIENT = 1,
  92   SILC_SOCKET_TYPE_SERVER = 2,
  93   SILC_SOCKET_TYPE_ROUTER = 3
  94 } SilcSocketType;
  95 /***/
  96
  97 /* Socket flags */
  98 #define SILC_SF_NONE             0
  99 #define SILC_SF_INBUF_PENDING    1
 100 #define SILC_SF_OUTBUF_PENDING   2
 101 #define SILC_SF_DISCONNECTING    3
 102 #define SILC_SF_DISCONNECTED     4
 103 #define SILC_SF_HOST_LOOKUP      5
 104
 105 /****s* silcutil/SilcSocketConnectionAPI/SilcSocketConnectionStruct
 106  *
 107  * NAME
 108  *
 109  *    struct SilcSocketConnectionStruct { ... };
 110  *
 111  * DESCRIPTION
 112  *
 113  *    This object holds information about the connected sockets to the server.
 114  *    This is quite important object since this is referenced by the server all
 115  *    the time when figuring out what the connection is supposed to be doing
 116  *    and to whom we should send a message. This structure is the structure
 117  *    for the SilcSocketConnection forward declaration.
 118  *
 119  *    Following short description of the fields:
 120  *
 121  *    int sock
 122  *
 123  *      The actual connected socket. This is usually saved when accepting
 124  *      new connection to the server.
 125  *
 126  *    SilcSocketType type
 127  *
 128  *      Type of the socket. This identifies the type of the connection. This
 129  *      is mainly used to identify whether the connection is a client or a
 130  *      server connection.
 131  *
 132  *    void *user_data
 133  *
 134  *      This is a pointer to a data that is is saved here at the same
 135  *      time a new connection object is allocated. Usually this is a
 136  *      back-pointer to some important data for fast referencing. For
 137  *      SILC server this is a pointer to the ID list and for SILC client
 138  *      to object holding active connections (windows).
 139  *
 140  *    SilcProtocol protocol
 141  *
 142  *      Protocol object for the socket. Currently only one protocol can be
 143  *      executing at a time for a particular socket.
 144  *
 145  *    uint32 flags
 146  *
 147  *      Socket flags that indicate the status of the socket. This can
 148  *      indicate several different status that can affect the use of the
 149  *      socket object.
 150  *
 151  *    int users
 152  *
 153  *      Reference counter. When allocated it is set to one (1) and it won't
 154  *      be freed until it hits zero (0).
 155  *
 156  *    char *hostname
 157  *    char *ip
 158  *    uint16 port
 159  *
 160  *      Resolved hostname, IP address and port of the connection who owns
 161  *      this object.
 162  *
 163  *    SilcBuffer inbuf
 164  *    SilcBuffer outbuf
 165  *
 166  *      Incoming and outgoing buffers for the particular socket connection.
 167  *      Incoming data from the socket is put after decryption in to the
 168  *      inbuf buffer and outgoing data after encryption is put to the outbuf
 169  *      buffer.
 170  *
 171  *    SilcSocketConnectionHB hb
 172  *
 173  *      The heartbeat context.  If NULL, heartbeat is not performed.
 174  *
 175  ***/
 176 struct SilcSocketConnectionStruct {
 177   int sock;
 178   SilcSocketType type;
 179   void *user_data;
 180   SilcProtocol protocol;
 181   uint32 flags;
 182   int users;
 183
 184   char *hostname;
 185   char *ip;
 186   uint16 port;
 187
 188   SilcBuffer inbuf;
 189   SilcBuffer outbuf;
 190
 191   SilcSocketConnectionHB hb;
 192 };
 193
 194 /* Macros */
 195
 196 /* Amount of bytes to be read from the socket connection at once. */
 197 #define SILC_SOCKET_READ_SIZE 16384
 198
 199 /* Default socket buffer size. */
 200 #define SILC_SOCKET_BUF_SIZE 1024
 201
 202 /* Generic manipulation of flags */
 203 #define SF_SET(x, f) (x)->flags |= (1L << (f))
 204 #define SF_UNSET(x, f) (x)->flags &= ~(1L << (f))
 205 #define SF_IS(x, f) ((x)->flags & (1L << (f)))
 206
 207 /* Setting/Unsetting flags */
 208 #define SILC_SET_OUTBUF_PENDING(x) SF_SET((x), SILC_SF_OUTBUF_PENDING)
 209 #define SILC_SET_INBUF_PENDING(x) SF_SET((x), SILC_SF_INBUF_PENDING)
 210 #define SILC_SET_DISCONNECTING(x) SF_SET((x), SILC_SF_DISCONNECTING)
 211 #define SILC_SET_DISCONNECTED(x) SF_SET((x), SILC_SF_DISCONNECTED)
 212 #define SILC_SET_HOST_LOOKUP(x) SF_SET((x), SILC_SF_HOST_LOOKUP)
 213 #define SILC_UNSET_OUTBUF_PENDING(x) SF_UNSET((x), SILC_SF_OUTBUF_PENDING)
 214 #define SILC_UNSET_INBUF_PENDING(x) SF_UNSET((x), SILC_SF_INBUF_PENDING)
 215 #define SILC_UNSET_DISCONNECTING(x) SF_UNSET((x), SILC_SF_DISCONNECTING)
 216 #define SILC_UNSET_DISCONNECTED(x) SF_UNSET((x), SILC_SF_DISCONNECTED)
 217 #define SILC_UNSET_HOST_LOOKUP(x) SF_UNSET((x), SILC_SF_HOST_LOOKUP)
 218
 219 /* Checking for flags */
 220 #define SILC_IS_OUTBUF_PENDING(x) SF_IS((x), SILC_SF_OUTBUF_PENDING)
 221 #define SILC_IS_INBUF_PENDING(x) SF_IS((x), SILC_SF_INBUF_PENDING)
 222 #define SILC_IS_DISCONNECTING(x) SF_IS((x), SILC_SF_DISCONNECTING)
 223 #define SILC_IS_DISCONNECTED(x) SF_IS((x), SILC_SF_DISCONNECTED)
 224 #define SILC_IS_HOST_LOOKUP(x) SF_IS((x), SILC_SF_HOST_LOOKUP)
 225
 226 /* Prototypes */
 227
 228 /****f* silcutil/SilcSocketConnectionAPI/silc_socket_alloc
 229  *
 230  * SYNOPSIS
 231  *
 232  *    void silc_socket_alloc(int sock, SilcSocketType type, void *user_data,
 233  *                           SilcSocketConnection *new_socket);
 234  *
 235  * DESCRIPTION
 236  *
 237  *    Allocates a new socket connection object. The allocated object is
 238  *    returned to the new_socket argument. The `sock' is the socket
 239  *    for the connection, the `type' the initial type of the connection and
 240  *    the `user_data' a application specific pointer.
 241  *
 242  ***/
 243 void silc_socket_alloc(int sock, SilcSocketType type, void *user_data,
 244                        SilcSocketConnection *new_socket);
 245
 246 /****f* silcutil/SilcSocketConnectionAPI/silc_socket_free
 247  *
 248  * SYNOPSIS
 249  *
 250  *    void silc_socket_free(SilcSocketConnection sock);
 251  *
 252  * DESCRIPTION
 253  *
 254  *    Frees the socket connection context. This frees it only if the
 255  *    reference counter of the socket is zero, otherwise it decreases the
 256  *    reference counter.
 257  *
 258  ***/
 259 void silc_socket_free(SilcSocketConnection sock);
 260
 261 /****f* silcutil/SilcSocketConnectionAPI/silc_socket_dup
 262  *
 263  * SYNOPSIS
 264  *
 265  *    SilcSocketConnection silc_socket_dup(SilcSocketConnection sock);
 266  *
 267  * DESCRIPTION
 268  *
 269  *    Duplicates the socket context. This actually does not duplicate
 270  *    any data, instead this increases the reference counter of the
 271  *    context. The reference counter is decreased by calling the
 272  *    silc_socket_free function and it frees the data when the counter
 273  *    hits zero.
 274  *
 275  ***/
 276 SilcSocketConnection silc_socket_dup(SilcSocketConnection sock);
 277
 278 /****f* silcutil/SilcSocketConnectionAPI/silc_socket_read
 279  *
 280  * SYNOPSIS
 281  *
 282  *    int silc_socket_read(SilcSocketConnection sock);
 283  *
 284  * DESCRIPTION
 285  *
 286  *    Reads data from the socket connection into the incoming data buffer.
 287  *    It reads as much as possible from the socket connection. This returns
 288  *    amount of bytes read or -1 on error or -2 on case where all of the
 289  *    data could not be read at once. Implementation of this function
 290  *    may be platform specific.
 291  *
 292  ***/
 293 int silc_socket_read(SilcSocketConnection sock);
 294
 295 /****f* silcutil/SilcSocketConnectionAPI/silc_socket_write
 296  *
 297  * SYNOPSIS
 298  *
 299  *    int silc_socket_read(SilcSocketConnection sock);
 300  *
 301  * DESCRIPTION
 302  *
 303  *    Writes data from the outgoing buffer to the socket connection. If the
 304  *    data cannot be written at once, it must be written at later time.
 305  *    The data is written from the data section of the buffer, not from head
 306  *    or tail section. This automatically pulls the data section towards end
 307  *    after writing the data. Implementation of this function may be
 308  *    platform specific.
 309  *
 310  ***/
 311 int silc_socket_write(SilcSocketConnection sock);
 312
 313 /****f* silcutil/SilcSocketConnectionAPI/SilcSocketConnectionHBCb
 314  *
 315  * SYNOPSIS
 316  *
 317  *    typedef void (*SilcSocketConnectionHBCb)(SilcSocketConnection sock,
 318  *                                             void *context);
 319  *
 320  * DESCRIPTION
 321  *
 322  *    Heartbeat callback function. This is the function in the application
 323  *    that this library will call when it is time to send the keepalive
 324  *    packet SILC_PACKET_HEARTBEAT.
 325  *
 326  ***/
 327 typedef void (*SilcSocketConnectionHBCb)(SilcSocketConnection sock,
 328                                          void *context);
 329
 330 /****f* silcutil/SilcSocketConnectionAPI/silc_socket_set_heartbeat
 331  *
 332  * SYNOPSIS
 333  *
 334  *    void silc_socket_set_heartbeat(SilcSocketConnection sock,
 335  *                                   uint32 heartbeat,
 336  *                                   void *hb_context,
 337  *                                   SilcSocketConnectionHBCb hb_callback,
 338  *                                   SilcSchedule schedule);
 339  *
 340  * DESCRIPTION
 341  *
 342  *    Sets the heartbeat timeout and prepares the socket for performing
 343  *    heartbeat in `heartbeat' intervals (seconds). The `hb_context' is
 344  *    allocated by the application and will be sent as argument to the
 345  *    `hb_callback' function that is called when the `heartbeat' timeout
 346  *    expires.  The callback `hb_context' won't be touched by the library
 347  *    but will be freed automatically when calling silc_socket_free.  The
 348  *    `schedule' is the application's scheduler.
 349  *
 350  ***/
 351 void silc_socket_set_heartbeat(SilcSocketConnection sock,
 352                                uint32 heartbeat,
 353                                void *hb_context,
 354                                SilcSocketConnectionHBCb hb_callback,
 355                                SilcSchedule schedule);
 356
 357 /****f* silcutil/SilcSocketConnectionAPI/SilcSocketHostLookupCb
 358  *
 359  * SYNOPSIS
 360  *
 361  *    typedef void (*SilcSocketHostLookupCb)(SilcSocketConnection sock,
 362  *                                           void *context);
 363  *
 364  * DESCRIPTION
 365  *
 366  *    Asynchronous host lookup callback function that will be called
 367  *    when the lookup is performed.
 368  *
 369  ***/
 370 typedef void (*SilcSocketHostLookupCb)(SilcSocketConnection sock,
 371                                        void *context);
 372
 373 /****f* silcutil/SilcSocketConnectionAPI/silc_socket_host_lookup
 374  *
 375  * SYNOPSIS
 376  *
 377  *    void silc_socket_host_lookup(SilcSocketConnection sock,
 378  *                                 bool port_lookup,
 379  *                                 SilcSocketHostLookupCb callback,
 380  *                                 void *context,
 381  *                                 SilcSchedule schedule);
 382  *
 383  * DESCRIPTION
 384  *
 385  *    Performs asynchronous host name and IP address lookups for the
 386  *    specified socket connection. This may be called when the socket
 387  *    connection is created and the full IP address and fully qualified
 388  *    domain name information is desired. The `callback' with `context'
 389  *    will be called after the lookup is performed. The `schedule'
 390  *    is the application's scheduler which the lookup routine needs.
 391  *    If the socket connection is freed during the lookup the library
 392  *    will automatically cancel the lookup and the `callback' will not be
 393  *    called.
 394  *
 395  *    If `port_lookup' is TRUE then the remote port of the socket
 396  *    connection is resolved. After the information is resolved they
 397  *    are accessible using sock->ip and sock->hostname pointers. Note
 398  *    that if the both IP and FQDN could not be resolved the sock->hostname
 399  *    includes the IP address of the remote host. The resolved port is
 400  *    available in sock->port.
 401  *
 402  ***/
 403 void silc_socket_host_lookup(SilcSocketConnection sock,
 404                              bool port_lookup,
 405                              SilcSocketHostLookupCb callback,
 406                              void *context,
 407                              SilcSchedule schedule);
 408
 409 #endif