1 /****h* silcutil/silcsockconn.h
9 * Author: Pekka Riikonen <priikone@silnet.org>
11 * Copyright (C) 1997 - 2001 Pekka Riikonen
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.
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.
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.
33 #ifndef SILCSOCKCONN_H
34 #define SILCSOCKCONN_H
36 /****s* silcutil/SilcSocketConnectionAPI/SilcSocketConnection
40 * typedef struct SilcSocketConnectionStruct *SilcSocketConnection;
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
52 typedef struct SilcSocketConnectionStruct *SilcSocketConnection;
54 /****s* silcutil/SilcSocketConnectionAPI/SilcSocketConnectionHB
58 * typedef struct SilcSocketConnectionHB *SilcSocketConnectionHB;
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
68 typedef struct SilcSocketConnectionHB *SilcSocketConnectionHB;
70 /****d* silcutil/SilcSocketConnectionAPI/SilcSocketType
74 * typedef enum { ... } SilcSocketType;
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.
88 SILC_SOCKET_TYPE_UNKNOWN = 0,
89 SILC_SOCKET_TYPE_CLIENT = 1,
90 SILC_SOCKET_TYPE_SERVER = 2,
91 SILC_SOCKET_TYPE_ROUTER = 3
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
102 /****f* silcutil/SilcSocketConnectionAPI/SilcSocketConnectionHBCb
106 * typedef void (*SilcSocketConnectionHBCb)(SilcSocketConnection sock,
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.
116 typedef void (*SilcSocketConnectionHBCb)(SilcSocketConnection sock,
119 /****s* silcutil/SilcSocketConnectionAPI/SilcSocketConnectionStruct
123 * struct SilcSocketConnectionStruct { ... };
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.
133 * Following short description of the fields:
137 * The actual connected socket. This is usually saved when accepting
138 * new connection to the server.
140 * SilcSocketType type
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
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).
154 * SilcProtocol protocol
156 * Protocol object for the socket. Currently only one protocol can be
157 * executing at a time for a particular socket.
161 * Socket flags that indicate the status of the socket. This can
162 * indicate several different status that can affect the use of the
167 * Reference counter. When allocated it is set to one (1) and it won't
168 * be freed until it hits zero (0).
174 * Resolved hostname, IP address and port of the connection who owns
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
185 * SilcSocketConnectionHB hb
187 * The heartbeat context. If NULL, heartbeat is not performed.
190 struct SilcSocketConnectionStruct {
194 SilcProtocol protocol;
205 SilcSocketConnectionHB hb;
210 /* Amount of bytes to be read from the socket connection at once. */
211 #define SILC_SOCKET_READ_SIZE 16384
213 /* Default socket buffer size. */
214 #define SILC_SOCKET_BUF_SIZE 1024
216 /* Generic manipulation of flags */
217 #define SF_SET(x, f) (x)->flags |= (1L << (f))
218 #define SF_UNSET(x, f) (x)->flags &= ~(1L << (f))
219 #define SF_IS(x, f) ((x)->flags & (1L << (f)))
221 /* Setting/Unsetting flags */
222 #define SILC_SET_OUTBUF_PENDING(x) SF_SET((x), SILC_SF_OUTBUF_PENDING)
223 #define SILC_SET_INBUF_PENDING(x) SF_SET((x), SILC_SF_INBUF_PENDING)
224 #define SILC_SET_DISCONNECTING(x) SF_SET((x), SILC_SF_DISCONNECTING)
225 #define SILC_SET_DISCONNECTED(x) SF_SET((x), SILC_SF_DISCONNECTED)
226 #define SILC_UNSET_OUTBUF_PENDING(x) SF_UNSET((x), SILC_SF_OUTBUF_PENDING)
227 #define SILC_UNSET_INBUF_PENDING(x) SF_UNSET((x), SILC_SF_INBUF_PENDING)
228 #define SILC_UNSET_DISCONNECTING(x) SF_UNSET((x), SILC_SF_DISCONNECTING)
229 #define SILC_UNSET_DISCONNECTED(x) SF_UNSET((x), SILC_SF_DISCONNECTED)
231 /* Checking for flags */
232 #define SILC_IS_OUTBUF_PENDING(x) SF_IS((x), SILC_SF_OUTBUF_PENDING)
233 #define SILC_IS_INBUF_PENDING(x) SF_IS((x), SILC_SF_INBUF_PENDING)
234 #define SILC_IS_DISCONNECTING(x) SF_IS((x), SILC_SF_DISCONNECTING)
235 #define SILC_IS_DISCONNECTED(x) SF_IS((x), SILC_SF_DISCONNECTED)
239 /****f* silcutil/SilcSocketConnectionAPI/silc_socket_alloc
243 * void silc_socket_alloc(int sock, SilcSocketType type, void *user_data,
244 * SilcSocketConnection *new_socket);
248 * Allocates a new socket connection object. The allocated object is
249 * returned to the new_socket argument. The `sock' is the socket
250 * for the connection, the `type' the initial type of the connection and
251 * the `user_data' a application specific pointer.
254 void silc_socket_alloc(int sock, SilcSocketType type, void *user_data,
255 SilcSocketConnection *new_socket);
257 /****f* silcutil/SilcSocketConnectionAPI/silc_socket_free
261 * void silc_socket_free(SilcSocketConnection sock);
265 * Frees the socket connection context. This frees it only if the
266 * reference counter of the socket is zero, otherwise it decreases the
270 void silc_socket_free(SilcSocketConnection sock);
272 /****f* silcutil/SilcSocketConnectionAPI/silc_socket_dup
276 * SilcSocketConnection silc_socket_dup(SilcSocketConnection sock);
280 * Duplicates the socket context. This actually does not duplicate
281 * any data, instead this increases the reference counter of the
282 * context. The reference counter is decreased by calling the
283 * silc_socket_free function and it frees the data when the counter
287 SilcSocketConnection silc_socket_dup(SilcSocketConnection sock);
289 /****f* silcutil/SilcSocketConnectionAPI/silc_socket_read
293 * int silc_socket_read(SilcSocketConnection sock);
297 * Reads data from the socket connection into the incoming data buffer.
298 * It reads as much as possible from the socket connection. This returns
299 * amount of bytes read or -1 on error or -2 on case where all of the
300 * data could not be read at once. Implementation of this funtion
301 * may be platform specific.
304 int silc_socket_read(SilcSocketConnection sock);
306 /****f* silcutil/SilcSocketConnectionAPI/silc_socket_write
310 * int silc_socket_read(SilcSocketConnection sock);
314 * Writes data from the outgoing buffer to the socket connection. If the
315 * data cannot be written at once, it must be written at later time.
316 * The data is written from the data section of the buffer, not from head
317 * or tail section. This automatically pulls the data section towards end
318 * after writing the data. Implementation of this functions may be
322 int silc_socket_write(SilcSocketConnection sock);
324 /****f* silcutil/SilcSocketConnectionAPI/silc_socket_set_heartbeat
328 * void silc_socket_set_heartbeat(SilcSocketConnection sock,
331 * SilcSocketConnectionHBCb hb_callback,
332 * void *timeout_queue);
336 * Sets the heartbeat timeout and prepares the socket for performing
337 * heartbeat in `heartbeat' intervals (seconds). The `hb_context' is
338 * allocated by the application and will be sent as argument to the
339 * `hb_callback' function that is called when the `heartbeat' timeout
340 * expires. The callback `hb_context' won't be touched by the library
341 * but will be freed automatically when calling silc_socket_free. The
342 * `timeout_queue' is the application's scheduler timeout queue.
345 void silc_socket_set_heartbeat(SilcSocketConnection sock,
348 SilcSocketConnectionHBCb hb_callback,
349 void *timeout_queue);