lib/silcutil/silcsockconn.h

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