-/*
-
- silcsockconn.h
-
- Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
-
- Copyright (C) 1997 - 2000 Pekka Riikonen
-
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
-*/
+/****h* silccore/silcsockconn.h
+ *
+ * NAME
+ *
+ * silcsockconn.h
+ *
+ * COPYRIGHT
+ *
+ * Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
+ *
+ * Copyright (C) 1997 - 2000 Pekka Riikonen
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * DESCRIPTION
+ *
+ * Implementation of the Socket Connection object. The SilcSocketConnection
+ * is used by all applications to represent a socket based connection
+ * to the network. The Socket Connection object handles inbound and outbound
+ * data buffers, can perform keepalive actions for the connection and
+ * supports connection based protocols as well.
+ *
+ ***/
#ifndef SILCSOCKCONN_H
#define SILCSOCKCONN_H
-/* Forward declarations */
+/****s* silccore/SilcSocketConnectionAPI/SilcSocketConnection
+ *
+ * NAME
+ *
+ * typedef struct SilcSocketConnectionStruct *SilcSocketConnection;
+ *
+ * DESCRIPTION
+ *
+ * This context is forward declaration for the SilcSocketConnectionStruct.
+ * This is allocated by the silc_socket_alloc and freed by the
+ * silc_socket_free function. The silc_socket_dup can be used to
+ * increase the reference counter of the context. The data is freed
+ * by the silc_socket_free function only after the reference counter
+ * hits zero.
+ *
+ ***/
typedef struct SilcSocketConnectionStruct *SilcSocketConnection;
+
+/****s* silccore/SilcSocketConnectionAPI/SilcSocketConnectionHB
+ *
+ * NAME
+ *
+ * typedef struct SilcSocketConnectionHB *SilcSocketConnectionHB;
+ *
+ * DESCRIPTION
+ *
+ * This context is the heartbeat context for the SilcSockeConnection.
+ * It is meant to hold the keepalive information for the connection.
+ * This is allocated internally and freed internally by the
+ * interface routines.
+ *
+ ***/
typedef struct SilcSocketConnectionHB *SilcSocketConnectionHB;
-/* Socket types. These identifies the socket connection. */
+/****d* silccore/SilcSocketConnectionAPI/SilcSocketType
+ *
+ * NAME
+ *
+ * typedef enum { ... } SilcSocketType;
+ *
+ * DESCRIPTION
+ *
+ * Socket types. These identifies the socket connection. There
+ * are four different types; unknown, client, server and router.
+ * Unknown connections are connections that hasn't advanced long
+ * enough so that we might know which type of connection it is.
+ * It is the applications responsibility to update the type
+ * information when it becomes available.
+ *
+ * SOURCE
+ */
typedef enum {
SILC_SOCKET_TYPE_UNKNOWN = 0,
SILC_SOCKET_TYPE_CLIENT = 1,
SILC_SOCKET_TYPE_SERVER = 2,
SILC_SOCKET_TYPE_ROUTER = 3
} SilcSocketType;
+/***/
/* Socket flags */
#define SILC_SF_NONE 0
#define SILC_SF_DISCONNECTING 3
#define SILC_SF_DISCONNECTED 4
-/* Heartbeat callback function. This is the function in the application
- that this library will call when it is time to send the keepalive
- packet SILC_PACKET_HEARTBEAT. */
+/****f* silccore/SilcSocketConnectionAPI/SilcSocketConnectionHBCb
+ *
+ * SYNOPSIS
+ *
+ * typedef void (*SilcSocketConnectionHBCb)(SilcSocketConnection sock,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * Heartbeat callback function. This is the function in the application
+ * that this library will call when it is time to send the keepalive
+ * packet SILC_PACKET_HEARTBEAT.
+ *
+ ***/
typedef void (*SilcSocketConnectionHBCb)(SilcSocketConnection sock,
void *context);
-/*
- SILC Socket Connection object.
-
- This object holds information about the connected sockets to the server.
- This is quite important object since this is referenced by the server all
- the time when figuring out what the connection is supposed to be doing
- and to whom we should send a message.
-
- Following short description of the fields:
-
- int sock
-
- The actual connected socket. This is usually saved when accepting
- new connection to the server.
-
- SilcSocketType type
-
- Type of the socket. This identifies the type of the connection. This
- is mainly used to identify whether the connection is a client or a
- server connection.
-
- void *user_data
-
- This is a pointer to a data that is is saved here at the same
- time a new connection object is allocated. Usually this is a
- back-pointer to some important data for fast referencing. For
- SILC server this is a pointer to the ID list and for SILC client
- to object holding active connections (windows).
-
- SilcProtocol protocol
-
- Protocol object for the socket. Currently only one protocol can be
- executing at a time for a particular socket.
-
- uint32 flags
-
- Socket flags that indicate the status of the socket. This can
- indicate several different status that can affect the use of the
- socket object.
-
- int users
-
- Reference counter. When allocated it is set to one (1) and it won't
- be freed until it hits zero (0).
-
- char *hostname
- char *ip
- uint16 port
-
- Resolved hostname, IP address and port of the connection who owns
- this object.
-
- SilcBuffer inbuf
- SilcBuffer outbuf
-
- Incoming and outgoing buffers for the particular socket connection.
- Incoming data from the socket is put after decryption in to the
- inbuf buffer and outgoing data after encryption is put to the outbuf
- buffer.
-
- SilcSocketConnectionHB hb
-
- The heartbeat context. If NULL, heartbeat is not performed.
-
-*/
+/****s* silccore/SilcSocketConnectionAPI/SilcSocketConnectionStruct
+ *
+ * NAME
+ *
+ * struct SilcSocketConnectionStruct { ... };
+ *
+ * DESCRIPTION
+ *
+ * This object holds information about the connected sockets to the server.
+ * This is quite important object since this is referenced by the server all
+ * the time when figuring out what the connection is supposed to be doing
+ * and to whom we should send a message. This structure is the structure
+ * for the SilcSocketConnection forward declaration.
+ *
+ * Following short description of the fields:
+ *
+ * int sock
+ *
+ * The actual connected socket. This is usually saved when accepting
+ * new connection to the server.
+ *
+ * SilcSocketType type
+ *
+ * Type of the socket. This identifies the type of the connection. This
+ * is mainly used to identify whether the connection is a client or a
+ * server connection.
+ *
+ * void *user_data
+ *
+ * This is a pointer to a data that is is saved here at the same
+ * time a new connection object is allocated. Usually this is a
+ * back-pointer to some important data for fast referencing. For
+ * SILC server this is a pointer to the ID list and for SILC client
+ * to object holding active connections (windows).
+ *
+ * SilcProtocol protocol
+ *
+ * Protocol object for the socket. Currently only one protocol can be
+ * executing at a time for a particular socket.
+ *
+ * uint32 flags
+ *
+ * Socket flags that indicate the status of the socket. This can
+ * indicate several different status that can affect the use of the
+ * socket object.
+ *
+ * int users
+ *
+ * Reference counter. When allocated it is set to one (1) and it won't
+ * be freed until it hits zero (0).
+ *
+ * char *hostname
+ * char *ip
+ * uint16 port
+ *
+ * Resolved hostname, IP address and port of the connection who owns
+ * this object.
+ *
+ * SilcBuffer inbuf
+ * SilcBuffer outbuf
+ *
+ * Incoming and outgoing buffers for the particular socket connection.
+ * Incoming data from the socket is put after decryption in to the
+ * inbuf buffer and outgoing data after encryption is put to the outbuf
+ * buffer.
+ *
+ * SilcSocketConnectionHB hb
+ *
+ * The heartbeat context. If NULL, heartbeat is not performed.
+ *
+ ***/
struct SilcSocketConnectionStruct {
int sock;
SilcSocketType type;
SilcSocketConnectionHB hb;
};
-/* Heartbeat context */
-struct SilcSocketConnectionHB {
- uint32 heartbeat;
- SilcSocketConnectionHBCb hb_callback;
- void *hb_context;
- void *timeout_queue;
- SilcTask hb_task;
- SilcSocketConnection sock;
-};
-
/* Macros */
/* Generic manipulation of flags */
#define SILC_IS_DISCONNECTED(x) SF_IS((x), SILC_SF_DISCONNECTED)
/* Prototypes */
+
+/****f* silccore/SilcSocketConnectionAPI/silc_socket_alloc
+ *
+ * SYNOPSIS
+ *
+ * void silc_socket_alloc(int sock, SilcSocketType type, void *user_data,
+ * SilcSocketConnection *new_socket);
+ *
+ * DESCRIPTION
+ *
+ * Allocates a new socket connection object. The allocated object is
+ * returned to the new_socket argument. The `sock' is the socket
+ * for the connection, the `type' the initial type of the connection and
+ * the `user_data' a application specific pointer.
+ *
+ ***/
void silc_socket_alloc(int sock, SilcSocketType type, void *user_data,
SilcSocketConnection *new_socket);
+
+/****f* silccore/SilcSocketConnectionAPI/silc_socket_free
+ *
+ * SYNOPSIS
+ *
+ * void silc_socket_free(SilcSocketConnection sock);
+ *
+ * DESCRIPTION
+ *
+ * Frees the socket connection context. This frees it only if the
+ * reference counter of the socket is zero, otherwise it decreases the
+ * reference counter.
+ *
+ ***/
void silc_socket_free(SilcSocketConnection sock);
+
+/****f* silccore/SilcSocketConnectionAPI/silc_socket_dup
+ *
+ * SYNOPSIS
+ *
+ * SilcSocketConnection silc_socket_dup(SilcSocketConnection sock);
+ *
+ * DESCRIPTION
+ *
+ * Duplicates the socket context. This actually does not duplicate
+ * any data, instead this increases the reference counter of the
+ * context. The reference counter is decreased by calling the
+ * silc_socket_free function and it frees the data when the counter
+ * hits zero.
+ *
+ ***/
SilcSocketConnection silc_socket_dup(SilcSocketConnection sock);
+
+/****f* silccore/SilcSocketConnectionAPI/silc_socket_set_heartbeat
+ *
+ * SYNOPSIS
+ *
+ * void silc_socket_set_heartbeat(SilcSocketConnection sock,
+ * uint32 heartbeat,
+ * void *hb_context,
+ * SilcSocketConnectionHBCb hb_callback,
+ * void *timeout_queue);
+ *
+ * DESCRIPTION
+ *
+ * Sets the heartbeat timeout and prepares the socket for performing
+ * heartbeat in `heartbeat' intervals (seconds). The `hb_context' is
+ * allocated by the application and will be sent as argument to the
+ * `hb_callback' function that is called when the `heartbeat' timeout
+ * expires. The callback `hb_context' won't be touched by the library
+ * but will be freed automatically when calling silc_socket_free. The
+ * `timeout_queue' is the application's scheduler timeout queue.
+ *
+ ***/
void silc_socket_set_heartbeat(SilcSocketConnection sock,
uint32 heartbeat,
void *hb_context,
projects / silc.git / blobdiff